RTI Connext Traditional C++ API Version 7.1.0
Installing Transport Plugins

Installing and configuring transports used by RTI Connext. More...

Classes

class  NDDSTransportSupport
 <<interface>> The utility class used to configure RTI Connext pluggable transports. More...
 

Typedefs

typedef NDDS_TRANSPORT_HANDLE_TYPE_NATIVE NDDS_Transport_Handle_t
 An opaque type representing the handle to a transport plugin registered with a DDSDomainParticipant. More...
 
typedef NDDS_Transport_Plugin *(* NDDS_Transport_create_plugin) (NDDS_Transport_Address_t *default_network_address_out, const struct DDS_PropertyQosPolicy *property_in)
 Function prototype for creating plugin through DDS_PropertyQosPolicy. More...
 

Functions

DDS_Boolean NDDS_Transport_Handle_is_nil (const NDDS_Transport_Handle_t *self)
 Is the given transport handle the NIL transport handle? More...
 

Variables

const NDDS_Transport_Handle_t NDDS_TRANSPORT_HANDLE_NIL
 The NIL transport handle. More...
 

Detailed Description

Installing and configuring transports used by RTI Connext.

There is more than one way to install a transport plugin for use with RTI Connext:

In the first two cases, the lifecycle of the transport plugin is automatically managed by RTI Connext. In the last case, user is responsible for deleting the transport plugin after the DDSDomainParticipant is deleted. See Transport Lifecycle for details.

Loading Transport Plugins through Property QoS Policy of Domain Participant

On architectures that support dynamic libraries, a non-builtin transport plugin written in C/C++ and built as a dynamic-link library (*.dll/*.so) can be loaded by RTI Connext through the PROPERTY QoS policy settings of the DDSDomainParticipant.

Dynamic libraries are supported on all architectures except INTEGRITY and certain VxWorks platforms. For VxWorks, dynamic libraries are only supported for architectures that are on Pentium/Arm CPUs AND use kernel mode.

The dynamic-link library (and all the dependent libraries) need to be in the library search path during runtime (in the LD_LIBRARY_PATH environment variable on Linux systems, DYLD_LIBRARY_PATH on macOS systems, or Path on Windows systems).

To allow dynamic loading of the transport plugin, the transport plugin must implement the RTI Connext abstract transport API and must provide a function with the signature NDDS_Transport_create_plugin that can be called by RTI Connext to create an instance of the transport plugin. The name of the dynamic library that contains the transport plugin implementation, the name of the function and properties that can be used to create the plugin, and the aliases and network address that are used to register the plugin can all be specified through the PROPERTY QoS policy of the DDSDomainParticipant.

The following table lists the property names that are used to load the transport plugins dynamically:

Properties for dynamically loading and registering transport plugins
Property Name Description Required?
dds.transport.load_plugins Comma-separated strings indicating the prefix names of all plugins that will be loaded by RTI Connext. Up to 8 plugins may be specified. For example, "dds.transport.TCPv4.tcp1, dds.transport.TCPv4.tcp2",
In the following examples, <TRANSPORT_PREFIX> is used to indicate one element of this string that is used as a prefix in the property names for all the settings that are related to the plugin. <TRANSPORT_PREFIX> must begin with "dds.transport." (such as "dds.transport.mytransport").
YES
<TRANSPORT_PREFIX>.library Should be set to the name of the dynamic library (*.so for Linux systems, *.dylib for macOS systems, and *.dll for Windows systems) that contains the transport plugin implementation. This library (and all the other dependent dynamic libraries) needs to be in the library search path used by RTI Connext during run time (pointed to by the environment variable LD_LIBRARY_PATH on Linux systems, DYLD_LIBRARY_PATH on macOS systems, or Path on Windows systems). YES
<TRANSPORT_PREFIX>.create_function Should be set to the name of the function with the prototype of NDDS_Transport_create_plugin that can be called by RTI Connext to create an instance of the plugin. The resulting transport plugin will then be registered by RTI Connext through NDDSTransportSupport::register_transport YES
<TRANSPORT_PREFIX>.aliases Used to register the transport plugin returned by NDDS_Transport_create_plugin (as specified by <TRANSPORT_PREFIX>.create_function) to the DDSDomainParticipant. Refer to aliases_in parameter in NDDSTransportSupport::register_transport for details. Aliases should be specified as a comma-separated string, with each comma delimiting an alias. If it is not specified, <TRANSPORT_PREFIX> –without the leading "dds.transport" – is used as the default alias for the plugin. NO
<TRANSPORT_PREFIX>.network_address Used to register the transport plugin returned by NDDS_Transport_create_plugin (as specified by <TRANSPORT_PREFIX>.create_function) to the DDSDomainParticipant. Refer to network_address_in parameter in NDDSTransportSupport::register_transport for details. If it is not specified, the network_address_out output parameter from NDDS_Transport_create_plugin is used. The default value is a zeroed out network address. NO
<TRANSPORT_PREFIX>.<property_name>

Property that is passed into NDDS_Transport_create_plugin (as specified by <TRANSPORT_PREFIX>.create_function) for creating the transport plugin. This property name-value pair will be passed to NDDS_Transport_create_plugin after stripping out <TRANSPORT_PREFIX> from the property name. The parsing of this property and configuring the transport using this property should be handled by the implementation of each transport plugin. Multiple <TRANSPORT_PREFIX>.<property_name> can be specified.

Note: "library", "create_function", "aliases" and "network_address" cannot be used as the <property_name> due to conflicts with other builtin property names.

NO

A transport plugin is dynamically created and registered to the DDSDomainParticipant by RTI Connext when:

whichever happens first.

Any changes to the transport plugin related properties in the PROPERTY QoS policy after the transport plugin has been registered with the DDSDomainParticipant will have no effect.

See also
Transport Use Cases

Typedef Documentation

◆ NDDS_Transport_Handle_t

typedef NDDS_TRANSPORT_HANDLE_TYPE_NATIVE NDDS_Transport_Handle_t

An opaque type representing the handle to a transport plugin registered with a DDSDomainParticipant.

A transport handle represents the association between a DDSDomainParticipant and a transport plugin.

◆ NDDS_Transport_create_plugin

typedef NDDS_Transport_Plugin *(* NDDS_Transport_create_plugin) (NDDS_Transport_Address_t *default_network_address_out, const struct DDS_PropertyQosPolicy *property_in)

Function prototype for creating plugin through DDS_PropertyQosPolicy.

By specifying some predefined property names in DDS_PropertyQosPolicy, RTI Connext can call a function from a dynamic library to create a transport plugin and register the returned plugin with a DDSDomainParticipant.

This is the function prototype of the function as specified in "<TRANSPORT_PREFIX>.create_function" of DDS_PropertyQosPolicy QoS policy that will be called by RTI Connext to create the transport plugin. See Loading Transport Plugins through Property QoS Policy of Domain Participant for details.

Parameters
default_network_address_out<<out>> Optional output parameter. If the network address is not specified in "<TRANSPORT_PREFIX>.network_address" in DDS_PropertyQosPolicy, this is the default network address that is used to register the returned transport plugin using NDDSTransportSupport::register_transport . This parameter will never be null. The default value is a zeroed-out network address.
property_in<<in>> property_in contains all the name-value pair properties that matches the format "<TRANSPORT_PREFIX>.<property_name>" in DDS_PropertyQosPolicy that can be used to create the transport plugin. Only <property_name> is passed in - the plugin prefix will be stripped out in the property name. Note: predefined <TRANSPORT_PREFIX> properties "library", "create_function", "aliases" and "network_address" will not be passed to this function. This parameter will never be null.
Returns
Upon success, a valid non-NIL transport plugin. NIL upon failure.

Function Documentation

◆ NDDS_Transport_Handle_is_nil()

DDS_Boolean NDDS_Transport_Handle_is_nil ( const NDDS_Transport_Handle_t self)

Is the given transport handle the NIL transport handle?

Returns
DDS_BOOLEAN_TRUE if the given transport handle is equal to NDDS_TRANSPORT_HANDLE_NIL or DDS_BOOLEAN_FALSE otherwise.

Variable Documentation

◆ NDDS_TRANSPORT_HANDLE_NIL

const NDDS_Transport_Handle_t NDDS_TRANSPORT_HANDLE_NIL
extern

The NIL transport handle.