|
RTI Connext .NET API (legacy)
Version 6.1.2
|
APIs related to RTI Connext pluggable transports. More...
Modules | |
| Installing Transport Plugins | |
| Installing and configuring transports used by RTI Connext. | |
| Built-in Transport Plugins | |
| Transport plugins delivered with RTI Connext. | |
| Creating New Transport Plugins | |
| Developing new transport plugins for RTI Connext. | |
APIs related to RTI Connext pluggable transports.
RTI Connext has a pluggable transports architecture. The core of RTI Connext is transport agnostic; it does not make any assumptions about the actual transports used to send and receive messages. Instead, the RTI Connext core uses an abstract "transport API" to interact with the transport plugins which implement that API.
A transport plugin implements the abstract transport API and performs the actual work of sending and receiving messages over a physical transport. A collection of builtin plugins (see Built-in Transport Plugins) is delivered with RTI Connext for commonly used transports. New transport plugins can easily be created, thus enabling RTI Connext applications to run over transports that may not even be conceived yet. This is a powerful capability and that distinguishes RTI Connext from competing middleware approaches.
RTI Connext also provides a set of APIs for installing and configuring transport plugins to be used in an application. So that RTI Connext applications work out of the box, a subset of the builtin transport plugins is preconfigured by default (see DDS::TransportBuiltinQosPolicy). You can "turn-off" some or all of the builtin transport plugins. In addition, you can configure other transport plugins for use by the application.
In order to use a transport plugin instance in an RTI Connext application, it must be registered with a DDS::DomainParticipant. When you register a transport, you specify a sequence of "alias" strings to symbolically refer to the transport plugin. The same alias strings can be used to register more than one transport plugin.
You can register multiple transport plugins with a DDS::DomainParticipant. An alias symbolically refers to one or more transport plugins registered with the DDS::DomainParticipant. Builtin transport plugin instances can be referred to using preconfigured aliases (see TRANSPORT_BUILTIN).
A transport plugin's class name is automatically used as an implicit alias. It can be used to refer to all the transport plugin instances of that class.
You can use aliases to refer to transport plugins, in order to specify:
- the transport plugins to use for discovery (see DDS::DiscoveryQosPolicy::enabled_transports), and for DDS::DataWriter and DDS::DataReader entities (see DDS::TransportSelectionQosPolicy).
- the multicast addresses on which to receive discovery messages (see DDS::DiscoveryQosPolicy::multicast_receive_addresses), and the multicast addresses and ports on which to receive user data (see DDS::DataReaderQos::multicast).
- the unicast ports used for user data (see DDS::TransportUnicastQosPolicy) on both DDS::DataWriter and DDS::DataReader entities.
- the transport plugins used to parse an address string in a locator (Locator Format and NDDS_DISCOVERY_PEERS).
A DDS::DomainParticipant (and contained its entities) start using a transport plugin after the DDS::DomainParticipant is enabled (see DDS::Entity::enable). An entity will use all the transport plugins that match the specified transport QoS policy. All transport plugins are treated uniformly, regardless of how they were created or registered; there is no notion of some transports being more "special" that others.
A transport plugin is owned by whomever creates it. Thus, if you create and register a transport plugin with a DDS::DomainParticipant, you are responsible for deleting it by calling its destructor. Note that builtin transport plugins (TRANSPORT_BUILTIN) and transport plugins that are loaded through the PROPERTY QoS policy (see Loading Transport Plugins through Property QoS Policy of Domain Participant) are automatically managed by RTI Connext.
A user-created transport plugin must not be deleted while it is still in use by a DDS::DomainParticipant. This generally means that a user-created transport plugin instance can only be deleted after the DDS::DomainParticipant with which it was registered is deleted (see DDS::DomainParticipantFactory::delete_participant). Note that a transport plugin cannot be "unregistered" from a DDS::DomainParticipant.
A transport plugin instance cannot be registered with more than one DDS::DomainParticipant at a time. This requirement is necessary to guarantee the multi-threaded safety of the transport API.
If the same physical transport resources are to be used with more than one DDS::DomainParticipant in the same address space, the transport plugin should be written in such a way so that it can be instantiated multiple times—once for each DDS::DomainParticipant in the address space. Note that it is always possible to write the transport plugin so that multiple transport plugin instances share the same underlying resources; however the burden (if any) of guaranteeing multi-threaded safety to access shared resource shifts to the transport plugin developer.
The address bits not used by the transport plugin for its internal addressing constitute its network address bits.
In order for RTI Connext to properly route the messages, each unicast interface in the RTI Connext domain must have a unique address.
The network address for a transport plugin should be chosen such that the resulting fully qualified 128-bit address will be unique in the RTI Connext domain. Thus, if two instances of a transport plugin are registered with a DDS::DomainParticipant, they will be at different network addresses in order for their unicast interfaces to have unique fully qualified 128-bit addresses. It is also possible to create multiple transports with the same network address, as it can be useful for certain use cases; note that this will require special entity configuration for most transports to avoid clashes in resource use (e.g. sockets for UDPv4 transport).