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

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