2. Configuration

This section describes how to configure Routing Service Protobuf Trasformation.

All configuration is specified in Routing Service’s XML configuration file.

2.1. Supported Data Types

Routing Service Protobuf Trasformation requires users to specify the name of a “bytes” member that contains a serialized Protocol Buffers message. The plugin can be configured to either:

• deserialize a Protocol Buffers message from the “bytes” member, and convert it to an equivalent DDS data type.

• convert a DDS data type to a Protocol Buffers message and serialize it into the “bytes” member.

The “bytes” member must be one of the following types:

• sequence<octet>

• sequence<char>

• octet[N]

• char[N]

The description of the Protocol Buffers message type must be provided in a descriptor set file, which is a binary file generated by the protoc compiler. The descriptor set file must contain the definition of the target Protocol Buffers message type and all included data types. A suitable file can be generated by using the following command:

protoc --descriptor_set_out=output_file.pb --include_imports your_file.proto

The name of the target Protocol Buffers message type will be automatically derived from the name of the DDS type by replacing all occurrences of :: with .. For example, if the DDS type is MyModule::MyType, the corresponding Protocol Buffers message type will be MyModule.MyType. If the derived name does not match the actual name of the Protocol Buffers message type, users can explicitly specify the name by using property message_type.

2.1.1. Protocol Buffers to DDS Mapping

2.1.1.1. Protocol Buffers User Types

Table 2.1 User Types Mapping

PB Types	DDS Types
message	struct, valuetype
enum	enum

2.1.1.2. Protocol Buffers Primitive Types

Table 2.2 Primitive Types Mapping

PB Types	DDS Types
double	double
float	float
int32, sint32, sfixed32	int32, long, int16, short, int8, char
int64, sint64, sfixed64	int64, long long
uint32, fixed32	uint32, unsigned long, uint16, unsigned short, uint8, octet
uint64, fixed64	uint64, unsigned long long
bool	boolean
string	string
bytes	int8[N], char[N], sequence<int8>, sequence<char>, uint8[N], octet[N], sequence<uint8>, sequence<octet>

2.1.1.3. Protocol Buffers Collections

Table 2.3 Collections Mapping

PB Types	DDS Types
repeated<T>	T[N], sequence<T>
map<K,V>	sequence<MapPair>, MapPair[N]. MapPair must be an aggregate, and it must contain two members, key and value, of types compatible with K and V respectively, e.g.: struct MapPair { K key; V value; };

2.1.2. DDS to Protocol Buffers Mapping

2.1.2.1. DDS User Types

Table 2.4 User Types Mapping

DDS Types	PB Types
struct, valuetype	message
enum	enum
union	Not supported.

2.1.2.2. DDS Primitive Types

Table 2.5 Primitive Types Mapping

DDS Types	PB Types
double	double
float	float
int32, long, int16, short, int8, char	int32, sint32, sfixed32
int64, long long	int64, sint64, sfixed64
uint32, unsigned long, uint16, unsigned short, uint8, octet	uint32, fixed32
uint64, unsigned long long	uint64, fixed64
boolean	bool
string	string
wchar, wstring	Not supported.

2.1.2.3. DDS Collections

Table 2.6 Collections Mapping

DDS Types	PB Types
T[N], sequence<T>	repeated<T>
MapPair[N], MapPair<T>, with struct MapPair { K key; V value; };	repeated<MapPair>, map<K,V>
sequence<SequenceAlias>, SequenceAlias[N], with: typedef sequence<T> SequenceAlias;	Not supported.

2.2. Load the Protobuf Transformation Plugin

Routing Service Protobuf Trasformation must be registered as a Routing Service plugin by using the <transformation_plugin> tag.

The following snippet demonstrates how to register the plugin in the <plugin_library> section of Routing Service’s XML configuration:

<?xml version="1.0"?>
<dds>
    <plugin_library name="MyPlugins">
        <transformation_plugin name="ProtobufTransformation">
            <dll>rtiprotobuftransf</dll>
            <create_function>
                RTI_TSFM_ProtobufTransformationPlugin_create
            </create_function>
        </transformation_plugin>
    </plugin_library>
</dds>

Warning

Routing Service must be able to find the Routing Service Protobuf Trasformation dynamic library (librtiprotobuftransf.so on Linux® systems, librtiprotobuftransf.dylib on macOS® systems, or rtiprotobuftransf.dll on Windows® systems). Make sure to include the library’s directory in the library search path environment variable appropriate for your system (LD_LIBRARY_PATH on Linux systems, RTI_LD_LIBRARY_PATH on macOS systems, or PATH on Windows systems, etc.).

Once the dynamic library and constructor function have been registered, Routing Service will create an instance of the plugin during start-up.

2.2.1. Configuration Properties

The Routing Service Protobuf Trasformation uses the following properties to configure its behavior:

Table 2.7 Protobuf Transformation Configuration Properties

Property	Required	Default	Accepted Values	Description
buffer_member	YES	-	String	An identifier for a member of a type (e.g. ‘foo.bar’)
transform_type	YES	-	‘serialize’ or ‘deserialize’	‘serialize’ transforms the buffer from DDS to Protobuf ‘deserialize’ transforms the buffer from Protobuf to DDS.
descriptor_file	YES	-	Path	A descriptor set file containing the target Protobuf message tgype and all included data types.
message_type	NO	Derived from DDS type	String	The fully-qualified name of the Protobuf type. It will be automatically derived from the DDS type by replacing “::” with “.” if not specified.

For example, given the following Protocol Buffers message type stored in a file named shape_type.proto:

syntax = "proto3";

message ShapeType {
    string color = 1;
    int32 x = 2;
    int32 y = 3;
    int32 shapesize = 4;
}

We can generate a descriptor set file named by using protoc:

protoc --descriptor_set_out=shape_type.pbdesc --include_imports shape_type.proto

We can define an equivalent DDS type, and a container for the serialized payload:

<types>
    <struct name= "ShapeType">
        <member name="color" stringMaxLength="128" type="string" key="true"/>
        <member name="x" type="int32"/>
        <member name="y" type="int32"/>
        <member name="shapesize" type="int32"/>
    </struct>
    <struct name="SerializedMessage">
        <member name="data" type="byte" sequenceMaxLength="-1"/>
    </struct>
</types>

We can configure the transformation to convert from Protocol Buffers to DDS:

<!-- inside <dds_output> or <output> -->

<registered_type_name>ShapeType</registered_type_name>
<transformation plugin_name="MyPlugins::ProtobufTransformation">
    <input_type_name>SerializedMessage</input_type_name>
    <property>
        <value>
            <element>
                <name>transform_type</name>
                <value>deserialize</value>
            </element>
            <element>
                <name>buffer_member</name>
                <value>data</value>
            </element>
            <element>
                <name>descriptor_file</name>
                <value>shape_type.pbdesc</value>
            </element>
        </value>
    </property>
</transformation>

We can configure the transformation to convert from DDS to Protocol Buffers:

<!-- inside <dds_output> or <output> -->

<registered_type_name>SerializedMessage</registered_type_name>
<transformation plugin_name="MyPlugins::ProtobufTransformation">
    <input_type_name>ShapeType</input_type_name>
    <property>
        <value>
            <element>
                <name>transform_type</name>
                <value>serialize</value>
            </element>
            <element>
                <name>buffer_member</name>
                <value>data</value>
            </element>
            <element>
                <name>descriptor_file</name>
                <value>shape_type.pbdesc</value>
            </element>
        </value>
    </property>
</transformation>