Configurable IPv4/UDP WAN Transport-Plugin properties. More...

Inheritance diagram for UDPv4WanTransport.Property_t:

Public Member Functions
	Property_t ()

Public Attributes
int	send_socket_buffer_size
	Size in bytes of the send buffer of a socket used for sending. More...

int	recv_socket_buffer_size
	Size in bytes of the receive buffer of a socket used for receiving. More...

int	ignore_loopback_interface
	Prevents the transport plugin from using the IP loopback interface. More...

int	ignore_nonup_interfaces
	[DEPRECATED] Prevents the transport plugin from using a network interface that is not reported as UP by the operating system. More...

int	ignore_nonrunning_interfaces
	Prevents the transport plugin from using a network interface that is not reported as RUNNING by the operating system. More...

int	no_zero_copy
	[DEPRECATED] Prevents the transport plugin from doing a zero copy. More...

int	send_blocking
	Control blocking behavior of send sockets. CHANGING THIS FROM THE DEFAULT CAN CAUSE SIGNIFICANT PERFORMANCE PROBLEMS. More...

int	use_checksum
	Configures whether to send UDP checksum. More...

long	transport_priority_mask
	Set mask for use of transport priority field. More...

int	transport_priority_mapping_low
	Set low value of output range to IPv4 TOS. More...

int	transport_priority_mapping_high
	Set high value of output range to IPv4 TOS. More...

int	send_ping
	Configures whether to send PING messages. More...

int	force_interface_poll_detection
	Forces the interface tracker to use a polling mechanism to detect changes on the UDPv4 interfaces. More...

long	interface_poll_period
	Specifies the period in milliseconds to query for changes in the state of all the interfaces. More...

int	protocol_overhead_max
	Maximum size in bytes of protocol overhead, including headers. More...

int	disable_interface_tracking
	Disables detection of network interface changes. More...

String	public_address
	Public IP address associated with the transport instantiation. More...

TransportUdpWanCommPortsMappingInfoSeq	comm_ports
	Configures the public and private UDP ports that a transport instance uses to receive/send RTPS data. More...

int	port_offset
	Port offset to allow coexistence with built-in UDPv4 transport. More...

long	binding_ping_period
	Specifies the period in milliseconds at which BINDING PINGS messages are sent to keep NAT mappings open. More...

Public Attributes inherited from Transport.Property_t
final int	classid
	The Transport-Plugin Class ID. More...

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

final int	properties_bitmap
	A bitmap that defines various properties of the transport to the RTI Connext core. More...

int	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...

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

final StringSeq	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...

final StringSeq	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...

final StringSeq	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...

final StringSeq	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...

byte []	transport_uuid = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
	Univocally identifies a transport plugin. More...

Additional Inherited Members
Static Public Attributes inherited from Transport.Property_t
static final int	NDDS_TRANSPORT_CLASSID_INVALID = -1
	Invalid Transport Class ID. More...

static final int	NDDS_TRANSPORT_CLASSID_RESERVED_RANGE = 1000
	Transport-Plugin class IDs below this are reserved by RTI. More...

static final int	NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED = 0x2
	Specified zero-copy behavior of transport. More...

static final int	NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN = 3
	Minimum number of gather-send buffers that must be supported by a Transport Plugin implementation. More...

Detailed Description

Configurable IPv4/UDP WAN Transport-Plugin properties.

You can modify the properties in this structure to configure the plugin. However, you must set the properties before the plugin is instantiated.

See also: com.rti.ndds.transport.TransportSupport.set_builtin_transport_property()

Constructor & Destructor Documentation

◆ Property_t()

Property_t ( )

Create an empty UDPv4WanTransport property with default values

Member Data Documentation

◆ send_socket_buffer_size

int send_socket_buffer_size

Size in bytes of the send buffer of a socket used for sending.

See also: com.rti.ndds.transport.UDPv4Transport.Property_t.send_socket_buffer_size

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ recv_socket_buffer_size

int recv_socket_buffer_size

Size in bytes of the receive buffer of a socket used for receiving.

See also: com.rti.ndds.transport.UDPv4Transport.Property_t.recv_socket_buffer_size

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ ignore_loopback_interface

int ignore_loopback_interface

Prevents the transport plugin from using the IP loopback interface.

Currently three values are allowed:

0: Forces local traffic to be sent over loopback, even if a more efficient transport (such as shared memory) is installed (in which case traffic will be sent over both transports).

1: Disables local traffic via this plugin. The IP loopback interface is not used, even if no NICs are discovered. This is useful when you want applications running on the same node to use a more efficient plugin (such as shared memory) instead of the IP loopback.

-1: Automatic. Lets RTI Connext decide between the above two choices.

The current "automatic" (-1) RTI Connext policy is as follows:

If a shared memory transport plugin is available for local traffic and there is a locator on the initial peers list that can use shared memory, the effective value is 1 (i.e., disable UPV4 local traffic).

Otherwise, the effective value is 0 (i.e., use UDPv4 for local traffic also).

[default] -1 Automatic RTI Connext policy based on availability of the shared memory transport.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ ignore_nonup_interfaces

int ignore_nonup_interfaces

[DEPRECATED] Prevents the transport plugin from using a network interface that is not reported as UP by the operating system.

DEPRECATED: this property has no effect. Non-UP interfaces are ignored until they change their status to UP, unless com.rti.ndds.transport.UDPv4WanTransport.Property_t.disable_interface_tracking is set to 1, in which case interfaces are ignored even if they change their status at a later point.

The transport checks the flags reported by the operating system for each network interface upon initialization. An interface that is not reported as UP will not be used. This property allows you to configure the transport to start using even the interfaces that were not reported as UP.

Two values are allowed:

0: Allow the use of interfaces that were not reported as UP.

1: Do not use interfaces that were not reported as UP.

[default] 1

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ ignore_nonrunning_interfaces

int ignore_nonrunning_interfaces

Prevents the transport plugin from using a network interface that is not reported as RUNNING by the operating system.

The transport checks the flags reported by the operating system for each network interface upon initialization. An interface that is not reported as UP will not be used. This property allows the same check to be extended to the IFF_RUNNING flag implemented by some operating systems. The RUNNING flag is defined to mean that "all resources are allocated," and may be off if there is no link detected, e.g., the network cable is unplugged.

Two values are allowed:

0: Do not check the RUNNING flag when enumerating interfaces, just make sure the interface is UP.

1: Check the flag when enumerating interfaces, and ignore those that are not reported as RUNNING. This can be used on some operating systems to cause the transport to ignore interfaces that are enabled but not connected to the network.

[default] 1 (i.e., check RUNNING flag)

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ no_zero_copy

int no_zero_copy

[DEPRECATED] Prevents the transport plugin from doing a zero copy.

DEPRECATED: This property has no effect. By default, this plugin will use the zero copy on OSes that offer it. While this is good for performance, it may sometimes tax the OS resources in a manner that cannot be overcome by the application.

The best example is if the hardware/device driver lends the buffer to the application itself. If the application does not return the loaned buffers soon enough, the node may err or malfunction. In case you cannot reconfigure the H/W, device driver, or the OS to allow the zero copy feature to work for your application, you may have no choice but to turn off zero copy use.

By default this is set to 0, so RTI Connext will use the zero-copy API if offered by the OS.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ send_blocking

int send_blocking

Control blocking behavior of send sockets. CHANGING THIS FROM THE DEFAULT CAN CAUSE SIGNIFICANT PERFORMANCE PROBLEMS.

Currently two values are defined:

NDDS_TRANSPORT_UDPV4_BLOCKING_ALWAYS: Sockets are blocking (default socket options for the operating system).

NDDS_TRANSPORT_UDPV4_BLOCKING_NEVER: Sockets are modified to make them non-blocking. THIS MAY CAUSE SIGNIFICANT PERFORMANCE PROBLEMS.

[default] NDDS_TRANSPORT_UDPV4_BLOCKING_ALWAYS

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ use_checksum

int use_checksum

Configures whether to send UDP checksum.

This property specifies whether the UDP checksum will be computed. On Windows and Linux, the UDP protocol will not set the checksum when use_checksum is set to 0. This is useful when RTPS protocol statistics related to corrupted messages need to be collected through the API com.rti.dds.domain.DomainParticipant.get_participant_protocol_status.

[default] 1 (enabled)

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ transport_priority_mask

long transport_priority_mask

Set mask for use of transport priority field.

This is used in conjunction with com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mapping_low and com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mapping_high to define the mapping from the DDS transport priority (see TRANSPORT_PRIORITY) to the IPv4 TOS field. Defines a contiguous region of bits in the 32-bit transport priority value that is used to generate values for the IPv4 TOS field on an outgoing socket.

For example, the value 0x0000ff00 causes bits 9-16 (8 bits) to be used in the mapping. The value will be scaled from the mask range (0x0000 - 0xff00 in this case) to the range specified by low and high.

If the mask is set to zero, then the transport will not set IPv4 TOS for send sockets.

[default] 0.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ transport_priority_mapping_low

int transport_priority_mapping_low

Set low value of output range to IPv4 TOS.

This is used in conjunction with com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mask and com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mapping_high to define the mapping from the DDS transport priority to the IPv4 TOS field. Defines the low value of the output range for scaling.

Note that IPv4 TOS is generally an 8-bit value.

[default] 0.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ transport_priority_mapping_high

int transport_priority_mapping_high

Set high value of output range to IPv4 TOS.

This is used in conjunction with com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mask and com.rti.ndds.transport.UDPv4WanTransport.Property_t.transport_priority_mapping_low to define the mapping from the DDS transport priority to the IPv4 TOS field. Defines the high value of the output range for scaling.

Note that IPv4 TOS is generally an 8-bit value.

[default] 0xff.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ send_ping

int send_ping

Configures whether to send PING messages.

This property specifies whether to send a PING message before commencing the discovery process. On certain operating systems or with certain switches the initial UDP packet, while configuring the ARP table, can unfortunately be dropped. To avoid dropping the initial RTPS discovery sample, a PING message is sent to preconfigure the ARP table in those environments.

[default] 1 (enabled)

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ force_interface_poll_detection

int force_interface_poll_detection

Forces the interface tracker to use a polling mechanism to detect changes on the UDPv4 interfaces.

When possible, the detection of an IP address change is done asynchronously using the APIs offered by the underlying OS. By setting this property on those OSes, the use of a polling mechanism to detect changes can be forced.

[default] 0 (disabled).

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ interface_poll_period

long interface_poll_period

Specifies the period in milliseconds to query for changes in the state of all the interfaces.

When possible, the detection of an IP address change is done asynchronously using the APIs offered by the underlying OS. If there is no mechanism to do that, the detection will use a polling strategy where the polling period can be configured by setting this property.

[default] 500 milliseconds.

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ protocol_overhead_max

int protocol_overhead_max

Maximum size in bytes of protocol overhead, including headers.

This value is the maximum size, in bytes, of protocol-related overhead. Normally, the overhead accounts for UDP and IP headers. The default value is set to accommodate the most common UDP/IP header size.

Note that when com.rti.ndds.transport.Transport.Property_t.message_size_max plus this overhead is larger than the UDPv4 maximum message size (65535 bytes), the middleware will automatically reduce the effective message_size_max, to 65535 minus this overhead.

[default] 28.

See also: com.rti.ndds.transport.Transport.Property_t.message_size_max

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ disable_interface_tracking

int disable_interface_tracking

Disables detection of network interface changes.

By default, network interface changes are propagated in the form of locators to other applications. This is done to support IP mobility scenarios.

For example, you could start a RTI Connext application with Wi-Fi and move to a wired connection. In order to continue communicating with other applications, this interface change has to be propagated.

In RTI Connext 5.2 (the initial release) and earlier versions of the product, IP mobility scenarios were not supported. 5.2 applications will report errors if they detect locator changes in a DataWriter or DataReader.

You can disable the notification and propagation of interface changes by setting this property to 1.

This way, an interface change in a newer application will not trigger errors in an application running 5.2 or earlier. Of course, this will prevent the new application from being able to detect network interface changes.

[default] 0

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ public_address

String public_address

Public IP address associated with the transport instantiation.

Setting the public IP address is only necessary for the Real-Time WAN Transport associated with an external com.rti.dds.domain.DomainParticipant (publicly reachable) in order to support the two communication scenarios shown in the Figure below.

For an external com.rti.dds.domain.DomainParticipant behind a NAT-enabled router, this address is the public IP address of the router.

When this property is set, the DomainParticipant will announce PUBLIC+UUID locators to other DomainParticipants. These locators are reachable locators because they contain this public IP address.

For additional information on Real-Time WAN Transport locators, see the Core Libraries User's Manual.

WAN Peer-to-Peer Communication with a Participant that has a Public Address

[default] null (the transport will announce UUID locators)

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ comm_ports

TransportUdpWanCommPortsMappingInfoSeq comm_ports

Configures the public and private UDP ports that a transport instance uses to receive/send RTPS data.

Array containing the mapping between "RTPS ports", "UDP receive host ports", and "UDP receive public ports".

When the transport is configured using properties, the port mapping array is provided using a JSON string.

For example:

{
     "default": {"host": 8192, "public": 9678},
     "mappings": [
         {"rtps": 1234, "host": 9999, "public": 5678},
         {"rtps": 1235, "host": 9990, "public": 5679},
     ]
 }

It is also possible to configure the mapping with XML:

<transport_builtin>
     <udpv4_wan>
         <comm_ports>
             <default>
                 <host>8192</host>
                 <public>9678</public>
             </default>
             <mappings>
                 <element>
                     <rtps>1234</rtps>
                     <host>9999</host>
                     <public>5678</public>
                 </element>
                 <element>
                     <rtps>1235</rtps>
                     <host>9990</host>
                     <public>5679</public>
                 </element>
             </mappings>
         </comm_ports>
     </udpv4_wan>
 <transport_builtin> 

For additional information on how to set the value of this property, see the Core Libraries User's Manual.

[default] NULL (The UDP ports used for communications will be derived from the RTPS ports associated with the locators for the DomainParticipant and its Endpoints (DataWriters and DataReaders)).

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ port_offset

int port_offset

Port offset to allow coexistence with built-in UDPv4 transport.

This property allows using the built-in UDPv4 transport and the Real-Time WAN Transport at the same time.

<transport_builtin>
     <mask>UDPv4_WAN|UDPv4</mask>
 </transport_builtin>

When the UDP ports used by Real-Time WAN Transport are not explicitly set, they are calculated as follows: RTPS port + port_offset.

[default] 125

Referenced by UDPv4WanTransport.Property_t.Property_t().

◆ binding_ping_period

long binding_ping_period

Specifies the period in milliseconds at which BINDING PINGS messages are sent to keep NAT mappings open.

Configures the period in milliseconds at which BINDING_PING messages are sent by a local transport instance to a remote transport instance. For example, 1000 means to send BINDING_PING messages every second.

BINDING_PING messages are used on the sending side to open NAT bindings from a local transport instance to a remote transport instance and they are sent periodically to keep the bindings open.

On the receiving side, BINDING_PINGS are used to calculate the public IP transport address of an UUID locator. This address will be used to send data to the locator.

For additional information on the role of BINDING_PING, see the Core Libraries User's Manual.

From a configuration point of view, and to avoid communication disruptions, the period at which a transport instance sends BINDING_PING messages should be smaller than the NAT binding session timeout. This timeout depends on the NAT router configuration.

[default] 1000 (1 sec)

Referenced by UDPv4WanTransport.Property_t.Property_t().

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Property_t()

Member Data Documentation

◆ send_socket_buffer_size

◆ recv_socket_buffer_size

◆ ignore_loopback_interface

◆ ignore_nonup_interfaces

◆ ignore_nonrunning_interfaces

◆ no_zero_copy

◆ send_blocking

◆ use_checksum

◆ transport_priority_mask

◆ transport_priority_mapping_low

◆ transport_priority_mapping_high

◆ send_ping

◆ force_interface_poll_detection

◆ interface_poll_period

◆ protocol_overhead_max

◆ disable_interface_tracking

◆ public_address

◆ comm_ports

◆ port_offset

◆ binding_ping_period