.. include:: vars.rst

.. _section-configuration:

*************
Configuration
*************

This section describes how to configure |RS_PB_TSFM|.

All configuration is specified in |RS|'s XML configuration file.

Supported Data Types
====================

|RS_PB_TSFM| requires users to specify the name of a "bytes" member that
contains a serialized |PB| message. The plugin can be configured to
either:

- deserialize a |PB| message from the "bytes" member, and convert it to an equivalent DDS data type.
- convert a DDS data type to a |PB| 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 |PB| 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 |PB| message type and all included data types. A suitable
file can be generated by using the following command:

.. code-block:: sh

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

The name of the target |PB| 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 |PB| message type will be ``MyModule.MyType``. If the derived name does not
match the actual name of the |PB| message type, users can explicitly
specify the name by using property |PROP_MESSAGE_TYPE|.

|PB| to *DDS* Mapping
---------------------
   
|PB| User Types
***************

.. list-table:: User Types Mapping
   :widths: 20 80
   :header-rows: 1

   * - **PB Types**
     - **DDS Types**
   * - ``message``
     - ``struct``, ``valuetype``
   * - ``enum``
     - ``enum``

|PB| Primitive Types
********************

.. list-table:: Primitive Types Mapping
   :widths: 20 80
   :header-rows: 1

   * - **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>``

|PB| Collections
****************

.. list-table:: Collections Mapping
   :widths: 20 80
   :header-rows: 1

   * - **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.:

         .. code-block:: omg-idl

             struct MapPair {
                 K key;
                 V value;
             };


*DDS* to |PB| Mapping
---------------------

*DDS* User Types
****************

.. list-table:: User Types Mapping
   :widths: 20 80
   :header-rows: 1

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


*DDS* Primitive Types
*********************

.. list-table:: Primitive Types Mapping
   :widths: 20 80
   :header-rows: 1

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

*DDS* Collections
*****************

.. list-table:: Collections Mapping
   :widths: 20 80
   :header-rows: 1

   * - **DDS Types**
     - **PB Types**
   * - ``T[N]``, ``sequence<T>``
     - ``repeated<T>``
   * - ``MapPair[N]``, ``MapPair<T>``, with

       .. code-block:: omg-idl

           struct MapPair {
               K key;
               V value;
           };
 
     - ``repeated<MapPair>``, ``map<K,V>``
   * - ``sequence<SequenceAlias>``, ``SequenceAlias[N]``, with:
        
       .. code-block:: omg-idl
    
           typedef sequence<T> SequenceAlias;

     - Not supported.

Load the Protobuf Transformation Plugin
=======================================

|RS_PB_TSFM| must be registered as a |RS| plugin by using the
``<transformation_plugin>`` tag.

The following snippet demonstrates how to register the plugin in the
``<plugin_library>`` section of |RS|'s XML configuration:

.. code-block:: xml

    <?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:: |RS| must be able to find the |RS_PB_TSFM| dynamic library
             (|PB_TRANSFORMATION_LIB_NAME_LINUX| on Linux® systems,
             |PB_TRANSFORMATION_LIB_NAME_MAC| on macOS® systems,
             or |PB_TRANSFORMATION_LIB_NAME_WIN| 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, |RS| will create an instance of the plugin during start-up.

.. _section-processor-configuration-attributes:

Configuration Properties
------------------------

The |RS_PB_TSFM| uses the following properties to configure its behavior:

.. csv-table:: Protobuf Transformation Configuration Properties
   :file: static/csv/protobuf_transformation_properties.csv
   :widths: 15 15 15 15 40
   :header-rows: 1

For example, given the following |PB| message type stored in a file named
``shape_type.proto``:

.. code-block:: protobuf

    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``:

.. code-block:: sh

    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:

.. code-block:: xml

    <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 |PB| to DDS:

.. code-block:: xml

    <!-- 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 |PB|:

.. code-block:: xml

    <!-- 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>