transport_interface_user.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_interface_user_h
#define transport_interface_user_h
 
#include "transport/transport_dll.h"
#include "transport/transport_common.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ================================================================= */
/*       Component: Custom Transport Plugin (Abstract)               */
/* ================================================================= */
 
/*i \file
 * \ingroup NDDS_TransportPluginComponent
 * \brief Abstract transport Plugin API visible to the transport plugin user.
 */
 
 
/* ================================================================= */
/*                         Transport Property                        */
/* ================================================================= */
 
/*e \dref_Transport_Property_t
 * \ingroup NDDS_TransportConfigurationComponent
 */
struct NDDS_Transport_Property_t {
    /*e \dref_Transport_Property_t_classid */
    NDDS_Transport_ClassId_t classid;
 
    /*e \dref_Transport_Property_t_address_bit_count */
    RTI_INT32 address_bit_count;
 
    /*e \dref_Transport_Property_t_properties_bitmap */
    RTI_INT32 properties_bitmap;
 
    /*e \dref_Transport_Property_t_gather_send_buffer_count_max */
    RTI_INT32 gather_send_buffer_count_max;
 
    /*e \dref_Transport_Property_t_message_size_max */
    RTI_INT32 message_size_max;
 
    /*e \dref_Transport_Property_t_allow_interfaces_list */
    char **allow_interfaces_list;
 
    /*e \dref_Transport_Property_t_allow_interfaces_list_length */
    RTI_INT32 allow_interfaces_list_length;
 
    /*e \dref_Transport_Property_t_deny_interfaces_list */
    char **deny_interfaces_list;
 
    /*e \dref_Transport_Property_t_deny_interfaces_list_length */
    RTI_INT32 deny_interfaces_list_length;
 
    /*e \dref_Transport_Property_t_allow_multicast_interfaces_list */
    char **allow_multicast_interfaces_list;
 
    /*e \dref_Transport_Property_t_allow_multicast_interfaces_list_length */
    RTI_INT32 allow_multicast_interfaces_list_length;
 
    /*e \dref_Transport_Property_t_deny_multicast_interfaces_list */
    char **deny_multicast_interfaces_list;
 
    /*e \dref_Transport_Property_t_deny_multicast_interfaces_list_length */
    RTI_INT32 deny_multicast_interfaces_list_length;
 
    /*e \dref_Transport_Property_t_transport_uuid */
    struct NDDS_Transport_UUID transport_uuid;
 
    /*i \dref_Transport_Property_t_domain_participant_ptr */
    void *domain_participant_ptr;
 
    /*i \dref_Transport_Property_t_domain_participant_forwarder */
    const struct NDDS_Transport_Plugin_DomainParticipantForwarder
            *domain_participant_forwarder;
 
    /*e \dref_Transport_Property_t_thread_name_prefix */
    char *thread_name_prefix;
 
    /*e \dref_Transport_Property_t_max_interface_count */
    RTI_INT32 max_interface_count;
};
 
/*i
 * @brief Free the memory of the interface list property.
 * @param allowInterfaceList \b In. The list of interfaces.
 * @param allowInterfaceListLength \b In. The length of the list of interfaces.
 */
extern NDDS_Transport_DllExport void
NDDS_Transport_Property_finalize_interface_list(
        char ***allowInterfaceList,
        RTI_INT32 *allowInterfaceListLength);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief  Safely copies NDDS_Transport_Property_t.
 *
 * @return 1 copy was successful, 0 if there is an error.
*/
extern NDDS_Transport_DllExport RTIBool NDDS_Transport_Property_copy(
        struct NDDS_Transport_Property_t *dst,
        const struct NDDS_Transport_Property_t *src);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief Returns NDDS_Transport_Property_t arrays.
 */
extern NDDS_Transport_DllExport void NDDS_Transport_Property_finalize(
        struct NDDS_Transport_Property_t *property);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Used to verify that a NDDS_Transport_Property_t is consistent
 * and valid.
 *
 * @param property_in \st_in
 *
 * @return 1 if the stucture is self-consistent, 0 if there is an error.
*/
extern NDDS_Transport_DllExport RTI_INT32 NDDS_Transport_Property_verify(
        const struct NDDS_Transport_Property_t *property_in);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 * \brief This method returns an array containing the list of valid parent
 * properties which are common for all the transports.
 */
extern NDDS_Transport_DllExport const char **
NDDS_Transport_Property_get_common_properties(void);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 * @brief parse transport Class ID property
 * @param property_value \b In. property value to parse.
 * @param class_id \b Out. Output classId.
 * @return RTI_TRUE if the parsing is done properly, RTI_FLASE otherwise.
 */
extern NDDS_Transport_DllExport RTIBool NDDS_Transport_parse_transport_class_id(
        const char *property_value,
        NDDS_Transport_ClassId_t *class_id);
 
/*i
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Set polled or blocking behavior of transport.
*
 * Some Transport Plugins may support the ability to have polled
 * receive calls as well as blocking receive calls.  This bit allows
 * the instantiator of the plugin to decide in which receive mode that
 * the Transport Plugin instance will run.
*
 * Currently, this ability is supported by the builtin Transport
 * Plugins only for testing purposes.  Thus this bit is not exposed to
 * customers for their own Transport Plugins.
 */
#define NDDS_TRANSPORT_PROPERTY_BIT_POLLED (0x1)
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Specified zero-copy behavior of transport.
 *
 * A Transport Plugin may commit to one of three behaviors for zero copy
 * receives:
 *
 * <OL>
 * <LI>Always does zero copy.
 * <LI>Sometimes does zero copy, up to the transport discretion.
 * <LI>Never does zero copy.
 * </OL>
 *
 * This bit should be set only if the Transport Plugin commits to
 * always doing a zero copy receive, or more specifically, always
 * loaning a buffer through its \c receive_rEA() call.
 *
 * In that case, \ndds will not need to allocate storage for a
 * message that it retrieves with the \c receive_rEA() call.
 *
 * \internal
 * @see \ref NDDS_TransportPlugin_loaning_receive
 */
#define NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED (0x2)
 
/*e
 * \ingroup NDDS_TransportConfigurationComponent
 *
 * \brief Minimum number of gather-send buffers that must be supported by a
 * Transport Plugin implementation.
 *
 * For the NDDS_Transport_Property_t structure to be valid, the value
 * of NDDS_Transport_Property_t#gather_send_buffer_count_max must be
 * greater than or equal to this value.
 *
 * \internal
 * @see \ref NDDS_TransportPlugin_gather_send
 */
#define NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN (3)
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* transport_interface_user_h */