Installing Transport Plugins

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

Data Structures
struct	NDDS_Transport_Support
	<<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 DDS_DomainParticipant. 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...
*NDDS_Transport_Handle_t	NDDS_Transport_Support_register_transport (DDS_DomainParticipant *participant_in, NDDS_Transport_Plugin *transport_in, const struct DDS_StringSeq *aliases_in, const NDDS_Transport_Address_t *network_address_in)
	Register a transport plugin for use with a DDS_DomainParticipant, assigning it a network_address. More...
NDDS_Transport_Handle_t	NDDS_Transport_Support_lookup_transport (DDS_DomainParticipant *participant_in, struct DDS_StringSeq *aliases_out, NDDS_Transport_Address_t *network_address_out, const NDDS_Transport_Plugin *transport_in)
	Look up a transport plugin within a DDS_DomainParticipant. More...
DDS_ReturnCode_t	NDDS_Transport_Support_add_send_route (const NDDS_Transport_Handle_t *transport_handle_in, const NDDS_Transport_Address_t *address_range_in, DDS_Long address_range_bit_count_in)
	Add a route for outgoing messages. More...
DDS_ReturnCode_t	NDDS_Transport_Support_add_receive_route (const NDDS_Transport_Handle_t *transport_handle_in, const NDDS_Transport_Address_t *address_range_in, DDS_Long address_range_bit_count_in)
	Add a route for incoming messages. More...
DDS_ReturnCode_t	NDDS_Transport_Support_get_builtin_transport_property (DDS_DomainParticipant *participant_in, DDS_TransportBuiltinKind builtin_transport_kind_in, struct NDDS_Transport_Property_t *builtin_transport_property_inout)
	Get the properties used to create a builtin transport plugin. More...
DDS_ReturnCode_t	NDDS_Transport_Support_set_builtin_transport_property (DDS_DomainParticipant *participant_in, DDS_TransportBuiltinKind builtin_transport_kind_in, const struct NDDS_Transport_Property_t *builtin_transport_property_in)
	Set the properties used to create a builtin transport plugin. More...
NDDS_Transport_Plugin *	NDDS_Transport_Support_get_transport_plugin (DDS_DomainParticipant *participant_in, const char *alias_in)
	Retrieve a transport plugin registered in a DDS_DomainParticipant by its alias. 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:

• If it is a builtin transport plugin, by specifying a bitmask in DDS_TransportBuiltinQosPolicy (see Built-in Transport Plugins)
• For all other non-builtin transport plugins, by dynamically loading the plugin through PROPERTY QoS policy settings of DDS_DomainParticipant (only supported on architectures that support dynamic libraries, see Loading Transport Plugins through Property QoS Policy of Domain Participant)
• By explicitly creating a transport plugin and registering the plugin with a DDS_DomainParticipant through NDDS_Transport_Support_register_transport (for both builtin and non-builtin plugins)

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

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

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 NDDS_Transport_Support_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 DDS_DomainParticipant. Refer to aliases_in parameter in NDDS_Transport_Support_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 DDS_DomainParticipant. Refer to network_address_in parameter in NDDS_Transport_Support_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 DDS_DomainParticipant by RTI Connext when:

• the DDS_DomainParticipant is enabled,
• the first DataWriter/DataReader is created, or
• you lookup a builtin DataReader (DDS_Subscriber_lookup_datareader),

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

A transport handle represents the association between a DDS_DomainParticipant 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 DDS_DomainParticipant.

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

NDDS_Transport_Support_register_transport()

*NDDS_Transport_Handle_t NDDS_Transport_Support_register_transport	(	DDS_DomainParticipant *	participant_in,
		NDDS_Transport_Plugin *	transport_in,
		const struct DDS_StringSeq *	aliases_in,
		const NDDS_Transport_Address_t *	network_address_in
	)

Register a transport plugin for use with a DDS_DomainParticipant, assigning it a network_address.

A transport plugin instance can be used by exactly one DDS_DomainParticipant at a time.

When a DataWriter/DataReader is created, only those transports already registered to the corresponding DDS_DomainParticipant are available to the DataWriter/DataReader.

Builtin transports can be automatically registered by RTI Connext as a convenience to the user. See Built-in Transport Plugins for details on how to control the builtin transports that are automatically registered.

Precondition

A disabled DDS_DomainParticipant and a transport plugin that will be registered exclusively with it.

Parameters

participant_in	<<in>> A non-null, disabled DDS_DomainParticipant.
transport_in	<<in>> A non-null transport plugin that is currently not registered with another DDS_DomainParticipant.
aliases_in	<<in>> A non-null sequence of strings used as aliases to symbolically refer to the transport plugins. The transport plugin will be "available for use" by a DDS_Entity in the DDS_DomainParticipant if the transport alias list associated with the DDS_Entity contains one of these transport aliases. An empty alias list represents a wildcard and matches all aliases. Alias names for the builtin transports are defined in TRANSPORT_BUILTIN.
network_address_in	<<in>> The network address at which to register this transport plugin. The bits indicated by transport_in.property.address_bit_count will be truncated. The remaining bits are the network address of the transport plugin. (see Transport Class Attributes).

Returns

Upon success, a valid non-NIL transport handle, representing the association between the DDS_DomainParticipant and the transport plugin; a NDDS_TRANSPORT_HANDLE_NIL upon failure.

Note that a transport plugin's class name is automatically registered as an implicit alias for the plugin. Thus, a class name can be used to refer to all the transport plugin instance of that class.

See also

Transport Class Attributes

Transport Network Address

Locator Format

NDDS_DISCOVERY_PEERS

NDDS_Transport_Support_lookup_transport()

NDDS_Transport_Handle_t NDDS_Transport_Support_lookup_transport	(	DDS_DomainParticipant *	participant_in,
		struct DDS_StringSeq *	aliases_out,
		NDDS_Transport_Address_t *	network_address_out,
		const NDDS_Transport_Plugin *	transport_in
	)

Look up a transport plugin within a DDS_DomainParticipant.

The transport plugin should have already been registered with the DDS_DomainParticipant.

Parameters

participant_in	<<in>> A non-null DDS_DomainParticipant.
aliases_out	<<inout>> A sequence of string where the aliases used to refer to the transport plugin symbolically will be returned. null if not interested.
network_address_out	<<inout>> The network address at which to register the transport plugin will be returned here. null if not interested.
transport_in	<<in>> A non-null transport plugin that is already registered with the DDS_DomainParticipant.

Returns

Upon success, a valid non-NIL transport handle, representating the association between the DDS_DomainParticipant and the transport plugin; a NDDS_TRANSPORT_HANDLE_NIL upon failure.

See also

Transport Class Attributes

Transport Network Address

NDDS_Transport_Support_add_send_route()

DDS_ReturnCode_t NDDS_Transport_Support_add_send_route	(	const NDDS_Transport_Handle_t *	transport_handle_in,
		const NDDS_Transport_Address_t *	address_range_in,
		DDS_Long	address_range_bit_count_in
	)

Add a route for outgoing messages.

This function can be used to narrow the range of addresses to which outgoing messages can be sent.

Precondition

A disabled DDS_DomainParticipant.

Parameters

transport_handle_in	<<in>> A valid non-NIL transport handle as a result of a call to NDDS_Transport_Support_register_transport().
address_range_in	<<in>> The outgoing address range for which to use this transport plugin.
address_range_bit_count_in	<<in>> The number of most significant bits used to specify the address range. This function only works for transport plugins that have a positive NDDS_Transport_Property_t::address_bit_count.

Returns

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

See also

Transport Send Route

NDDS_Transport_Support_add_receive_route()

DDS_ReturnCode_t NDDS_Transport_Support_add_receive_route	(	const NDDS_Transport_Handle_t *	transport_handle_in,
		const NDDS_Transport_Address_t *	address_range_in,
		DDS_Long	address_range_bit_count_in
	)

Add a route for incoming messages.

This function can be used to narrow the range of addresses at which to receive incoming messages.

Precondition

A disabled DDS_DomainParticipant.

Parameters

transport_handle_in	<<in>> A valid non-NIL transport handle as a result of a call to NDDS_Transport_Support_register_transport().
address_range_in	<<in>> The incoming address range for which to use this transport plugin.
address_range_bit_count_in	<<in>> The number of most significant bits used to specify the address range. This function only works for transport plugins that have a positive NDDS_Transport_Property_t::address_bit_count.

Returns

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

See also

Transport Receive Route

NDDS_Transport_Support_get_builtin_transport_property()

DDS_ReturnCode_t NDDS_Transport_Support_get_builtin_transport_property	(	DDS_DomainParticipant *	participant_in,
		DDS_TransportBuiltinKind	builtin_transport_kind_in,
		struct NDDS_Transport_Property_t *	builtin_transport_property_inout
	)

Get the properties used to create a builtin transport plugin.

Retrieves the properties that will be used to create a builtin transport plugin.

Precondition

The builtin_transport_property_inout parameter must be of the type specified by the builtin_transport_kind_in.

Parameters

participant_in	<<in>> A valid non-null DDS_DomainParticipant
builtin_transport_kind_in	<<in>> The builtin transport kind for which to retrieve the properties.
builtin_transport_property_inout	<<inout>> The storage area where the retrieved property will be output. The specific type required by the builtin_transport_kind_in must be used.

Returns

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

See also

NDDS_Transport_Support_set_builtin_transport_property()

NDDS_Transport_Support_set_builtin_transport_property()

DDS_ReturnCode_t NDDS_Transport_Support_set_builtin_transport_property	(	DDS_DomainParticipant *	participant_in,
		DDS_TransportBuiltinKind	builtin_transport_kind_in,
		const struct NDDS_Transport_Property_t *	builtin_transport_property_in
	)

Set the properties used to create a builtin transport plugin.

Specifies the properties that will be used to create a builtin transport plugin.

If the builtin transport is already registered when this operation is called, these property changes will not have any effect. Builtin transport properties should always be set before the transport is registered. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition

A disabled DDS_DomainParticipant. The builtin_transport_property_inout parameter must be of the type specified by the builtin_transport_kind_in.

Parameters

participant_in	<<in>> A valid non-null DDS_DomainParticipant that has not been enabled.
builtin_transport_kind_in	<<in>> The builtin transport kind for which to specificy the properties.
builtin_transport_property_in	<<inout>> The new transport property that will be used to the create the builtin transport plugin. The specific type required by the builtin_transport_kind_in must be used.

Returns

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

See also

NDDS_Transport_Support_get_builtin_transport_property()

NDDS_Transport_Support_get_transport_plugin()

NDDS_Transport_Plugin * NDDS_Transport_Support_get_transport_plugin	(	DDS_DomainParticipant *	participant_in,
		const char *	alias_in
	)

Retrieve a transport plugin registered in a DDS_DomainParticipant by its alias.

This method can be used to get a pointer to a transport Plugin that has been registered into the DDS_DomainParticipant.

Parameters

participant_in	<<in>> A non-null DDS_DomainParticipant.
alias_in	<<in>> A non-null string used to symbolically refer to the transport plugins.

Returns

Upon success, a valid non-null pointer to a registered plugin; a null pointer if a plugin with that alias is not registered/found in that participant.

Variable Documentation

NDDS_TRANSPORT_HANDLE_NIL

const NDDS_Transport_Handle_t NDDS_TRANSPORT_HANDLE_NIL

extern

The NIL transport handle.