RTI Connext DDS Micro  Version 2.4.8
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
netio_interface.h
Go to the documentation of this file.
1 /*
2  * FILE: netio_interface.h - NETIO 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  * 17dec2015,eh MICRO-1511: add NETIO_PacketInfo.valid_key
14  * 04nov2015,tk MICRO-1505 Reduce memory footprint
15  * 03feb2014,eh MICRO-714 Change ack to acknack
16  * 27jan2014,eh MICRO-714 Add post_event. For reliable reader activity change
17  * 17may2013,eh MICRO-385 Remove unused fns/fields of packet
18  * 25apr2012,tk Written
19  */
20 
21 /*ce
22  * \file
23  * \brief Generic NETIO_Interface functions
24  *
25  * \details
26  * This file contains generic NETIO interface functions. A NETIO_Interface is
27  * a base-class and is typically not instantiated on its own. Derived classes
28  * call methods here to initialize/finalize a base-class. This file also
29  * defines the NETIO interface structure as well as the NETIO_Packet structure
30  * and protocol types.
31  */
32 #ifndef netio_interface_h
33 #define netio_interface_h
34 
35 #ifndef netio_dll_h
36 #include "netio/netio_dll.h"
37 #endif
38 
39 #ifndef osapi_config_h
40 #include "osapi/osapi_config.h"
41 #endif
42 
43 #ifndef osapi_types_h
44 #include "osapi/osapi_types.h"
45 #endif
46 #ifndef osapi_time_h
47 #include "osapi/osapi_time.h"
48 #endif
49 #ifndef reda_sequenceNumber_h
50 #include "reda/reda_sequenceNumber.h"
51 #endif
52 
53 #ifndef db_api_h
54 #include "db/db_api.h"
55 #endif
56 
57 #ifndef rt_rt_h
58 #include "rt/rt_rt.h"
59 #endif
60 
61 #ifndef netio_address_h
62 #include "netio/netio_address.h"
63 #endif
64 
65 #ifdef __cplusplus
66 extern "C"
67 {
68 #endif
69 
70 /*ce
71  * \brief Default name for the automatically registered UDP transport
72  */
73 NETIODllVariable extern const char* const NETIO_DEFAULT_UDP_NAME;
74 
75 /*ce
76  * \brief Default name for the automatically registered INTRA transport
77  */
78 NETIODllVariable extern const char* const NETIO_DEFAULT_INTRA_NAME;
79 
80 /*ce
81  * \brief Default name for the automatically registered RTPS interface
82  */
83 NETIODllVariable extern const char* const NETIO_DEFAULT_RTPS_NAME;
84 
85 /*ci
86  * \defgroup NETIO_PacketClass NETIO Packet API
87  * \ingroup NETIOCommon
88  * \brief NETIO_Packet implementation
89  */
90 /*ci
91  * \addtogroup NETIO_PacketClass
92  * @{
93  */
94 /*
95  * The following constants are passed as part of a NETIO_Packet to
96  * indicate what protocol it originated from. It may be used the receiver
97  */
98 /*ci
99  * \def NETIO_PROTOCOL_INTRA
100  * \brief The packet originates from the INTRA protocol
101  */
102 #define NETIO_PROTOCOL_INTRA (1)
103 
104 /*ci
105  * \def NETIO_PROTOCOL_RTPS
106  * \brief The packet originates from the RTPS protocol
107  */
108 #define NETIO_PROTOCOL_RTPS (2)
109 
110 /*ci
111  * \def NETIO_PROTOCOL_UDP
112  * \brief The packet originates from the UDP protocol
113  */
114 #define NETIO_PROTOCOL_UDP (3)
115 
116 /*
117  * The following constants are passed as part of a NETIO_Packet to
118  * provide meta information about the content (if any).
119  */
120 /*ci
121  * \def NETIO_RTPS_FLAGS_DISPOSE
122  * \brief The packet is a RTPS dispose message, a key is disposed
123  */
124 #define NETIO_RTPS_FLAGS_DISPOSE (0x1)
125 
126 /*ci
127  * \def NETIO_RTPS_FLAGS_UNREGISTER
128  * \brief The packet is a RTPS unregister message, a key has been unregistered
129  * by a writer
130  */
131 #define NETIO_RTPS_FLAGS_UNREGISTER (0x2)
132 
133 /*ci
134  * \def NETIO_RTPS_FLAGS_LIVELINESS
135  * \brief The packet counts as liveliness, even if it does not contain any data
136  */
137 #define NETIO_RTPS_FLAGS_LIVELINESS (0x4)
138 
139 /*ci
140  * \def NETIO_RTPS_FLAGS_INLINEQOS
141  * \brief The packet contains inline Qos as defined by RTPS
142  */
143 #define NETIO_RTPS_FLAGS_INLINEQOS (0x8)
144 
145 /*ci
146  * \def NETIO_RTPS_FLAGS_LOST_DATA
147  * \brief The flag indicates that some packets have been permanently lost
148  * and any attempt to wait for them should be aborted
149  */
150 #define NETIO_RTPS_FLAGS_LOST_DATA (0x10)
151 
152 /*ci
153  * \def NETIO_RTPS_FLAGS_COMMIT_DATA
154  * \brief The flag indicates that even if the packet does not contain
155  * data, it does contain information about which packets can be considered
156  * to be received in order.
157  */
158 #define NETIO_RTPS_FLAGS_COMMIT_DATA (0x20)
159 
160 /*ci
161  * \def NETIO_RTPS_FLAGS_DATA
162  * \brief The flag indicates that the packet contains data
163  */
164 #define NETIO_RTPS_FLAGS_DATA (0x40)
165 
166 /*ci
167  * \def NETIO_RTPS_FLAGS_LAST_WRITE_FOR_SN
168  * \brief
169  */
170 #define NETIO_RTPS_FLAGS_LAST_WRITE_FOR_SN (0x80)
171 
172 /*ci
173  * \def NETIO_RTPS_FLAGS_LITTLE_ENDIAN
174  * \brief The packet payload is in little endian format
175  */
176 #define NETIO_RTPS_FLAGS_LITTLE_ENDIAN (0x100)
177 
178 /*ci
179  * \brief RTPS protocol specific data
180  */
181 struct NETIO_RtpsInfo
182 {
183  /*ci
184  * \brief Pointer to beginning of data-payload
185  */
186  struct REDA_Buffer *inline_data;
187 
188  /*ci
189  * \brief The GUID prefix of the peer
190  */
191  struct NETIO_GuidPrefix guid_prefix;
192 };
193 
194 /*ci
195  * \brief INTRA protocol specific data
196  */
197 struct NETIO_IntraInfo
198 {
199  /*ci
200  * \brief opaque pointer to in-memory representation of data
201  */
202  const void *user_data;
203 
204  /*ci
205  * \brief Pointer to beginning of intra data-payload. Intra data-payload
206  * only contains inline Qos
207  */
208  struct REDA_Buffer *inline_data;
209 };
210 
211 /*ci
212  *\brief NETIO_IntraInfo initializer constant
213  */
214 #define NETIO_IntraInfo_INITIALIZER \
215 { \
216  NULL, /* user_data */ \
217  NULL, /* inline_data */ \
218 }
219 
220 /*ci
221  *\brief Structure containing meta-data about a \ref NETIO_Packet payload
222  */
223 struct NETIO_PacketInfo
224 {
225  /*ci
226  * \brief The SN of the packet. The SN and PacketId is synonymous
227  */
228  struct REDA_SequenceNumber sn;
229 
230  /*ci
231  * \brief The reception time-stamp of the packet
232  */
233  struct OSAPI_NtpTime timestamp;
234 
235  /*ci
236  * \brief Whether the serialized-payload is valid data or not
237  */
238  RTI_UINT8 valid_data;
239 
240  /*ci
241  * \brief Whether the serialized-payload is a valid key or not
242  */
243  RTI_UINT8 valid_key;
244 
245  /*ci
246  * \brief Key for the sample
247  */
248  struct NETIO_Guid instance;
249 
250  /*ci
251  * \brief Flags describing the contents of the payload
252  */
253  RTI_UINT32 rtps_flags;
254 
255  /*ci
256  * \brief The committable_sn means that all SNs up to, but not including
257  * this SN can be committed (made available to the user).
258  */
259  struct REDA_SequenceNumber committable_sn;
260 
261  /*ci
262  * \brief The first_available_sn indicates the first available SN which is
263  * available. It is typically used downstream to boot-strap the
264  * reliability protocol.
265  */
266  struct REDA_SequenceNumber first_available_sn;
267 
268  /*ci
269  * \brief If NETIO_RTPS_FLAGS_LOST_DATA is set, this is the highest sequence
270  * number which has been lost.
271  */
272  struct REDA_SequenceNumber lost_sample_sn;
273 
274  /*ci
275  * \brief If NETIO_RTPS_FLAGS_LOST_DATA is set, this is the total number
276  * of samples that have been lost up to and including lost_sample_sn
277  */
278  RTI_UINT32 lost_sample_count;
279 
280  /*ci
281  * \brief The protocol which produced this packet, it may change as the
282  * packet traverses a NETIO stack
283  */
284  RTI_INT32 protocol_id;
285 
286  /*ci
287  * \brief Protocol specific data based, protocol_id identifies which one
288  * is valid.
289  */
290  struct
291  {
292  struct NETIO_IntraInfo intra_info;
293  struct NETIO_RtpsInfo rtps_data;
294  } protocol_data;
295 };
296 
297 /*ci
298  * \def NETIO_PacketInfo_INITIALIZER
299  * \brief Constant to initialize NETIO_PacketInfo
300  */
301 #define NETIO_PacketInfo_INITIALIZER \
302 { \
303  REDA_SEQUENCE_NUMBER_ZERO, /* sn */\
304  OSAPI_NTP_TIME_ZERO, /* timestamp */ \
305  0, /* valid_data */ \
306  0, /* valid_key */ \
307  NETIO_ADDRESS_GUID_UNKNOWN, /* instance */ \
308  0, /* flags */ \
309  REDA_SEQUENCE_NUMBER_ZERO, /* committable_sn */ \
310  REDA_SEQUENCE_NUMBER_ZERO, /* first_available_sn */ \
311  REDA_SEQUENCE_NUMBER_ZERO, /* lost_sample_sn */ \
312  0, /* lost sample count */ \
313  0, /* protocol_id */\
314  {{NULL,NULL},{NULL,{{0,0,0,0,0,0,0,0,0,0,0,0}}}}\
315 }
316 
317 /*ci
318  * \brief Implementation of the abstract NETIO_Packet type.
319  *
320  * \details
321  * The NETIO layers passed \ref NETIO_Packet structures upstream/downstream.
322  * Any meta-data about the packet must be encapsulated either in the packet
323  * payload or the packet info field.
324  */
325 struct NETIO_Packet
326 {
327  /*ci
328  * \brief The source of the packet, typically the peer address
329  */
330  struct NETIO_Address source;
331 
332  /*ci
333  * \brief The local source of the packet, the address it was received on.
334  */
335  struct NETIO_Address local_source;
336 
337  /*ci
338  * \brief Buffer holding a NETIO_Packet. The buffer must be allocated
339  * and managed outside of this structure. That, is NETIO_Packet
340  * only manages payloads by reference.
341  */
342  char *buffer;
343 
344  /*ci
345  * \brief The maximum number of bytes buffer can hold
346  */
347  RTI_SIZE_T max_length;
348 
349  /*ci
350  * \brief The current position of head cursor
351  */
352  RTI_SIZE_T head_pos;
353 
354  /*ci
355  * \brief The current position of tail cursor
356  */
357  RTI_SIZE_T tail_pos;
358 
359  /*ci
360  * \brief Temporary storage for the current head position so it can later
361  * be restored if a packet payload is traversed multiple times
362  */
363  RTI_SIZE_T saved_head_pos;
364 
365  /*ci
366  * \brief Temporary storage for the current tail position so it can later
367  * be restored if a packet payload is traversed multiple times
368  */
369  RTI_SIZE_T saved_tail_pos;
370 
371  /*ci
372  * \brief Meta data about the packet, refer to \ref NETIO_PacketInfo for
373  * details
374  */
375  struct NETIO_PacketInfo info;
376 
377  /*ci
378  * \brief Sequence of destinations for single packet. Memory owned by sender.
379  */
380  struct NETIO_AddressSeq *dests;
381 
382  /*ci
383  * \brief Application level reference pointer to be able to retrieve
384  * content based on the NETIO_Packet.
385  */
386  void *ref;
387 };
388 
389 /*ci
390  * \brief Abstract NETIO_Packet type
391  */
392 typedef struct NETIO_Packet NETIO_Packet_T;
393 
394 /*ci
395  * \brief Every packet must have a unique ID. Since RTPS SN does not wrap around,
396  * it is safe to use as a unique ID per data-writer. It also avoids having
397  * to map a between packet id to a RTPS SN.
398  */
399 typedef struct REDA_SequenceNumber NETIO_PacketId_T;
400 
401 /*ci
402  * \def NETIO_Packet_INITIALIZER
403  * \brief Constant to initialize a \ref NETIO_Packet
404  */
405 #define NETIO_Packet_INITIALIZER \
406 {\
407  NETIO_Address_INITIALIZER,\
408  NETIO_Address_INITIALIZER,\
409  NULL, /* buffer */\
410  0, /* max_length */\
411  0, /* head_pos */\
412  0, /* tail_pos */\
413  0, /* saved_head_pos */\
414  0, /* saved_tail_pos */\
415  NETIO_PacketInfo_INITIALIZER,\
416  NULL /* dests */,\
417  NULL /* ref */\
418 }
419 
420 /*ci
421  * \brief Adjust the head cursor in the packet payload
422  *
423  * \details
424  *
425  * Adjust the head cursor in the packet payload. A positive value moves the
426  * cursor forward, a negative value backwards.
427  *
428  * \param[in] packet Packet to adjust head cursor in
429  * \param[in] delta Adjustment to make
430  *
431  * \return RTI_TRUE on success, RTI_FALSE on failure
432  */
433 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
434 NETIO_Packet_set_head(NETIO_Packet_T *packet,RTI_INT32 delta);
435 
436 /*ci
437  * \brief Adjust the tail cursor in the packet payload
438  *
439  * \details
440  *
441  * Adjust the tail cursor in the packet payload. A positive value moves the
442  * cursor forward, a negative value backwards.
443  *
444  * \param[in] packet Packet to adjust tail cursor in
445  * \param[in] delta Adjustment to make
446  *
447  * \return RTI_TRUE on success, RTI_FALSE on failure
448  */
449 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
450 NETIO_Packet_set_tail(NETIO_Packet_T *packet,RTI_INT32 delta);
451 
452 /*ci
453  * \brief Get a pointer to the current head
454  *
455  * \details
456  *
457  * Get a pointer to the current head. Note that it can be assumed that the
458  * payload buffer is contiguous.
459  *
460  * \param[in] packet Packet to get the head pointer for
461  *
462  * \return pointer to packet head
463  *
464  * \sa \ref NETIO_Packet_set_head
465  */
466 MUST_CHECK_RETURN NETIODllExport void*
467 NETIO_Packet_get_head(NETIO_Packet_T *packet);
468 
469 /*ci
470  * \brief Get a pointer to the tail head
471  *
472  * \details
473  *
474  * Get a pointer to the current tail. Note that it can be assumed that the
475  * payload buffer is contiguous.
476  *
477  * \param[in] packet Packet to get the tail pointer for
478  *
479  * \return pointer to packet tail
480  *
481  * \sa \ref NETIO_Packet_set_tail
482  */
483 MUST_CHECK_RETURN NETIODllExport void*
484 NETIO_Packet_get_tail(NETIO_Packet_T *packet);
485 
486 /*ci
487  * \brief Initialize a packet with a payload buffer of the given length
488  *
489  * \details
490  *
491  * NETIO_Packet only manipulates payloads by reference. The actual buffer
492  * holding a payload must be managed outside of the packet structure. A
493  * payload buffer is assigned to the packet with the length and an initialized
494  * destination sequence.
495  *
496  * \param[in] packet Packet structure to initialize
497  * \param[in] init_buffer Payload buffer
498  * \param[in] init_length Initial length in bytes of the buffer
499  * \param[in] trailer_length The initial trail position in the payload
500  * \param[in] dest_seq Initialized sequence of destination address for
501  * the packet
502  *
503  * \return RTI_TRUE on successful initialization, RTI_FALSE on failure
504  */
505 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
506 NETIO_Packet_initialize(NETIO_Packet_T *packet,
507  void *init_buffer,
508  RTI_SIZE_T init_length,
509  RTI_SIZE_T trailer_length,
510  struct NETIO_AddressSeq *dest_seq);
511 
512 #ifndef RTI_CERT
513 /*ci
514  * \brief Finalize a packet structure
515  *
516  * \details
517  *
518  * Finalize a packet structure
519  *
520  * \param[in] packet Packet structure to finalize
521  *
522  * \return RTI_TRUE on successful initialization, RTI_FALSE on failure
523  */
524 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
525 NETIO_Packet_finalize(NETIO_Packet_T *packet);
526 #endif /* !RTI_CERT */
527 
528 /*ci
529  * \brief Get pointer to the packet info
530  * *
531  * \param[in] packet Packet structure to get packet info for
532  *
533  * \return Pointer to packet info
534  */
535 MUST_CHECK_RETURN NETIODllExport struct NETIO_PacketInfo*
536 NETIO_Packet_get_info(NETIO_Packet_T *packet);
537 
538 /*ci
539  * \brief Set the source address of a packet
540  *
541  * \param[in] packet Packet to set source address in
542  * \param[in] src Source address of packet
543  */
544 NETIODllExport void
545 NETIO_Packet_set_source(NETIO_Packet_T *packet,struct NETIO_Address *src);
546 
547 /*ci
548  * \brief Get the length the packet payload
549  *
550  * \details
551  *
552  * Get the length the packet payload
553  *
554  * \param[in] packet Packet to return the payload length for
555  *
556  * \return Length of payload
557  */
558 SHOULD_CHECK_RETURN NETIODllExport RTI_SIZE_T
559 NETIO_Packet_get_payload_length(NETIO_Packet_T *packet);
560 
561 /*ci
562  * \brief Save the current head and tail positions
563  *
564  * \details
565  *
566  * Save the current head and tail positions
567  *
568  * \param[in] packet Packet to save the head and tail positions for
569  *
570  *\sa \ref NETIO_Packet_restore_positions
571  *
572  */
573 NETIODllExport void
574 NETIO_Packet_save_positions(NETIO_Packet_T *packet);
575 
576 /*ci
577  * \brief Restore the saved head and tail positions
578  *
579  * \details
580  *
581  * Restore the saved head and tail positions
582  *
583  * \param[in] packet Packet to restore the head and tail positions for
584  *
585  * \sa \ref NETIO_Packet_save_positions
586  */
587 NETIODllExport void
588 NETIO_Packet_restore_positions(NETIO_Packet_T *packet);
589 
590 /*ci
591  * \brief Save the saved head and tail positions to external variables
592  *
593  * \details
594  *
595  * Save the saved head and tail positions to external variables
596  *
597  * \param[in] packet Packet to save the head and tail positions for
598  * \param[out] head Contains current head position for packet on return
599  * \param[out] tail Contains current tail position for packet on return
600  *
601  * \sa \ref NETIO_Packet_restore_positions_from
602  */
603 NETIODllExport void
604 NETIO_Packet_save_positions_to(NETIO_Packet_T *packet,
605  RTI_SIZE_T *head,
606  RTI_SIZE_T *tail);
607 
608 /*ci
609  * \brief Save the saved head and tail positions to external variables
610  *
611  * \details
612  *
613  * Restore the saved head and tail positions from external variables
614  *
615  * \param[in] packet Packet to restore the head and tail positions for
616  * \param[in] head Set head position for packet
617  * \param[in] tail Set tail position for packet
618  *
619  * \sa \ref NETIO_Packet_save_positions_to
620  */
621 NETIODllExport void
622 NETIO_Packet_restore_positions_from(NETIO_Packet_T *packet,
623  RTI_SIZE_T head,
624  RTI_SIZE_T tail);
625 
626 /*ci @} */
627 
628 /*ci
629  * \defgroup NETIO_InterfaceClass NETIO Interface API
630  * \ingroup NETIOModule
631  */
632 /*ci \addtogroup NETIO_InterfaceClass
633  * @{
634  */
635 
636 /*ci
637  * \brief The required number of bytes to convert an component id and
638  * counter to a table name
639  */
640 #define NETIO_TABLE_NAME_SIZE (16)
641 
642 /*ci
643  * \brief NETIO base-class property
644  */
645 struct NETIO_InterfaceProperty
646 {
647  struct RT_ComponentProperty _parent;
648  RTI_INT32 max_routes;
649  RTI_INT32 max_binds;
650 };
651 
652 
653 /*ci
654  * \brief Constant to initialize \ref NETIO_InterfaceProperty
655  */
656 #define NETIO_InterfaceProperty_INITIALIZER \
657 {\
658  RT_ComponentProperty_INITIALIZER,\
659  0,\
660  0\
661 }
662 
663 /*ci
664  * \brief NETIO listener structure
665  *
666  * \details
667  *
668  * All NETIO interface are RT Components, and all NETIO layers derives
669  * the listener class from the RT_ComponentListener.
670  */
671 struct NETIO_InterfaceListener
672 {
673  /*ci
674  * \brief Derived from member
675  */
676  struct RT_ComponentListener _parent;
677 };
678 
679 /*ci
680  * \def NETIO_InterfaceListener_INITIALIZE
681  * \brief Constant to initialize \ref NETIO_InterfaceListener
682  */
683 #define NETIO_InterfaceListener_INITIALIZE \
684 {\
685  RT_ComponentListener_INITIALIZER \
686 }
687 
688 /*ci
689  * \brief Common NETIO Interface factory properties
690  *
691  * \details
692  *
693  * All NETIO layers are implemented as RT components. All NETIO layers
694  * are created from NETIO factories, and all NETIO factories are RT
695  * component factories that share common properties inherited from
696  * this structure.
697  */
698 struct NETIO_InterfaceFactoryProperty
699 {
700  /*ci
701  * \brief derived from member
702  */
703  struct RT_ComponentFactoryProperty _parent;
704 };
705 
706 /*ci
707  * \def NETIO_InterfaceFactoryProperty_INITIALIZER
708  * \brief Constant to initialize a \ref NETIO_InterfaceFactoryProperty
709  */
710 #define NETIO_InterfaceFactoryProperty_INITIALIZER \
711 {\
712  RT_ComponentFactoryProperty_INITIALIZER \
713 }
714 
715 /*ci
716  * \brief Definitions of valid NETIO interface states
717  */
718 typedef enum
719 {
720  /*ci
721  * \brief The interface has been created, but will not send/receive
722  */
723  NETIO_INTERFACESTATE_CREATED,
724 
725  /*ci
726  * \brief The interface is enabled, can send/receive
727  */
728  NETIO_INTERFACESTATE_ENABLED
729 } NETIO_InterfaceState_T;
730 
731 /*ci
732  * \brief Base-class definition for all NETIO interfaces
733  *
734  * \details
735  *
736  * All NETIO layers are RT components and are derived from RT components.
737  * All NETIO layers also share a common base class, \ref NETIO_Interface
738  * and share common properties.
739  */
740 struct NETIO_Interface
741 {
742  /*ci
743  * \brief Derived member
744  */
745  struct RT_Component _parent;
746 
747  /*ci
748  * \brief A route table with addresses to send to
749  */
750  DB_Table_T _rtable;
751 
752  /*ci
753  * \brief A bind table with addresses to listen to
754  */
755  DB_Table_T _btable;
756 
757  /*ci
758  * \brief The local address of the NETIO layer. The use is NETIO
759  * specific. It is not guaranteed to be unique outside of the
760  * stack the layer belongs to.
761  */
762  struct NETIO_Address local_address;
763 
764  /*ci
765  * \brief The current NETIO interface state
766  */
767  NETIO_InterfaceState_T state;
768 };
769 
770 /*ci
771  * \brief Abstract NETIO_Interface type
772  */
773 typedef struct NETIO_Interface NETIO_Interface_T;
774 
775 /*ci
776  * \brief Common bind properties
777  */
778 struct NETIOBindProperty
779 {
780  /*ci
781  * \brief The strength of the bind. Strength is a DDS concept and used to
782  * determine ownerships for instances.
783  */
784  RTI_UINT32 strength;
785 };
786 
787 /*ci
788  * \def NETIOBindProperty_INITIALIZER
789  * \brief Constant to initialize \ref NETIOBindProperty
790  */
791 #define NETIOBindProperty_INITIALIZER \
792 {\
793  0\
794 }
795 
796 /*ci
797  * \brief Common route properties
798  */
799 struct NETIORouteProperty
800 {
801  /*ci
802  * \brief There are no common route properties. This field is present
803  * because some compilers do not allow empty structures.
804  */
805  RTI_INT32 _dummy;
806 };
807 
808 /*ci
809  * \def NETIORouteProperty_INITIALIZER
810  * \brief Constant to initialize \ref NETIORouteProperty
811  */
812 #define NETIORouteProperty_INITIALIZER \
813 {\
814  0 \
815 }
816 
817 /*ci
818  * \brief Generic bind key to listen to a source
819  */
820 struct NETIOBindEntryKey
821 {
822  /*ci
823  * \brief The source address to listen to
824  */
825  struct NETIO_Address source;
826 
827  /*ci
828  * \brief The destination address listening to the source
829  */
830  struct NETIO_Address destination;
831 };
832 
833 /*ci
834  * \brief Generic bind entry
835  */
836 struct NETIOBindEntry
837 {
838  /*ci
839  * \brief The source address to listen to
840  */
841  struct NETIO_Address source;
842 
843  /*ci
844  * \brief The destination address listening to the source
845  */
846  struct NETIO_Address destination;
847 
848  /*ci
849  * \brief The interface to use to listen to the source
850  */
851  NETIO_Interface_T *intf;
852 };
853 
854 /*ci
855  * \brief The state of a route as determined by the protocol layer
856  */
857 typedef enum
858 {
859  /*ci
860  * \brief The route is active, it can send data
861  */
862  NETIO_ROUTESTATE_ACTIVE,
863 
864  /*ci
865  * \brief The route is inactive, it cannot send data
866  */
867  NETIO_ROUTESTATE_INACTIVE
868 } NETIO_RouteState_T;
869 
870 /*ci
871  * \brief Definition of generic route entry key. Typically all route entries
872  * inherit from this key
873  */
874 struct NETIORouteEntryKey
875 {
876  /*ci
877  * \brief The address which an be reached on this route
878  */
879  struct NETIO_Address destination;
880 
881  /*ci
882  * \brief The interface which can reach the destination
883  */
884  NETIO_Interface_T *intf;
885 
886  /*ci
887  * \brief The address of the interface itself (source)
888  */
889  struct NETIO_Address intf_address;
890 };
891 
892 /*ci
893  * \brief Generic route entry, typically all routes inherit from this type
894  */
895 struct NETIORouteEntry
896 {
897  /*ci
898  * \brief The destination address which can be reached
899  */
900  struct NETIO_Address destination;
901 
902  /*ci
903  * \brief The interface which can reach the address
904  */
905  NETIO_Interface_T *intf;
906 
907  /*ci
908  * \brief The address of the interface
909  */
910  struct NETIO_Address intf_address;
911 
912  /*ci
913  * \brief State of the route entry
914  */
915  NETIO_RouteState_T state;
916 };
917 
918 /*ci
919  * \brief Discriminator for status changes detected at protocol level
920  */
921 typedef enum
922 {
923  /*ci
924  * \brief A NETIO layer has determined that the peer is inactive
925  */
926  NETIO_EVENTKIND_INACTIVE_PEER,
927 
928  /*ci
929  * \brief A NETIO layer has determined that the peer is active
930  */
931  NETIO_EVENTKIND_ACTIVE_PEER
932 } NETIO_EventKind_T;
933 
934 /*ci
935  * \brief Structure to signal protocol level status changes upstream/downstream
936  */
937 struct NETIO_Event_PeerActivity
938 {
939  /*ci
940  * \brief Address of peer layer with the activity change
941  */
942  struct NETIO_Address peer_addr;
943 
944  /*ci
945  * \brief Total number of times the peer has become inactive
946  */
947  RTI_INT32 inactive_total;
948 
949  /*ci
950  * \brief Change in inactivity since last time signaled
951  */
952  RTI_INT32 inactive_change;
953 
954  /*ci
955  * \brief Total number of times the peer has become active
956  */
957  RTI_INT32 active_total;
958 
959  /*ci
960  * \brief Change in activity since last time signaled
961  */
962  RTI_INT32 active_change;
963 };
964 
965 /*ci
966  * \brief Generic event structure to signal status changes detected at the
967  * protocol level
968  */
969 struct NETIO_Event
970 {
971  /*ci
972  * \brief Event discriminator
973  */
974  NETIO_EventKind_T kind;
975 
976  /*ci
977  * \brief Additional event information
978  */
979  union
980  {
981  struct NETIO_Event_PeerActivity peer_activity;
982  } value;
983 };
984 
985 struct NETIO_InterfaceI;
986 
987 /*ci
988  * \brief Create a table name with a consistent format for NETIO route
989  * and bind tables
990  *
991  * \param[out] tbl_name The resulting table name is placed here. It is assumed
992  * that the buffer is long enough and is should be at least
993  * NETIO_TABLE_NAME_SIZE bytes large.
994  * \param[in] id The name of the factory owning the table
995  * \param[in] suffix Single character identifying the type of table
996  * \param[in] instance The instance the table is created from
997  *
998  */
999 NETIODllExport void
1000 NETIO_Interface_Table_name_from_id(char *tbl_name,
1001  union RT_ComponentFactoryId *id,
1002  char suffix,
1003  RTI_INT32 instance);
1004 
1005 /*ci
1006  * \brief Initialize a NETIO_Interface base-class
1007  *
1008  * \param[in] netio The netio interface to initialize
1009  * \param[in] netio_intf Pointer to the NETIO interface implementation
1010  * \param[in] property The NETIO properties
1011  * \param[in] listener The NETIO listener
1012  *
1013  * \return This function always returns RTI_TRUE
1014  *
1015  * \sa \ref NETIO_Interface_finalize
1016  */
1017 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
1018 NETIO_Interface_initialize(struct NETIO_Interface *netio,
1019  struct NETIO_InterfaceI *netio_intf,
1020  const struct NETIO_InterfaceProperty *const property,
1021  const struct NETIO_InterfaceListener *const listener);
1022 
1023 #ifndef RTI_CERT
1024 /*ci
1025  * \brief Finalize a NETIO_Interface base-class
1026  *
1027  * \param[in] netio The netio interface to finalize
1028  *
1029  * \return RTI_TRUE on success, RTI_FALSE on failure
1030  *
1031  * \sa \ref NETIO_Interface_initialize
1032  */
1033 SHOULD_CHECK_RETURN NETIODllExport RTI_BOOL
1034 NETIO_Interface_finalize(struct NETIO_Interface *netio);
1035 #endif /* !RTI_CERT */
1036 
1037 /*ci
1038  * \brief Implementation of required database function to compare
1039  * NETIO route records stored in a database
1040  *
1041  * \details
1042  *
1043  * This function is installed as the compare function for the
1044  * tables holding NETIO_Route records
1045  *
1046  * \param[in] flags Passed in from the database
1047  * \param[in] op1 Existing database record
1048  * \param[in] op2 New database record or key depending on flags
1049  *
1050  * \return positive integer if op1 is greater than op2,
1051  * negative integer if op1 is less than op2,
1052  * zero if op1 is equal to op2
1053  */
1054 MUST_CHECK_RETURN NETIODllExport RTI_INT32
1055 NETIO_Interface_compare_route(RTI_INT32 flags,
1056  const DB_Record_T op1, void *op2);
1057 
1058 /*ci
1059  * \brief Implementation of required database function to compare
1060  * NETIO route records stored in a database
1061  *
1062  * \details
1063  *
1064  * This function is installed as the compare function for the
1065  * tables holding NETIO_Bind records
1066  *
1067  * \param[in] flags Passed in from the database
1068  * \param[in] op1 Existing database record
1069  * \param[in] op2 New database record or key depending on flags
1070  *
1071  * \return positive integer if op1 is greater than op2,
1072  * negative integer if op1 is less than op2,
1073  * zero if op1 is equal to op2
1074  */
1075 MUST_CHECK_RETURN NETIODllExport RTI_INT32
1076 NETIO_Interface_compare_bind(RTI_INT32 flags,
1077  const DB_Record_T op1, void *op2);
1078 
1079 /*ci
1080  * \brief Definition of the \ref NETIO_InterfaceI send method
1081  *
1082  * \param[in] self NETIO interface to send from
1083  * \param[in] source The source interface for the packet
1084  * \param[in] destination The destination address for the packet
1085  * \param[in] packet The packet to send
1086  *
1087  * \return RTI_TRUE on success, RTI_FALSE on failure
1088  *
1089  * \sa \ref NETIO_Interface_send, \ref NETIO_InterfaceI
1090  */
1091 FUNCTION_MUST_TYPEDEF(
1092 RTI_BOOL
1093 (*NETIO_Interface_sendFunc)(NETIO_Interface_T *self,
1094  struct NETIO_Interface *source,
1095  struct NETIO_Address *destination,
1096  NETIO_Packet_T *packet)
1097 )
1098 
1099 /*ci
1100  * \brief Definition of the \ref NETIO_InterfaceI receive method
1101  *
1102  * \param[in] netio_intf NETIO interface to receive in
1103  * \param[in] src_addr The source address of the packet
1104  * \param[in] dst_addr The destination address for the packet
1105  * \param[in] packet The forwarded packet from downstream
1106  *
1107  * \return RTI_TRUE on success, RTI_FALSE on failure
1108  *
1109  * \sa \ref NETIO_Interface_receive, \ref NETIO_InterfaceI
1110  */
1111 FUNCTION_MUST_TYPEDEF(
1112 RTI_BOOL
1113 (*NETIO_Interface_receiveFunc)(NETIO_Interface_T *netio_intf,
1114  struct NETIO_Address *src_addr,
1115  struct NETIO_Address *dst_addr,
1116  NETIO_Packet_T *packet)
1117 )
1118 
1119 /*ci
1120  * \brief Definition of the \ref NETIO_InterfaceI acknack method
1121  *
1122  * \param[in] self The NETIO interface receiving the acknack
1123  * \param[in] source The peer source address of the acknack
1124  * \param[in] packet_id The packet_id/SN of the NETIO_Packet being acked/nacked
1125  * \param[in] nack RTI_TRUE if this is a negative acknowledgment
1126  *
1127  * \return RTI_TRUE on success, RTI_FALSE on failure
1128  *
1129  * \sa \ref NETIO_Interface_acknack, \ref NETIO_InterfaceI
1130  */
1131 FUNCTION_MUST_TYPEDEF(
1132 RTI_BOOL
1133 (*NETIO_Interface_acknackFunc)(NETIO_Interface_T *self,
1134  struct NETIO_Address *source,
1135  NETIO_PacketId_T *packet_id,
1136  RTI_BOOL nack)
1137 )
1138 
1139 /*ci
1140  * \brief Definition of the \ref NETIO_InterfaceI request method
1141  *
1142  * \param[in] self The NETIO interface receiving the request
1143  * \param[in] source The peer source address of the request
1144  * \param[in] dest The peer destination address of the request
1145  * \param[out] packet The requested packet if it existed, NULL
1146  * otherwise
1147  * \param[in] packet_id The packet_id/SN of the NETIO_Packet being
1148  * requested
1149  * \param[in] actual_packet_id The if packet_id is not available, the next
1150  * available SN/packet_id
1151  *
1152  * \return RTI_TRUE on success, RTI_FALSE on failure
1153  *
1154  * \sa \ref NETIO_Interface_return_loan, \ref NETIO_InterfaceI
1155  */
1156 FUNCTION_MUST_TYPEDEF(
1157 RTI_BOOL
1158 (*NETIO_Interface_requestFunc)(NETIO_Interface_T *self,
1159  struct NETIO_Address *source,
1160  struct NETIO_Address *dest,
1161  NETIO_Packet_T **packet,
1162  NETIO_PacketId_T *packet_id,
1163  NETIO_PacketId_T *actual_packet_id)
1164 )
1165 
1166 /*ci
1167  * \brief Definition of the \ref NETIO_InterfaceI return_loan method
1168  *
1169  * \param[in] self The NETIO interface receiving the request
1170  * \param[in] source The peer source address of the loan
1171  * \param[in] packet The packet being returned
1172  * \param[in] packet_id The packet_id/SN of the NETIO_Packet being returned
1173  * requested
1174  *
1175  * \return RTI_TRUE on success, RTI_FALSE on failure
1176  *
1177  * \sa \ref NETIO_Interface_request, \ref NETIO_InterfaceI
1178  */
1179 FUNCTION_MUST_TYPEDEF(
1180 RTI_BOOL
1181 (*NETIO_Interface_return_loanFunc)(NETIO_Interface_T *self,
1182  struct NETIO_Address *source,
1183  NETIO_Packet_T *packet,
1184  NETIO_PacketId_T *packet_id)
1185 )
1186 
1187 /*ci
1188  * \brief Definition of the \ref NETIO_InterfaceI xmit_remove method
1189  *
1190  * \param[in] self NETIO interface to cancel a transmit on
1191  * \param[in] destination The destination address of the packet
1192  * \param[in] packet_id The packet_id/SN of the NETIO_Packet to cancel
1193  *
1194  * \return RTI_TRUE on success, RTI_FALSE on failure
1195  *
1196  * \sa \ref NETIO_Interface_xmit_remove, \ref NETIO_InterfaceI
1197  */
1198 FUNCTION_MUST_TYPEDEF(
1199 RTI_BOOL
1200 (*NETIO_Interface_xmit_removeFunc)(NETIO_Interface_T *self,
1201  struct NETIO_Address *destination,
1202  NETIO_PacketId_T *packet_id)
1203 )
1204 
1205 /*ci
1206  * \brief Definition of the \ref NETIO_InterfaceI add_route method
1207  *
1208  * \param[in] self NETIO interface to add the route to
1209  * \param[in] dst_addr The destination address for the route
1210  * \param[in] via_intf The downstream interface
1211  * \param[in] via_addr The address to pass to the downstream interface
1212  * \param[in] property The route property
1213  * \param[in] existed Whether the route already existed
1214  *
1215  * \sa \ref NETIO_Interface_add_route, \ref NETIO_InterfaceI
1216  */
1217 FUNCTION_MUST_TYPEDEF(
1218 RTI_BOOL
1219 (*NETIO_Interface_add_routeFunc)(NETIO_Interface_T *self,
1220  struct NETIO_Address *dst_addr,
1221  NETIO_Interface_T *via_intf,
1222  struct NETIO_Address *via_addr,
1223  struct NETIORouteProperty *property,
1224  RTI_BOOL *existed)
1225 )
1226 
1227 /*ci
1228  * \brief Definition of the \ref NETIO_InterfaceI delete_route method
1229  *
1230  * \param[in] self NETIO interface to delete the route from
1231  * \param[in] dst_addr The destination address for the route
1232  * \param[in] via_intf The downstream interface
1233  * \param[in] via_addr The address to pass to the downstream interface
1234  * \param[out] existed Whether the route existed
1235  *
1236  * \return RTI_TRUE on success, RTI_FALSE on failure. Note that is it not
1237  * considered a failure if the interface didn't exist.
1238  *
1239  * \sa \ref NETIO_Interface_delete_route, \ref NETIO_InterfaceI
1240  */
1241 FUNCTION_MUST_TYPEDEF(
1242 RTI_BOOL
1243 (*NETIO_Interface_delete_routeFunc)(NETIO_Interface_T *self,
1244  struct NETIO_Address *dst_addr,
1245  NETIO_Interface_T *via_intf,
1246  struct NETIO_Address *via_addr,
1247  RTI_BOOL *existed)
1248 )
1249 
1250 /*ci
1251  * \brief Definition of the \ref NETIO_InterfaceI bind method
1252  *
1253  * \param[in] netio_intf NETIO interface to bind
1254  * \param[in] src_addr The address to bind to
1255  * \param[in] property The property to use for the bind
1256  * \param[out] existed Whether a previous bind existed or not
1257  *
1258  * \return RTI_TRUE on success, RTI_FALSE on failure.
1259  *
1260  * \sa \ref NETIO_Interface_bind, \ref NETIO_InterfaceI
1261  */
1262 FUNCTION_MUST_TYPEDEF(
1263 RTI_BOOL
1264 (*NETIO_Interface_bindFunc)(NETIO_Interface_T *netio_intf,
1265  struct NETIO_Address *src_addr,
1266  struct NETIOBindProperty *property,
1267  RTI_BOOL *existed)
1268 )
1269 
1270 /*ci
1271  * \brief Definition of the \ref NETIO_InterfaceI unbind method
1272  *
1273  * \param[in] netio_intf NETIO interface to unbind
1274  * \param[in] src_addr The address to unbind from
1275  * \param[in] dst_intf Interface to unbind from
1276  * \param[out] existed Whether a bind existed or not
1277  *
1278  * \return RTI_TRUE on success, RTI_FALSE on failure.
1279  *
1280  * \sa \ref NETIO_Interface_unbind, \ref NETIO_InterfaceI
1281  */
1282 FUNCTION_MUST_TYPEDEF(
1283 RTI_BOOL
1284 (*NETIO_Interface_unbindFunc)(NETIO_Interface_T *netio_intf,
1285  struct NETIO_Address *src_addr,
1286  NETIO_Interface_T *dst_intf,
1287  RTI_BOOL *existed)
1288 )
1289 
1290 /*ci
1291  * \brief Definition of the \ref NETIO_InterfaceI bind_external method
1292  *
1293  * \param[in] src_intf NETIO interface to bind to upstream interface
1294  * \param[in] src_addr The address to bind to
1295  * \param[in] dst_intf The upstream interface
1296  * \param[in] dst_addr The address to pass to the upstream interface
1297  * \param[in] property The properties for the bind
1298  * \param[out] existed Whether a previous bind already existed for this entry
1299  *
1300  * \return RTI_TRUE on success, RTI_FALSE on failure.
1301  *
1302  * \sa \ref NETIO_Interface_bind_external, \ref NETIO_InterfaceI
1303  */
1304 FUNCTION_MUST_TYPEDEF(
1305 RTI_BOOL
1306 (*NETIO_Interface_bind_externalFunc)(NETIO_Interface_T *src_intf,
1307  struct NETIO_Address *src_addr,
1308  NETIO_Interface_T *dst_intf,
1309  struct NETIO_Address *dst_addr,
1310  struct NETIOBindProperty *property,
1311  RTI_BOOL *existed)
1312 )
1313 
1314 /*ci
1315  * \brief Definition of the \ref NETIO_InterfaceI unbind_external method
1316  *
1317  * \param[in] src_intf NETIO interface to unbind from upstream interface
1318  * \param[in] src_addr The address to unbind from
1319  * \param[in] dst_intf The upstream interface
1320  * \param[in] dst_addr The address to passed to the upstream interface
1321  * \param[out] existed Whether a previous bind already existed for this entry
1322  *
1323  * \return RTI_TRUE on success, RTI_FALSE on failure.
1324  *
1325  * \sa \ref NETIO_Interface_unbind_external, \ref NETIO_InterfaceI
1326  */
1327 FUNCTION_MUST_TYPEDEF(
1328 RTI_BOOL
1329 (*NETIO_Interface_unbind_externalFunc)(NETIO_Interface_T *src_intf,
1330  struct NETIO_Address *src_addr,
1331  NETIO_Interface_T *dst_intf,
1332  struct NETIO_Address *dst_addr,
1333  RTI_BOOL *existed)
1334 )
1335 
1336 /*ci
1337  * \brief Definition of the \ref NETIO_InterfaceI get_external_interface method
1338  *
1339  * \param[in] netio_intf NETIO interface to get the external interface for
1340  * \param[in] src_addr The address to send to
1341  * \param[out] dst_intf The interface to use when sending to the address
1342  * \param[out] dst_addr The destination address to use when forwarding
1343  * packets to the destination interface
1344  *
1345  * \return RTI_TRUE on success, RTI_FALSE on failure.
1346  *
1347  * \sa \ref NETIO_Interface_get_external_interface, \ref NETIO_InterfaceI
1348  */
1349 FUNCTION_MUST_TYPEDEF(
1350 RTI_BOOL
1351 (*NETIO_Interface_get_external_interfaceFunc)(NETIO_Interface_T *netio_intf,
1352  struct NETIO_Address *src_addr,
1353  NETIO_Interface_T **dst_intf,
1354  struct NETIO_Address *dst_addr)
1355 )
1356 
1357 /*ci
1358  * \brief Definition of the \ref NETIO_InterfaceI reserve_address method
1359  *
1360  * \param[in] self NETIO interface to reserve addresses on
1361  * \param[in] req_address List of requested addresses
1362  * \param[inout] rsvd_address The downstream interface
1363  * \param[in] property Properties to use to listen on the reserved addresses
1364  *
1365  * \return RTI_TRUE on success, RTI_FALSE on failure.
1366  *
1367  * \sa \ref NETIO_Interface_reserve_address, \ref NETIO_InterfaceI
1368  */
1369 FUNCTION_MUST_TYPEDEF(
1370 RTI_BOOL
1371 (*NETIO_Interface_reserve_addressFunc)(NETIO_Interface_T *self,
1372  struct NETIO_AddressSeq *req_address,
1373  struct NETIO_AddressSeq *rsvd_address,
1374  struct NETIOBindProperty *property)
1375 )
1376 
1377 /*ci
1378  * \brief Definition of the \ref NETIO_InterfaceI release_address method
1379  *
1380  * \param[in] self NETIO interface to release addresses on
1381  * \param[in] src_addr Address to release
1382  *
1383  * \return RTI_TRUE on success, RTI_FALSE on failure.
1384  *
1385  * \sa \ref NETIO_Interface_release_address, \ref NETIO_InterfaceI
1386  */
1387 FUNCTION_MUST_TYPEDEF(
1388 RTI_BOOL
1389 (*NETIO_Interface_release_addressFunc)(NETIO_Interface_T *self,
1390  struct NETIO_Address *src_addr)
1391 )
1392 
1393 /*ci
1394  * \brief Definition of the \ref NETIO_InterfaceI set_state method
1395  *
1396  * \param[in] netio_intf NETIO interface to set state on
1397  * \param[in] state New state
1398  *
1399  * \return RTI_TRUE on success, RTI_FALSE on failure.
1400  *
1401  * \sa \ref NETIO_Interface_set_state, \ref NETIO_InterfaceI
1402  */
1403 FUNCTION_MUST_TYPEDEF(
1404 RTI_BOOL
1405 (*NETIO_Interface_set_stateFunc)(NETIO_Interface_T *netio_intf,
1406  NETIO_InterfaceState_T state)
1407 )
1408 
1409 /*ci
1410  * \brief Definition of the \ref NETIO_InterfaceI resolve_adddress method
1411  *
1412  * \param[out] netio_intf Interface
1413  * \param[in] address_string Address to convert
1414  * \param[out] address_value Converted address on success
1415  * \param[out] is_invalid Whether the address is valid or not
1416  *
1417  * \return RTI_TRUE on success, RTI_FALSE on failure.
1418  *
1419  * \sa \ref NETIO_Interface_resolve_adddress, \ref NETIO_InterfaceI
1420  */
1421 FUNCTION_MUST_TYPEDEF(
1422 RTI_BOOL
1423 (*NETIO_Interface_resolve_adddressFunc)(NETIO_Interface_T *netio_intf,
1424  const char *address_string,
1425  struct NETIO_Address *address_value,
1426  RTI_BOOL *invalid)
1427 )
1428 
1429 /*ci
1430  * \brief Definition of the \ref NETIO_InterfaceI get_route_table method
1431  *
1432  * \param[in] netio_intf The NETIO interface
1433  * \param[inout] address Sequence of NETIO addresses this interface understands
1434  * \param[inout] netmask Sequence of the corresponding netmasks
1435  *
1436  * \return RTI_TRUE on success, RTI_FALSE on failure.
1437  *
1438  * \sa \ref NETIO_Interface_get_route_table, \ref NETIO_InterfaceI
1439  */
1440 FUNCTION_MUST_TYPEDEF(
1441 RTI_BOOL
1442 (*NETIO_Interface_get_route_tableFunc)(NETIO_Interface_T *netio_intf,
1443  struct NETIO_AddressSeq *address,
1444  struct NETIO_NetmaskSeq *netmask)
1445 )
1446 
1447 /*ci
1448  * \brief Definition of the \ref NETIO_InterfaceI post_event method
1449  *
1450  * \param[in] self The datawriter interface the event occurred on
1451  * \param[in] src_intf The source of the event
1452  * \param[in] event The NETIO event
1453  *
1454  * \return RTI_TRUE if the event was handled successfully, RTI_FALSE if not
1455  *
1456  * \sa \ref NETIO_Interface_post_event, \ref NETIO_InterfaceI
1457  */
1458 FUNCTION_MUST_TYPEDEF(
1459 RTI_BOOL
1460 (*NETIO_Interface_post_eventFunc)(NETIO_Interface_T *self,
1461  NETIO_Interface_T *src_intf,
1462  struct NETIO_Event *event)
1463 )
1464 
1465 /*ci
1466  * \brief Definition of the \ref NETIO_InterfaceI lookup_route method
1467  *
1468  * \details
1469  *
1470  * Check if a NETIO interface has a route to a specific destination
1471  *
1472  * \param[in] netio_intf NETIO interface to get the external interface for
1473  * \param[in] dst_reader The address to send to
1474  * \param[in] via_intf The interface to use
1475  * \param[in] via_address The interface address to use
1476  * \param[out] route_exists RTI_TRUE if the route existed, RTI_FALSE if not
1477  *
1478  * \return RTI_TRUE if the event was handled successfully, RTI_FALSE if not
1479  */
1480 FUNCTION_MUST_TYPEDEF(
1481 RTI_BOOL
1482 (*NETIO_Interface_lookup_routeFunc)(struct NETIO_Interface *netio_intf,
1483  struct NETIO_Address *dst_reader,
1484  struct NETIO_Interface *via_intf,
1485  struct NETIO_Address *via_address,
1486  RTI_BOOL *route_exists)
1487 )
1488 
1489 /*ci
1490  * \brief NETIO_InterfaceI interface required to be implemented by all NETIO
1491  * layers.
1492  */
1493 struct NETIO_InterfaceI
1494 {
1495  /*ci
1496  * \brief Base-class interface
1497  */
1498  struct RT_ComponentI _parent;
1499 
1500  /*ci
1501  * \brief Method to send packets to one or more destinations
1502  */
1503  NETIO_Interface_sendFunc send;
1504 
1505  /*ci
1506  * \brief Method to ACK/NACK a packet upstream
1507  */
1508  NETIO_Interface_acknackFunc acknack;
1509 
1510  /*ci
1511  * \brief Method to request packet upstream
1512  */
1513  NETIO_Interface_requestFunc request;
1514 
1515  NETIO_Interface_return_loanFunc return_loan;
1516 
1517  /*ci
1518  * \brief Method to cancel a transmission downstream
1519  */
1520  NETIO_Interface_xmit_removeFunc xmit_remove;
1521 
1522  /*ci
1523  * \brief Method to add a destination route to an interface
1524  */
1525  NETIO_Interface_add_routeFunc add_route;
1526 
1527  /*ci
1528  * \brief Method to remove a route to a destination from an interface
1529  */
1530  NETIO_Interface_delete_routeFunc delete_route;
1531 
1532  /*ci
1533  * \brief Method to reserve addresses to listen to on an interface
1534  */
1535  NETIO_Interface_reserve_addressFunc reserve_address;
1536 
1537  /*ci
1538  * \brief Method to start listening for data from a peer interface
1539  */
1540  NETIO_Interface_bindFunc bind;
1541 
1542  /*ci
1543  * \brief Method to stop listening for data from a peer interface
1544  */
1545  NETIO_Interface_unbindFunc unbind;
1546 
1547  /*ci
1548  * \brief Method to forward a packet to an interface upstream
1549  */
1550  NETIO_Interface_receiveFunc receive;
1551 
1552  /*ci
1553  * \brief Method to get the interface to forward packets to from an
1554  * downstream interface
1555  */
1556  NETIO_Interface_get_external_interfaceFunc get_external_interface;
1557 
1558  /*ci
1559  * \brief Method to add a path from an interface to an upstream interface
1560  */
1561  NETIO_Interface_bind_externalFunc bind_external;
1562 
1563  /*ci
1564  * \brief Method to remove a path from an interface to an upstream interface
1565  */
1566  NETIO_Interface_unbind_externalFunc unbind_external;
1567 
1568  /*ci
1569  * \brief Method to set the state of an interface
1570  */
1571  NETIO_Interface_set_stateFunc set_state;
1572 
1573  /*ci
1574  * \brief Method to release addresses to listen to on an interface
1575  */
1576  NETIO_Interface_release_addressFunc release_address;
1577 
1578  /*ci
1579  * \brief Method to query an interface if it can resolve an address or not
1580  */
1581  NETIO_Interface_resolve_adddressFunc resolve_address;
1582 
1583  /*ci
1584  * \brief Method to query an interface for what addresses it can forward
1585  * packets to
1586  */
1587  NETIO_Interface_get_route_tableFunc get_route_table;
1588 
1589  /*ci
1590  * \brief Method to post external events to an interface
1591  */
1592  NETIO_Interface_post_eventFunc post_event;
1593 
1594  /*ci
1595  * \brief Method to lookup if a route exists to a destination
1596  */
1597  NETIO_Interface_lookup_routeFunc lookup_route;
1598 };
1599 
1600 /*ci
1601  * \brief Wrapper to call of the NETIO_InterfaceFactory->create_component
1602  *
1603  * \param[in] f_ The NETIO interface factory
1604  * \param[in] p_ The property
1605  * \param[in] l_ The listener
1606  */
1607 #define NETIO_InterfaceFactory_create_component(f_,p_,l_) \
1608  (NETIO_Interface_T*)((f_)->intf->create_component(\
1609  (f_),p_,l_))
1610 
1611 /*ci
1612  * \brief Wrapper to call of the NETIO_InterfaceFactory->delete_component
1613  *
1614  * \param[in] f_ The NETIO interface factory
1615  * \param[in] intf_ The NETIO interface to delete
1616  */
1617 #define NETIO_InterfaceFactory_delete_component(f_,intf_) \
1618  (f_)->intf->delete_component(f_,(&(intf_)->_parent))
1619 
1620 /*ci
1621  * \brief Wrapper to call the \ref NETIO_InterfaceI::send
1622  *
1623  * \details
1624  * Forward a packet from a source interface to a destination
1625  *
1626  * \param[in] self_ NETIO interface to send from
1627  * \param[in] src_intf_ The source interface for the packet
1628  * \param[in] dst_addr_ The destination address for the packet
1629  * \param[in] pkt_ The packet to send
1630  *
1631  * \return RTI_TRUE on success, RTI_FALSE on failure
1632  */
1633 #define NETIO_Interface_send(self_,src_intf_,dst_addr_,pkt_) \
1634  ((struct NETIO_InterfaceI*)(\
1635  (self_)->_parent._intf))->send(self_,src_intf_,dst_addr_,pkt_)
1636 
1637 /*ci
1638  * \brief Wrapper to call \ref NETIO_InterfaceI::acknack
1639  *
1640  * \details
1641  * An acknack is processed for a peer. If all peers who should receive this
1642  * sample has acked it, then it can be ack'ed in the queue and is up for removal
1643  * A peer (source parameter) must acknack a sample at most once.
1644  *
1645  * \param[in] self_ The NETIO interface receiving the acknack
1646  * \param[in] src_intf_ The peer source address of the acknack
1647  * \param[in] sn_ The packet_id/SN of the NETIO_Packet being acked/nacked
1648  * \param[in] nack_ RTI_TRUE if this is a negative acknowledgment
1649  *
1650  * \return RTI_TRUE on success, RTI_FALSE on failure
1651  */
1652 #define NETIO_Interface_acknack(self_,src_intf_,sn_,nack_) \
1653  ((struct NETIO_InterfaceI*)(\
1654  (self_)->_parent._intf))->acknack(self_,src_intf_,sn_,nack_)
1655 
1656 /*ci
1657  * \brief Wrapper to call \ref NETIO_InterfaceI::request
1658  *
1659  * \details
1660  * Request a SN from source interface and destination address.
1661  * if SN is not available nextpktid_ contains the next available
1662  * SN.
1663  *
1664  * \param[in] self_ The NETIO interface receiving the request
1665  * \param[in] src_ The peer source address of the request
1666  * \param[in] dst_ The peer destination address of the request
1667  * \param[in] pkt_ The requested packet if it existed, NULL
1668  * otherwise
1669  * \param[in] pktid_ The packet_id/SN of the NETIO_Packet being
1670  * requested
1671  * \param[in] nextpktid_ The if packet_id is not available, the next
1672  * available SN/packet_id
1673  *
1674  * \return RTI_TRUE on success, RTI_FALSE on failure
1675  */
1676 #define NETIO_Interface_request(self_,src_,dst_,pkt_,pktid_,nextpktid_) \
1677  ((struct NETIO_InterfaceI*)(\
1678  (self_)->_parent._intf))->request(self_,src_,dst_,pkt_,pktid_,nextpktid_)
1679 
1680 /*ci
1681  * \brief Wrapper to call \ref NETIO_InterfaceI::return_loan method
1682  *
1683  * \param[in] self_ The NETIO interface receiving the request
1684  * \param[in] src_ The peer source address of the loan
1685  * \param[in] pkt_ The packet being returned
1686  * \param[in] pkt_id_ The packet_id/SN of the NETIO_Packet being returned
1687  * requested
1688  *
1689  * \return RTI_TRUE on success, RTI_FALSE on failure
1690  *
1691  * \sa \ref NETIO_Interface_request, \ref NETIO_InterfaceI
1692  */
1693 #define NETIO_Interface_return_loan(self_,src_,pkt_,pkt_id_) \
1694  ((struct NETIO_InterfaceI*)(\
1695  (self_)->_parent._intf))->return_loan(self_,src_,pkt_,pkt_id_)
1696 
1697 /*ci
1698  * \brief Wrapper to call \ref NETIO_InterfaceI::xmit_remove
1699  *
1700  * \details
1701  * Inform all downstream interfaces all attempts at delivering a packet
1702  * should be cancelled.
1703  *
1704  * \param[in] self_ NETIO interface to cancel a transmit on
1705  * \param[in] dst_ The destination address of the packet
1706  * \param[in] pkt_id_ The packet_id/SN of the NETIO_Packet to cancel
1707  *
1708  * \return RTI_TRUE on success, RTI_FALSE on failure
1709  */
1710 #define NETIO_Interface_xmit_remove(self_,dst_,pkt_id_) \
1711  ((struct NETIO_InterfaceI*)(\
1712  (self_)->_parent._intf))->xmit_remove(self_,dst_,pkt_id_)
1713 
1714 /*ci
1715  * \brief Wrapper to call \ref NETIO_InterfaceI::add_route
1716  *
1717  * \details
1718  * Add route to a matching peer to be reached via a downstream interface
1719  * using the specified downstream address.
1720  *
1721  * \param[in] self_ NETIO interface to add the route to
1722  * \param[in] dst_ The destination address for the route
1723  * \param[in] intf_ The downstream interface
1724  * \param[in] intf_addr_ The address to pass to the downstream interface
1725  * \param[in] prop_ The route property
1726  * \param[in] ex_ Whether the route already existed
1727  *
1728  * \return RTI_TRUE on success, RTI_FALSE on failure
1729  */
1730 #define NETIO_Interface_add_route(self_,dst_,intf_,intf_addr,prop_,ex_) \
1731  ((struct NETIO_InterfaceI*)(\
1732  (self_)->_parent._intf))->add_route(self_,dst_,intf_,intf_addr,prop_,ex_)
1733 
1734 /*ci
1735  * \brief Wrapper to call \ref NETIO_InterfaceI::delete_route
1736  *
1737  * \details
1738  * Remove a route to a peer, either because it no longer matches or that the
1739  * peer has been deleted.
1740  *
1741  * \param[in] self_ NETIO interface to add the route to
1742  * \param[in] dst_ The destination address for the route
1743  * \param[in] intf_ The downstream interface
1744  * \param[in] intf_addr_ The address to pass to the downstream interface
1745  * \param[out] exist_ Whether the route existed
1746  *
1747  * \return RTI_TRUE on success, RTI_FALSE on failure. Note that is it not
1748  * considered a failure if the interface didn't exist.
1749  */
1750 #define NETIO_Interface_delete_route(self_,dst_,intf_,intf_addr_,exist_) \
1751  ((struct NETIO_InterfaceI*)(\
1752  (self_)->_parent._intf))->delete_route(self_,dst_,intf_,intf_addr_,exist_)
1753 
1754 /*ci
1755  * \brief Wrapper to call \ref NETIO_InterfaceI::reserve_address
1756  *
1757  * \details
1758  * Reserve addresses on an interface to listen to using the requested addresses
1759  * as the starting point. The resulting addresses may be fewer than requested,
1760  * even 0 is legal.
1761  *
1762  * \param[in] self_ NETIO interface to reserve addresses on
1763  * \param[in] src_addr_ List of requested addresses
1764  * \param[inout] pub_addr_ List of addresses that are reserved
1765  * \param[in] prop_ Properties to use to listen on the reserved addresses
1766  *
1767  * \return RTI_TRUE on success, RTI_FALSE on failure.
1768  */
1769 #define NETIO_Interface_reserve_address(self_,src_addr_,pub_addr_,prop_)\
1770  ((struct NETIO_InterfaceI*)(\
1771  (self_)->_parent._intf))->reserve_address(self_,src_addr_,pub_addr_,prop_)
1772 
1773 /*ci
1774  * \brief Wrapper to call \ref NETIO_InterfaceI::release_address
1775  *
1776  * Release an address previously reserved. The address will no longer be
1777  * listened on by the caller.
1778  *
1779  * \param[in] self_ NETIO interface to release addresses on
1780  * \param[in] src_addr_ Address to release
1781  *
1782  * \return RTI_TRUE on success, RTI_FALSE on failure.
1783  */
1784 #define NETIO_Interface_release_address(self_,src_addr_) \
1785  ((struct NETIO_InterfaceI*)(\
1786  (self_)->_parent._intf))->release_address(self_,src_addr_)
1787 
1788 /*ci
1789  * \brief Wrapper to call \ref NETIO_InterfaceI::bind
1790  *
1791  * \details
1792  * When an interface is matched with another interface (how is outside the
1793  * scope of this function) an entry in the bind-table for the interface is
1794  * created. The peer-to-peer state between the two interfaces should be
1795  * maintained based on this relationship until an unbind is performed.
1796  *
1797  * \param[in] self_ NETIO interface to bind
1798  * \param[in] src_ The address to bind to
1799  * \param[in] prop_ The property to use for the bind
1800  * \param[out] ex_ Whether a previous bind existed or not
1801  *
1802  * \return RTI_TRUE on success, RTI_FALSE on failure.
1803  */
1804 #define NETIO_Interface_bind(self_,src_,prop_,ex_) \
1805  ((struct NETIO_InterfaceI*)(\
1806  (self_)->_parent._intf))->bind(self_,src_,prop_,ex_)
1807 
1808 /*ci
1809  * \brief Wrapper to call \ref NETIO_InterfaceI::unbind
1810  *
1811  * \details
1812  * When an interface is unmatched from another interface (how is outside the
1813  * scope of this function) an entry in the bind-table for the interface can
1814  * safely be removed (although not required). No state is expected to be
1815  * maintained from this point on
1816  *
1817  * \param[in] self_ NETIO interface to unbind
1818  * \param[in] src_ The address to unbind from
1819  * \param[in] dst_ Interface to unbind from
1820  * \param[out] exist_ Whether a bind existed or not
1821  *
1822  * \return RTI_TRUE on success, RTI_FALSE on failure.
1823  */
1824 #define NETIO_Interface_unbind(self_,src_,dst_,exist_) \
1825  ((struct NETIO_InterfaceI*)(\
1826  (self_)->_parent._intf))->unbind(self_,src_,dst_,exist_)
1827 
1828 /*ci
1829  * \brief Wrapper to call \ref NETIO_InterfaceI::bind_external
1830  *
1831  * \details
1832  * When an upstream interface wants to listen to data from a local
1833  * downstream interface it binds to the downstream interface using the
1834  * external bind function. This typically means adding an interface to a
1835  * bind table in the downstream interface so the downstream interface is
1836  * able to forward data upstream.
1837  *
1838  * \param[in] src_intf_ NETIO interface to bind to upstream interface
1839  * \param[in] src_adr_ The address to bind to
1840  * \param[in] dst_intf_ The upstream interface
1841  * \param[in] dst_adr_ The address to pass to the upstream interface
1842  * \param[in] p_ The properties for the bind
1843  * \param[out] e_ Whether a previous bind already existed for this entry
1844  *
1845  * \return RTI_TRUE on success, RTI_FALSE on failure.
1846  */
1847 #define NETIO_Interface_bind_external(src_intf_,src_adr_,dst_intf_,dst_adr_,p_,e_) \
1848 ((struct NETIO_InterfaceI*)(\
1849  (src_intf_)->_parent._intf))->bind_external(src_intf_,src_adr_,dst_intf_,dst_adr_,p_,e_)
1850 
1851 /*ci
1852  * \brief Wrapper to call \ref NETIO_InterfaceI::unbind_external
1853  *
1854  * \details
1855  * When an upstream interface no longer wants to listen to data from a local
1856  * downstream interface it unbinds from the downstream interface using the
1857  * external unbind function. This typically means removing an interface from a
1858  * bind table in the downstream interface so the downstream interface no longer
1859  * forwards data upstream to a non-existent interface.
1860  *
1861  * \param[in] src_intf_ NETIO interface to unbind from upstream interface
1862  * \param[in] src_adr_ The address to unbind from
1863  * \param[in] dst_adr_ The upstream interface
1864  * \param[in] dst_intf_ The address to passed to the upstream interface
1865  * \param[out] exist_ Whether a previous bind already existed for this entry
1866  *
1867  * \return RTI_TRUE on success, RTI_FALSE on failure.
1868  */
1869 #define NETIO_Interface_unbind_external(src_intf_,src_adr_,dst_adr_,dst_intf_,exist_) \
1870 ((struct NETIO_InterfaceI*)(\
1871  (src_intf_)->_parent._intf))->unbind_external(src_intf_,src_adr_,dst_adr_,dst_intf_,exist_)
1872 
1873 /*ci
1874  * \brief Wrapper to call \ref NETIO_InterfaceI::receive
1875  *
1876  * \details
1877  *
1878  * A NETIO interface receives data from a downstream interface.
1879  * The data can be in different protocol formats. Depending on the
1880  * downstream protocol different actions may be taken, but semantically it
1881  * does not matter where data is coming from. The receive interface is
1882  * synchronous, _all_ processing takes place in the context of the downstream
1883  * receive context, such as a thread.
1884  *
1885  * \param[in] self_ The interface receiving data
1886  * \param[in] src_ The source address of the data
1887  * \param[in] dst_ The destination address of the data
1888  * \param[in] p_ A NETIO_Packet with the payload
1889  *
1890  * \return RTI_TRUE on success, RTI_FALSE on failure
1891  */
1892 #define NETIO_Interface_receive(self_,src_,dst_,p_) \
1893  ((struct NETIO_InterfaceI*)(\
1894  (self_)->_parent._intf))->receive(self_,src_,dst_,p_)
1895 
1896 /*ci
1897  * \brief Wrapper to call \ref NETIO_InterfaceI::get_external_interface
1898  *
1899  * \details
1900  * When an interface is bound to a downstream interface it must provide
1901  * which interface and address the downstream interface should use when
1902  * forwarding a NETIO_Packet.
1903  *
1904  * \param[in] self_ NETIO interface to get the external interface for
1905  * \param[in] src_ The address to send to
1906  * \param[out] ul_ The interface to use
1907  * \param[out] dst_ The destination address to use
1908  *
1909  * \return RTI_TRUE on success, RTI_FALSE on failure.
1910  */
1911 #define NETIO_Interface_get_external_interface(self_,src_,ul_,dst_) \
1912  ((struct NETIO_InterfaceI*)(\
1913  (self_)->_parent._intf))->get_external_interface(self_,src_,ul_,dst_)
1914 
1915 /*ci
1916  * \brief Wrapper to call \ref NETIO_InterfaceI::set_state
1917  *
1918  * \details
1919  * Set the state of an interface, the interface is not required to perform
1920  * any action as this is interface dependent.
1921  *
1922  * \param[in] self_ NETIO interface to set state on
1923  * \param[in] state_ New state
1924  *
1925  * \return RTI_TRUE on success, RTI_FALSE on failure.
1926  */
1927 #define NETIO_Interface_set_state(self_,state_) \
1928  ((struct NETIO_InterfaceI*)(\
1929  (self_)->_parent._intf))->set_state(self_,state_)
1930 
1931 /*ci
1932  * \brief Wrapper to call \ref NETIO_InterfaceI::resolve_address
1933  *
1934  * \details
1935  * Request an interface to convert a string address to a \ref NETIO_Address.
1936  * If an interface successfully translated it, is_invalid_ is set to RTI_TRUE,
1937  * otherwise false and the content of the output is undefined.
1938  *
1939  * \param[out] self_ Interface requested to do the conversion
1940  * \param[in] address_ Address to convert
1941  * \param[out] resolved_ Converted address on success
1942  * \param[out] is_invalid_ Whether the address is valid or not
1943  *
1944  * \return RTI_TRUE on success, RTI_FALSE on failure.
1945  */
1946 #define NETIO_Interface_resolve_address(self_,address_,resolved_,is_invalid_) \
1947 ((struct NETIO_InterfaceI*)(\
1948  (self_)->_parent._intf))->resolve_address(self_,address_,resolved_,is_invalid_)
1949 
1950 /*ci
1951  * \brief Wrapper to call \ref NETIO_InterfaceI::get_route_table
1952  *
1953  * \details
1954  * Query an interface for what addresses it can forward packets to. Not
1955  * all interfaces provides a routing table, this is implementation dependent.
1956  *
1957  * \param[in] self_ The NETIO interface
1958  * \param[inout] address_ Sequence of NETIO addresses this interface understands
1959  * \param[inout] netmask_ Sequence of the corresponding netmasks
1960  *
1961  * \return RTI_TRUE on success, RTI_FALSE on failure.
1962  */
1963 #define NETIO_Interface_get_route_table(self_,address_,netmask_) \
1964  ((struct NETIO_InterfaceI*)(\
1965  (self_)->_parent._intf))->get_route_table(self_,address_,netmask_)
1966 
1967 /*ci
1968  * \brief Wrapper to call \ref NETIO_InterfaceI::post_event
1969  *
1970  * \details
1971  * Post an external event on the interface
1972  *
1973  * \param[in] self_ The interface interface the event occurred on
1974  * \param[in] src_intf_ The source of the event
1975  * \param[in] event_ The NETIO event
1976  *
1977  * \return RTI_TRUE if the event was handled successfully, RTI_FALSE if not
1978  */
1979 #define NETIO_Interface_post_event(self_,src_intf_,event_) \
1980  ((struct NETIO_InterfaceI*)(\
1981  (self_)->_parent._intf))->post_event(self_,src_intf_,event_)
1982 
1983 /*ci
1984  * \brief Lookup if a route exists to a destination via an interface
1985  *
1986  * \param[in] self_ The source interface
1987  * \param[in] dst_reader_ The destination address
1988  * \param[in] via_intf_ The downstream interface
1989  * \param[in] via_address_ The address to pass to the downstream interface
1990  * \param[out] route_exists_ RTI_TRUE if the route existed, RTI_FALSE if not
1991  *
1992  * \return RTI_TRUE if the event was handled successfully, RTI_FALSE if not
1993  */
1994 #define NETIO_Interface_lookup_route(self_,dst_reader_,via_intf_,\
1995  via_address_,route_exists_) \
1996  ((struct NETIO_InterfaceI*)(\
1997  (self_)->_parent._intf))->lookup_route(self_,dst_reader_,via_intf_,\
1998  via_address_,route_exists_)
1999 
2000 #ifdef __cplusplus
2001 }
2002 #endif
2003 
2004 #endif /* netio_interface_h */
2005 
2006 /*ci @} */

RTI Connext DDS Micro Version 2.4.8 Copyright © Tue Apr 12 2016 Real-Time Innovations, Inc