Fixed documentation warnings for c-docs
[iotivity.git] / resource / csdk / routing / include / routingtablemanager.h
1 /* ****************************************************************
2  *
3  * Copyright 2015 Samsung Electronics All Rights Reserved.
4  *
5  *
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *      http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  ******************************************************************/
20
21 /**
22  * @file
23  * This file contains the APIs for routing table manager.
24  */
25 #ifndef ROUTING_TABLE_MANAGER_H_
26 #define ROUTING_TABLE_MANAGER_H_
27
28 #ifndef SINGLE_THREAD
29 #include <unistd.h>
30 #include <time.h>
31 #include <sys/time.h>
32 #endif
33
34 #if defined(__ANDROID__)
35 #include <linux/time.h>
36 #endif
37 #include "ulinklist.h"
38 #include "uarraylist.h"
39 #include "octypes.h"
40
41
42 #ifdef __cplusplus
43 extern "C"
44 {
45 #endif
46
47 /**
48  * Maximum hop/destination address length.
49  */
50 #define MAX_DEST_ADDR_LEN 40
51
52 /**
53  * Maximum number of observers for the gateway resource.
54  */
55 #define MAX_NUM_OBSERVERS 10
56
57 /**
58  * Maximum time after which gateway should send a notification for its existence.
59  * Every 30s gateway will send its existence notification.
60  */
61 #define GATEWAY_ALIVE_TIMEOUT 30
62
63 /**
64  * The routing table entries are validated for every 40 seconds for its existence.
65  */
66 #define ROUTINGTABLE_REFRESH_TIMEOUT 40
67
68 /**
69  * The routing table entries are removed if entries are invalid every 45 seconds.
70  */
71 #define ROUTINGTABLE_VALIDATION_TIMEOUT 45
72
73 /**
74  * Destination Interface Address entries.
75  */
76 typedef struct
77 {
78     uint32_t observerId;                    /**< Observer Id. */
79     CAEndpoint_t destIntfAddr;              /**< Destination Interface Address. */
80     uint32_t timeElapsed;                   /**< Time elapsed. */
81     bool isValid;                           /**< Valid check for Gateway. */
82 } RTMDestIntfInfo_t;
83
84 /**
85  * Endpoint Address entries.
86  */
87 typedef struct
88 {
89     uint16_t endpointId;                    /**< Endpoint Id. */
90     CAEndpoint_t destIntfAddr;              /**< Destination Interface Address. */
91 } RTMEndpointEntry_t;
92
93 /**
94  * Gateway Address entries.
95  */
96 typedef struct gatewayAddress
97 {
98     uint32_t gatewayId;                     /**< Gateway Id. */
99     u_arraylist_t *destIntfAddr;            /**< Destination Interface Addresses. */
100 } RTMGatewayId_t;
101
102 /**
103  * Routing table entries at Gateway.
104  */
105 typedef struct
106 {
107     RTMGatewayId_t *destination;            /**< destination Address. */
108     RTMGatewayId_t *nextHop;                /**< Next Hop Information. */
109     uint32_t routeCost;                     /**< routeCost. */
110     uint16_t mcastMessageSeqNum;            /**< sequence number for last mcast packet. */
111     uint32_t seqNum;                        /**< sequence number for notification. */
112 } RTMGatewayEntry_t;
113
114 /**
115  * Initialize the Routing Table Manager.
116  * @param[in,out] gatewayTable      Gateway Routing Table.
117  * @param[in,out] endpointTable     Endpoint Routing Table.
118  * @return  ::OC_STACK_OK or Appropriate error code.
119  */
120 OCStackResult RTMInitialize(u_linklist_t **gatewayTable, u_linklist_t **endpointTable);
121
122 /**
123  * Terminates the Routing Table Manager.
124  * @param[in,out] gatewayTable      Gateway Routing Table.
125  * @param[in,out] endpointTable     Endpoint Routing Table.
126  * @return  ::OC_STACK_OK or Appropriate error code.
127  */
128 OCStackResult RTMTerminate(u_linklist_t **gatewayTable, u_linklist_t **endpointTable);
129
130 /**
131  * Frees the gateway table memory with nodes containing structure RTMGatewayEntry_t.
132  * @param[in,out] gatewayTable      Gateway Routing Table.
133  * @return  ::OC_STACK_OK or Appropriate error code.
134  */
135 OCStackResult RTMFreeGatewayRouteTable(u_linklist_t **gatewayTable);
136
137 /**
138  * Frees the gateway ID list memory with nodes containing structute RTMGatewayId_t.
139  * @param[in,out] gatewayIdTable      Gateway ID list.
140  * @return  ::OC_STACK_OK or Appropriate error code.
141  */
142 OCStackResult RTMFreeGatewayIdList(u_linklist_t **gatewayIdTable);
143
144 /**
145  * Frees the endpoint table memory with nodes containing structute RTMEndpointEntry_t.
146  * @param[in,out] endpointTable     Endpoint Routing Table.
147  * @return  ::OC_STACK_OK or Appropriate error code.
148  */
149 OCStackResult RTMFreeEndpointRouteTable(u_linklist_t **endpointTable);
150
151 /**
152  * Adds the entry to the routing table if the entry for Gateway id is
153  * not preset in Routing table, Updates the Old entry if Entry for
154  * Gateway Id is already present in Routing table i.e routeCost and NextHop
155  * will be updated for efficient hop result.
156  *
157  * @param[in]       gatewayId           Gateway Id.
158  * @param[in]       nextHop             Next Hop address.
159  * @param[in]       routeCost           Shortest Path to Destination - Hopcount.
160  * @param[in]       destInterfaces      Destination Interface Information.
161  * @param[in,out]   gatewayTable        Gateway Routing Table.
162  * @return  ::OC_STACK_OK or Appropriate error code.
163  */
164 OCStackResult RTMAddGatewayEntry(uint32_t gatewayId, uint32_t nextHop, uint32_t routeCost,
165                                  const RTMDestIntfInfo_t *destInterfaces, u_linklist_t **gatewayTable);
166
167 /**
168  * Adds the endpoint entry to the routing table.
169  * @param[in,out]   endpointId          Endpoint Id.
170  * @param[in]       destAddr            Destination Address.
171  * @param[in,out]   endpointTable       Endpoint Routing Table.
172  * @return  ::OC_STACK_OK or Appropriate error code.
173  */
174 OCStackResult RTMAddEndpointEntry(uint16_t *endpointId, const CAEndpoint_t *destAddr,
175                                   u_linklist_t **endpointTable);
176
177 /**
178  * Removes the gateway entry from the routing table and also removes
179  * corresponding entries having nexthop as removed gateway.
180  * @param[in]        gatewayId              Gateway id of node need to be removed.
181  * @param[in,out]    removedGatewayNodes    Linklist containing removed gateway nodes
182  *                                          list need to be freed by caller.
183  * @param[in,out]    gatewayTable           Gateway Routing Table.
184  * @return  ::OC_STACK_OK or Appropriate error code.
185  */
186 OCStackResult RTMRemoveGatewayEntry(uint32_t gatewayId, u_linklist_t **removedGatewayNodes,
187                                     u_linklist_t **gatewayTable);
188
189 /**
190  * Removes the endpoint entry from the routing table.
191  * @param[in]       endpointId        Endpoint id of node need to be removed.
192  * @param[in,out]   endpointTable     Endpoint Routing Table.
193  * @return  ::OC_STACK_OK or Appropriate error code.
194  */
195 OCStackResult RTMRemoveEndpointEntry(uint16_t endpointId, u_linklist_t **endpointTable);
196
197 /**
198  * Removes the gateway entry from the routing table which has gateway id and nexthop as given.
199  * @param[in]        gatewayId              Gateway Id.
200  * @param[in]        nextHop                Next Hop address.
201  * @param[in]        destInfAdr             Destination Address of Next Hop to update time.
202  * @param[in,out]    existEntry             Entry which has different Next Hop.
203  * @param[in,out]    gatewayTable           Gateway Routing Table.
204  * @return  ::OC_STACK_OK or Appropriate error code.
205  */
206 OCStackResult RTMRemoveGatewayDestEntry(uint32_t gatewayId, uint32_t nextHop,
207                                         const RTMDestIntfInfo_t *destInfAdr,
208                                         RTMGatewayEntry_t **existEntry, u_linklist_t **gatewayTable);
209 /**
210  * Removes the gateway nodes.
211  * @param[in,out]    gatewayTable           Gateway Routing Table.
212  * @return  ::OC_STACK_OK or Appropriate error code.
213  */
214 OCStackResult RTMRemoveGateways(u_linklist_t **gatewayTable);
215
216 /**
217  * Removes the endpoint nodes.
218  * @param[in,out]   endpointTable           Endpoint Routing Table.
219  * @return  ::OC_STACK_OK or Appropriate error code.
220  */
221 OCStackResult RTMRemoveEndpoints(u_linklist_t **endpointTable);
222
223 /**
224  * Gets the neighbor nodes i.e nodes with routecost 1.
225  * @param[in,out]   neighbourNodes        link list containing neighbor nodes.
226                                           this list will be pointer to GatewayIds
227                                           and must be freed by caller.
228  * @param[in]       gatewayTable           Gateway Routing Table.
229  */
230 void RTMGetNeighbours(u_linklist_t **neighbourNodes, const u_linklist_t *gatewayTable);
231
232 /**
233  * Gets next hop from the routing table.
234  * @param[in]        gatewayId              Gateway Id.
235  * @param[in]        gatewayTable           Gateway Routing Table.
236  * @return  Next Hop address - returns NULL if it is End Device.
237  */
238 RTMGatewayId_t *RTMGetNextHop(uint32_t gatewayId, const u_linklist_t *gatewayTable);
239
240 /**
241  * Gets endpoint entry
242  * @param[in]       endpointId        Endpoint id of node need to be removed.
243  * @param[in]       endpointTable     Endpoint Routing Table.
244  * @return  Endpoint Destination inteface address.
245  */
246 CAEndpoint_t *RTMGetEndpointEntry(uint16_t endpointId, const u_linklist_t *endpointTable);
247
248 /**
249  * Updates destination interface address of an entry with provided gateway id
250  * as destination.
251  * @param[in]        gatewayId               Gateway Id of Hop need to be updated.
252  * @param[in]        destInterfaces          Destination Interface Information.
253  * @param[in]        addAdr                  Add/Remove destination address.
254  * @param[in,out]    gatewayTable            Gateway Routing Table.
255  * @return  ::OC_STACK_OK or Appropriate error code.
256  */
257 OCStackResult RTMUpdateDestinationIntfAdr(uint32_t gatewayId, RTMDestIntfInfo_t destInterfaces,
258                                           bool addAdr, u_linklist_t **gatewayTable);
259
260 /**
261  * Updates Multicast sequence number for gatewayID
262  * @param[in]       gatewayId           Gateway Id of Hop need to be updated.
263  * @param[in]       seqNum              Sequence number for last cast packet from gateway.
264  * @param[in,out]   gatewayTable        Gateway Routing Table.
265  * @return  ::OC_STACK_OK or Appropriate error code.
266  */
267 OCStackResult RTMUpdateMcastSeqNumber(uint32_t gatewayId, uint16_t seqNum,
268                                       u_linklist_t **gatewayTable);
269
270 /**
271  * Prints the routing table
272  * @param[in]    gatewayTable           Gateway Routing Table.
273  * @param[in]    endpointTable          Endpoint Routing Table.
274  */
275 void RTMPrintTable(const u_linklist_t *gatewayTable, const u_linklist_t *endpointTable);
276
277 /**
278  * Frees the GatewayId
279  * @param[in]        gateway                Gateway Structure pointer.
280  * @param[in,out]    gatewayTable           Gateway Routing Table.
281  */
282 void RTMFreeGateway(RTMGatewayId_t *gateway, u_linklist_t **gatewayTable);
283
284 /**
285  * Gets the list of observer IDs.
286  * @param[in,out]    obsList                List of Observation IDs.
287  * @param[in,out]    obsListLen             Length if Observation ID list.
288  * @param[in]        gatewayTable           Gateway Routing Table.
289  */
290 void RTMGetObserverList(OCObservationId **obsList, uint8_t *obsListLen,
291                         const u_linklist_t *gatewayTable);
292
293 /**
294  * Adds a observer address and obsID to the list.
295  * @param[in]        obsID                  Observation ID.
296  * @param[in]        devAddr                Address of Gateway.
297  * @param[in,out]    gatewayTable           Gateway Routing Table.
298  * @return  ::OC_STACK_OK or Appropriate error code.
299  */
300 OCStackResult RTMAddObserver(uint32_t obsID, CAEndpoint_t devAddr, u_linklist_t **gatewayTable);
301
302 /**
303  * Check if a particular observer address is already registerd and returns
304  * its obsID if present.
305  * @param[in]        devAddr                Address of Gateway.
306  * @param[in,out]    obsID                  Observation ID.
307  * @param[in]        gatewayTable           Gateway Routing Table.
308  * @return  true or false.
309  */
310 bool RTMIsObserverPresent(CAEndpoint_t devAddr, OCObservationId *obsID,
311                           const u_linklist_t *gatewayTable);
312
313 /**
314  * Gets Current Time in Micro Seconds.
315  * @return  Current Time.
316  */
317 uint64_t RTMGetCurrentTime();
318
319 /**
320  * Update Gateway Address Validity.
321  * @param[in,out]    invalidTable      Removed entries Table.
322  * @param[in,out]    gatewayTable      Gateway Routing Table.
323  * @return  ::OC_STACK_OK or Appropriate error code.
324  */
325 OCStackResult RTMUpdateDestAddrValidity(u_linklist_t **invalidTable, u_linklist_t **gatewayTable);
326
327 /**
328  * Removes invalid gateways.
329  * @param[in,out]    invalidTable      Removed entries Table.
330  * @param[in,out]    gatewayTable      Gateway Routing Table.
331  * @return  ::OC_STACK_OK or Appropriate error code.
332  */
333 OCStackResult RTMRemoveInvalidGateways(u_linklist_t **invalidTable, u_linklist_t **gatewayTable);
334
335 /**
336  * Update Sequence number of Gateway Entry.
337  * @param[in]       gatewayId           Gateway Id.
338  * @param[in]       seqNum              Sequence Number of Entry.
339  * @param[in]       destAdr             Destination Interface Information.
340  * @param[out]      gatewayTable        Gateway Routing Table.
341  * @param[in]       forceUpdate         To Update parameters forcefully.
342  * @return  ::OC_STACK_OK or Appropriate error code.
343  */
344 OCStackResult RTMUpdateEntryParameters(uint32_t gatewayId, uint32_t seqNum,
345                                        const RTMDestIntfInfo_t *destAdr, u_linklist_t **gatewayTable,
346                                        bool forceUpdate);
347
348 #ifdef __cplusplus
349 } /* extern "C" */
350 #endif
351
352 #endif /* ROUTING_TABLE_MANAGER_H_ */
353