RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
netio_route.h
1 /*
2  * FILE: netio_route.h - NETIO Route API
3  *
4  * Copyright 2012-2014 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 31jul2014,tk MICRO-842/PR#9683 - Removed superfluous paramaters in DB
14  * compare function
15  * 05may2014,tk MICRO-72 - Updated based on CR-232
16  * 25apr2012,tk Written
17  */
18 /*ci
19  * \file
20  * \defgroup NETIO_ResolverClass NETIO Resolver API
21  * \ingroup NETIOCommon
22  * \brief NETIO Resolver API
23  */
24 
25 #ifndef netio_route_h
26 #define netio_route_h
27 
28 #ifndef netio_dll_h
29 #include "netio/netio_dll.h"
30 #endif
31 
32 #ifndef osapi_config_h
33 #include "osapi/osapi_config.h"
34 #endif
35 
36 #ifndef osapi_types_h
37 #include "osapi/osapi_types.h"
38 #endif
39 
40 #ifndef reda_string_h
41 #include "reda/reda_string.h"
42 #endif
43 
44 #ifndef netio_address_h
45 #include "netio/netio_address.h"
46 #endif
47 
48 #ifndef netio_interface_h
49 #include "netio/netio_interface.h"
50 #endif
51 
52 #ifdef __cplusplus
53 extern "C"
54 {
55 #endif
56 
57 /*ci
58  * \defgroup NETIO_AddressResolver NETIO Address Resolver API
59  * \ingroup NETIO_ResolverClass
60  * \addtogroup NETIO_AddressResolver
61  * @{
62  */
63 /*ci
64  *\brief Properties for an address resolver
65  */
66 struct NETIO_AddressResolverProperty
67 {
68  /*ci
69  * \brief The maximum number of interfaces which can translate addresses
70  */
71  RTI_UINT32 max_interfaces;
72 
73  /*ci
74  * \brief The default low index if none is specified in the address string
75  */
76  RTI_INT32 default_low_index;
77 
78  /*ci
79  * \brief The default high index if none is specified in the address string
80  */
81  RTI_INT32 default_high_index;
82 
83  /*ci
84  * \brief The default port number
85  */
86  RTI_INT32 default_base_port;
87 };
88 
89 /*ci
90  * \brief Constant to initialize NETIO_AddressResolverProperty
91  */
92 #define NETIO_AddressResolverProperty_INITIALIZER \
93 {\
94  1,\
95  0,\
96  4,\
97  7400\
98 }
99 
100 /*ci
101  * \brief Implementation of the NETIO_AddressResolver
102  */
103 typedef struct NETIO_AddressResolver
104 {
105  /*ci
106  * \brief Proprties the address resolver was created with
107  */
108  struct NETIO_AddressResolverProperty property;
109 
110  /*ci
111  * \brief Table with registered address resolvers
112  */
113  DB_Table_T resolver_table;
114 
115  /*ci
116  * \brief Database where the address resolvers are stored
117  */
118  DB_Database_T db;
119 } NETIO_AddressResolver_T;
120 
121 struct NETIO_AddressResolveEntry;
122 
123 /*ci
124  * \brief State information when resolving address. It should not be accessed
125  * directly
126  *
127  * \details
128  *
129  * When an address string is resolved, a resolved context is created. The
130  * resolved context can be iterated over in case an address string resolved
131  * to more than one entry, for example [1,10]\@mammoth. The \ref
132  * NETIO_AddressResolver_get_next function is used to iterate over a context.
133  */
134 typedef struct NETIO_AddressResolveContext
135 {
136  /*ci
137  * \brief Whether the context has been initialized or not
138  */
139  RTI_BOOL is_initialized;
140 
141  /*ci
142  * \brief The lowest index based on the address string and the default
143  * low index.
144  */
145  RTI_INT32 low_index;
146 
147  /*ci
148  * \brief The highest index based on the address string and the default
149  * low index. The range from low_index is always in increments of 1
150  */
151  RTI_INT32 high_index;
152 
153  /*ci
154  * \brief The highest index based on the address string and the default
155  * low index. The range from low_index is always in increments of 1
156  */
157  RTI_UINT32 base_port;
158 
159  /*ci
160  * \brief The index which is currently iterated over.
161  */
162  RTI_INT32 current_index;
163 
164  /*ci
165  * \brief The resolver which contributed the address resolution
166  */
167  struct NETIO_AddressResolveEntry *r_entry;
168 
169  /*ci
170  * \brief The cursor into the address resolver table.
171  */
172  DB_Cursor_T cursor;
173 
174  /*ci
175  * \brief The address part of a NETIO_Address string format. NETIO
176  * does not interprete this part, it is up to a specific layer
177  * to do so.
178  */
179  char out_address_string[NETIO_ADDRESS_TOKEN_MAX_SIZE];
180 
181  /*ci
182  * \brief The current interface Id
183  */
184  RT_ComponentFactoryId_T intfid;
185 
186  /*ci
187  * \brief The current kind of address being resolved
188  */
189  NETIO_RouteKind_T kind;
190 } NETIO_AddressResolveContext_T;
191 
192 /*ci
193  * \brief Constant to initialize NETIO_AddressResolveContext
194  */
195 #define NETIO_AddressResolveContext_INITIALIZER \
196 { \
197  RTI_FALSE\
198 }
199 
200 /*ci
201  * \brief Create a new address resolver
202  *
203  * \param[in] name The name of the address resolver, for information only
204  * \param[in] db The database to create the resolver table in
205  * \param[in] property The resolver properties to use
206  *
207  * \return Pointer to created address resolver on success, NULL on failure
208  *
209  * \sa \ref NETIO_AddressResolver_delete
210  */
211 MUST_CHECK_RETURN NETIODllExport NETIO_AddressResolver_T*
212 NETIO_AddressResolver_new(const char *name,
213  DB_Database_T db,
214  struct NETIO_AddressResolverProperty *property);
215 /*ci
216  * \brief Delete an address resolver
217  *
218  * \param[in] nar Address resolver to delete
219  *
220  * \return RTI_TRUE on success, RTI_FALSE on failure
221  *
222  * \sa \ref NETIO_AddressResolver_new
223  */
224 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
225 NETIO_AddressResolver_delete(NETIO_AddressResolver_T *nar);
226 
227 /*ci
228  * \brief Add an address resolver interface to the address resolver
229  *
230  * \param[in] nar Address resolver to add interface to
231  * \param[in] name The address prefix name the transport understands
232  * \param[in] port_resolve The port resolver function. Can be NULL
233  * \param[in] port_resolve_param Parameter to add to port resolver function
234  * \param[in] intf The interface to call to resolve an address
235  *
236  * \return RTI_TRUE on success, RTI_FALSE on failure
237  *
238  * \sa \ref NETIO_AddressResolver_delete_interface
239  */
240 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
241 NETIO_AddressResolver_add_interface(NETIO_AddressResolver_T *nar,
242  const char *name,
243  NETIO_PortCalculateFunc_T port_resolve,
244  void *port_resolve_param,
245  NETIO_Interface_T *intf);
246 
247 /*ci
248  * \brief Delete an address resolver interface from the address resolver
249  *
250  * \param[in] nar Address resolver to delete interface from
251  * \param[in] name The address prefix name the transport understands
252  * \param[out] existed RTI_TRUE is the interface existed, otherwise RTI_FALSE
253  * \param[out] intf If the interface existed it is returned in this
254  * parameter
255  *
256  * \return RTI_TRUE on success, RTI_FALSE on failure
257  *
258  * \sa \ref NETIO_AddressResolver_add_interface
259  */
260 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
261 NETIO_AddressResolver_delete_interface(NETIO_AddressResolver_T *nar,
262  const char *name,
263  RTI_BOOL *existed,
264  NETIO_Interface_T **intf);
265 
266 /*ci
267  * \brief Find an resolver interface based on the address prefix
268  *
269  * \param[in] nar Address resolver to search in
270  * \param[in] name The address prefix name the transport understands
271  * \param[out] intf If the interface existed it is returned in this
272  * parameter
273  *
274  * \return RTI_TRUE on success, RTI_FALSE on failure
275  *
276  * \sa \ref NETIO_AddressResolver_add_interface
277  */
278 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
279 NETIO_AddressResolver_lookup_interface(NETIO_AddressResolver_T *nar,
280  const char *name,
281  NETIO_Interface_T **intf);
282 /*ci
283  * \brief Resolve a NETIO_Address address string
284  *
285  * \details
286  *
287  * Resolve an address string to one or more NETIO_Address structures.
288  * This function parses the address, but does return the NETIO_Address.
289  * Instead use NETIO_AddressResolver_get_next to retrieve the address.
290  *
291  * \param[in] nar Address resolver to search in
292  * \param[in] try_index If try_index is >= 0, only try the specified index
293  * otherwise use the index specified in the address string
294  * \param[in] kind The type of address to convert
295  * \param[in] address_string The address string to resolve
296  * \param[inout] context On success the resolver context is returned. The
297  * context must have been initialized with before
298  * calling this function.
299  *
300  * \return RTI_TRUE on success, RTI_FALSE on failure
301  *
302  * \sa \ref NETIO_AddressResolver_get_next
303  */
304 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
305 NETIO_AddressResolver_resolve(NETIO_AddressResolver_T *nar,
306  RTI_INT32 try_index,
307  NETIO_RouteKind_T kind,
308  const char *address_string,
309  NETIO_AddressResolveContext_T *context);
310 /*ci
311  * \brief Iterate over an resolver context
312  *
313  * \param[in] nar Address resolver the context was created from
314  * \param[in] netio_intf The NETIO interface which resolved the context
315  * \param[in] id The id of the NETIO inteface factory that resolved
316  * the address
317  * \param[in] address A NETIO_Address structure with a valid address
318  * \param[inout] context The context to iterate over
319  * \param[in] error An error occured
320  *
321  * \return RTI_TRUE on success, RTI_FALSE on failure
322  *
323  * \sa \ref NETIO_AddressResolver_resolve
324  */
325 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
326 NETIO_AddressResolver_get_next(NETIO_AddressResolver_T *nar,
327  NETIO_Interface_T **netio_intf,
328  RT_ComponentFactoryId_T *id,
329  struct NETIO_Address *address,
330  NETIO_AddressResolveContext_T *context,
331  RTI_BOOL *error);
332 
333 /*ci
334  * \brief Initialize a \ref NETIO_AddressResolveContext_T
335  *
336  * \param[in] c Context to initialize
337  *
338  * \sa \ref NETIO_AddressResolver_resolve \ref NETIO_AddressResolver_get_next
339  */
340 NETIODllExport void
341 NETIO_AddressResolveContext_init(NETIO_AddressResolveContext_T *c);
342 
343 /*ci @} */
344 
345 /*ci
346  * \defgroup NETIO_RouteClass NETIO Route Resolver API
347  * \ingroup NETIO_ResolverClass
348  * \addtogroup NETIO_RouteClass
349  * @{
350  */
351 
352 /*ci
353  * \brief Properties for the route resolved
354  */
355 struct NETIO_RouteResolverProperty
356 {
357  /*ci
358  * \brief The maximum number of destination which can be resolved
359  */
360  RTI_SIZE_T max_routes;
361 };
362 
363 /*ci
364  * \def NETIO_RouteResolverProperty_INITIALIZER
365  * \brief Iniitalizer constant for NETIO_RouteResolverProperty
366  */
367 #define NETIO_RouteResolverProperty_INITIALIZER \
368 {\
369  16\
370 }
371 
372 struct NETIO_RouteResolver;
373 
374 /*ci
375  * \brief Abstract NETIO_RouteResolver type
376  */
377 typedef struct NETIO_RouteResolver NETIO_RouteResolver_T;
378 
379 /*ci
380  * \brief Create a new route resolver
381  *
382  * \details
383  *
384  * Create a new route resolver
385  *
386  * \param[in] db The database to use when creating tables
387  * \param[in] nar The address resolver to use
388  * \param[in] name The name of the route resolver, typically used when
389  * creating database tables
390  * \param[in] property The properties for the route resolver
391  *
392  * \return A new route resolver on success, NULL on failure
393  *
394  * \sa \ref NETIO_RouteResolver_delete
395  */
396 MUST_CHECK_RETURN NETIODllExport NETIO_RouteResolver_T*
397 NETIO_RouteResolver_new(DB_Database_T db,NETIO_AddressResolver_T *nar,
398  const char* const name,
399  struct NETIO_RouteResolverProperty *const property);
400 
401 /*ci
402  * \brief Delete a route resolver
403  *
404  * \details
405  *
406  * Delete a route resolver
407  *
408  * \param[in] r_table
409  *
410  * \return RTI_TRUE on success, RTI_FALSE on failure
411  *
412  * \sa \ref NETIO_RouteResolver_new
413  */
414 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
415 NETIO_RouteResolver_delete(NETIO_RouteResolver_T *r_table);
416 
417 /*ci
418  * \brief Add an interface to the route resolver
419  *
420  * \details
421  *
422  * When a route is resolved (finding an outgoing interface), the route
423  * resolver searches among the interfaces that has been added with this
424  * call
425  *
426  * \param[in] r_table Route resolver to add the interface too
427  * \param[in] intf The interface routing to the source
428  * \param[in] address The address which the interface can route
429  * \param[in] netmask The netmask applied before testing for a match
430  * \param[out] exists Whether an interface existed or not
431  *
432  * \return RTI_TRUE on success, RTI_FALSE on failure
433  *
434  * \sa \ref NETIO_RouteResolver_delete_interface
435  */
436 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
437 NETIO_RouteResolver_add_interface(NETIO_RouteResolver_T *r_table,
438  NETIO_Interface_T *intf,
439  struct NETIO_Address *address,
440  struct NETIO_Netmask *netmask,
441  RTI_BOOL *exists);
442 
443 /*ci
444  * \brief Delete an interface from the route resolver
445  *
446  * \details
447  *
448  * Delete an interface from the route resolver
449  *
450  * \param[in] r_table Route resolver to add the interface too
451  * \param[in] intf The interface routing to the source
452  * \param[in] address The address which the interface can route
453  * \param[in] netmask The netmask applied before testing for a match
454  * \param[out] exists Whether an interface existed or not
455  *
456  * \return RTI_TRUE on success, RTI_FALSE on failure
457  *
458  * \sa \ref NETIO_RouteResolver_add_interface
459  */
460 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
461 NETIO_RouteResolver_delete_interface(NETIO_RouteResolver_T *r_table,
462  NETIO_Interface_T *intf,
463  struct NETIO_Address *address,
464  struct NETIO_Netmask *netmask,
465  RTI_BOOL *exists);
466 
467 /*ci
468  * \brief Add a new route to a destination
469  *
470  * \details
471  *
472  * Add a new route to a destination if one does not exist. This function
473  * also takes the \a via_address parameter which indicates which address
474  * to pass to a downstream interface to reach the destination. For example,
475  * to reach an RTPS endpoint over UDP the \a via_address contains the UDP
476  * address to pass to the downstream UDP NETIO interface.
477  *
478  * \param[in] r_table Route resolver
479  * \param[in] src_intf The source address of the route
480  * \param[in] dst_reader The destination address to send too
481  * \param[in] via_address The downstream address to use
482  * \param[in] property The proprties for this route
483  * \param[out] route_existed Whether the route existed or not
484  * \param[out] found_route Whether an interface capable of routing to the
485  * destination was found or not
486  *
487  * \return RTI_TRUE on success, RTI_FALSE on failure
488  *
489  * \sa \ref NETIO_RouteResolver_delete_route
490  */
491 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
492 NETIO_RouteResolver_add_route(NETIO_RouteResolver_T *r_table,
493  NETIO_Interface_T *src_intf,
494  struct NETIO_Address *dst_reader,
495  struct NETIO_Address *via_address,
496  struct NETIORouteProperty *property,
497  RTI_BOOL *route_existed,
498  RTI_BOOL *found_route);
499 
500 /*ci
501  * \brief Delete a route from
502  *
503  * \details
504  *
505  * \param[in] r_table Route resolver
506  * \param[in] src_intf The source address of the route
507  * \param[in] dst_reader The destination address to send too
508  * \param[in] via_address The downstream address to use
509  * \param[out] route_existed Whether the route existed or not
510  * \param[out] found_route Whether an interface capable of routing to the
511  * destination was found or not
512  *
513  * \return RTI_TRUE on success, RTI_FALSE on failure
514  *
515  * \sa \ref NETIO_RouteResolver_add_route
516  */
517 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
518 NETIO_RouteResolver_delete_route(NETIO_RouteResolver_T *r_table,
519  NETIO_Interface_T *src_intf,
520  struct NETIO_Address *dst_reader,
521  struct NETIO_Address *via_address,
522  RTI_BOOL *route_existed,
523  RTI_BOOL *found_route);
524 
525 /*ci
526  * \brief Add peers to the route resolver
527  *
528  * \details
529  *
530  * The function is similar to \ref NETIO_RouteResolver_add_route, but serves
531  * a slightly different purpose. Instead of adding a route an address specified
532  * in NETIO_Address format, this function takes the address in the NETIO
533  * Address string format. The route resolver parses the address string and
534  * adds the resulting NETIO_Address (there may be more than on depending
535  * o the index, for example 2@... will yield 3 address). There are two kinds
536  * of peers (meta and user). In all other respects this function behaves as
537  * \ref NETIO_RouteResolver_add_route
538  *
539  * \param[in] r_table Route resolver
540  * \param[in] src_intf The source address of the route
541  * \param[in] dst_reader The destination address to send too
542  * \param[in] peer_kind The type of address
543  * \param[in] peer_address Peer address string
544  * \param[in] property The properties for this route
545  * \param[in] via_address The downstream address to use
546  * \param[out] route_existed Whether the route existed or not
547  * \param[out] found_route Whether an interface capable of routing to the
548  * destination was found or not
549  *
550  * \return RTI_TRUE on success, RTI_FALSE on failure
551  *
552  * \sa \ref NETIO_RouteResolver_add_route
553  */
554 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
555 NETIO_RouteResolver_add_peer(NETIO_RouteResolver_T *r_table,
556  NETIO_Interface_T *src_intf,
557  struct NETIO_Address *dst_reader,
558  NETIO_RouteKind_T peer_kind,
559  const char *peer_address,
560  struct NETIORouteProperty *property,
561  RTI_BOOL *route_existed,
562  RTI_BOOL *found_route);
563 
564 /*ci
565  * \brief Delete peers from the route resolver
566  *
567  * \details
568  *
569  * The function is similar to \ref NETIO_RouteResolver_delete_route, but serves
570  * a slightly different purpose. Instead of adding a route an address specified
571  * in NETIO_Address format, this function takes the address in the NETIO
572  * Address string format. The route resolver parses the address string and
573  * removes the resulting NETIO_Address (there may be more than on depending
574  * o the index, for example 2@... will yield 3 address). There are two kinds
575  * of peers (meta and user). In all other respects this function behaves as
576  * \ref NETIO_RouteResolver_add_route
577  *
578  * \param[in] r_table Route resolver
579  * \param[in] src_intf The source address of the route
580  * \param[in] dst_reader The destination address to send too
581  * \param[in] peer_kind The type of address
582  * \param[in] peer_address Peer address string
583  * \param[in] property The properties for this route
584  * \param[in] via_address The downstream address to use
585  * \param[out] route_existed Whether the route existed or not
586  * \param[out] found_route Whether an interface capable of routing to the
587  * destination was found or not
588  *
589  * \return RTI_TRUE on success, RTI_FALSE on failure
590  *
591  * \sa \ref NETIO_RouteResolver_add_route
592  */
593 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
594 NETIO_RouteResolver_delete_peer(NETIO_RouteResolver_T *r_table,
595  NETIO_Interface_T *src_intf,
596  struct NETIO_Address *dst_reader,
597  NETIO_RouteKind_T peer_kind,
598  const char *peer_address,
599  RTI_BOOL *route_existed,
600  RTI_BOOL *found_route);
601 
602 
603 /*ci @} */
604 
605 /*ci
606  * \defgroup NETIO_BindClass NETIO Bind Resolver API
607  * \ingroup NETIO_ResolverClass
608  * \addtogroup NETIO_BindClass
609  * @{
610  */
611 struct NETIO_BindResolver;
612 
613 /*ci
614  * \brief Abstract NETIO_BindResolver type
615  */
616 typedef struct NETIO_BindResolver NETIO_BindResolver_T;
617 
618 /*ci
619  * \brief Properties for the bind resolver
620  */
621 struct NETIO_BindResolverProperty
622 {
623  /*ci
624  * \brief The maximum number of sources which can listened to
625  */
626  RTI_SIZE_T max_routes;
627 };
628 
629 /*ci
630  * \def NETIO_BindResolverProperty_INITIALIZER
631  * \brief Initializer constant for NETIO_BindResolverProperty
632  */
633 #define NETIO_BindResolverProperty_INITIALIZER \
634 {\
635  1\
636 }
637 
638 /*ci
639  * \brief Create a new bind resolver
640  *
641  * \details
642  *
643  * Create a new bind resolver
644  *
645  * \param[in] db The database to use for tables
646  * \param[in] nar The address resolver to use to resolve addresses
647  * specified as strings
648  * \param[in] name The name of the bind resolver, typically used to
649  * when creating database tables
650  * \param[in] property The bind resolver properties
651  *
652  * \return Pointer to the newly created bind resolver on exit, NULL on failure
653  *
654  * \sa \ref NETIO_BindResolver_delete
655  */
656 MUST_CHECK_RETURN NETIODllExport NETIO_BindResolver_T*
657 NETIO_BindResolver_new(DB_Database_T db,NETIO_AddressResolver_T *nar,
658  const char* const name,
659  struct NETIO_BindResolverProperty *const property);
660 
661 #ifndef RTI_CERT
662 /*ci
663  * \brief Delete a bind resolver
664  *
665  * \details
666  *
667  * Create a new bind resolver
668  *
669  * \param[in] r_table Delete a bind resolver
670  *
671  * \return RTI_TRUE on success, RTI_FALSE on failure
672  *
673  * \sa \ref NETIO_BindResolver_new
674  */
675 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
676 NETIO_BindResolver_delete(NETIO_BindResolver_T* r_table);
677 #endif
678 
679 /*ci
680  * \brief Add a new route to the bind resolver
681  *
682  * \details
683  *
684  * Add a new interface tgo listen to
685  *
686  * \param[in] r_table The bind table
687  * \param[in] kind The type of address
688  * \param[in] id The interface factory
689  * \param[in] address The address which can be listened too
690  * \param[in] intf The interface to listen to for the address
691  * \param[out] exists Whether the route already existed or not
692  *
693  * \return RTI_TRUE on success, RTI_FALSE on failure
694  *
695  * \sa \ref NETIO_BindResolver_delete_route
696  */
697 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
698 NETIO_BindResolver_add_route(NETIO_BindResolver_T *r_table,
699  NETIO_RouteKind_T kind,
700  RT_ComponentFactoryId_T *id,
701  struct NETIO_Address *address,
702  NETIO_Interface_T *intf,
703  RTI_BOOL *exists);
704 
705 /*ci
706  * \brief Delete a route from the bind resolver
707  *
708  * \details
709  *
710  * Delete a route from the bind resolver
711  *
712  * \param[in] r_table The bind table
713  * \param[in] kind The type of address
714  * \param[in] id The interface factory
715  * \param[in] address The address which can be listened too
716  * \param[in] intf The interface to listen to for the address
717  * \param[out] exists Whether the route already existed or not
718  *
719  * \return RTI_TRUE on success, RTI_FALSE on failure
720  *
721  * \sa \ref NETIO_BindResolver_add_route
722  */
723 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
724 NETIO_BindResolver_delete_route(NETIO_BindResolver_T *r_table,
725  NETIO_RouteKind_T kind,
726  RT_ComponentFactoryId_T *id,
727  struct NETIO_Address *address,
728  RTI_BOOL *existed);
729 
730 /*ci
731  * \brief Lookup an interface by name
732  *
733  * \details
734  *
735  * Given a kind, index, an address in string format the bind resolver will
736  * search among its routes to find an interface capable of receiving the
737  * address.
738  *
739  * \param[in] r_table The bind table
740  * \param[in] kind The type of address
741  * \param[in] try_index The index to use,
742  * \param[in] name The address string to listen to
743  * \param[out] id The factory which successfully resolved the address
744  * \param[out] intf The interface to receive on
745  * \param[out] resolved Sequence of addresses resolved from the address string
746  *
747  * \return RTI_TRUE on success, RTI_FALSE on failure
748  *
749  * \sa \ref NETIO_BindResolver_lookup_by_address,
750  * \ref NETIO_BindResolver_lookup_by_kind
751  */
752 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
753 NETIO_BindResolver_lookup_by_name(NETIO_BindResolver_T *r_table,
754  NETIO_RouteKind_T kind,
755  RTI_INT32 try_index,
756  const char *const name,
757  RT_ComponentFactoryId_T *id,
758  NETIO_Interface_T **intf,
759  struct NETIO_AddressSeq *resolved);
760 
761 /*ci
762  * \brief Lookup an interface by address
763  *
764  * \details
765  *
766  * Given a kind, an address and a factory, find the interface which can
767  * listen on the address.
768  *
769  * \param[in] r_table The bind table
770  * \param[in] kind The type of address
771  * \param[out] id The factory which successfully resolved the address
772  * \param[out] address The address
773  * \param[out] intf The interface to receive on
774  *
775  * \return RTI_TRUE on success, RTI_FALSE on failure
776  *
777  * \sa \ref NETIO_BindResolver_lookup_by_name,
778  * \ref NETIO_BindResolver_lookup_by_kind
779  */
780 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
781 NETIO_BindResolver_lookup_by_address(NETIO_BindResolver_T *r_table,
782  NETIO_RouteKind_T kind,
783  RT_ComponentFactoryId_T *id,
784  struct NETIO_Address *address,
785  NETIO_Interface_T **intf);
786 
787 /*ci
788  * \brief Release addresses previously reserved with
789  * NETIO_BindResolver_reserve_addresses
790  *
791  * \details
792  *
793  * \param[in] r_table The bind table
794  * \param[in] transport A sequence of registered NETIO interfaces
795  * \param[out] kind The kind of address to reserve
796  * \param[out] locator_seq On success a sequence of addresses which have been
797  * reserved
798  *
799  * \return RTI_TRUE on success, RTI_FALSE on failure
800  *
801  * \sa \ref NETIO_BindResolver_reserve_addresses
802  */
803 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
804 NETIO_BindResolver_release_addresses(NETIO_BindResolver_T* r_table,
805  struct REDA_StringSeq *transport,
806  NETIO_RouteKind_T kind,
807  struct NETIO_AddressSeq *locator_seq);
808 
809 /*ci
810  * \brief Reserve addresses from one or more NETIO interfaces
811  *
812  * \details
813  *
814  * This function reserves addresses. What it means to reserve an address is
815  * defined by the NETIO layer. For example, in the case of UDP it means to
816  * reserve port. While NETIO itself does not make a distiction between
817  * unicast and multicast, this function will sort address into two output
818  * sequences, one for multicast and one for unicast.
819  *
820  * \param[in] r_table The bind table
821  * \param[in] try_index The index to use
822  * \param[in] transport A sequence of registered NETIO interfaces
823  * \param[in] kind The kind of address to reserve
824  * \param[out] reserved_address The reserved addresses
825  * \param[out] mc_locator_seq The reserved multicast addresses
826  * \param[out] uc_locator_seq The reserved unicast addresses
827 
828  * \return RTI_TRUE on success, RTI_FALSE on failure
829  *
830  * \sa \ref NETIO_BindResolver_release_addresses
831  */
832 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
833 NETIO_BindResolver_reserve_addresses(NETIO_BindResolver_T* r_table,
834  RTI_INT32 try_index,
835  struct REDA_StringSeq *transport,
836  NETIO_RouteKind_T kind,
837  struct NETIO_AddressSeq *reserved_address,
838  struct NETIO_AddressSeq *mc_locator_seq,
839  struct NETIO_AddressSeq *uc_locator_seq);
840 
841 /*ci
842  * \brief Unbind from a NETIO address
843  *
844  * \details
845  *
846  * Remove an entry listening to a specific address.
847  *
848  * \param[in] r_table The bind table
849  * \param[in] transport A sequence of addresses to remove
850  * \param[in] kind The kind of address remove binding for
851  * \param[in] from_address The source address being listened too
852  * \param[in] to_intf The destination interface being forward to
853  * \param[in] to_address The destination address to forward to
854  * \param[out] route_existed Whether a bind entry existed or not
855  * \param[out] found_route Whether a bind entry was found or not
856 
857  * \return RTI_TRUE on success, RTI_FALSE on failure
858  *
859  * \sa \ref NETIO_BindResolver_bind
860  */
861 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
862 NETIO_BindResolver_unbind(NETIO_BindResolver_T* r_table,
863  struct REDA_StringSeq *transport,
864  NETIO_RouteKind_T kind,
865  struct NETIO_Address *from_address,
866  NETIO_Interface_T *to_intf,
867  struct NETIO_Address *to_address,
868  RTI_BOOL *route_existed,
869  RTI_BOOL *found_route);
870 
871 /*ci
872  * \brief Bind to an NETIO address
873  *
874  * \details
875  *
876  * \param[in] r_table The bind table
877  * \param[in] transport A sequence of addresses to listen to
878  * \param[in] kind The kind of address to bind to
879  * \param[in] from_address The source address to listened too
880  * \param[in] to_intf The destination interface to forward to
881  * \param[in] to_address The destination address to forward to
882  * \param[in] route_existed Whether a bind entry already existed or not
883  * \param[in] found_route Whether a bind entry was found or not
884 
885  * \return RTI_TRUE on success, RTI_FALSE on failure
886  *
887  * \sa \ref NETIO_BindResolver_unbind
888  */
889 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
890 NETIO_BindResolver_bind(NETIO_BindResolver_T* r_table,
891  struct REDA_StringSeq *transport,
892  NETIO_RouteKind_T kind,
893  struct NETIO_Address *from_address,
894  NETIO_Interface_T *to_intf,
895  struct NETIO_Address *to_address,
896  RTI_BOOL *route_existed,
897  RTI_BOOL *found_route);
898 
899 
900 #ifdef __cplusplus
901 }
902 #endif
903 
904 #endif /* netio_route_h */
905 
906 /*ci @} */
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc