transport_udp.h

/*
 * (c) Copyright, Real-Time Innovations, 2005-2024.
 * All rights reserved.
 *
 * 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.
 */
 
#ifndef transport_udp_h
#define transport_udp_h
 
#include "osapi/osapi_socket.h"
#include "osapi/osapi_atomic.h"
#include "clock/clock_interface.h"
#include "transport/transport_dll.h"
#include "transport/transport_interface.h"
#include "transport/transport_udp_wan_library.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct NDDS_Transport_UDP; /* forward declare */
 
struct NDDS_Transport_UDP_SocketFactory;
 
struct NDDS_Transport_UDP_Interface_t;
 
/* ================================================================= */
/*                 Component: UDP/IP Transport Plugin                */
/* ================================================================= */
 
/*e \dref_UDPTransportBuiltinGroupDocs
 */
 
/*i \file
 *   \ingroup NDDS_Transport_UDP_Plugin
 *   \brief UDP Transport Plugin interfaces and definitions.
 */
 
/* ================================================================= */
/*             Transport UDP WAN Listener Class                      */
/* ================================================================= */
typedef void (
        *NDDS_Transport_UDP_WAN_Listener_Public_Mapping_Resolved_Callback)(
        void *listener_data,
        const NDDS_Transport_Address_t *public_uuid_adress,
        NDDS_Transport_Port_t rtps_port);
 
struct NDDS_Transport_UDP_WAN_Listener {
    void *listener_data;
    NDDS_Transport_UDP_WAN_Listener_Public_Mapping_Resolved_Callback
            on_public_mapping_resolved;
};
 
/* ================================================================= */
/*                  UDP Port                                         */
/* ================================================================= */
/*e \dref_UDPTransport_Port
 */
typedef RTI_UINT16 NDDS_Transport_UDP_Port;
 
#define NDDS_TRANSPORT_UDP_PORT_INVALID (0)
#define NDDS_TRANSPORT_UDP_PORT_MAX (RTI_UINT16_MAX)
 
/* ================================================================= */
/*                  UDP WAN CommPorts                                */
/* ================================================================= */
 
/*e \dref_UDPTransport_WAN_CommPortsMappingInfo
 */
struct NDDS_Transport_UDP_WAN_CommPortsMappingInfo {
    /*e \dref_UDPTransport_WAN_CommPortsMappingInfo_rtps_port
     */
    NDDS_Transport_Port_t rtps_port;
    /*e \dref_UDPTransport_WAN_CommPortsMappingInfo_host_port
     */
    NDDS_Transport_UDP_Port host_port;
    /*e \dref_UDPTransport_WAN_CommPortsMappingInfo_public_port
     */
    NDDS_Transport_UDP_Port public_port;
    /*i
     * CORE-16439: It is possible the before a receive resource has been removed
     * (e.g, interface goes DOWN) the application tries to recreate it again
     * (e.g, interfaces goes UP). In this scenario, if the
     * previous resource is still in the process of being removed the creation
     * of the new resource will fail because it will try to add the same mapping
     * again to the comm_ports_list. To avoid this situation, we keep a
     * reference count of how many receive resources are using this mapping
     * info.
     *
     * See CORE-16439 for additional details.
     *
     * This field is marked as internal as it is not intended to be used
     * by applications.
     */
    int ref_count;
};
 
/* ================================================================= */
/*                  Unicast UDP Properties                           */
/* ================================================================= */
 
struct NDDS_Transport_UDP_Property_t {
    struct NDDS_Transport_Property_t parent;
    RTI_INT32 send_socket_buffer_size;
    RTI_INT32 recv_socket_buffer_size;
    RTI_INT32 unicast_enabled;
    RTI_INT32 multicast_enabled;
    RTI_INT32 multicast_ttl;
    RTI_INT32 multicast_loopback_disabled;
    RTI_INT32 ignore_loopback_interface;
    RTI_INT32 ignore_nonup_interfaces;
    RTI_INT32 ignore_nonrunning_interfaces;
    RTI_INT32 no_zero_copy;
    RTI_INT32 send_blocking;
    RTI_INT32 enable_v4mapped;
    RTI_INT32 use_checksum;
    RTI_UINT32 transport_priority_mask;
    RTI_INT32 transport_priority_mapping_low;
    RTI_INT32 transport_priority_mapping_high;
    RTI_INT32 send_ping;
    RTI_INT32 force_interface_poll_detection;
    RTI_UINT32 interface_poll_period;
    RTI_INT32 reuse_multicast_receive_resource;
    RTI_INT32 protocol_overhead_max;
    RTI_INT32 disable_interface_tracking;
    RTI_UINT32 join_multicast_group_timeout;
    char *public_address;
    struct NDDS_Transport_UDP_WAN_CommPortsMappingInfo *comm_ports_list;
    RTI_INT32 comm_ports_list_length;
    struct NDDS_Transport_UDP_WAN_Listener *wan_listener;
    RTI_INT32 port_offset;
    RTI_UINT32 binding_ping_period;
    /*
     * Maximum time that an orphan binding–ping mapping may exist without being
     * refreshed before it is removed.
     */
    RTI_UINT32 binding_ping_mapping_expiration;
    /*i
     * \brief If this property is set, we use this function to check for an
     * enabled WAN transport. If the function is not set, we would try to load a
     * default shared library with the correct function to enable WAN transport.
     */
    NDDS_Transport_UDP_WAN_Library_Is_Plugin_Enabled_Function
            plugin_enabled_function_ptr;
    /****************** START TESTING ONLY FIELDS *****************/
    /*i
     * \brief If this property is set we will update the send
     * and receive statistics split into participant and endpoint discovery
     * by parsing the packets. We will update the discovery/user packets
     * based on the port number regardless of if this property is set.
     * The default is false for performance reasons and is set to true only
     * for testing purposes.
     */
    RTIBool gather_detailed_statistics;
    /*i
     * \brief If this property is set to TRUE we will check if the guid prefix
     * in the RTPS header matches guid_prefix_to_drop. If it does we will drop
     * the sample.
     */
    RTIBool drop_samples_by_guid_prefix;
    /*i
     * \brief GUID prefix to drop when drop_samples_by_guid_prefix is set to
     * TRUE.
     */
    struct RTIOsapiRtpsGuidPrefix guid_prefix_to_drop;
    /****************** END TESTING ONLY FIELDS *****************/
};
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Default value of NDDS_Transport_Property_t#properties_bitmap.
 */
#define NDDS_TRANSPORT_UDP_PROPERTIES_BITMAP_DEFAULT (0)
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Default value of
 * NDDS_Transport_Property_t#gather_send_buffer_count_max.
 *
 * This is also the maximum value that can be used when instantiating the udp
 * transport.
 *
 * 16 is sufficient for \ndds, but more may improve discovery and reliable
 * performance.
 * Porting note: find out what the maximum gather buffer count is on your OS!
 */
#define NDDS_TRANSPORT_UDP_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT (16)
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Used to specify that os maximum be used to specify socket buffer size.
 *
 * This property, if set, uses the maximum allowable size set in your OS for
 * send and receive socket buffer sizes. If you update the maximum allowable
 * size in your OS setting, then \ndds will automatically pick up that change.
 * This property is not supported on all platforms because not all platforms
 * have maximum values for the size of the send and receive buffers for sockets.
 * If the platform does not support this property, then the property will be
 * set to \ref
 * NDDS_Transport_UDP_Plugin#NDDS_TRANSPORT_UDP_SEND_SOCKET_BUFFER_SIZE_DEFAULT
 * or \ref
 * NDDS_Transport_UDP_Plugin#NDDS_TRANSPORT_UDP_RECV_SOCKET_BUFFER_SIZE_DEFAULT,
 * depending on the property being set.
 * See the Platform Notes to determine if this property is supported on your
 * platform.
 *
 * This value is -2.
 */
#define NDDS_TRANSPORT_UDP_SOCKET_BUFFER_SIZE_OS_MAX \
    RTI_OSAPI_UDP_SOCKET_BUFFER_SIZE_OS_MAX
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Used to specify that os default be used to specify socket buffer size.
 *
 * This property, if set, uses the default size set in your OS for send and
 * receive socket buffer sizes. If you update the default size in your OS
 * settings, then \ndds will automatically pick up that change.
 *
 * This value is -1.
 */
#define NDDS_TRANSPORT_UDP_SOCKET_BUFFER_SIZE_OS_DEFAULT \
    RTI_OSAPI_UDP_SOCKET_BUFFER_SIZE_OS_DEFAULT
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Default value of send_socket_buffer_size.
 *
 * The default value is 2097152 bytes (1048576 bytes on AIX platforms).
 */
#define NDDS_TRANSPORT_UDP_SEND_SOCKET_BUFFER_SIZE_DEFAULT \
    RTI_OSAPI_UDP_SEND_SOCKET_BUFFER_SIZE_DEFAULT
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Default value of recv_socket_buffer_size.
 *
 * The default value is 2097152 bytes (1048576 bytes on AIX platforms).
 */
#define NDDS_TRANSPORT_UDP_RECV_SOCKET_BUFFER_SIZE_DEFAULT \
    RTI_OSAPI_UDP_RECV_SOCKET_BUFFER_SIZE_DEFAULT
 
#define NDDS_TRANSPORT_UDP_DATAGRAM_LENGTH_MAX (65535)
 
/*e \ingroup NDDS_Transport_UDP_Plugin
 * \brief Default value of multicast_ttl.
 */
#define NDDS_TRANSPORT_UDP_MULTICAST_TTL_DEFAULT (1)
 
 
#ifdef RTI_MULTICAST
  #define NDDS_TRANSPORT_UDP_USE_MULTICAST_DEFAULT 1
#else
  #define NDDS_TRANSPORT_UDP_USE_MULTICAST_DEFAULT 0
#endif
 
 
/*e \dref_UDPTransport_IGNORE_LOOPBACK_DISABLED
 */
#define NDDS_TRANSPORT_UDP_IGNORE_LOOPBACK_DISABLED (0)
 
/*e \dref_UDPTransport_IGNORE_LOOPBACK_ENABLED
 */
#define NDDS_TRANSPORT_UDP_IGNORE_LOOPBACK_ENABLED (1)
 
/*e \dref_UDPTransport_IGNORE_LOOPBACK_AUTO
 */
#define NDDS_TRANSPORT_UDP_IGNORE_LOOPBACK_AUTO (-1)
 
 
/*e \dref_UDPTransport_BLOCKING_NEVER
 */
#define NDDS_TRANSPORT_UDP_BLOCKING_NEVER (0)
 
/*e \dref_UDPTransport_BLOCKING_ALWAYS
 */
#define NDDS_TRANSPORT_UDP_BLOCKING_ALWAYS (1)
#define NDDS_TRANSPORT_UDP_BLOCKING_UNICAST_ONLY (2)
 
/*e \dref_UDPTransport_BLOCKING_DEFAULT
 */
#define NDDS_TRANSPORT_UDP_BLOCKING_DEFAULT NDDS_TRANSPORT_UDP_BLOCKING_ALWAYS
 
/* ================================================================= */
/*                   InterfaceListener Class                         */
/* ================================================================= */
 
/*i
 * \defgroup NDDS_Transport_UDP_InterfaceListenerClass
 * NDDS_Transport_UDP_InterfaceListener \ingroup NDDS_Transport_UDP_Plugin
 * \brief Interface for IPv4 or v6 interface acceptance/rejection
 *
 * @mtsafety See NDDS_Transport_UDP_public UML diagram
 *
 * @see NDDS_Transport_UDP_newI
 */
struct NDDS_Transport_UDP_InterfaceListener; /*forward declare */
 
/*i \ingroup NDDS_Transport_UDP_InterfaceListenerClass
 * \brief A user-provided function to be used to filter out particular
 * network interfaces to be used by the Transport Plugin.
 *
 * The user may implement this function and pass it to an
 * instance of a Transport Plugin to reject or accept network
 * interfaces that the plugin offers as ones to use to receive
 * messages.
 *
 * When \ndds contacts other applications, it will provide a list of
 * interfaces that other applications can use to send messages (on a
 * plugin by plugin basis).  The addresses of the interfaces are used
 * as the destination addresses of messages that are sent.  If a plugin
 * rejects one of the available network interfaces, then that interface
 * will not be offered as one to which other plugins should send
 * messages.
 *
 * For interfaces that can be used by the plugin, this function also
 * enables the user to select which interfaces \ndds is allowed to use
 * in sending multicast messages.  The set of interfaces enabled for
 * multicast sending is a subset of the interfaces that can be used for
 * receiving.  That is, an interface cannot be enabled to send
 * multicast messages but disabled for receiving unicast messages.
 *
 * Only IP network interfaces that are "UP" (enabled by the OS and
 * ready to use) will be passed to this filter function.  The ones that
 * are "DOWN" will not be used by definition.
 *
 * @param plugin \st_in The instance of the plugin for which the filter
 * is being called.
 *
 * @param multicast_enabled_out \st_out The filter should set whether
 * or not the plugin is allowed to use this interface for
 * sending/receiving multicast messages.
 *
 * @param interface_in \st_in An interface offered by the plugin as a
 * candidate for receive messages.
 *
 * @return 1 to use the interface.
 *         \c multicast_enabled_out will indicate whether it is also OK
 *         to use the interface to send multicast messages.
 *
 * @return 0 to reject using the interface.
 */
typedef RTI_INT32 (*NDDS_Transport_UDP_Interface_Filter_Fcn)(
        struct NDDS_Transport_UDP_InterfaceListener *self,
        struct NDDS_Transport_UDP *plugin,
        RTI_INT32 *multicast_enabled_out,
        NDDS_Transport_Interface_t *interface_in,
        const char *interface_name_in);
 
/*i \ingroup NDDS_Transport_UDP_InterfaceListenerClass
 * \brief Pure virtual class for the interface listener.
 * RTI does NOT supply a default interface listener
 */
struct NDDS_Transport_UDP_InterfaceListener {
    /* \copydoc NDDS_Transport_UDP_Interface_Filter_Fcn */
    NDDS_Transport_UDP_Interface_Filter_Fcn onInterface;
};
 
/* ================================================================= */
/*                   Socket Factory Class                            */
/* ================================================================= */
/*i
 * \defgroup NDDS_Transport_UDP_SocketFactoryClass
 * NDDS_Transport_UDP_SocketFactory \ingroup NDDS_Transport_UDP_Plugin \brief
 * Interface for socket creation and destruction.
 *
 * @mtsafety See NDDS_Transport_UDP_public UML diagram
 *
 * @see NDDS_Transport_UDP_new
 */
 
/*i
 * \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Interface representation for socket creation and destruction.
 */
struct NDDS_Transport_UDP_SocketFactory;
 
/*i
 * \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Create a new sending socket for the Itransport.
 *
 * @pre a valid UDP transport.
 *
 * @post A valid UDP send socket, that may not necessarily be bound.
 *
 * @param transport_in \b In.  The NDDS_Transport_UDP transport that will use
 * the new socket.  Specific property of the transport, such as the maximum
 * message size allowed, can be queried from the
 * NDDS_Transport_Plugin#property
 *
 * @param interface_address_in \b In. If set, must be the address of
 * a valid interface.  In addition, the socket created should be enabled
 * to send via multicast.  If is NULL, then the socket created will not
 * be enabled to send multicast.
 *
 * @param interface_index_in \b In. If set, must be the index of
 * a valid interface.  In addition, the socket created should be enabled
 * to send via multicast.  If is NULL, then the socket created will not
 * be enabled to send multicast. Interface index is used instead of an
 * interface address in UDPv6.
 *
 * @return Newly created socket descriptor.
 *
 * @mtsafety <<oneThreadAtATime>>
 *
 * @see NDDS_Transport_UDP_SocketFactory_create_send_socket
 * NDDS_Transport_UDP_SocketFactory_Socket_Destroy_Fcn
 */
typedef RTI_INT32 (*NDDS_Transport_UDP_SocketFactory_Send_Socket_Create_Fcn)(
        struct NDDS_Transport_UDP_SocketFactory *me,
        NDDS_Transport_Port_t *port_out,
        const struct NDDS_Transport_UDP *transport_in,
        const NDDS_Transport_Address_t *interface_address_in,
        const int *interface_index_in);
 
/*i
 * \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Create a new receiving socket for the transport, which
 * may be a multicast transport.
 *
 * @pre valid IP unicast transport.
 *
 * @post A valid, bound unicast receive socket.
 *
 * @param port_inout. \b InOut. NOT optional. If
 * NDDS_TRANSPORT_PORT_INVALID, a new, previously unassigned port must
 * be chosen, and the port must be assigned a new value so the caller
 * knows which port it is listening on.  If the port is a valid value,
 * you must attempt to bind to that port, and not proceed in case of
 * failure (such as if the port is already bound).
 *
 * @param transport_in \b In. The transport that wishes to use the
 * socket.  Properties of the IP unicast transport described in
 * NDDS_Transport_UDP_Property_t must be met in "at least" manner.  That
 * is, doing more than requested is allowed (but will lead to waste
 * unless the implementer has other insights which suggests more
 * optimal use of resources), but creation of a socket that cannot meet
 * the minimum requirement will put the system into an inconsistent
 * state.  For example, the receiving socket will be either polled or
 * blocking; if the transport is polled
 * (NDDS_Transport_Plugin_isPolled) it is an error to create a blocking
 * socket.  On the other hand, creating a socket that can buffer more
 * data than requires is allowed.  Specific property of the transport,
 * such as the maximum message size to be buffered, can be queried from
 * the NDDS_Transport_Plugin#property.
 *
 * @param transport_priority_in \b In. transport_priority hint.  The
 * RTI supplied socket factory NDDS_Transport_UDP_SocketFactory does not
 * act on transport_priority.  If you want to implement a
 * transport_priority aware socket factory, either implement your own
 * from scratch or use
 * NDDS_Transport_UDP_SocketFactory_createReceiveSocket and specialize.
 *
 * @param multicast_address_in \b In. Valid if joining a multicast group.
 *
 * @see NDDS_Transport_UDP_SocketFactory_Send_Socket_Create_Fcn
 * NDDS_Transport_UDP_SocketFactory_create_receive_socket
 * NDDS_Transport_UDP_SocketFactory_Socket_Destroy_Fcn
 */
typedef RTI_INT32 (*NDDS_Transport_UDP_SocketFactory_Receive_Socket_Create_Fcn)(
        struct NDDS_Transport_UDP_SocketFactory *me,
        NDDS_Transport_Port_t *port_inout,
        const struct NDDS_Transport_UDP *transport_in,
        const NDDS_Transport_Address_t *multicast_address_in);
 
/*i \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Destroy a previously created socket.
 *
 * @pre Socket no longer used, and no thread blocked on the socket.
 * @post All resources associate with the socket released.
 *
 * @param s_in \b In. socket descriptor.
 *
 * @mtsafety <<oneThreadAtATime>>
 *
 * @see NDDS_Transport_UDP_SocketFactory_destroy_socket
 */
typedef RTI_INT32 (*NDDS_Transport_UDP_SocketFactory_Socket_Destroy_Fcn)(
        struct NDDS_Transport_UDP_SocketFactory *me,
        RTI_INT32 s_in);
 
/*i \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Pure virtual class for the socket factory functionality.
 * RTI supplies the UDP socket factory.
 */
struct NDDS_Transport_UDP_SocketFactory {
    /*e Children: implement this method. */
    NDDS_Transport_UDP_SocketFactory_Send_Socket_Create_Fcn create_send_socket;
 
    /*e Children: implement this method. */
    NDDS_Transport_UDP_SocketFactory_Receive_Socket_Create_Fcn
            create_receive_socket;
 
    /*e Children: implement this method to destroy both the send and
     receive sockets. */
    NDDS_Transport_UDP_SocketFactory_Socket_Destroy_Fcn destroy_socket;
};
 
/*i \ingroup NDDS_Transport_UDP_SocketFactoryClass
 * \brief Convenience to check if the pure virtual methods have all been
 * implemented
 */
#define NDDS_Transport_UDP_SocketFactory_is_valid(m) \
  ((m)->create_send_socket && (m)->create_receive_socket && (m)->destroy_socket)
 
/* ================================================================= */
/*                 IP Socket Factory Class                           */
/* ================================================================= */
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Realization of NDDS_Transport_Get_Class_Name_Fcn_cEA for IPv6
 * transports.
 *
 * Returns the string "udpv4" or "udpv6".
 *
 * @see NDDS_Transport_Get_Class_Name_Fcn_cEA for complete
 * documentation.
 */
extern NDDS_Transport_DllExport const char *
NDDS_Transport_UDP_get_class_name_cEA(NDDS_Transport_Plugin *self);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Realization of NDDS_Transport_String_To_Address_Fcn_cEA for IP
 * transports.
 *
 * Converts a host name string to an address.
 *
 * @param self  NOT USED. May be NULL.
 *
 * @param address_out \st_out The corresponding numerical value in IPv6
 * format.
 *
 * @param address_in \st_in The name of the address. It can be a
 * dot notation name or a host name. If NULL, then the IP address of
 * the localhost will be returned.
 *
 * @see NDDS_Transport_String_To_Address_Fcn_cEA for complete
 * documentation.
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_UDP_string_to_address_cEA(
        NDDS_Transport_Plugin *self,
        NDDS_Transport_Address_t *address_out,
        const char *address_in);
 
/* ================================================================= */
/*                      UDP/IP Transport Plugin                      */
/* ================================================================= */
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Create an instance of a UDP Transport Plugin.
 *
 * An application may create and register multiple instances of this
 * Transport Plugin with \ndds. Multiple instances of the plugin may be useful
 * for partitioning the network interfaces across multiple \ndds domains.
 * However, note that the underlying transport, the operating system's IP layer,
 * is still a "singleton."  For example, if a unicast transport has already
 * bound to a port, and another unicast transport tries to bind to the same
 * port, the second attempt will fail.
 *
 * The transport plugin honors the interface/multicast "white" and "black"
 * lists specified in the NDDS_Transport_UDP_Property_t#parent:
 * - NDDS_Transport_Property_t#allow_interfaces_list,
 * - NDDS_Transport_Property_t#deny_interfaces_list,
 * - NDDS_Transport_Property_t#allow_multicast_interfaces_list,
 * - NDDS_Transport_Property_t#deny_multicast_interfaces_list
 *
 * The format of a string in these lists is assumed to be in standard IPv4
 * dot notation, possibly containing wildcards. For example:
 *       - 10.10.30.232
 *       - 10.10.*.*
 *       - 192.168.1.*
 *       - etc.
 * Strings not in the correct format will be ignored.
 *
 * @param property_in \st_in Desired behavior of this transport. May be
 * NULL for default property.
 *
 * @return A UDP Transport Plugin instance on success; or NULL on failure.
 */
extern NDDS_Transport_DllExport NDDS_Transport_Plugin *NDDS_Transport_UDP_new(
        const struct NDDS_Transport_UDP_Property_t *property_in);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Create an instance of a UDP Transport Plugin.
 *
 * \copydoc NDDS_Transport_UDP_new
 *
 * @param socket_factory_in \st_in The factory that will create all the
 * sockets to be used in the transport.  May be NULL if default factory
 * is to be used.  Only used by RTI internal testing.
 * End users should set this parameter to NULL.
 *
 * @param interface_filter_in \st_in A function that will be used to
 * filter out network interfaces that this plugin can use. May be NULL if
 * default interface listener is to be used. The default listener uses
 * The NDDS_Transport_UDP_Property_t#parent's lists to select the interfaces.
 * Only used by RTI internal testing. End users should set this
 * parameter to NULL.
 *
 * @exception RTI_LOG_MALLOC_FAILURE_d RTI_LOG_CREATION_FAILURE_s
 * RTI_LOG_PRECONDITION_FAILURE RTI_LOG_INIT_FAILURE_s
 */
extern NDDS_Transport_DllExport NDDS_Transport_Plugin *NDDS_Transport_UDP_newI(
        const struct NDDS_Transport_UDP_Property_t *property_in,
        struct NDDS_Transport_UDP_SocketFactory *socket_factory_in,
        struct NDDS_Transport_UDP_InterfaceListener *interface_listener_in);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Realization of NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA
 * for IP transports.
 *
 * Retrieves a list of available network interfaces.
 *
 * @see NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA for complete
 * documentation.
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_UDP_get_receive_interfaces_cEA(
        NDDS_Transport_Plugin *self,
        RTI_INT32 *found_more_than_provided_for_out,
        RTI_INT32 *interface_reported_count_out,
        NDDS_Transport_Interface_t interface_array_inout[],
        RTI_INT32 interface_array_size_in);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Retrieve ignore_loopback property
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_UDP_get_ignore_loopback_interface_status(
        const NDDS_Transport_Plugin *self);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Checks if the provided address is a loopback address or a known
 * interface address.
 *
 * The provided address is an IPv6 address which is internally mapped into a
 * IPv4 socket address (network byte order).
 *
 * Unions are used to force 4-byte allignment of the IPV4 portion of
 * the addresses. Otherwise we risk bus faults if we are ever passed
 * unaligned address arrays.
 */
extern NDDS_Transport_DllExport RTIBool NDDS_Transport_UDP_is_local_address(
        const NDDS_Transport_Plugin *self,
        const NDDS_Transport_Address_t *address_in);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 *  Map transport_priority to an IP_TOS value based on the configured
 *  transport properties.
 *
 *  @brief transport_priority to IP_TOS mapping
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_UDP_map_transport_priority(
        struct NDDS_Transport_UDP_Property_t *property,
        RTI_INT32 transport_priority_in);
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief Size of special "unblock" message
 *
 * When an ReceiveResource is unblocked with
 * NDDS_Transport_unblock_recv_fnc_rrEA, a special unblock
 * message may be sent. This message is guaranteed to be smaller than the
 * minimum RTPS message size.  Higher layer that processes messages
 * returned by netio should throw away messages of this size, as it was
 * intended to unblock a blocked thread only.
 */
#define NDDS_TRANSPORT_UDP_UNBLOCK_MESSAGE_SIZE \
  (4 + 4 + sizeof(NDDS_Transport_Plugin *))
 
/*i \ingroup NDDS_Transport_UDP_Plugin
 * \brief DiffServ max value
 *
 * Maximum value of the DiffServ field in an IP packet
 */
#define NDDS_TRANSPORT_UDP_DIFF_SERV_MAX_VALUE RTI_OSAPI_SOCKET_MAX_DIFF_SERV
 
struct NDDS_Transport_UDP_Statistics {
    /***********************
     *   PUBLIC FIELDS
     ***********************/
    RTI_ATOMIC(RTI_UINT64) user_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) user_bytes_received;
    RTI_ATOMIC(RTI_UINT64) user_packets_sent;
    RTI_ATOMIC(RTI_UINT64) user_packets_received;
    /*
     * discovery_bytes and discovery_packets are calculated using the
     * port number that is sent to/received from. This assumes the port
     * is an even number. When using an odd port number (ie, using an odd
     * domain ID), these statistics will not be calculated correctly.
     * You should not use these members in tests where the domain ID
     * and port numbers may change.
     */
    RTI_ATOMIC(RTI_UINT64) discovery_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) discovery_bytes_received;
    RTI_ATOMIC(RTI_UINT64) discovery_packets_sent;
    RTI_ATOMIC(RTI_UINT64) discovery_packets_received;
    /*
     * participant_discovery_bytes and participant_discovery_packets refer to
     * DATA(P)s or participant bootstrap messages (i.e. messages sent/received
     * by the anonymous participant writer/reader).
     */
    RTI_ATOMIC(RTI_UINT64) participant_discovery_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) participant_discovery_bytes_received;
    RTI_ATOMIC(RTI_UINT64) participant_discovery_packets_sent;
    RTI_ATOMIC(RTI_UINT64) participant_discovery_packets_received;
    /*
     * participant_config_bytes and participant_config_packets refer to
     * participant configuration announcements sent reliably between
     * participants.
     */
    RTI_ATOMIC(RTI_UINT64) participant_config_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) participant_config_bytes_received;
    RTI_ATOMIC(RTI_UINT64) participant_config_packets_sent;
    RTI_ATOMIC(RTI_UINT64) participant_config_packets_received;
    RTI_ATOMIC(RTI_UINT64) automatic_liveliness_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) automatic_liveliness_bytes_received;
    RTI_ATOMIC(RTI_UINT64) automatic_liveliness_packets_sent;
    RTI_ATOMIC(RTI_UINT64) automatic_liveliness_packets_received;
    RTI_ATOMIC(RTI_UINT64) manual_liveliness_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) manual_liveliness_bytes_received;
    RTI_ATOMIC(RTI_UINT64) manual_liveliness_packets_sent;
    RTI_ATOMIC(RTI_UINT64) manual_liveliness_packets_received;
    RTI_ATOMIC(RTI_UINT64) endpoint_discovery_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) endpoint_discovery_bytes_received;
    RTI_ATOMIC(RTI_UINT64) endpoint_discovery_packets_sent;
    RTI_ATOMIC(RTI_UINT64) endpoint_discovery_packets_received;
    /*
     * Overhead statistics are for packets that use a builtin port (so are not
     * user data), but are also not associated with participant or endpoint
     * discovery
     */
    RTI_ATOMIC(RTI_UINT64) overhead_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) overhead_bytes_received;
    RTI_ATOMIC(RTI_UINT64) overhead_packets_sent;
    RTI_ATOMIC(RTI_UINT64) overhead_packets_received;
    RTI_ATOMIC(RTI_UINT64) binding_ping_event_count;
    RTI_ATOMIC(RTI_UINT64) binding_ping_packets_sent;
    RTI_ATOMIC(RTI_UINT64) binding_ping_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) binding_ping_packets_received;
    RTI_ATOMIC(RTI_UINT64) binding_ping_bytes_received;
 
    /*
     * Array of counters, one per DiffServ value. These counters will be
     * incremented based on the received DiffServ values of the UDP packet.
     *
     * If received_priority_count[2] == 45 it means that we have received 45
     * packets with DiffServ value 2.
     *
     * This field is populated only when gather_detailed_statistics is set
     * to 1.
     */
    RTI_ATOMIC(RTI_UINT32)
    received_priority_count[NDDS_TRANSPORT_UDP_DIFF_SERV_MAX_VALUE + 1];
 
    /***********************
     *   PRIVATE FIELDS
     ***********************/
    /*
     * This field is used differently depending on whether or not we are using
     * security. If we are not using security, this field will count the
     * automatic liveliness messages sent and received. If we are using
     * security, this field will count both automatic and manual liveliness
     * messages sent and received.
     */
    RTI_ATOMIC(RTI_UINT64) _liveliness_bytes_sent;
    RTI_ATOMIC(RTI_UINT64) _liveliness_bytes_received;
    RTI_ATOMIC(RTI_UINT64) _liveliness_packets_sent;
    RTI_ATOMIC(RTI_UINT64) _liveliness_packets_received;
};
 
/*i
 * @brief Initializes NDDS_Transport_UDP_Statistics.
 */
NDDS_Transport_DllExport void NDDS_Transport_UDP_Statistics_initialize(
        struct NDDS_Transport_UDP_Statistics *stats);
 
/*i
 * @brief Copies the content of an NDDS_Transport_UDP_Statistics object to
 * another.
 */
NDDS_Transport_DllExport void NDDS_Transport_UDP_copy_statistics(
        struct NDDS_Transport_UDP_Statistics *dst,
        const struct NDDS_Transport_UDP_Statistics *src);
 
/*i
 * @brief Gets transport UDP statistics from self into statistics_out.
 */
NDDS_Transport_DllExport void NDDS_Transport_UDP_get_statistics(
        NDDS_Transport_Plugin *self,
        struct NDDS_Transport_UDP_Statistics *statistics_out);
 
/*i
 * @brief Gets the minimum and maximum transport priorities of the self's send
 * resources.
 */
NDDS_Transport_DllExport void NDDS_Transport_UDP_get_priority_range(
        NDDS_Transport_Plugin *self,
        RTI_INT32 *min_priority,
        RTI_INT32 *max_priority);
 
/*i
 * @brief Prints an address with a leading indent of "indent" spaces and a
 * description string "%s:".
 */
NDDS_Transport_DllExport void NDDS_Transport_UDP_Address_print(
        const NDDS_Transport_Address_t *me,
        const char *desc,
        RTI_INT32 indent);
 
/*i
 * @brief Gets bytes sent by an UDP transport in a time interval from before and
 * after transport statistics.
 */
NDDS_Transport_DllExport RTI_UINT64 NDDS_Transport_UDP_get_bytes_sent(
        const struct NDDS_Transport_UDP_Statistics * const before,
        const struct NDDS_Transport_UDP_Statistics * const after);
 
/*i
 * @brief Gets packets sent by an UDP transport in a time interval from before
 * and after transport statistics.
 */
NDDS_Transport_DllExport RTI_UINT64 NDDS_Transport_UDP_get_packets_sent(
        const struct NDDS_Transport_UDP_Statistics * const before,
        const struct NDDS_Transport_UDP_Statistics * const after);
 
/*i
 * @brief Gets bytes received by an UDP transport in a time interval from
 * before and after transport statistics.
 */
NDDS_Transport_DllExport RTI_UINT64 NDDS_Transport_UDP_get_bytes_received(
        const struct NDDS_Transport_UDP_Statistics * const before,
        const struct NDDS_Transport_UDP_Statistics * const after);
 
/*i
 * @brief Gets packets received by an UDP transport in a time interval
 * from before and after transport statistics.
 */
NDDS_Transport_DllExport RTI_UINT64 NDDS_Transport_UDP_get_packets_received(
        const struct NDDS_Transport_UDP_Statistics * const before,
        const struct NDDS_Transport_UDP_Statistics * const after);
 
/* ================================================================= */
/*                            UDP WAN UUID                           */
/* ================================================================= */
/* Universal Unique IDentifier for a transport UDP_WAN instance. */
typedef struct {
    RTI_UINT8 value[9];
} NDDS_Transport_UDP_WAN_UUID;
 
#define NDDS_Transport_UDP_WAN_UUID_Initializer \
    {{0, 0, 0, 0, 0, 0, 0, 0, 0}}
 
extern NDDS_Transport_DllVariable const NDDS_Transport_UDP_WAN_UUID
        NDDS_Transport_UDP_WAN_UUID_ZERO;
 
extern NDDS_Transport_DllExport RTIBool
NDDS_Transport_UDP_WAN_UUID_is_zero(NDDS_Transport_UDP_WAN_UUID *uuid);
 
extern NDDS_Transport_DllExport RTIBool NDDS_Transport_UDP_WAN_UUID_populate(
        NDDS_Transport_UDP_WAN_UUID *self,
        const struct RTIOsapiRtpsGuidPrefix *guidPrefix,
        RTI_UINT32 hostAddress);
 
/* ================================================================= */
/*                 UDPv4 WAN Transport Adress Flag                   */
/* ================================================================= */
 
typedef RTI_UINT8 NDDS_Transport_UDP_WAN_AddressFlag;
 
 
#define NDDS_TRANSPORT_UDP_WAN_ADDRESS_FLAG_NONE (0)
 
/*
 * The U flag indicates if the locator contains a UUID. While this identifier by
 * itself cannot be directly used to reach the transport instance, the UUID can
 * be mapped to a public IP  address by  other Connext DDS applications and
 * services. Also, a locator can have both, the U flag, and the P flag, enabled
 * simultaneously. Locators with the U flag set are called UUID locators.
 */
#define NDDS_TRANSPORT_UDP_WAN_ADDRESS_FLAG_U (0x01U << 0)
/*
 * The P flag indicates that the locator contains a globally public IP address
 * and public port where a transport instance can be reached. public_ip_address
 * contains the public IP address and public_port contains the public UDP port.
 * The port is always used to receive data and if the B flag is set it is also
 * used to send data. Locators with the P flag set are called PUBLIC locators.
 */
#define NDDS_TRANSPORT_UDP_WAN_ADDRESS_FLAG_P (0x01U << 1)
/*
 * The B flag indicates if the locator is unidirectional or bidirectional.
 * Bidirectional locators can send/receive RTPS traffic. Unidirectional locators
 * can only receive RTPS traffic.
 */
#define NDDS_TRANSPORT_UDP_WAN_ADDRESS_FLAG_B (0x01U << 2)
/*
 * The R flag indicates if the locator is a relay locator provided by a Relay
 * Service. Locators with the R flag set are called RELAY locators.
 */
#define NDDS_TRANSPORT_UDP_WAN_ADDRESS_FLAG_R (0x01U << 3)
 
/* ================================================================= */
/*                 UDPv4 WAN Transport Address Public Port           */
/* ================================================================= */
 
typedef struct {
    RTI_UINT8 network_ordered_value[2];
} NDDS_Transport_UDP_WAN_NetworkPort;
 
#define NDDS_TRANSPORT_UDP_WAN_NETWORK_PORT_INVALID {{0}}
 
/* ================================================================= */
/*                 UDPv4 WAN Transport Address Public Address        */
/* ================================================================= */
 
typedef struct {
    RTI_UINT8 network_ordered_value[4];
} NDDS_Transport_UDP_WAN_NetworkIpv4Address;
 
#define NDDS_TRANSPORT_UDP_WAN_NETWORK_IP_ADDRESS_INVALID {{0}}
 
/* ================================================================= */
/*                 UDPv4 WAN Transport Address                       */
/* ================================================================= */
/*
 * UDPv4_WAN locators use the following NDDS_Transport_Address_t mapping:
 *
 * +-------+-------+-------+-------+
 * | Flags |                       |
 * +-------+                       +
 * |       DDS_Octet UUID[9]       |
 * |               +-------+-------+
 * |               |  public_port  |
 * +-------+-------+-------+-------+
 * | DDS_Octet public_ip_address[4]|
 * +-------+-------+-------+-------+
 */
 
typedef struct {
    NDDS_Transport_UDP_WAN_AddressFlag _flags;
    NDDS_Transport_UDP_WAN_UUID _uuid;
    NDDS_Transport_UDP_WAN_NetworkPort _publicPort;
    NDDS_Transport_UDP_WAN_NetworkIpv4Address _publicAddress;
} NDDS_Transport_UDPv4_WAN_Address;
 
extern NDDS_Transport_DllExport NDDS_Transport_UDP_Port
NDDS_Transport_UDPv4_WAN_Address_get_public_port(
        const NDDS_Transport_UDPv4_WAN_Address *self);
 
extern NDDS_Transport_DllExport NDDS_Transport_UDP_Port
NDDS_Transport_UDPv4_WAN_Address_get_public_port_for_rtps_port(
        const NDDS_Transport_UDPv4_WAN_Address *self,
        NDDS_Transport_Port_t rtps_port,
        RTI_INT32 udp_port_offset);
 
extern NDDS_Transport_DllExport void
NDDS_Transport_UDPv4_WAN_Address_set_public_port(
        NDDS_Transport_UDPv4_WAN_Address *self,
        NDDS_Transport_UDP_Port public_port);
 
extern NDDS_Transport_DllExport RTI_UINT32
NDDS_Transport_UDPv4_WAN_Address_get_public_address(
        const NDDS_Transport_UDPv4_WAN_Address *self);
 
extern NDDS_Transport_DllExport void
NDDS_Transport_UDPv4_WAN_Address_set_public_address(
        NDDS_Transport_UDPv4_WAN_Address *self,
        RTI_UINT32 public_address);
 
extern NDDS_Transport_DllExport void NDDS_Transport_UDP_combine_addresses(
        const NDDS_Transport_Plugin *self,
        NDDS_Transport_Address_t *address_out,
        const NDDS_Transport_Address_t *first_address_in,
        const NDDS_Transport_Address_t *second_address_in);
 
/*i
 * @brief Gets the public address mapping in the provided address for the provided
 * (UUID, RTPS port) tuple.
 *
 * @param self \b In. Plugin, must be WAN.
 * @param address \b Out. Address to populate with the binding ping mapping.
 * @param rtpsPort \b In. Binding ping RTPS port.
 * @param uuid \b In. Binding ping UUID.
 *
 * @return RTI_TRUE if success, RTI_FALSE if error or if the binding ping
 * mapping does not exist.
 */
extern NDDS_Transport_DllExport RTIBool
NDDS_Transport_UDP_get_binding_ping_mapping(
        NDDS_Transport_Plugin *self,
        NDDS_Transport_UDPv4_WAN_Address *address,
        NDDS_Transport_Port_t rtpsPort,
        const NDDS_Transport_UDP_WAN_UUID *uuid);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#include "transport/transport_udp_impl.h"
 
#endif /* transport_udp_h */