RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
netio_address.h
1 /*
2  * FILE: netio_address.h - NETIO Address 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  * 30jun2015,tk MICRO-1378/PR#15203 Updated comments
14  * 19may2015,as MICRO-1193 Refactoring of Sequence API levels
15  * 05may2014,tk MICRO-72 - Updated based on CR-232
16  * 25apr2012,tk Written
17  */
18 /*ci
19  * \file
20  * \brief NETIO Address API
21  * \defgroup NETIOAddressClass NETIO Address API
22  * \ingroup NETIOCommon
23  *
24  * \details
25  *
26  * This file contains functions to manipulate NETIO addresses.
27  */
28 /*ci \addtogroup NETIOAddressClass
29  * @{
30  */
31 #ifndef netio_address_h
32 #define netio_address_h
33 
34 #ifndef netio_dll_h
35 #include "netio/netio_dll.h"
36 #endif
37 #ifndef osapi_config_h
38 #include "osapi/osapi_config.h"
39 #endif
40 #ifndef osapi_types_h
41 #include "osapi/osapi_types.h"
42 #endif
43 #ifndef reda_sequence_h
44 #include "reda/reda_sequence.h"
45 #endif
46 #ifndef db_db_h
47 #include "db/db_api.h"
48 #endif
49 #ifndef rt_rt_h
50 #include "rt/rt_rt.h"
51 #endif
52 
53 #ifdef __cplusplus
54 extern "C"
55 {
56 #endif
57 
58 /*ci
59  * \def NETIO_ADDRESS_PORT_INVALID
60  * \brief Constant for an invalid port number
61  */
62 #define NETIO_ADDRESS_PORT_INVALID (0)
63 
64 /*ci
65  * \def NETIO_ADDRESS_KIND_INVALID
66  * \brief Constant for an invalid address kind
67  */
68 #define NETIO_ADDRESS_KIND_INVALID (-1)
69 
70 /*ci
71  * \def NETIO_ADDRESS_KIND_RESERVED
72  * \brief Constant reserved for internal address kinds.
73  */
74 #define NETIO_ADDRESS_KIND_RESERVED 0
75 
76 /*ci
77  * \def NETIO_ADDRESS_KIND_UDPv4
78  * \brief Constant reserved for UDPv4 address kinds
79  */
80 #define NETIO_ADDRESS_KIND_UDPv4 1
81 
82 /*ci
83  * \def NETIO_ADDRESS_KIND_UDPv6
84  * \brief Constant reserved for UDPv6 address kinds
85  */
86 #define NETIO_ADDRESS_KIND_UDPv6 2
87 
88 /*ci
89  * \def NETIO_ADDRESS_KIND_USER
90  * \brief User defined (not in spec) locator kind shall
91  * be greater or equal than this constant
92  */
93 #define NETIO_ADDRESS_KIND_USER 0x01000000
94 
95 /*ci
96  * \def NETIO_ADDRESS_KIND_SHMEM
97  * \brief Constant reserved for shared memory addresses
98  */
99 #define NETIO_ADDRESS_KIND_SHMEM 0x01000000
100 
101 /*ci
102  * \def NETIO_ADDRESS_KIND_INTRA
103  * \brief Constant reserved for INTRA addresses
104  */
105 #define NETIO_ADDRESS_KIND_INTRA 0x01001000
106 
107 /*ci
108  * \def NETIO_ADDRESS_KIND_TUDPv4
109  * \brief Constant reserved for transformed UDP payloads
110  */
111 #define NETIO_ADDRESS_KIND_TUDPv4 0x01001001
112 
113 /*ci
114  * \def NETIO_ADDRESS_MAX_32BIT
115  * \brief The maximum number of 32bit values in an address
116  */
117 #define NETIO_ADDRESS_MAX_32BIT (4)
118 
119 /*ci
120  * \def NETIO_ADDRESS_MAX_8IT
121  * \brief The maximum number of 8bit values in an address
122  */
123 #define NETIO_ADDRESS_MAX_8IT (16)
124 
125 /*ci
126  * \brief 12 byte GUID prefix, can used as part of a complete GUID address
127  */
128 struct NETIO_GuidPrefix
129 {
130  RTI_UINT8 value[12];
131 };
132 
133 /*ci
134  * \brief 4 byte GUID entity part, can used as part of a complete GUID address
135  */
136 struct NETIO_GuidEntity
137 {
138  RTI_UINT8 value[4];
139 };
140 
141 /*ci
142  * \brief Address in RTPS format, commonly used by RTI internally
143  */
144 struct NETIO_AddressRtps
145 {
146  RTI_UINT32 host_id;
147  RTI_UINT32 app_id;
148  RTI_UINT32 instance_id;
149  RTI_UINT32 object_id;
150 };
151 
152 /*ci
153  * \brief Address in GUID format
154  */
155 struct NETIO_Guid
156 {
157  struct NETIO_GuidPrefix prefix;
158  struct NETIO_GuidEntity entity;
159 };
160 
161 /*ci
162  * \brief Address in GUID format, but with individual bytes accessible
163  */
164 struct NETIO_AddressGuidPrefix
165 {
166  RTI_UINT8 prefix[12];
167  RTI_UINT32 entity;
168 };
169 
170 /*ci
171  * \brief Address in UDPv4 format. By internal convention, only the 4 most
172  * significant bytes are used.
173  */
174 struct NETIO_AddressIp4
175 {
176  /*ci
177  * \brief 32 bit IPv4 address in host order
178  */
179  RTI_UINT32 address;
180  RTI_UINT8 _unused[12];
181 };
182 
183 /*ci
184  * \brief Address in UDPv6 format. By internal convention
185  */
186 struct NETIO_AddressIpv6
187 {
188  RTI_UINT8 octet[16];
189 };
190 
191 /*ci
192  * \brief Address in shared memory format. By internal convention
193  */
194 struct NETIO_AddressShem
195 {
196  /*ci
197  * \brief shared memory key
198  */
199  RTI_UINT32 key;
200  RTI_UINT8 guid[12];
201 };
202 
203 /*ci
204  * \brief Convenience structure to initialize an \ref NETIO_Address structure
205  */
206 struct NETIO_AddressInit
207 {
208  RTI_UINT32 val0;
209  RTI_UINT32 val1;
210  RTI_UINT32 val2;
211  RTI_UINT32 val3;
212 };
213 
214 /*ci
215  * \brief Convenience structure to access \ref NETIO_Address as an array of 4
216  * signed integers
217  */
218 struct NETIO_AddressInt32
219 {
220  RTI_INT32 value[4];
221 };
222 
223 /*ci
224  * \brief Convenience structure to access \ref NETIO_Address as an array of 4
225  * unsigned integers
226  */
227 struct NETIO_AddressUInt32
228 {
229  RTI_UINT32 value[4];
230 };
231 
232 /*ci
233  * \brief All the different address formats
234  */
235 union NETIO_AddressValue
236 {
237  struct NETIO_AddressRtps rtps_guid;
238  struct NETIO_Guid guid;
239  struct NETIO_AddressGuidPrefix guid_prefix;
240  struct NETIO_AddressIp4 ipv4;
241  struct NETIO_AddressIpv6 ipv6;
242  struct NETIO_AddressShem shmem;
243  struct NETIO_AddressInit init;
244  struct NETIO_AddressInt32 as_int32;
245  struct NETIO_AddressUInt32 as_uint32;
246 };
247 
248 /*ci
249  * \brief The definition of the NETIO address structure
250  */
251 struct NETIO_Address
252 {
253  /*ci
254  * \brief Address discriminator. Note that the 8 MSB of the kind
255  * is reserved for internal use
256  */
257  RTI_INT32 kind;
258 
259  /*ci
260  * \brief Port number
261  */
262  RTI_UINT32 port;
263 
264  /*ci
265  * \brief Address as defined by the discriminator
266  */
267  union NETIO_AddressValue value;
268 };
269 
270 /*ci
271  * \def NETIO_ADDRESS_FLAG_MULTICAST
272  * \brief Flags to indicate is an address is multicast
273  */
274 #define NETIO_ADDRESS_FLAG_MULTICAST (0x80000000)
275 
276 /*ci
277  * \def NETIO_ADDRESS_FLAG_INTERNAL
278  * \brief Flags to indicate is an address is an internal address
279  */
280 #define NETIO_ADDRESS_FLAG_INTERNAL (0x40000000)
281 
282 /*ci
283  * \brief Check if a \ref NETIO_Address is a multicast address
284  *
285  * \param[in] addr Address to check
286  *
287  * \return RTI_TRUE is the address is multicast, RTI_FALSE if not
288  */
289 NETIODllExport RTI_BOOL
290 NETIO_Address_is_multicast(const struct NETIO_Address *const addr);
291 
292 /*ci
293  * \brief Check if a \ref NETIO_Address is an internal address
294  *
295  * \param[in] addr Address to check
296  *
297  * \return RTI_TRUE is the address is internal, RTI_FALSE if not
298  */
299 NETIODllExport RTI_BOOL
300 NETIO_Address_is_internal(const struct NETIO_Address *const addr);
301 
302 /*ci
303  * \brief Mark a \ref NETIO_Address as a multicast address
304  *
305  * \param[in] addr Address to mark
306  */
307 NETIODllExport void
308 NETIO_Address_set_multicast(struct NETIO_Address *const addr);
309 
310 /*ci
311  * \brief Mark a \ref NETIO_Address as an internal address
312  *
313  * \param[in] addr Address to mark
314  */
315 NETIODllExport void
316 NETIO_Address_set_internal(struct NETIO_Address *const addr);
317 
318 /*ci
319  * \brief Set the \ref NETIO_Address kind
320  *
321  * \param[in] addr Address to set kind of
322  * \param[in] kind Address kind
323  * \param[in] flags Address flags such as internal or multicast
324  */
325 NETIODllExport void
326 NETIO_Address_set_kind(struct NETIO_Address *const addr,RTI_UINT32 kind,RTI_INT32 flags);
327 
328 /*ci
329  * \brief Get the \ref NETIO_Address kind
330  *
331  * \param[in] addr Address to get kind of
332  *
333  * \return The address kind
334  */
335 NETIODllExport RTI_INT32
336 NETIO_Address_get_kind(const struct NETIO_Address *const addr);
337 
338 /*ci
339  * \brief Convert a \ref NETIO_Address::kind field to a valid kind
340  *
341  * \param[in] kind Kind to mask
342  *
343  * \return The kind
344  */
345 NETIODllExport RTI_INT32
346 NETIO_Address_kind(RTI_INT32 kind);
347 
348 /*ci
349  * \def NETIO_NETMASK_MASK_LENGTH
350  * \brief The maximum number of elements in a netmask
351  */
352 #define NETIO_NETMASK_MASK_LENGTH (4)
353 
354 /*ci
355  * \def NETIO_NETMASK_MASK_BITS_PER_UNIT
356  * \brief The number of bits per netmask element
357  */
358 #define NETIO_NETMASK_MASK_BITS_PER_UNIT ((RTI_INT32)(sizeof(RTI_INT32) * 8))
359 
360 /*ci
361  * \brief The maximum number of bits in a netmask
362  */
363 #define NETIO_NETMASK_MASK_MAX_BITS \
364  (NETIO_NETMASK_MASK_LENGTH * NETIO_NETMASK_MASK_BITS_PER_UNIT)
365 
366 /*ci
367  * \brief Representation of a netmask
368  */
369 struct NETIO_Netmask
370 {
371  /*ci
372  * \brief The number of valid bits in the netmask
373  */
374  RTI_INT32 bits;
375 
376  /*ci
377  * \brief The netmask
378  */
379  RTI_UINT32 mask[NETIO_NETMASK_MASK_LENGTH];
380 };
381 
382 /*ci
383  * \brief \ref NETIO_Netmask initializer
384  */
385 #define NETIO_Netmask_INITIALIZER \
386 {\
387  0,\
388  {0,0,0,0}\
389 }
390 
391 /* The NETIO API uses both individual NETIO_Addresses and NETIO_Netmask
392  * field, as well as sequences of these. Thi declares the sequence
393  * of the respective types.
394  */
395 #define T struct NETIO_Address
396 #define TSeq NETIO_AddressSeq
397 #include <reda/reda_sequence_decl.h>
398 
399 #define T struct NETIO_Netmask
400 #define TSeq NETIO_NetmaskSeq
401 #include <reda/reda_sequence_decl.h>
402 
403 /*ci
404  * \def NETIO_AddressSeq_INITIALIZER
405  * \brief Macro to initialize a NETIO_Address sequence
406  */
407 #define NETIO_AddressSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(struct NETIO_Address)
408 
409 /*ci
410  * \def NETIO_NetmaskSeq_INITIALIZER
411  * \brief Macro to initialize a NETIO_Netmask sequence
412  */
413 #define NETIO_NetmaskSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(struct NETIO_Netmask)
414 
415 /*ci
416  * \def NETIO_ADDRESS_GUID_UNKNOWN
417  * \brief Constant used to initialize an NETIO_Address of the GUID kind to
418  * unknown.
419  */
420 #define NETIO_ADDRESS_GUID_UNKNOWN {{{0,0,0,0,0,0,0,0,0,0,0,0}},{{0,0,0,0}}}
421 
422 /*ci
423  * \brief Compare two NETIO_Addresses
424  *
425  * \details
426  *
427  * This function compares two NETIO_Address structures.
428  *
429  * \param[in] left_addr Left side of the comparison
430  * \param[in] right_addr Right side of the comparison
431  *
432  * \return positive integer if left_addr is greater than right_addr,
433  * negative integer if left_addr is less than right_addr,
434  * zero if left_addr is equal to right_addr
435  */
436 NETIODllExport RTI_INT32
437 NETIO_Address_compare(const struct NETIO_Address *left_addr,
438  const struct NETIO_Address *right_addr);
439 
440 /*ci
441  * \def NETIO_Address_INITIALIZER
442  * Constant to initialize a \ref NETIO_Address
443  */
444 #define NETIO_Address_INITIALIZER \
445 {\
446  NETIO_ADDRESS_KIND_RESERVED, /* kind */ \
447  0, /* port */ \
448  {{0,0,0,0}} /* value */ \
449 }
450 
451 /*ci
452  * \brief Initialize a \ref NETIO_Address to a known state
453  *
454  * \param[inout] addr Address to initialize
455  * \param[in] kind Address kind
456  */
457 NETIODllExport void
458 NETIO_Address_init(struct NETIO_Address *addr,RTI_INT32 kind);
459 
460 /*ci
461  * \brief Set the IPv4 address part of a \ref NETIO_Address
462  *
463  * \param[inout] addr Address to initialize
464  * \param[in] port Address port
465  * \param[in] address IPv4 address in host order
466  */
467 NETIODllExport void
468 NETIO_Address_set_ipv4(struct NETIO_Address *addr,RTI_UINT32 port,RTI_UINT32 address);
469 
470 /*ci
471  * \brief Set the GUID address part of a \ref NETIO_Address
472  *
473  * \param[inout] addr Address to initialize
474  * \param[in] port Address port
475  * \param[in] guid GUID to set
476  */
477 NETIODllExport void
478 NETIO_Address_set_guid(struct NETIO_Address *addr,RTI_UINT32 port,struct NETIO_Guid *guid);
479 
480 /*ci
481  * \brief Set the GUID address part of a \ref NETIO_Address from a DDS Key.
482  *
483  * \details
484  * DDS keys are received over the arrays as an array of 4 integers
485  * as defined by the DDS specification. Because the key is represented as
486  * 4 integers in the <em> host order </em> of the sender but are internally
487  * represented as 16 octets (endianess is not an issue), care must be
488  * taken to perform endianness conversion.
489  *
490  * \param[inout] addr Address to initialize
491  * \param[in] port Address port
492  * \param[in] key Key to set
493  */
494 NETIODllExport void
495 NETIO_Address_set_guid_from_key(struct NETIO_Address *addr,RTI_UINT32 port,
496  struct NETIO_AddressInt32 *key);
497 
498 /*ci
499  * \brief Set the GUID address part of a \ref NETIO_Address from 4 integers.
500  *
501  * \details
502  * A GUID is an array of 16 octets and it is necessary
503  * to perform endianess conversion based on the host's endianess
504  *
505  * \param[inout] addr Address to initialize
506  * \param[in] port Address port
507  * \param[in] int0 Byte 15-12
508  * \param[in] int1 Byte 11-8
509  * \param[in] int2 Byte 7-4
510  * \param[in] int3 Byte 3-0
511  */
512 NETIODllExport void
513 NETIO_Address_set_guid_from_int32(struct NETIO_Address *addr,RTI_UINT32 port,
514  RTI_UINT32 int0,RTI_UINT32 int1,
515  RTI_UINT32 int2,RTI_UINT32 int3);
516 
517 /*ci
518  * \brief Check if an address is a UDPv4 multicast address
519  *
520  * \param[in] addr Address to check
521  *
522  * \return RTI_TRUE if the address is multicast, RTI_FALSE if not
523  *
524  */
525 NETIODllExport RTI_BOOL
526 NETIO_Address_is_udpv4_multicast(struct NETIO_Address *addr);
527 
528 /*ci
529  * \brief Parse an address string
530  *
531  * \details
532  *
533  * This function parses an NETIO address in stringa format and breaks
534  * it into the individual parts.
535  *
536  * Algorithm:
537  *
538  * An address is on the form:
539  *
540  * [index @][<interface>://][<address>]
541  *
542  * - break address string into 3 parts:
543  * - An optional index. Three index formats are supported
544  * N@ - In this type the low_index = 0 and high_index is N
545  * [N-M]@ - In this type the low_index = N and high_index is M
546  * M@ - In this type the low_index = high_index = M
547  * - An optional interface id (out_id)
548  * - An optional address string (address_string)
549  *
550  * The parse allows an empty string. If an index is not specified -1 is
551  * returned. If a prefix is not specified an empty prefix is returned.
552  *
553  * \param[in] name The address to be parsed
554  * \param[out] base_port The base port in used in port calculation
555  * \param[out] low_index The lowest index parsed from the address
556  * \param[out] high_index The highest index parsed from the address
557  * \param[out] out_id The ComponentFactoryId that successfully parsed it
558  * \param[out] address_string The address part of the NETIO address string
559  * \param[out] address_max_string The maximum length of the address part
560  *
561  * \return RTI_TRUE on success, RTI_FALSE on failure
562  */
563 MUST_CHECK_RETURN NETIODllExport RTI_BOOL
564 NETIO_Address_parse(const char *name,
565  RTI_UINT32 *base_port,
566  RTI_INT32 *low_index,
567  RTI_INT32 *high_index,
568  RT_ComponentFactoryId_T *out_id,
569  char *address_string,
570  RTI_SIZE_T address_max_string);
571 
572 /*ci
573  * \brief The maximum size of an individual address part.
574  */
575 #define NETIO_ADDRESS_TOKEN_MAX_SIZE 256
576 
577 /*ci
578  * \brief The maximum size of an an address prefix. The address prefix
579  * is limited by the the run-time can handle, which is 7 octets, excluding the
580  * NULL termination.
581  */
582 #define NETIO_PREFIX_TOKEN_MAX_SIZE (RT_MAX_FACTORY_NAME + 1)
583 
584 /*ci
585  * \brief Enumeration of what type of address is being resolved. NETIO
586  * supports 2 types of address, meta and user. It is up to the
587  * caller to determine what the definition of user and meta means.
588  */
589 typedef enum
590 {
591  /*ci
592  * \brief The address if for meta traffic
593  */
594  NETIO_ROUTEKIND_META,
595 
596  /*ci
597  * \brief The address if for user traffic
598  */
599  NETIO_ROUTEKIND_USER
600 } NETIO_RouteKind_T;
601 
602 /*ci
603  * \brief Calculate a port number based on user provided information
604  *
605  * \details
606  *
607  * NETIO does not enforce the user of a port calculation function. However,
608  * some layers such as DDS defines a port mapping to enable discovery on
609  * well-known ports. Based on information provided by the caller
610  * the user can calculate specific port numbers which will be used as
611  * part of a \ref NETIO_Address.
612  *
613  * \param[in] param User provided parameter passed transparently
614  * \param[in] kind The type of address the port is calculated for
615  * \param[in] port_base The base-port number, typically used together with an
616  * index to calculate the final port
617  * \param[in] index The index extracted from an address string
618  * \param[out] address The NETIO_Address structure to update the port for
619  */
620 typedef RTI_BOOL
621 (*NETIO_PortCalculateFunc_T)(void *param,NETIO_RouteKind_T kind,
622  RTI_UINT32 port_base,RTI_INT32 index,
623  struct NETIO_Address *address);
624 
625 #ifdef __cplusplus
626 } /* extern "C" */
627 #endif
628 
629 #endif /* netio_address_h */
630 
631 /*ci @} */
632 

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc