RTI Routing Service Version 7.3.0
RTI Routing Service Transformation API

This module describes the Transformation API. More...

Data Structures

struct  RTI_RoutingServiceTransformationPlugin
 Transformation plugin. More...
 

Macros

#define RTI_RoutingServiceTransformationPlugin_initialize(transf)
 Initializes the plugin structure. More...
 

Typedefs

typedef void * RTI_RoutingServiceTransformation
 Transformation. More...
 
typedef struct RTI_RoutingServiceTransformationPlugin *(* RTI_RoutingServiceTransformationPlugin_CreateFcn) (const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that creates a transformation plugin. More...
 
typedef void(* RTI_RoutingServiceTransformationPlugin_DeleteFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that deletes a transformation plugin. More...
 
typedef RTI_RoutingServiceTransformation(* RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, const struct RTI_RoutingServiceTypeInfo *input_type_info, const struct RTI_RoutingServiceTypeInfo *output_type_info, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that creates a route transformation. More...
 
typedef void(* RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that deletes a transformation. More...
 
typedef void(* RTI_RoutingServiceTransformation_TransformFcn) (RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceSample **out_sample_lst, RTI_RoutingServiceSampleInfo **out_info_lst, int *out_count, RTI_RoutingServiceSample *in_sample_lst, RTI_RoutingServiceSampleInfo *in_info_lst, int in_count, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that transforms a sequence of input samples into a sequence of output samples. More...
 
typedef void(* RTI_RoutingServiceTransformation_ReturnLoanFcn) (RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceSample *sample_lst, RTI_RoutingServiceSampleInfo *info_lst, int count, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that returns the loan on the output samples and infos. More...
 
typedef void(* RTI_RoutingServiceTransformation_UpdateFcn) (RTI_RoutingServiceTransformation transformation, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)
 Prototype of the function that updates a transformation configuration. More...
 

Detailed Description

This module describes the Transformation API.

An RTI Routing Service route transforms the incoming data using a transformation, which is an object created by a transformation plugin.

Transformation plugins implement the transformation API described in this module and must be provided as shared libraries that RTI Routing Service will load dynamically.

To register a transformation plugin with RTI Routing Service, you must use the tag <transformation_plugin> within <transformation_library>. For example:

<dds>
    ...
    <transformation_library name="MyTransfLib">
        <transformation_plugin name="MyTransfPlugin">
            <dll>mytransformation</dll>
            <create_function>
               MyTransfPlugin_create
           </create_function>
       </transformation_plugin>
       ...
    </transformation_library>
    ...
    <routing_service>
    ...
    </routing_service>
    ...
</dds>

Once a transformation plugin is registered, an Output can use it to create a data transformation. For example:

<topic_route name="SquareSwitchCoord">
    <input participant="1">
        <topic_name>Square</topic_name>
        <registered_type_name>ShapeType</registered_type_name>
    </input>
    <output>
        <topic_name>Square</topic_name>
        <registered_type_name>ShapeType</registered_type_name>
    </output>
    <transformation plugin_name="MyTransfLib::MyTransPlugin">
        <property>
            <value>
                <element>
                    <name>X</name>
                    <value>Y</value>
                </element>
                <element>
                    <name>Y</name>
                    <value>X</value>
                </element>
            </value>
        </property>
    </transformation>
</topic_route>

For additional information on configuring transformations, see the RTI Routing Service User's Manual.

Development Requirements

Linux or macOS Systems Windows Systems
Shared Library librtirsinfrastructure.so

If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):
libnddsc.so and libnddscore.so
rtirsinfrastructure.dll

If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):
nddsc.dll and nddscore.dll
Header routingservice_transformation.h

If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):
ndds_c.h

Macro Definition Documentation

◆ RTI_RoutingServiceTransformationPlugin_initialize

#define RTI_RoutingServiceTransformationPlugin_initialize (   transf)

Initializes the plugin structure.

This macro must be called to initialize the return value of RTI_RoutingServiceTransformationPlugin_CreateFcn

Parameters
transfPointer to the transformation plugin structure
See also
RTI_RoutingServiceTransformationPlugin_CreateFcn

Typedef Documentation

◆ RTI_RoutingServiceTransformation

Transformation.

A route can transform the incoming data using transformation objects.

The transformation objects are created by transformation plugins.

◆ RTI_RoutingServiceTransformationPlugin_CreateFcn

typedef struct RTI_RoutingServiceTransformationPlugin *(* RTI_RoutingServiceTransformationPlugin_CreateFcn) (const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)

Prototype of the function that creates a transformation plugin.

The name of the function that implements this prototype must be provided to RTI Routing Service using the tag <create_function> when the transformation plugin is registered.

For example:

<plugin_library name="MyTransfLib">
    <transformation_plugin name="MyTransfPlugin">
        <dll>mytransformation</dll>
        <create_function>
           MyTransfPlugin_create
        </create_function>
    </transformation_plugin>
    ...
</plugin_library>

This is the only function that is not part of RTI_RoutingServiceTransformationPlugin.

Required: yes

Parameters
properties<<in>> Configuration properties for the transformation.
env<<inout>> Environment for error indications.
Returns
New plugin instance if successful. Otherwise, NULL.
See also
RTI_RoutingServiceTransformationPlugin_DeleteFcn

◆ RTI_RoutingServiceTransformationPlugin_DeleteFcn

typedef void(* RTI_RoutingServiceTransformationPlugin_DeleteFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, RTI_RoutingServiceEnvironment *env)

Prototype of the function that deletes a transformation plugin.

Transformation plugins are deleted when RTI Routing Service is closed.

Required: yes

Parameters
plugin<<in>> Transformation plugin to be deleted.
env<<inout>> Environment for error indications.
See also
RTI_RoutingServiceTransformationPlugin_CreateFcn

◆ RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn

typedef RTI_RoutingServiceTransformation(* RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, const struct RTI_RoutingServiceTypeInfo *input_type_info, const struct RTI_RoutingServiceTypeInfo *output_type_info, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)

Prototype of the function that creates a route transformation.

This function is called when the route containing the transformation is ready to forward data.

The format associated with the input and output types depends on the format provided by the route adapters.

For the built-in DDS adapter, the format of the types is DDS_TypeCode.

Required: yes

Parameters
plugin<<in>> Transformation plugin that will be used to create the transformation.
input_type_info<<in>> Type information associated with the input samples.
output_type_info<<in>> Type information associated with the output samples.
properties<<in>> Configuration properties for the transformation. These properties corresponds to the properties specified within the tag <transformation>.
env<<inout>> Environment for error indications.
Returns
New transformation if successful. Otherwise, error.
See also
RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn

◆ RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn

typedef void(* RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn) (struct RTI_RoutingServiceTransformationPlugin *plugin, RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceEnvironment *env)

Prototype of the function that deletes a transformation.

This function is called when the route containing the transformation is disabled.

Parameters
plugin<<in>> Transformation plugin that will be used to delete the transformation.
transformation<<in>> Transformation to be deleted.
env<<inout>> Environment for error indications.
See also
RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn

◆ RTI_RoutingServiceTransformation_TransformFcn

typedef void(* RTI_RoutingServiceTransformation_TransformFcn) (RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceSample **out_sample_lst, RTI_RoutingServiceSampleInfo **out_info_lst, int *out_count, RTI_RoutingServiceSample *in_sample_lst, RTI_RoutingServiceSampleInfo *in_info_lst, int in_count, RTI_RoutingServiceEnvironment *env)

Prototype of the function that transforms a sequence of input samples into a sequence of output samples.

When RTI Routing Service is done using the output samples, it will 'return the loan' to the transformation by calling RTI_RoutingServiceTransformation_ReturnLoanFcn.

The number of output samples can be different than the number of input samples.

The format associated with the input and output samples and sample infos depends on the format provided and consumed by the route StreamReader and StreamWriter.

For the built-in DDS adapter, the format of the samples is DDS_DynamicData and the format of the sample info is DDS_SampleInfo.

Required: yes

Parameters
transformation<<in>> Transformation that will transform the samples.
out_sample_lst<<out>> Array that will hold the output samples. This array will be provided by the transformation.
out_info_lst<<out>> Array that will hold the output sample infos. This array will be provided by the transformation.
out_count<<out>> Number of output samples. The value must be greater than or equal to zero.
in_sample_lst<<in>> Array of input samples.
in_info_lst<<in>> Array of input sample infos.
in_count<<in>> Number of input samples.
env<<inout>> Environment for error indications.
See also
RTI_RoutingServiceTransformation_ReturnLoanFcn

◆ RTI_RoutingServiceTransformation_ReturnLoanFcn

typedef void(* RTI_RoutingServiceTransformation_ReturnLoanFcn) (RTI_RoutingServiceTransformation transformation, RTI_RoutingServiceSample *sample_lst, RTI_RoutingServiceSampleInfo *info_lst, int count, RTI_RoutingServiceEnvironment *env)

Prototype of the function that returns the loan on the output samples and infos.

This function is called by RTI Routing Service to indicate that it is done accessing the array of data samples obtained by an earlier invocation of RTI_RoutingServiceTransformation_TransformFcn

Required: yes

Parameters
transformation<<in>> Transformation that owns the samples and sample infos.
sample_lst<<in>> Array of samples.
info_lst<<in>> Array of sample infos.
count<<in>> Number of samples in the array.
env<<inout>> Environment for error indications.

◆ RTI_RoutingServiceTransformation_UpdateFcn

typedef void(* RTI_RoutingServiceTransformation_UpdateFcn) (RTI_RoutingServiceTransformation transformation, const struct RTI_RoutingServiceProperties *properties, RTI_RoutingServiceEnvironment *env)

Prototype of the function that updates a transformation configuration.

Parameters
transformation<<in>> Transformation.
properties<<in>> New configuration properties.
env<<inout>> Environment for error indications.