|
RTI Routing Service
Version 6.1.2
|
This module describes the C Adapter API. More...
Data Structures | |
| struct | RTI_RoutingServiceStreamReaderListener |
| StreamReader listener used to notify Routing Service that new data is available. More... | |
| struct | RTI_RoutingServiceAdapterPlugin |
| Adapter plugin. More... | |
Macros | |
| #define | RTI_RoutingServiceAdapterPlugin_initialize(adapter) |
| Initializes the adapter plugin structure. More... | |
Variables | |
| RTI_RoutingServiceStreamReaderListener_OnDataAvailableCallback | RTI_RoutingServiceStreamReaderListener::on_data_available |
| Prototype of the callback used to notify of new samples. More... | |
This module describes the C Adapter API.
Adapters are pluggable components that allow RTI Routing Service to consume and produce data for different data domains (e.g., Connext DDS, MQTT, Socket, etc.).
By default, Routing Service is distributed with a builtin DDS adapter. Any other adapter plugins must be provided as external components registered through the XML configuration or through the service API.
The following figure shows an overview of the Routing Service adapter.
Input adapters are used to collect data samples from different data domains, such as DDS or MQTT. The input samples are processed by the Routing Service engine and are passed along to output adapters through the Processor, applying any Transformation beforehand if present.
For additional details about Adapter configuration see the RTI Routing Service User's Manual.
| Linux/macOS Systems | Windows Systems | |
|---|---|---|
| Shared Libraries | librtirsinfrastructure.so | rtirsinfrastructure.dll |
| ^ | libnddsc.so | nddsc.dll |
| ^ | libnddscore.so | nddscore.dll |
| Headers | routingservice_adapter.h |
The Adapter architecture is shown in the class diagram below.
The sequence diagram in this figure shows when the different adapter entities are created.
A Route cannot forward data until the type representations (e.g., TypeCode) associated with the input and output streams are available.
If a Route refers to types that are not defined in the configuration file, RTI Routing Service has to discover their type representation (e.g., TypeCode) before creating the RTI_RoutingServiceStreamReader and RTI_RoutingServiceStreamWriter. The adapter discovery API is used to provide stream and type information in a data domain to Routing Service*.
The discovery API consists of the following methods:
These methods provide access to RTI_RoutingServiceStreamReader used to discover streams in the data domain associated with a connection.
The input stream discovery RTI_RoutingServiceStreamReader provides information about input streams. An input stream is a stream from which an input's RTI_RoutingServiceStreamReader reads data. Notification of disposed scenarios, where an input stream disappears, are also made using the input stream discovery StreamReader.
In the builtin DDS adapter, the input stream discovery StreamReader is associated with the publication builtin DataReader of the DomainParticipant.
The output stream discovery RTI_RoutingServiceStreamReader provides information about output streams. An output stream is a stream to which an output's RTI_RoutingServiceStreamWriter can write data. Notification of disposed scenarios, where an output stream disappears, are also made using the output stream discovery StreamReader.
In the builtin DDS adapter, the output stream discovery StreamReader is associated with the subscription builtin DataReader of the DomainParticipant.
The samples provided by the stream discovery StreamReaders have the type RTI_RoutingServiceStreamInfo.
| #define RTI_RoutingServiceAdapterPlugin_initialize | ( | adapter | ) |
Initializes the adapter plugin structure.
This macro must be called to initialize the return value of RTI_RoutingServiceAdapterPlugin_CreateFcn
| adapter | Pointer to the adapter plugin structure |
| typedef void* RTI_RoutingServiceStreamWriter |
StreamWriter.
A StreamWriter provides a way to write samples of a specific type in a data domain.
In the XML configuration file, StreamWriters are associated with the tag <output> within <route> and <auto_route>.
The StreamWriter type is a typedef to a 'void *' pointer. The concrete implementation is up to the adapter implementor.
| typedef int(* RTI_RoutingServiceStreamWriter_WriteFcn) (RTI_RoutingServiceStreamWriter stream_writer, const RTI_RoutingServiceSample *sample_list, const RTI_RoutingServiceSampleInfo *info_list, int count, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that writes a collection of data samples to an output stream.
Required: Only when the adapter is used to write data.
| stream_writer | <<in>> Stream writer. |
| sample_list | <<in>> Array of samples. The data representation associated with the samples will be given by the value of the connection attribute com.rti.routingservice.adapter.data_representation_kind that is obtained using the associated RTI_RoutingServiceStreamInfo. |
| info_list | <<in>> Array of sample infos. The info representation associated with the sample infos will be given by the value of the connection attribute com.rti.routingservice.adapter.info_representation_kind that is obtained using the associated RTI_RoutingServiceStreamInfo. |
| count | <<in>> Number of samples in the sample list |
| env | <<inout>> Environment for error indications. |
| typedef void* RTI_RoutingServiceStreamReader |
StreamReader.
A StreamReader provides a way to read samples of a specific type from a data domain.
In the XML configuration file, StreamReaders are associated with the tag <input> within <route> and <auto_route>.
The StreamReader type is a typedef to a 'void *' pointer. The concrete implementation is up to the adapter implementor.
| typedef void(* RTI_RoutingServiceStreamReaderListener_OnDataAvailableCallback) (RTI_RoutingServiceStreamReader stream_reader, void *listener_data) |
Prototype of the callback used to notify of new samples.
When a StreamReader receives new data, it will use this callback to notify RTI Routing Service that there are new samples.
Required: Only when the adapter is used to read data.
| stream_reader | <<in>> Stream reader. |
| listener_data | <<inout>> Data associated with the listener when the listener is set. |
| typedef void(* RTI_RoutingServiceStreamReader_ReadFcn) (RTI_RoutingServiceStreamReader stream_reader, RTI_RoutingServiceSample **sample_list, RTI_RoutingServiceSampleInfo **info_list, int *count, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that reads a collection of data samples and sample infos from an input stream.
When RTI Routing Service is done using the samples, it will 'return the loan' to the StreamReader by calling RTI_RoutingServiceStreamReader_ReturnLoanFcn.
Required: Only when the adapter is used to read data.
| stream_reader | <<in>> Stream reader. |
| sample_list | <<out>> Array that will hold the output samples. This array will be provided by the StreamReader. The contents of the array are typically structures of the type DDS_DynamicData (see the RTI Connext documentation). But in general, the data representation associated with the output samples will be given by the value of the connection attribute com.rti.routingservice.adapter.data_representation_kind that is obtained using the associated RTI_RoutingServiceStreamInfo. |
| info_list | <<out>> Array that will hold the output sample infos. This array will be provided by the StreamReader. It can be NULL if there is no info associated to the samples. The contents of the array are typically structures of the type DDS_SampleInfo (see the RTI Connext documentation). But in general the info representation associated with the output sample infos will be given by the value of the connection attribute com.rti.routingservice.adapter.info_representation_kind that is obtained using the associated RTI_RoutingServiceStreamInfo. |
| count | <<out>> Number of output samples. The value must be greater than or equal to zero. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceStreamReader_ReturnLoanFcn) (RTI_RoutingServiceStreamReader stream_reader, RTI_RoutingServiceSample *sample_list, RTI_RoutingServiceSampleInfo *info_list, int count, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that returns the loan on the read samples and infos.
RTI Routing Service calls this method to indicate that it is done accessing the collection of data samples and sample infos obtained by an earlier invocation of RTI_RoutingServiceStreamReader_ReadFcn.
Required: Only when the adapter is used to read data.
| stream_reader | <<in>> Stream reader. |
| sample_list | <<in>> Array of samples. |
| info_list | <<in>> Array of infos. |
| count | <<in>> Number of samples in the sample list. |
| env | <<inout>> Environment for error indications. |
| typedef void* RTI_RoutingServiceSession |
Session.
A Session is a concurrency unit within a connection that has an associated set of StreamReaders and StreamWriters. Access to the StreamReaders and StreamWriters in the same Session is serialized by RTI Routing Service.
In the XML configuration file, Sessions are associated with the tag <session> within a domain route. For each <session> tag, RTI Routing Service will create two adapter Sessions, one per connection.
The Session type is a typedef to a 'void *' pointer. The concrete implementation is up to the adapter implementor.
| typedef void* RTI_RoutingServiceConnection |
Connection.
A Connection object provides access to a data domain (such as a DDS domain or a JMS network provider).
In the XML configuration file, Connections are created using the tag <connection> within a DomainRoute.
The Connection type is a typedef to a 'void *' pointer. The concrete implementation is up to the adapter implementor.
| typedef RTI_RoutingServiceSession(* RTI_RoutingServiceConnection_CreateSessionFcn) (RTI_RoutingServiceConnection connection, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that creates a Session.
A Session is a concurrency unit within a Connection that has an associated set of StreamReaders and StreamWriters. Access to the StreamReaders and StreamWriters in the same Session is serialized by RTI Routing Service.
Session objects are created when the associated routing service sessions are enabled.
In the XML configuration file, Sessions are associated with the tag <session> within a domain route.
Required: No
| connection | <<in>> Connection. |
| properties | <<in>> Configuration properties for the Session. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceConnection_DeleteSessionFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceSession session, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that deletes a Session.
Session objects are deleted when the routing service sessions that contain them are disabled.
Required: No
| connection | <<in>> Connection. |
| session | <<in>> Session to be deleted. |
| env | <<inout>> Environment for error indications. |
| typedef RTI_RoutingServiceStreamReader(* RTI_RoutingServiceConnection_CreateStreamReaderFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceSession session, const struct RTI_RoutingServiceStreamInfo *stream_info, const struct RTI_RoutingServiceProperties *properties, const struct RTI_RoutingServiceStreamReaderListener *listener, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that creates a StreamReader.
A StreamReader provides a way to read samples of a specific type from a data domain.
In the XML configuration file, StreamReaders are associated with the tag <input> within <route> or <auto_route>.
This function is called when the route is enabled and the 'creation mode' condition associated with the route's input becomes true.
Required: Only when the adapter is used to read data.
| connection | <<in>> Connection. |
| session | <<in>> Session associated with the StreamReader. This parameter is NULL if Sessions are not used by the adapter. |
| stream_info | <<in>> Name of the stream and type representation. |
| properties | <<in>> Configuration properties for the StreamReader. |
| listener | <<in>> The listener of the StreamReader used to notify the routing service when new data is available. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceConnection_DeleteStreamReaderFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceStreamReader stream_reader, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that deletes a StreamReader.
A StreamReader object is deleted when the route that contains it is disabled, when the 'creation mode' condition associated with the route's input becomes false or when RTI Routing Service is closed.
Required: Only when the adapter is used to read data.
| connection | <<in>> Connection. |
| stream_reader | <<in>> StreamReader to be deleted. |
| env | <<inout>> Environment for error indications. |
| typedef RTI_RoutingServiceStreamWriter(* RTI_RoutingServiceConnection_CreateStreamWriterFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceSession session, const struct RTI_RoutingServiceStreamInfo *stream_info, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that creates a StreamWriter.
A StreamWriter provides a way to write samples of a specific type in a data domain.
In the XML configuration file, StreamWriters are associated with the tag <output> within <route> or <auto_route>.
This function is called when the route is enabled and the 'creation mode' condition associated with the route's output becomes true.
Required: Only when the adapter is used to write data.
| connection | <<in>> Connection. |
| session | <<in>> Session associated with the StreamWriter. This parameter is NULL if Sessions are not used by the adapter. |
| stream_info | <<in>> Name of the stream and type representation. |
| properties | <<in>> Configuration properties for the StreamWriter. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceConnection_DeleteStreamWriterFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceStreamWriter stream_writer, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that deletes a StreamWriter.
A StreamWriter object is deleted when the route or domain route that contains it is disabled, when the 'creation mode' condition associated with the route's output becomes false or when RTI Routing Service is closed.
Required: Only when the adapter is used to write data.
| connection | <<in>> Connection. |
| stream_writer | <<in>> StreamWriter to be deleted. |
| env | <<inout>> Environment for error indications. |
| typedef RTI_RoutingServiceStreamReader(* RTI_RoutingServiceConnection_GetDiscoveryReaderFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that gets a built-in discovery StreamReader.
There are two built-in discovery StreamReaders:
The first StreamReader provides information about output streams. An output stream is a stream to which StreamWriters can write data. Disposed scenarios, where an output streams dissapears, are also notified using this StreamReader.
The second StreamReader provides information about input streams. An input stream is a stream from which StreamReaders can read data. Disposed scenarios, where an output streams dissapears, are also notified using this StreamReader.
The StreamReaderListeners associated with the built-in discovery StreamReaders are provided as parameters to RTI_RoutingServiceAdapterPlugin_CreateConnectionFcn.
Required: No
The implementation of this function is optional. However, if none of the adapters in a domain route implement the discovery API, the routes' types must be declared in the XML configuration file.
| connection | <<in>> Connection. |
| env | <<inout>> Environment for error indications. |
| typedef RTI_RoutingServiceTypeRepresentation(* RTI_RoutingServiceConnection_CopyTypeRepresentationFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceTypeRepresentationKind type_representation_kind, RTI_RoutingServiceTypeRepresentation type_representation, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that copies a type representation.
This function is part of the adapter discovery API and is used by RTI Routing Service to copy the type representation associated with the discovered streams.
Required: No (Tied to the implementation RTI_RoutingServiceConnection_GetDiscoveryReaderFcn).
| connection | <<in>> Connection. |
| type_representation_kind | <<in>> Type representation kind. |
| type_representation | <<in>> Type representation to be copied. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceConnection_DeleteTypeRepresentationFcn) (RTI_RoutingServiceConnection connection, RTI_RoutingServiceTypeRepresentationKind type_representation_kind, RTI_RoutingServiceTypeRepresentation type_representation, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that deletes a type representation.
This function is part of the adapter discovery API.
Required: No (Tied to the implementation RTI_RoutingServiceConnection_GetDiscoveryReaderFcn).
| connection | <<in>> Connection. |
| type_representation_kind | <<in>> Type representation kind. |
| type_representation | <<in>> Type representation to be deleted. |
| env | <<inout>> Environment for error indications. |
| typedef void* RTI_RoutingServiceAdapterEntity |
Adapter entity.
The adapter entities are:
| typedef void(* RTI_RoutingServiceAdapterEntity_UpdateFcn) (RTI_RoutingServiceAdapterEntity entity, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that updates the configuration of an adapter entity.
This function is called when remote administration is used.
Adapter entities that can be updated are:
Required: No. Implement this function only when remote configuration is needed.
| entity | <<in>> Entity. |
| properties | <<in>> New configuration properties. |
| env | <<inout>> Environment for error indications. |
| typedef void(* RTI_RoutingServiceAdapterPlugin_DeleteFcn) (struct RTI_RoutingServiceAdapterPlugin *plugin, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that deletes an adapter plugin.
Adapter plugins are deleted when RTI Routing Service is closed.
Required: yes
| plugin | <<in>> Adapter plugin to be deleted. |
| env | <<inout>> Environment for error indications. |
| typedef struct RTI_RoutingServiceAdapterPlugin*(* RTI_RoutingServiceAdapterPlugin_CreateFcn) (const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env) |
Prototype of the function that creates an adapter plugin.
The name of the function that implements this prototype must be provided to RTI Routing Service using the tag <create_function> when the adapter plugin is registered. For example:
<dds>
...
<plugin_library name="MyAdapterLib">
<adapter_plugin name="MyAdapterPlugin">
<dll>mycadapter</dll>
<create_function>
MyAdapterPlugin_create
</create_function>
</adapter_plugin>
...
</plugin_library>
...
<routing_service>
...
</routing_service>
...
</dds>
Required: yes
| properties | Configuration properties for the adapter. |
| env | <<inout>> Environment for error indications. |
| RTI_RoutingServiceStreamReaderListener_OnDataAvailableCallback RTI_RoutingServiceStreamReaderListener::on_data_available |
Prototype of the callback used to notify of new samples.
When a StreamReader receives new data, it will use this callback to notify RTI Routing Service that there are new samples.
Required: Only when the adapter is used to read data.
| stream_reader | <<in>> Stream reader. |
| listener_data | <<inout>> Data associated with the listener when the listener is set. |