transport_common.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_common_h
#define transport_common_h
 
#include "osapi/osapi_type.h"
#include "osapi/osapi_rtpsGuid.h"
#include "reda/reda_buffer.h"
#include "transport/transport_dll.h"
 
/* Include the APIs useful for the transport plugin user */
#include "transport/transport_common_user.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ================================================================= */
/*                     Fundamental types                             */
/* ================================================================= */
/*i
 * \file
 * \ingroup NDDS_TransportCommonComponent
 * \brief Basic types and macros used by the \ndds Transport Plugin interface.
 */
 
/* Data submessage ID */
#define NDDS_TRANSPORT_UDP_DATA_SUBMESSAGE_ID (0x15)
 
/* OID for SPDP participant announcement writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SPDP_PARTICIPANT_WRITER (0x000100C2)
 
/* OID for SPDP2 bootstrap participant announcement writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SPDP2_PARTICIPANT_BOOTSTRAP_WRITER \
  (0x00010082)
 
/* OID for SPDP2 config participant writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SPDP2_PARTICIPANT_CONFIG_WRITER \
  (0x00010182)
 
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SPDP2_PARTICIPANT_SECURE_CONFIG_WRITER \
  (0xFF010182)
 
/* OID for publications writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_PUB_WRITER (0x000003C2)
 
/* OID for subscriptions writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SUB_WRITER (0x000004C2)
 
/* OID for publications reader */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_PUB_READER (0x000003C7)
 
/* OID for subscriptions reader */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SUB_READER (0x000004C7)
 
/* OID for liveliness writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_P2P_PARTICIPANT_LIVELINESS_WRITER \
  (0x000200C2)
 
/* OID for secure liveliness writer */
#define NDDS_TRANSPORT_RTPS_OBJECT_ID_SECURE_P2P_PARTICIPANT_LIVELINESS_WRITER \
  (0xFF0200C2)
 
/* Auto liveliness kind */
#define NDDS_TRANSPORT_INTER_PARTICIPANT_MESSAGE_KIND_AUTOMATIC_LIVELINESS_UPDATE \
  (0x00000001)
 
/* Manual livelienss kind */
#define NDDS_TRANSPORT_INTER_PARTICIPANT_MESSAGE_KIND_MANUAL_LIVELINESS_UPDATE \
  (0x00000002)
 
/* ================================================================= */
/*                         Port Type                                 */
/* ================================================================= */
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Type for storing \ndds RTPS ports.
 *
 * Unlike IPv4 Socket API ports, which are 2 bytes long, the \ndds
 * representation of an RTPS port is 4 bytes.
 */
typedef RTI_UINT32 NDDS_Transport_Port_t;
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Port 0 is considered to be invalid.
 */
#define NDDS_TRANSPORT_PORT_INVALID ((NDDS_Transport_Port_t) 0)
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 * Represents a port that is shared across multiple users.
 */
struct NDDS_Transport_SharedPort_t {
    NDDS_Transport_Port_t port;
    int ref_count;
};
 
/* ================================================================= */
/*                         UUID Type                                 */
/* ================================================================= */
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Size of a NDDS_Transport_UUID.
 */
#define NDDS_TRANSPORT_UUID_SIZE 12
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Represent an unlimited length
 */
#define NDDS_TRANSPORT_LENGTH_UNLIMITED -1
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Rank interface as unknown or not yet set
 */
#define NDDS_TRANSPORT_INTERFACE_RANK_UNKNOWN 0
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Unequivocally identifies a transport plugin instance.
 */
struct NDDS_Transport_UUID {
    unsigned char value[NDDS_TRANSPORT_UUID_SIZE];
};
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Value for UUIDs that have no known value. Used as default.
 */
#define NDDS_TRANSPORT_UUID_UNKNOWN \
  { \
    { \
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 \
    } \
  }
 
/* ================================================================= */
/*                 (Network) Interface Type                          */
/* ================================================================= */
/*e
 * \defgroup NDDS_Transport_Interface_t Interface
 * \ingroup NDDS_TransportCommonComponent
 * \brief Abstraction of a Transport Plugin network interface.
 *
 * A Transport Plugin may be able to use several logical or physical
 * network interfaces in a single node (machine).  For example, there
 * may be multiple NICs for IP networks or multiple serial ports for
 * serial networks.
 *
 * An instance of a Transport Plugin is a conduit to one or more network
 * interfaces associated with the transport.
 *
 * Instances of a Transport Plugin must assign a unique unicast
 * address to each of the network interfaces that it can use to send
 * and receive messages.  The unicast address should be within the
 * range of addresses that are addressable by the Transport Plugin (as
 * defined by the plugin itself).
 *
 * Then, when \ndds sends a message to an unicast destination address,
 * the destination address will be made of two parts.  The network
 * address and an interface address.  The network address portion will
 * be used by \ndds to select the Transport Plugin instance that will
 * send the message.  The interface address portion is passed to the
 * Transport Plugin instance as the destination interface to which the
 * message should be sent.
 *
 * @see NDDS_Transport_Address_t NDDS_Transport_ClassId_t
 */
 
/*e
  \ingroup NDDS_Transport_Interface_t
  \brief Interface status
 */
typedef enum {
    /*e
     * \brief The transport interface is OFF.
     */
    NDDS_TRANSPORT_INTERFACE_OFF = 0,
    /*e
     * \brief The transport interface is ON.
     */
    NDDS_TRANSPORT_INTERFACE_ON = 1
} NDDS_Transport_Interface_Status_t;
 
/*e
 * \ingroup NDDS_Transport_Interface_t
 * \brief Storage for the description of a network interface used by a
 * Transport Plugin.
 */
typedef struct {
    /*e
     * \brief The transport classid of the interface.
     */
    NDDS_Transport_ClassId_t transport_classid;
 
    /*e
     * \brief An unicast address that uniquely identifies this
     * interface in the network specified by the transport class.
     */
    NDDS_Transport_Address_t address;
 
    /*e
     * \brief The state of the interface
     */
    NDDS_Transport_Interface_Status_t status;
 
    /*e
     * \brief Rank of the interface. Used when allow_interfaces_list Qos is set.
     * A rank value will be assigned to each of the interfaces that match the
     * allow_interfaces_list filter allowing an endpoint to prioritize some
     * interfaces upon others.
     */
    RTI_UINT16 rank;
 
} NDDS_Transport_Interface_t;
 
#define NDDS_TRANSPORT_INTERFACE_INITIALIZER \
  { \
    NDDS_TRANSPORT_CLASSID_INVALID, \
            NDDS_TRANSPORT_ADDRESS_INVALID_INITIALIZER, \
            NDDS_TRANSPORT_INTERFACE_OFF, \
            NDDS_TRANSPORT_INTERFACE_RANK_UNKNOWN \
  }
 
/*i
 * \ingroup NDDS_Transport_Interface_t
 * \brief Prints the contents of an interface to standard out.
 *
 * @param interface_in \st_in Interface to be printed.
 * @param desc_in    \st_in A prefix to be printed before the interface.
 * @param indent_in  \st_in Indentation level for the printout.
 */
extern NDDS_Transport_DllExport void NDDS_Transport_Interface_print(
        const NDDS_Transport_Interface_t *interface_in,
        const char *desc_in,
        RTI_INT32 indent_in);
 
/*i
 * \ingroup NDDS_Transport_Interface_t
 * \brief Copy an interface from the source to the destination.
 *
 * @param dst_out \st_out From where the Interface is copied.
 * @param src_in  \st_in  To where the Interface is copied.
 */
extern NDDS_Transport_DllExport void NDDS_Transport_Interface_copy(
        NDDS_Transport_Interface_t *dst_out,
        const NDDS_Transport_Interface_t *src_in);
 
#define NDDS_TRANSPORT_CONTEXT_INVALID \
  { \
    NDDS_TRANSPORT_ADDRESS_INVALID_INITIALIZER, \
    NDDS_TRANSPORT_ADDRESS_INVALID_INITIALIZER, \
    NDDS_TRANSPORT_PORT_INVALID, \
    NDDS_TRANSPORT_PORT_INVALID, \
    NDDS_TRANSPORT_PORT_INVALID, \
    NDDS_TRANSPORT_CLASSID_INVALID \
  }
 
/*i
 * \ingroup NDDS_TransportCommonComponent
 * @brief Holds the transport information to be used by Network Capture.
 *
 * This struct is first filled by the transport (then associated to a
 * RTINetioMessage if it is inbound traffic) and finally given as input to
 * RTINetioCapManager_enqueueRtpsFrame.
 */
struct NDDS_Transport_Context_t {
    /*i
     * @brief Source address of the message.
     */
    NDDS_Transport_Address_t sourceAddress;
    /*i
     * @brief Destination address of the message.
     */
    NDDS_Transport_Address_t destinationAddress;
    /*i
     * @brief source port of the message.
     */
    NDDS_Transport_Port_t sourcePort;
    /*i
     * @brief Destination port of the message.
     * In the case of TCP, if participant is acting as server,
     * this is the server bind port.
     */
    NDDS_Transport_Port_t destinationPort;
    /*i
     * @brief RTPS port when TCP and participant acting as server.
     * Otherwise, destinationRTPSPort is equal to 0 and we are assuming
     * destinationRTPSPort==destinationPort.
     */
    NDDS_Transport_Port_t destinationRTPSPort;
    /*i
     * @brief Transport class Id. This information is filled by netio.
     */
    NDDS_Transport_ClassId_t classId;
};
 
/* ================================================================= */
/*                         Transport Priority                        */
/* ================================================================= */
/*i
 * \defgroup NDDS_TransportPriority Transport Priority
 * \ingroup NDDS_TransportCommonComponent
 *
 * \brief A QoS set in DDS DataWriters, \idref_TransportPriorityQosPolicy
 * that is passed to the Transport Plugin when creating SendResources.
 *
 * Sometimes also referred to as Transport QoS or CoS (class of
 * service), a transport priority at the Transport Plugin level is
 * directly set by the value of the \idref_TransportPriorityQosPolicy
 * set on DataWriters. The \ndds core will pass the value of the
 * \idref_TransportPriorityQosPolicy to the \c share/create SendResource
 * functions of the Transport API when a DataWriter is created.
 *
 * The \ndds core itself does not do anything with the transport priority
 * except passing it from the user code that set the value via the DDS
 * API to the Transport API.
 *
 * Only Transport Plugin implementations that have the concept of
 * sending of messages at different priorities or with different
 * classes of service (CoSs) will find this support useful.  It is up
 * to each implementation to use the transport priority in what ever
 * way it can to configure itself.  Transport Plugins implementations
 * that do not have a concept of sending data with different priorities
 * can ignore it.
 *
 * For example, TCP/IP-based plugins may offer the user application the
 * ability to specify different CoS for DataWriters so that individual
 * message streams may be treated differently by the physical transport
 * itself.
 */
 
/*i
 * \ingroup NDDS_TransportPriority
 * \brief The default value of the transport_priority.
 */
#define NDDS_TRANSPORT_PRIORITY_DEFAULT (0)
 
/* ================================================================= */
/*                         Buffer Type                               */
/* ================================================================= */
/*i \ingroup NDDS_TransportCommonComponent
 * \brief Generic buffer to hold data, described by a pointer to the
 * data and length of the data.
 */
#ifdef DOXYGEN_DOCUMENTATION_ONLY
typedef struct {
    /*i @brief Length of the buffer pointed to by pointer. */
    RTI_INT32 length;
    /*i @brief Pre-allocated (by the caller) buffer. */
    char *pointer;
} NDDS_Transport_Buffer_t;
#endif
typedef struct REDABuffer NDDS_Transport_Buffer_t;
 
/*
 * Structure subject to hidden padding in 64bit build,
 * so use field compare instead of memory compare.
 */
#define NDDS_Transport_Buffer_t_compare(transportBuffer1, transportBuffer2) \
  (((transportBuffer1)->length < (transportBuffer2)->length) \
           ? -1 \
           : (((transportBuffer1)->length > (transportBuffer2)->length) \
                      ? 1 \
                      : (((transportBuffer1)->pointer \
                          < (transportBuffer2)->pointer) \
                                 ? -1 \
                                 : (((transportBuffer1)->pointer \
                                     > (transportBuffer2)->pointer) \
                                            ? 1 \
                                            : 0))))
 
extern NDDS_Transport_DllExport RTIBool NDDS_Transport_get_address(
        char *addresses_str_out,
        size_t addresses_str_buffer_size_in,
        const char *list,
        RTI_UINT32 index);
 
extern NDDS_Transport_DllExport RTIBool
NDDS_Transport_get_number_of_addresses_in_string(
        RTI_UINT32 *number_out,
        const char *list);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#include "transport/transport_common_impl.h"
 
#endif /* transport_common_h */