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

RTI Connext DDS Micro Version 2.4.9 Copyright © Thu Dec 15 2016 Real-Time Innovations, Inc