netio_address.h

/*
 * FILE: netio_address.h - NETIO Address API
 *
 * Copyright 2012-2014 Real-Time Innovations, Inc.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 *
 * Modification History
 * --------------------
 * 05may2014,tk MICRO-72 - Updated based on CR-232
 * 25apr2012,tk Written
 */
/*ci
 * \file
 * \brief NETIO Address API
 * \defgroup NETIOAddressClass NETIO Address API
 * \ingroup NETIOCommon
 *
 * \details
 *
 * This file contains functions to manipulate NETIO addresses.
 */
/*ci \addtogroup NETIOAddressClass
 * @{
 */
#ifndef netio_address_h
#define netio_address_h

#ifndef netio_dll_h
#include "netio/netio_dll.h"
#endif
#ifndef osapi_config_h
#include "osapi/osapi_config.h"
#endif
#ifndef osapi_types_h
#include "osapi/osapi_types.h"
#endif
#ifndef reda_sequence_h
#include "reda/reda_sequence.h"
#endif
#ifndef db_db_h
#include "db/db_api.h"
#endif
#ifndef rt_rt_h
#include "rt/rt_rt.h"
#endif

#ifdef __cplusplus
extern "C"
{
#endif

/*ci
 * \def NETIO_ADDRESS_PORT_INVALID
 * \brief Constant for an invalid port number
 */
#define NETIO_ADDRESS_PORT_INVALID   (0)

/*ci
 * \def NETIO_ADDRESS_KIND_INVALID
 * \brief Constant for an invalid address kind
 */
#define NETIO_ADDRESS_KIND_INVALID   (-1)

/*ci
 * \def NETIO_ADDRESS_KIND_RESERVED
 * \brief Constant reserved for internal address kinds.
 */
#define NETIO_ADDRESS_KIND_RESERVED  0

/*ci
 * \def NETIO_ADDRESS_KIND_UDPv4
 * \brief Constant reserved for UDPv4 address kinds
 */
#define NETIO_ADDRESS_KIND_UDPv4     1

/*ci
 * \def NETIO_ADDRESS_KIND_UDPv6
 * \brief Constant reserved for UDPv6 address kinds
 */
#define NETIO_ADDRESS_KIND_UDPv6     2

/*ci
 * \def NETIO_ADDRESS_KIND_SHMEM
 * \brief Constant reserved for shared memory addresses
 */
#define NETIO_ADDRESS_KIND_SHMEM     3

/*ci
 * \def NETIO_ADDRESS_KIND_GUID
 * \brief Constant reserved for GUID addresses
 */
#define NETIO_ADDRESS_KIND_GUID      4

/*ci
 * \def NETIO_ADDRESS_MAX_32BIT
 * \brief The maximum number of 32bit values in an address
 */
#define NETIO_ADDRESS_MAX_32BIT (4)

/*ci
 * \def NETIO_ADDRESS_MAX_8IT
 * \brief The maximum number of 8bit values in an address
 */
#define NETIO_ADDRESS_MAX_8IT   (16)

/*ci
 * \brief 12 byte GUID prefix, can used as part of a complete GUID address
 */
struct NETIO_GuidPrefix
{
    RTI_UINT8 value[12];
};

/*ci
 * \brief 4 byte GUID entity part, can used as part of a complete GUID address
 */
struct NETIO_GuidEntity
{
    RTI_UINT8 value[4];
};

/*ci
 * \brief Address in RTPS format, commonly used by RTI internally
 */
struct NETIO_AddressRtps
{
    RTI_UINT32 host_id;
    RTI_UINT32 app_id;
    RTI_UINT32 instance_id;
    RTI_UINT32 object_id;
};

/*ci
 * \brief Address in GUID format
 */
struct NETIO_Guid {
    struct NETIO_GuidPrefix prefix;
    struct NETIO_GuidEntity entity;
};

/*ci
 * \brief Address in GUID format, but with individual bytes accessible
 */
struct NETIO_AddressGuidPrefix
{
    RTI_UINT8 prefix[12];
    RTI_UINT32 entity;
};

/*ci
 * \brief Address in UDPv4 format. By internal convention, only the 4 most
 *        significant bytes are used.
 */
struct NETIO_AddressIp4
{
    /*ci
     * \brief 32 bit IPv4 address in host order
     */
    RTI_UINT32 address;
    RTI_UINT8 _unused[12];
};

/*ci
 * \brief Address in UDPv6 format. By internal convention
 */
struct NETIO_AddressIpv6
{
    RTI_UINT8 octet[16];
};

/*ci
 * \brief Address in shared memory format. By internal convention
 */
struct NETIO_AddressShem
{
    /*ci
     * \brief shared memory key
     */
    RTI_UINT32 key;
    RTI_UINT8 guid[12];
};

/*ci
 * \brief Convenience structure to initialize an \ref NETIO_Address structure
 */
struct NETIO_AddressInit
{
    RTI_UINT32 val0;
    RTI_UINT32 val1;
    RTI_UINT32 val2;
    RTI_UINT32 val3;
};

/*ci
 * \brief Convenience structure to access \ref NETIO_Address as an array of 4
 *        signed integers
 */
struct NETIO_AddressInt32
{
    RTI_INT32 value[4];
};

/*ci
 * \brief Convenience structure to access \ref NETIO_Address as an array of 4
 *        unsigned integers
 */
struct NETIO_AddressUInt32
{
    RTI_UINT32 value[4];
};

/*ci
 * \brief All the different address formats
 */
union NETIO_AddressValue
{
    struct NETIO_AddressRtps rtps_guid;
    struct NETIO_Guid guid;
    struct NETIO_AddressGuidPrefix guid_prefix;
    struct NETIO_AddressIp4 ipv4;
    struct NETIO_AddressIpv6 ipv6;
    struct NETIO_AddressShem shmem;
    struct NETIO_AddressInit init;
    struct NETIO_AddressInt32 as_int32;
    struct NETIO_AddressUInt32 as_uint32;
};

/*ci
 * \brief The definition of the NETIO address structure
 */
struct NETIO_Address
{
    /*ci
     * \brief Address discriminator. Note that the 8 MSB of the kind
     *        is reserved
     */
    RTI_INT32 kind;

    /*ci
     * \brief Port number
     */
    RTI_UINT32 port;

    /*ci
     * \brief Address as defined by the discriminator
     */
    union NETIO_AddressValue value;
};

/*ci
 * \def NETIO_ADDRESS_FLAG_MULTICAST
 * \brief Flags to indicate is an address is multicast
 */
#define NETIO_ADDRESS_FLAG_MULTICAST     (0x80000000)

/*ci
 * \def NETIO_ADDRESS_FLAG_INTERNAL
 * \brief Flags to indicate is an address is an internal address
 */
#define NETIO_ADDRESS_FLAG_INTERNAL      (0x40000000)

/*ci
 * \def NETIO_ADDRESS_IS_MULTICAST
 * \brief Macro to check is a \ref NETIO_Address is a multicast address
 */
#define NETIO_ADDRESS_IS_MULTICAST(a_)   ((a_)->kind & NETIO_ADDRESS_FLAG_MULTICAST)

/*ci
 * \def NETIO_ADDRESS_IS_INTERNAL
 * \brief Macro to check is a \ref NETIO_Address is an internal address
 */
#define NETIO_ADDRESS_IS_INTERNAL(a_)    ((a_)->kind & NETIO_ADDRESS_FLAG_INTERNAL)

/*ci
 * \def NETIO_ADDRESS_SET_MULTICAST
 * \brief Macro to mark a \ref NETIO_Address as a multicast address
 */
#define NETIO_ADDRESS_SET_MULTICAST(a_)  ((a_)->kind | NETIO_ADDRESS_FLAG_MULTICAST)

/*ci
 * \def NETIO_ADDRESS_SET_INTERNAL
 * \brief Macro to mark a \ref NETIO_Address as an internal address
 */
#define NETIO_ADDRESS_SET_INTERNAL(a_)   ((a_)->kind | NETIO_ADDRESS_FLAG_INTERNAL)

/*ci
 * \def NETIO_ADDRESS_SET_KIND
 * \brief Macro to set the \ref NETIO_Address kind
 */
#define NETIO_ADDRESS_SET_KIND(a_,k_,f_) ((a_)->kind = (k_) | (f_))

/*ci
 * \def NETIO_ADDRESS_GET_KIND
 * \brief Macro to get the \ref NETIO_Address kind. This macro masks out the
 *        8 msb
 */
#define NETIO_ADDRESS_GET_KIND(a_)       ((a_)->kind & 0x00ffffff)

/*ci
 * \def NETIO_ADDRESS_KIND
 * \brief Convert a \ref NETIO_Address::kind field to a valid kind
 */
#define NETIO_ADDRESS_KIND(k_)           ((k_) & 0x00ffffff)

/*ci
 * \def NETIO_NETMASK_MASK_LENGTH
 * \brief The maximum number of elements in a netmask
 */
#define NETIO_NETMASK_MASK_LENGTH        (4)

/*ci
 * \def NETIO_NETMASK_MASK_SIZE
 * \brief The size in bytes of a netmask element
 */
#define NETIO_NETMASK_MASK_SIZE          ((RTI_INT32)(sizeof(RTI_INT32)))

/*ci
 * \def NETIO_NETMASK_MASK_BITS_PER_UNIT
 * \brief The number of bits per netmask element
 */
#define NETIO_NETMASK_MASK_BITS_PER_UNIT ((RTI_INT32)(sizeof(RTI_INT32) * 8))

/*ci
 * \def NETIO_NETMASK_MASK_MAX_BITS
 * \brief The maximum number of bits in a netmask
 */
#define NETIO_NETMASK_MASK_MAX_BITS      (NETIO_NETMASK_MAX_LENGTH * NETIO_NETMASK_ELEMENT_SIZE*8)

/*ci
 * \brief Representation of a netmask
 */
struct NETIO_Netmask
{
    /*ci
     * \brief The number of valid bits in the netmask
     */
    RTI_INT32 bits;

    /*ci
     * \brief The netmask
     */
    RTI_UINT32 mask[NETIO_NETMASK_MASK_LENGTH];
};

/*ci
 * \brief \ref NETIO_Netmask initializer
 */
#define NETIO_Netmask_INITIALIZER \
{\
    0,\
    {0,0,0,0}\
}

/* The NETIO API uses both individual NETIO_Addresses and NETIO_Netmask
 * field, as well as sequences of these. Thi declares the sequence
 * of the respective types.
 */
REDA_DEFINE_SEQUENCE(NETIO_AddressSeq, struct NETIO_Address)
REDA_DEFINE_SEQUENCE(NETIO_NetmaskSeq, struct NETIO_Netmask)

/*ci
 * \def NETIO_AddressSeq_INITIALIZER
 * \brief Macro to initialize a NETIO_Address sequence
 */
#define NETIO_AddressSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(struct NETIO_Address)

/*ci
 * \def NETIO_NetmaskSeq_INITIALIZER
 * \brief Macro to initialize a NETIO_Netmask sequence
 */
#define NETIO_NetmaskSeq_INITIALIZER REDA_DEFINE_SEQUENCE_INITIALIZER(struct NETIO_Netmask)

/*ci
 * \def NETIO_ADDRESS_GUID_UNKNOWN
 * \brief Constant used to initialize an NETIO_Address of the GUID kind to
 *        unknown.
 */
#define NETIO_ADDRESS_GUID_UNKNOWN {{{0,0,0,0,0,0,0,0,0,0,0,0}},{{0,0,0,0}}}

/*ci
 * \brief Compare two NETIO_Addresses
 *
 * \details
 *
 * This function compares two NETIO_Address structures.
 *
 * \param[in] left_addr   Left side of the comparison
 * \param[in] right_addr  Right side of the comparison
 *
 * \return 0 is left = right, > 0 if left > right, < 0 if left < right
 */
NETIODllExport RTI_INT32
NETIO_Address_compare(const struct NETIO_Address *left_addr,
                      const struct NETIO_Address *right_addr);

/*ci
 * \def NETIO_Address_INITIALIZER
 * Constant to initialize a \ref NETIO_Address
 */
#define NETIO_Address_INITIALIZER \
{\
    NETIO_ADDRESS_KIND_RESERVED, /* kind */ \
    0, /* port */ \
    {{0,0,0,0}} /* value */ \
}

/*ci
 * \def NETIO_Address_init
 *  Macro to initialize a \ref NETIO_Address to a known state
 */
#define NETIO_Address_init(addr_,kind_) \
{\
    (addr_)->kind = kind_; (addr_)->port = 0; \
    (addr_)->value.init.val0 = (addr_)->value.init.val1 = 0;\
    (addr_)->value.init.val2 = (addr_)->value.init.val3 = 0;\
}

/*ci
 * \def NETIO_Address_set_ipv4
 *  Macro to set the IPv4 address part of a \ref NETIO_Address
 */
#define NETIO_Address_set_ipv4(addr_,port_,address_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_UDPv4; \
    (addr_)->port = port_; \
    (addr_)->value.ipv4.address = address_;\
}

/*ci
 * \def NETIO_Address_set_guid
 *  Macro to set the GUID address part of a \ref NETIO_Address
 */
#define NETIO_Address_set_guid(addr_,port_,guid_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_GUID; \
    (addr_)->port = port_; \
    OSAPI_Memory_copy(&((addr_)->value.guid),(guid_),16);\
}

/*ci
 * \def NETIO_Address_set_guid_from_key
 *  Macro to set the GUID address part of a \ref NETIO_Address from a
 *  DDS Key. DDS keys are received over the arrays as an array of 4 integers
 *  as defined by the DDS specification. Because the key is represented as
 *  4 integers in the <em> host order </em> of the sender but are internally
 *  representaed as 16 octets (endianess is not an issue), care must be
 *  taken to perform endianness conversion.
 */
#if RTI_ENDIAN_BIG
#define NETIO_Address_set_guid_from_key(addr_,port_,key_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_GUID; \
    (addr_)->port = port_; \
    OSAPI_Memory_copy(&((addr_)->value.guid),(key_),16);\
}

#else
#define NETIO_Address_set_guid_from_key(addr_,port_,key_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_GUID; \
    (addr_)->port = port_; \
    (addr_)->value.rtps_guid.host_id = NETIO_htonl((key_)->value[0]);\
    (addr_)->value.rtps_guid.app_id = NETIO_htonl((key_)->value[1]);\
    (addr_)->value.rtps_guid.instance_id = NETIO_htonl((key_)->value[2]);\
    (addr_)->value.rtps_guid.object_id = NETIO_htonl((key_)->value[3]);\
}
#endif

/*ci
 * \def NETIO_Address_set_guid_from_int32
 *  Macro to set the GUID address part of a \ref NETIO_Address from a
 *  4 integers. A GUID is an array of 16 octets and it is necessary
 *  to perform endianess conversion based on the host's endianess
 */
#if RTI_ENDIAN_BIG
#define NETIO_Address_set_guid_from_int32(addr_,port_,int0_,int1_,int2_,int3_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_GUID; \
    (addr_)->port = port_; \
    (addr_)->value.rtps_guid.host_id = int0_;\
    (addr_)->value.rtps_guid.app_id = int1_;\
    (addr_)->value.rtps_guid.instance_id = int2_;\
    (addr_)->value.rtps_guid.object_id = int3_;\
}

#else
#define NETIO_Address_set_guid_from_int32(addr_,port_,int0_,int1_,int2_,int3_) \
{\
    (addr_)->kind = NETIO_ADDRESS_KIND_GUID; \
    (addr_)->port = port_; \
    (addr_)->value.rtps_guid.host_id = NETIO_htonl(int0_);\
    (addr_)->value.rtps_guid.app_id = NETIO_htonl(int1_);\
    (addr_)->value.rtps_guid.instance_id = NETIO_htonl(int2_);\
    (addr_)->value.rtps_guid.object_id = NETIO_htonl(int3_);\
}
#endif

/*ci
 * \def NETIO_Address_is_udpv4_multicast
 * Macro to check is an address is a UDPv4 multicast address
 */
#define NETIO_Address_is_udpv4_multicast(addr_) \
 ((NETIO_ADDRESS_GET_KIND(addr_) == NETIO_ADDRESS_KIND_UDPv4) && \
   ((addr_)->value.ipv4.address >= 0xe0000000) && \
   ((addr_)->value.ipv4.address <= 0xefffffff))

/*ci
 * \brief Parse an address string
 *
 * \details
 *
 * This function parses an NETIO address in stringa format and breaks
 * it into the individual parts.
 *
 * Algorithm:
 *
 * An address is on the form:
 *
 * [index @][<interface>://][<address>]
 *
 * - break address string into 3 parts:
 *   - An optional index. Three index  formats are supported
 *     N@     - In this type the low_index = 0 and high_index is N
 *     [N-M]@ - In this type the low_index = N and high_index is M
 *     M@     - In this type the low_index = high_index = M
 * - An optional interface id (out_id)
 * - An optional address string (address_string)
 *
 * The parse allows an empty string. If an index is not specified -1 is
 * returned. If a prefix is not specified an empty prefix is returned.
 *
 * \param[in]  name               The address to be parsed
 * \param[out] base_port          The base port in used in port calculation
 * \param[out] low_index          The lowest index parsed from the address
 * \param[out] high_index         The highest index parsed from the address
 * \param[out] out_id             The ComponentFactoryId that successfully parsed it
 * \param[out] address_string     The address part of the NETIO address string
 * \param[out] address_max_string The maximum length of the address part
 *
 * \return RTI_TRUE on success, RTI_FALSE on failure
 */
MUST_CHECK_RETURN NETIODllExport RTI_BOOL
NETIO_Address_parse(const char *name,
                    RTI_UINT32 *base_port,
                    RTI_INT32 *low_index,
                    RTI_INT32 *high_index,
                    RT_ComponentFactoryId_T *out_id,
                    char *address_string,
                    RTI_SIZE_T address_max_string);

/*ci
 * \brief The maximum size of an individual address part.
 */
#define NETIO_ADDRESS_TOKEN_MAX_SIZE 256

/*ci
 * \brief The maximum size of an an address prefix. The address prefix
 * is limited by the the run-time can handle, which is 7 octets, excluding the
 * NULL termination.
 */
#define NETIO_PREFIX_TOKEN_MAX_SIZE  (RT_MAX_FACTORY_NAME + 1)

/*ci
 * \brief Enumeration of what type of address is being resolved. NETIO
 *        supports 2 types of address, meta and user. It is up to the
 *        caller to determine what the definition of user and meta means.
 */
typedef enum
{
    /*ci
     * \brief The address if for meta traffic
     */
    NETIO_ROUTEKIND_META,

    /*ci
     * \brief The address if for user traffic
     */
    NETIO_ROUTEKIND_USER
} NETIO_RouteKind_T;

/*ci
 * \brief Calculate a port number based on user provided information
 *
 * \details
 *
 * NETIO does not enforce the user of a port calculation function. However,
 * some layers such as DDS defines a port mapping to enable discovery on
 * well-known ports. Based on information provided by the caller
 * the user can calculate specific port numbers which will be used as
 * part of a \ref NETIO_Address.
 *
 * \param[in] param     User provided parameter passed transparently
 * \param[in] kind      The type of address the port is calculated for
 * \param[in] port_base The base-port number, typically used together with an
 *                      to calculate the final port
 * \param[in] index     The index has been extracted from an address string
 * \param[out] address  The NETIO_Address structure to update the port for
 */
typedef RTI_BOOL
(*NETIO_PortCalculateFunc_T)(void *param,NETIO_RouteKind_T kind,
                             RTI_UINT32 port_base,RTI_INT32 index,
                             struct NETIO_Address *address);

#ifdef __cplusplus
}                               /* extern "C" */
#endif

#endif /* netio_address_h */

/*ci @} */