.. _section-dds-options:

DDS Options for Protocol Buffers
********************************

The ``omg/dds/descriptor.proto`` file is a |PROTOBUF| extension
provided by RTI. This file acts as a bridge between 
|PROTOBUF| and DDS, enabling you to use DDS-specific features in your 
|PROTOBUF| definitions.

``omg/dds/descriptor.proto`` defines rules that are expressed as 
custom options in your |PROTOBUF| message definitions. When the 
definitions are compiled to |IDL|, the DDS options are applied to the 
generated |IDL| code as specific annotations to the corresponding |IDL| 
types.

Message Options
===============

  .. list-table:: Message Options (``.omg.dds.type``)
      :name: MessageOptions
      :widths: 20 60 40 40
      :header-rows: 1

      * - Option
        - Description
        - Value
        - |IDL| Output
      * - ``.name``
        - Specifies a custom name to identify types used on a DDS |TOPIC|.
        -  ``"MyCustomName"`` (non-empty string literal)
        -  ``@type_name("MyCustomName")``
      * - ``.extensibility``
        - Controls the extensibility annotation of the corresponding |IDL| ``struct``.
          The default value is ``MUTABLE``.
        - ``MUTABLE``
        - ``@mutable``
      * -
        -
        -  ``FINAL``
        -  ``@final``

      * -
        -
        -  ``APPENDABLE``
        -  ``@appendable``

      * - ``.default_id``
        - Specifies the default policy used to control the default ``@id`` annotation
          emitted for each member of an |IDL| ``struct``.
        - ``PROTOBUF_DEFAULT_ID``
        - ``@id(N)`` (on members)

      * -
        -
        - ``DDS_DEFAULT_ID``
        - N/A (use default DDS id for each member)
      * - ``.auto_id``
        - Controls the ``@autoid`` annotation for the |IDL| ``struct``.
        - ``NO_AUTO_ID``
        - N/A (no annotation)
      * -
        -
        - ``SEQUENTIAL``
        - ``@autoid(sequential)``
      * -
        -
        - ``HASH``
        - ``@autoid(hash)``

Field Options
=============

  .. list-table:: Field Options (``.omg.dds.member``)
      :name: FieldOptions
      :widths: 20 60 40 40
      :header-rows: 1

      * - Option
        - Description
        - Value
        - |IDL| Output
      * - ``.key``
        - Specifies whether the associated member is part of the DDS key.
        - ``true``
        - ``@key``
      * - 
        - 
        - ``false`` (default)
        - N/A (no annotation)
      * - ``.optional``
        - Controls whether the associated member is annotated as 
          ``@optional``. If specified, this option takes precedence over the 
          default annotation derived from the :ref:`field presence <section-proto2idl-field-presence>` 
          setting. 
        - ``true``
        - ``@optional``
      * -
        -
        - ``false``
        - N/A (no annotation)
      * - ``.default_id``
        - Controls the default ``@id`` annotation emitted for the associated 
          member. If specified, this option takes precedence over the 
          default policy set at the message level in the option 
          ``.omg.dds.type.default_id``.
        - See ``.omg.dds.type.default_id``.
        - 
      * - ``.id``
        - Assigns and emits an explicit ``@id`` annotation for the associated 
          member.
        - ``N`` (32-bit unsigned integer)
        - ``@id(N)``
      * - ``.hash_id`` 
        - Generates the ``@hashid`` annotation for the associated member with
          the specified source string.
        - ``"My String"`` (non-empty string literal)
        - ``@hashid("My String")``

.. _section-omg-dds-descriptor:

RTI |PROTOBUF| Descriptor File
==============================

The RTI |PROTOBUF| descriptor file included with |PROTOBUF_EXT|, 
``omg/dds/descriptor.proto``, allows you to mark your Protobuf definitions 
with specific DDS instructions. The file is located at 
``<NDDSHOME>/include/omg/dds/descriptor.proto``. The complete file content 
is shown below.


.. literalinclude:: /../../resource/proto/omg/dds/descriptor.proto
   :language: protobuf
   :linenos:
   :caption: omg/dds/descriptor.proto