5. DDS Options for Protocol Buffers

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

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

5.1. Message Options

Table 5.1 Message Options (.omg.dds.type)

Option	Description	Value	IDL4 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 IDL4 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 IDL4 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 IDL4 struct.	NO_AUTO_ID	N/A (no annotation)
		SEQUENTIAL	@autoid(sequential)
		HASH	@autoid(hash)

5.2. Field Options

Table 5.2 Field Options (.omg.dds.member)

Option	Description	Value	IDL4 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 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")

5.3. RTI Protocol Buffers Descriptor File

The RTI Protocol Buffers descriptor file included with Protocol Buffers Extension, 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.

Listing 5.1 omg/dds/descriptor.proto

syntax = "proto2";
import "google/protobuf/descriptor.proto";

package omg.dds;

enum ExtensibilityKind {
  MUTABLE = 0; // "Mutable" extensibility, members can be reordered,  added, or removed.
  APPENDABLE = 1; // "Appendable" extensibility, members can be added or removed from the end.
  FINAL = 2; // "Final" extensibility, member cannot be added, removed or reordered.
}

enum DefaultIdKind {
  PROTOBUF_DEFAULT_ID = 0; // Derive an @id annotation for each DDS member from the corresponding protobuf field number.
  DDS_DEFAULT_ID = 1; // Do not emit @id annotations, unless explicitly provided through the "omg.dds.member.id" option.
}

enum AutoIdKind {
  NO_AUTO_ID = 0; // Do not emit an @autoid annotation
  SEQUENTIAL = 1; // Emit @autoid(sequential) to use sequential IDs starting from 0
  HASH = 2; // Emit @autoid(hash), to use a hash of the field name to generate IDs
}

message TypeAnnotation {
  optional string name = 1;
  optional ExtensibilityKind extensibility = 2;
  optional DefaultIdKind default_id = 3;
  optional AutoIdKind auto_id = 4;
}

extend google.protobuf.MessageOptions {
  optional TypeAnnotation type = 7400;
}

message MemberAnnotation {
  optional bool key = 1;
  optional bool filterable = 2;
  optional bool optional = 3;
  optional DefaultIdKind default_id = 4;
  optional uint32 id = 5;
  optional string hash_id = 6;
}

extend google.protobuf.FieldOptions {
  optional MemberAnnotation member = 7400;
}