RTI Connext Modern C++ API  Version 7.0.0
NDDS_Transport_Property_t Struct Reference

Base configuration structure that must be inherited by derived Transport Plugin classes. More...

Public Attributes

NDDS_Transport_ClassId_t classid
 The Transport-Plugin Class ID. More...
 
RTI_INT32 address_bit_count
 Number of bits in a 16-byte address that are used by the transport. Should be between 0 and 128. More...
 
RTI_INT32 properties_bitmap
 A bitmap that defines various properties of the transport to the RTI Connext core. More...
 
RTI_INT32 gather_send_buffer_count_max
 Specifies the maximum number of buffers that RTI Connext can pass to the send() method of a transport plugin. More...
 
RTI_INT32 message_size_max
 The maximum size of an RTPS message in bytes that can be sent or received by the transport plugin. More...
 
char ** allow_interfaces_list
 A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., allow_interfaces_list_length > 0), allow the use of only these interfaces. If the list is empty, allow the use of all interfaces. More...
 
RTI_INT32 allow_interfaces_list_length
 Number of elements in the allow_interfaces_list. More...
 
char ** deny_interfaces_list
 A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., deny_interfaces_list_length > 0), deny the use of these interfaces. More...
 
RTI_INT32 deny_interfaces_list_length
 Number of elements in the deny_interfaces_list. More...
 
char ** allow_multicast_interfaces_list
 A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., allow_multicast_interfaces_list_length > 0), allow the use of multicast only on these interfaces; otherwise allow the use of all the allowed interfaces. More...
 
RTI_INT32 allow_multicast_interfaces_list_length
 Number of elements in the allow_multicast_interfaces_list. More...
 
char ** deny_multicast_interfaces_list
 A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., deny_multicast_interfaces_list_length > 0), deny the use of those interfaces for multicast. More...
 
RTI_INT32 deny_multicast_interfaces_list_length
 Number of elements in deny_multicast_interfaces_list. More...
 
struct NDDS_Transport_UUID transport_uuid
 Univocally identifies a transport plugin. More...
 
char * thread_name_prefix
 Prefix used to name the transport threads. More...
 
RTI_INT32 max_interface_count
 Maximum number of addresses from the allow_interfaces_list that will be announced. More...
 

Detailed Description

Base configuration structure that must be inherited by derived Transport Plugin classes.

This structure contains properties that must be set before registration of any transport plugin with RTI Connext. The RTI Connext core will configure itself to use the plugin based on the properties set within this structure.

A transport plugin may extend from this structure to add transport-specific properties.

WARNING: The transport properties of an instance of a Transport Plugin should be considered immutable after the plugin has been created. That means the values contained in the property structure stored as a part of the transport plugin itself should not be changed. If those values are modified, the results are undefined.

Member Data Documentation

◆ classid

NDDS_Transport_ClassId_t NDDS_Transport_Property_t::classid

The Transport-Plugin Class ID.

The transport plugin sets the value for this field.

Class IDs below NDDS_TRANSPORT_CLASSID_RESERVED_RANGE are reserved for RTI (Real-Time Innovations) usage.

User-defined transports should set an ID above this range.

The ID should be globally unique for each Transport-Plugin class. Transport-Plugin implementors should ensure that the class IDs do not conflict with each other amongst different Transport-Plugin classes.

Invariant
The classid is invariant for the lifecycle of a transport plugin.

◆ address_bit_count

RTI_INT32 NDDS_Transport_Property_t::address_bit_count

Number of bits in a 16-byte address that are used by the transport. Should be between 0 and 128.

The transport plugin sets the value for this field.

A transport plugin should define the range of addresses (starting from 0x0) that are meaningful to the plugin. It does this by setting the number of bits of an IPv6 address that will be used to designate an address in the network to which the transport plugin is connected.

For example, for an address range of 0-255, the address_bit_count should be set to 8. For the range of addresses used by IPv4 (4 bytes), it should be set to 32.

See also
Transport Class Attributes

◆ properties_bitmap

RTI_INT32 NDDS_Transport_Property_t::properties_bitmap

A bitmap that defines various properties of the transport to the RTI Connext core.

Currently, the only property supported is whether or not the transport plugin will always loan a buffer when RTI Connext tries to receive a message using the plugin. This is in support of a zero-copy interface.

See also
NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED

◆ gather_send_buffer_count_max

RTI_INT32 NDDS_Transport_Property_t::gather_send_buffer_count_max

Specifies the maximum number of buffers that RTI Connext can pass to the send() method of a transport plugin.

The transport plugin send() API supports a gather-send concept, where the send() call can take several discontiguous buffers, assemble and send them in a single message. This enables RTI Connext to send a message from parts obtained from different sources without first having to copy the parts into a single contiguous buffer.

However, most transports that support a gather-send concept have an upper limit on the number of buffers that can be gathered and sent. Setting this value will prevent RTI Connext from trying to gather too many buffers into a send call for the transport plugin.

RTI Connext requires all transport-plugin implementations to support a gather-send of least a minimum number of buffers. This minimum number is defined to be NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN.

If the underlying transport does not support a gather-send concept directly, then the transport plugin itself must copy the separate buffers passed into the send() call into a single buffer for sending or otherwise send each buffer individually. However this is done by the transport plugin, the receive_rEA() call of the destination application should assemble, if needed, all of the pieces of the message into a single buffer before the message is passed to the RTI Connext layer.

◆ message_size_max

RTI_INT32 NDDS_Transport_Property_t::message_size_max

The maximum size of an RTPS message in bytes that can be sent or received by the transport plugin.

If the maximum size of a message that can be sent by a transport plugin is user configurable, the transport plugin should provide a default value for this property. In any case, this value must be set before the transport plugin is registered, so that RTI Connext can properly use the plugin.

For information about the default value for different transports, see the Core Libraries User's Manual.

◆ allow_interfaces_list

char** NDDS_Transport_Property_t::allow_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., allow_interfaces_list_length > 0), allow the use of only these interfaces. If the list is empty, allow the use of all interfaces.

The "white" list restricts reception to a particular set of interfaces for unicast UDP.

For UDPv4 and UDPv6 transports, the resulting list also controls the interfaces over which the DomainParticipant will send multicast traffic to the remote DomainParticipants (if multicast is supported on the platform).

Note: This property does not affect the interfaces that the transport uses to send unicast data from that DomainParticipant. That decision is made by the OS based on the destination address.

It is up to the transport plugin to interpret the list of strings passed in.

For example, the following are acceptable strings in IPv4 format: 192.168.1.1, 192.168.1.*, 192.168.*, 192.*, ether0

The left-to-right order of this list matters if you are using the max_interface_count to limit the allowable interfaces further. See max_interface_count.

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

The caller (user) must manage the memory of the list. The memory may be freed after the dds::domain::DomainParticipant is deleted.

[default] empty list that represents all available interfaces.

See also
NDDS_Transport_Property_t::max_interface_count

◆ allow_interfaces_list_length

RTI_INT32 NDDS_Transport_Property_t::allow_interfaces_list_length

Number of elements in the allow_interfaces_list.

By default, allow_interfaces_list_length = 0, i.e. an empty list.

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

[default] 0

◆ deny_interfaces_list

char** NDDS_Transport_Property_t::deny_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., deny_interfaces_list_length > 0), deny the use of these interfaces.

This "black" list is applied after the allow_interfaces_list and filters out the interfaces that should not be used.

The resulting list restricts reception to a particular set of interfaces for unicast UDP.

For UDPv4 and UDPv6 transports, the resulting list also controls the interfaces over which the DomainParticipant will send multicast traffic to the remote DomainParticipants (if multicast is supported on the platform).

Note: This property does not affect the interfaces that the transport uses to send unicast data from that DomainParticipant. That decision is made by the OS based on the destination address.

It is up to the transport plugin to interpret the list of strings passed in.

For example, the following are acceptable strings in IPv4 format: 192.168.1.1, 192.168.1.*, 192.168.*, 192.*, ether0

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

The caller (user) must manage the memory of the list. The memory may be freed after the dds::domain::DomainParticipant is deleted.

[default] empty list that represents no denied interfaces.

◆ deny_interfaces_list_length

RTI_INT32 NDDS_Transport_Property_t::deny_interfaces_list_length

Number of elements in the deny_interfaces_list.

By default, deny_interfaces_list_length = 0 (i.e., an empty list).

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

[default] 0

◆ allow_multicast_interfaces_list

char** NDDS_Transport_Property_t::allow_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., allow_multicast_interfaces_list_length > 0), allow the use of multicast only on these interfaces; otherwise allow the use of all the allowed interfaces.

This "white" list sub-selects from the allowed interfaces obtained after applying the allow_interfaces_list "white" list and the deny_interfaces_list "black" list.

After allow_multicast_interfaces_list, the deny_multicast_interfaces_list is applied. Multicast output will be sent and may be received over the interfaces in the resulting list.

If this list is empty, all the allowed interfaces will be potentially used for multicast. It is up to the transport plugin to interpret the list of strings passed in.

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

The caller (user) must manage the memory of the list. The memory may be freed after the dds::domain::DomainParticipant is deleted.

[default] empty list that represents all available interfaces.

◆ allow_multicast_interfaces_list_length

RTI_INT32 NDDS_Transport_Property_t::allow_multicast_interfaces_list_length

Number of elements in the allow_multicast_interfaces_list.

By default, allow_multicast_interfaces_list_length = 0 (i.e., an empty list).

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

[default] 0

◆ deny_multicast_interfaces_list

char** NDDS_Transport_Property_t::deny_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty (i.e., deny_multicast_interfaces_list_length > 0), deny the use of those interfaces for multicast.

This "black" list is applied after allow_multicast_interfaces_list and filters out interfaces that should not be used for multicast.

Multicast output will be sent and may be received over the interfaces in the resulting list.

It is up to the transport plugin to interpret the list of strings passed in.

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

The caller (user) must manage the memory of the list. The memory may be freed after the dds::domain::DomainParticipant is deleted.

[default] empty list that represents no denied interfaces.

◆ deny_multicast_interfaces_list_length

RTI_INT32 NDDS_Transport_Property_t::deny_multicast_interfaces_list_length

Number of elements in deny_multicast_interfaces_list.

By default, deny_multicast_interfaces_list_length = 0 (i.e., an empty list).

This property is not interpreted by the RTI Connext core; it is provided merely as a convenient and standardized way to specify the interfaces for the benefit of the transport plugin developer and user.

[default] 0

◆ transport_uuid

struct NDDS_Transport_UUID NDDS_Transport_Property_t::transport_uuid

Univocally identifies a transport plugin.

It represents the prefix of the participant GUID.

◆ thread_name_prefix

char* NDDS_Transport_Property_t::thread_name_prefix

Prefix used to name the transport threads.

This field is optional.

The maximum size of this string is 8 characters.

If "thread_name_prefix" is not set by the user, RTI Connext creates the following prefix: 'r' + 'Tr' + participant identifier + '\0'.

Where 'r' indicates this is a thread from RTI, 'Tr' indicates the thread is related to a transport, and participant identifier contains 5 characters as follows:

If participant_name is set: The participant identifier will be the first 3 characters and the last 2 characters of the participant_name.

If participant_name is not set, then the identifier is computed as domain_id (3 characters) followed by participant_id (2 characters).

If participant_name is not set and the participant_id is set to -1 (defalt value), then the participant identifier is computed as the last 5 digits of the rtps_instance_id in the participant GUID.

◆ max_interface_count

RTI_INT32 NDDS_Transport_Property_t::max_interface_count

Maximum number of addresses from the allow_interfaces_list that will be announced.

By default, max_interface_count = LENGTH_UNLIMITED: all the interfaces are announced.

This feature is useful if you want to control the network interfaces on which your DomainParticipants receive data. For example, if you have one wired and one wireless interface both up and running, and max_interface_count is set to 1, the DomainParticipant will receive data over the interface you list first in the allow_interfaces_list —for example, the wired one.

RTI Connext selects the preferred interface(s) by iterating over the list of allowed interfaces until the first max_interfaces_count of active interfaces encountered are announced. The order of iteration is left to right as specified in the allow_interfaces_list setting.

This setting applies only if the allow_interfaces_list is not empty.

The max_interface_count setting does not consider end-to-end connectivity to select interfaces. The decision is based purely on whether interfaces are up or down in a node. Therefore, this feature is not intended to be used in the following scenarios:

  • A DomainParticipant is not reachable by other DomainParticipants in all the interfaces in the allow_interfaces_list. This could occur if the DomainParticipant is in different subnets, and some of these subnets cannot be reached by other DomainParticipants.
  • End-to-end connectivity issues lead to situations in which the interfaces selected after applying max_interface_count cannot be reached by other DomainParticipants.

For UDPv4 and UDPv6 transports, this feature also affects multicast traffic by limiting the interfaces over which a DomainParticipant sends multicast traffic. The (allow/deny)_multicast_interfaces_list applies to the interfaces selected by using the max_interfaces_count property.

Note: If a pattern string in the allow_interfaces_list matches multiple interface addresses, and max_interface_count is set to a finite value, the order for the matching allowed interfaces is decided based on the order in which the operating system provides these interfaces.

[default] LENGTH_UNLIMITED

See also
NDDS_Transport_Property_t::allow_interfaces_list