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

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc