XML profiles

The Configuration section shows how to configure entity attributes using XML profiles, but this section goes deeper on it, explaining each field with its available values and how to compound the complete XML files.

eProsima Fast RTPS permits to load several XML files, each one containing XML profiles. In addition to the API functions to load user XML files, at initialization eProsima Fast RTPS tries to locate and load several default XML files. eProsima Fast RTPS offers the following options to use default XML files:

  • Using an XML file with the name DEFAULT_FASTRTPS_PROFILES.xml and located in the current execution path.
  • Using an XML file which location is defined in the environment variable FASTRTPS_DEFAULT_PROFILES_FILE.

An XML profile is defined by a unique name (or <transport_id> label in the Transport descriptors case) that is used to reference the XML profile during the creation of a Fast RTPS entity, Transports, or Dynamic Topic Types.

Making an XML

An XML file can contain several XML profiles. The available profile types are Transport descriptors, XML Dynamic Types, Participant profiles, Publisher profiles, and Subscriber profiles.

<transport_descriptor>
    <transport_id>TransportProfile</transport_id>
    <type>UDPv4</type>
    <!-- ... -->
</transport_descriptor>

<types>
    <type>
        <struct name="struct_profile">
            <!-- ... -->
        </struct>
    </type>
</types>

<participant profile_name="participant_profile">
    <rtps>
    <!-- ... -->
    </rtps>
</participant>

<publisher profile_name="publisher_profile">
    <!-- ... -->
</publisher>

<subscriber profile_name="subscriber_profile">
    <!-- ... -->
</subscriber>

The Fast-RTPS XML format uses some structures along several profiles types. For readability, the Common section groups these common structures.

Finally, The Example section shows an XML file that uses all the possibilities. This example is useful as a quick reference to look for a particular property and how to use it. This XSD file can be used as a quick reference too.

Loading and applying profiles

Before creating any entity, it’s required to load XML files using Domain::loadXMLProfilesFile function. createParticipant, createPublisher and createSubscriber have a version that expects the profile name as an argument. eProsima Fast RTPS searches the XML profile using this profile name and applies the XML profile to the entity.

eprosima::fastrtps::Domain::loadXMLProfilesFile("my_profiles.xml");

Participant *participant = Domain::createParticipant("participant_xml_profile");
Publisher *publisher = Domain::createPublisher(participant, "publisher_xml_profile");
Subscriber *subscriber = Domain::createSubscriber(participant, "subscriber_xml_profile");

To load dynamic types from its declaration through XML see the Usage section of XML Dynamic Types.

Transport descriptors

This section allows creating transport descriptors to be referenced by the Participant profiles. Once a well-defined transport descriptor is referenced by a Participant profile, every time that profile is instantiated it will use or create the related transport.

The following XML code shows the complete list of configurable parameters:

<transport_descriptors>
    <transport_descriptor>
        <transport_id>TransportId1</transport_id> <!-- string -->
        <type>UDPv4</type> <!-- string -->
        <sendBufferSize>8192</sendBufferSize> <!-- uint32 -->
        <receiveBufferSize>8192</receiveBufferSize> <!-- uint32 -->
        <TTL>250</TTL> <!-- uint8 -->
        <non_blocking_send>false</non_blocking_send> <!-- boolean -->
        <maxMessageSize>16384</maxMessageSize> <!-- uint32 -->
        <maxInitialPeersRange>100</maxInitialPeersRange> <!-- uint32 -->
        <interfaceWhiteList>
            <address>192.168.1.41</address> <!-- string -->
            <address>127.0.0.1</address> <!-- string -->
        </interfaceWhiteList>
        <wan_addr>80.80.55.44</wan_addr> <!-- string -->
        <output_port>5101</output_port> <!-- uint16 -->
        <keep_alive_frequency_ms>5000</keep_alive_frequency_ms> <!-- uint32 -->
        <keep_alive_timeout_ms>25000</keep_alive_timeout_ms> <!-- uint32 -->
        <max_logical_port>9000</max_logical_port> <!-- uint16 -->
        <logical_port_range>100</logical_port_range> <!-- uint16 -->
        <logical_port_increment>2</logical_port_increment> <!-- uint16 -->
        <listening_ports>
            <port>5100</port> <!-- uint16 -->
            <port>5200</port> <!-- uint16 -->
        </listening_ports>
        <calculate_crc>false</calculate_crc> <!-- boolean -->
        <check_crc>false</check_crc> <!-- boolean -->
        <enable_tcp_nodelay>false</enable_tcp_nodelay> <!-- boolean -->
        <tls><!-- TLS Section --></tls>
    </transport_descriptor>

The XML label <transport_descriptors> can hold any number of <transport_descriptor>.

Name Description Values Default
<transport_id> Unique name to identify each transport descriptor. string  
<type> Type of the transport descriptor. UDPv4, UDPv6, TCPv4, TCPv6 UDPv4
<sendBufferSize> Size in bytes of the socket send buffer. If the value is zero then FastRTPS will use the default size from the configuration of the sockets, using a minimum size of 65536 bytes. uint32 0
<receiveBufferSize> Size in bytes of the socket receive buffer. If the value is zero then FastRTPS will use the default size from the configuration of the sockets, using a minimum size of 65536 bytes. uint32 0
<TTL> Time To Live, only for UDP transports . uint8 1
<non_blocking_send> Whether to set the non-blocking send mode on the socket bool false
<maxMessageSize> The maximum size in bytes of the transport’s message buffer. uint32 65500
<maxInitialPeersRange> The maximum number of guessed initial peers to try to connect. uint32 4
<interfaceWhiteList> Allows defining Whitelist Interfaces. Whitelist Interfaces  
<wan_addr> Public WAN address when using TCPv4 transports. This field is optional if the transport doesn’t need to define a WAN address.

string with IPv4 Format

XXX.XXX.XXX.XXX.

  
<output_port> Port used for output bound. If this field isn’t defined, the output port will be random (UDP only). uint16 0
<keep_alive_frequency_ms> Frequency in milliseconds for sending RTCP keep-alive requests (TCP only). uint32 50000
<keep_alive_timeout_ms> Time in milliseconds since sending the last keep-alive request to consider a connection as broken. (TCP only). uint32 10000
<max_logical_port> The maximum number of logical ports to try during RTCP negotiations. (TCP only) uint16 100
<logical_port_range> The maximum number of logical ports per request to try during RTCP negotiations. (TCP only) uint16 20
<logical_port_increment> Increment between logical ports to try during RTCP negotiation. (TCP only) uint16 2
<listening_ports> Local port to work as TCP acceptor for input connections. If not set, the transport will work as TCP client only (TCP only). List <uint16>  
<tls> Allows to define TLS related parameters and options (TCP only). TLS Configuration  

RTCP is the control protocol for communications with RTPS over TCP/IP connections.

There are more examples of transports descriptors in Transports.

TLS Configuration

Fast-RTPS allows configuring TLS parameters through the <tls> tag of its Transport Descriptor. The full list of options is listed here:

<transport_descriptors>
    <transport_descriptor>
        <transport_id>Test</transport_id>
        <type>TCPv4</type>
        <tls>
            <password>Password</password>
            <private_key_file>Key_file.pem</private_key_file>
            <rsa_private_key_file>RSA_file.pem</rsa_private_key_file>
            <cert_chain_file>Chain.pem</cert_chain_file>
            <tmp_dh_file>DH.pem</tmp_dh_file>
            <verify_file>verify.pem</verify_file>
            <verify_mode>
                <verify>VERIFY_PEER</verify>
            </verify_mode>
            <options>
                <option>NO_TLSV1</option>
                <option>NO_TLSV1_1</option>
            </options>
            <verify_paths>
                <verify_path>Path1</verify_path>
                <verify_path>Path2</verify_path>
                <verify_path>Path3</verify_path>
            </verify_paths>
            <verify_depth>55</verify_depth>
            <default_verify_path>true</default_verify_path>
            <handshake_role>SERVER</handshake_role>
        </tls>
    </transport_descriptor>
</transport_descriptors>
Name Description Values Default
<password> Password of the private_key_file if provided (or RSA). string  
<private_key_file> Path to the private key certificate file. string  
<rsa_private_key_file> Path to the private key RSA certificate file. string  
<cert_chain_file> Path to the public certificate chain file. string  
<tmp_dh_file> Path to the Diffie-Hellman parameters file string  
<verify_file> Path to the CA (Certification- Authority) file. string  
<verify_mode> Establishes the verification mode mask. VERIFY_NONE, VERIFY_PEER, VERIFY_FAIL_IF_NO_PEER_CERT, VERIFY_CLIENT_ONCE  
<options> Establishes the SSL Context options mask DEFAULT_WORKAROUNDS, NO_COMPRESSION, NO_SSLV2, NO_SSLV3, NO_TLSV1, NO_TLSV1_1, NO_TLSV1_2, NO_TLSV1_3, SINGLE_DH_USE  
<verify_paths> Paths where the system will look for verification files. string  
<verify_depth> Maximum allowed depth for verify intermediate certificates. uint32  
<default_verify_path> Default paths where the system will look for verification files. boolean false
<handshake_role> Role that the transport will take on handshaking. On default, the acceptors act as SERVER and the connectors as CLIENT. DEFAULT, SERVER, CLIENT DEFAULT

XML Dynamic Types

XML Dynamic Types allows creating eProsima Fast RTPS Dynamic Types directly defining them through XML. It allows any application to change TopicDataTypes without modifying its source code.

XML Structure

The XML Types definition (<types> tag) can be placed similarly to the profiles tag inside the XML file. It can be a stand-alone XML Types file or be a child of the Fast-RTPS XML root tag (<dds>). Inside the types tag, there must be one or more type tags (<type>).

Stand-Alone:

<types>
    <type>
        <!-- Type definition -->
    </type>
    <type>
        <!-- Type definition -->
        <!-- Type definition -->
    </type>
</types>

Rooted:

<dds>
    <types>
        <type>
            <!-- Type definition -->
        </type>
        <type>
            <!-- Type definition -->
            <!-- Type definition -->
        </type>
    </types>
</dds>

Finally, each <type> tag can contain one or more Type definitions. Defining several types inside a <type> tag or defining each type in its <type> tag has the same result.

Type definition

Enum

The <enum> type is defined by its name and a set of enumerators, each of them with its name and its (optional) value.

Example:

XML C++ 
<enum name="MyEnum">
    <enumerator name="A" value="0"/>
    <enumerator name="B" value="1"/>
    <enumerator name="C" value="2"/>
</enum>

DynamicTypeBuilder_ptr enum_builder = DynamicTypeBuilderFactory::get_instance()->create_enum_builder();
enum_builder->set_name("MyEnum");
enum_builder->add_empty_member(0, "A");
enum_builder->add_empty_member(1, "B");
enum_builder->add_empty_member(2, "C");
DynamicType_ptr enum_type = DynamicTypeBuilderFactory::get_instance()->create_type(enum_builder.get());

Typedef

The <typedef> type is defined by its name and its value or an inner element for complex types. <typedef> corresponds to Alias in Dynamic Types glossary.

Example:

XML C++ 
<typedef name="MyAliasEnum" type="nonBasic" nonBasicTypeName="MyEnum"/>

<typedef name="MyAliasArray" type="int32" arrayDimension="2,2"/>

DynamicTypeBuilder_ptr alias1_builder = DynamicTypeBuilderFactory::get_instance()->create_alias_builder(enum_builder.get(), "MyAlias1");
DynamicType_ptr alias1_type = DynamicTypeBuilderFactory::get_instance()->create_type(alias1_builder.get());

std::vector<uint32_t> sequence_lengths = { 2, 2 };
DynamicTypeBuilder_ptr int_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr array_builder = DynamicTypeBuilderFactory::get_instance()->create_array_builder(int_builder.get(), sequence_lengths);
DynamicTypeBuilder_ptr alias2_builder = DynamicTypeBuilderFactory::get_instance()->create_alias_builder(array_builder.get(), "MyAlias2");
DynamicType_ptr alias2_type = DynamicTypeBuilderFactory::get_instance()->create_type(alias2_builder.get());

Struct

The <struct> type is defined by its name and inner members.

Example:

XML C++ 
<struct name="MyStruct">
    <member name="first" type="int32"/>
    <member name="second" type="int64"/>
</struct>

DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr long_long_builder = DynamicTypeBuilderFactory::get_instance()->create_int64_builder();
DynamicTypeBuilder_ptr struct_builder = DynamicTypeBuilderFactory::get_instance()->create_struct_builder();

struct_builder->set_name("MyStruct");
struct_builder->add_member(0, "first", long_builder.get());
struct_builder->add_member(1, "second", long_long_builder.get());
DynamicType_ptr struct_type = DynamicTypeBuilderFactory::get_instance()->create_type(struct_builder.get());

Structs can inherit from another structs:

XML C++ 
<struct name="ParentStruct">
    <member name="first" type="int32"/>
    <member name="second" type="int64"/>
</struct>
<struct name="ChildStruct" baseType="ParentStruct">
    <member name="third" type="int32"/>
    <member name="fourth" type="int64"/>
</struct>

DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr long_long_builder = DynamicTypeBuilderFactory::get_instance()->create_int64_builder();
DynamicTypeBuilder_ptr struct_builder = DynamicTypeBuilderFactory::get_instance()->create_struct_builder();

struct_builder->set_name("ParentStruct");
struct_builder->add_member(0, "first", long_builder.get());
struct_builder->add_member(1, "second", long_long_builder.get());
DynamicType_ptr struct_type = DynamicTypeBuilderFactory::get_instance()->create_type(struct_builder.get());

DynamicTypeBuilder_ptr child_builder =
    DynamicTypeBuilderFactory::get_instance()->create_child_struct_builder(struct_builder.get());

child_builder->set_name("ChildStruct");
child_builder->add_member(0, "third", long_builder.get());
child_builder->add_member(1, "fourth", long_long_builder.get());
DynamicType_ptr child_struct_type = DynamicTypeBuilderFactory::get_instance()->create_type(child_builder.get());

Union

The <union> type is defined by its name, a discriminator and a set of cases. Each case has one or more caseDiscriminator and a member.

Example:

XML C++ 
<union name="MyUnion">
    <discriminator type="byte"/>
    <case>
        <caseDiscriminator value="0"/>
        <caseDiscriminator value="1"/>
        <member name="first" type="int32"/>
    </case>
    <case>
        <caseDiscriminator value="2"/>
        <member name="second" type="nonBasic" nonBasicTypeName="MyStruct"/>
    </case>
    <case>
        <caseDiscriminator value="default"/>
        <member name="third" type="nonBasic" nonBasicTypeName="int64"/>
    </case>
</union>

DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr long_long_builder = DynamicTypeBuilderFactory::get_instance()->create_int64_builder();
DynamicTypeBuilder_ptr struct_builder = DynamicTypeBuilderFactory::get_instance()->create_struct_builder();
DynamicTypeBuilder_ptr octet_builder = DynamicTypeBuilderFactory::get_instance()->create_byte_builder();
DynamicTypeBuilder_ptr union_builder = DynamicTypeBuilderFactory::get_instance()->create_union_builder(octet_builder.get());

union_builder->set_name("MyUnion");
union_builder->add_member(0, "first", long_builder.get(), "", { 0, 1 }, false);
union_builder->add_member(1, "second", struct_builder.get(), "", { 2 }, false);
union_builder->add_member(2, "third", long_long_builder.get(), "", { }, true);
DynamicType_ptr union_type = DynamicTypeBuilderFactory::get_instance()->create_type(union_builder.get());

Bitset

The <bitset> type is defined by its name and inner bitfields.

Example:

XML C++ 
<bitset name="MyBitSet">
    <bitfield name="a" bit_bound="3"/>
    <bitfield name="b" bit_bound="1"/>
    <bitfield bit_bound="4"/>
    <bitfield name="c" bit_bound="10"/>
    <bitfield name="d" bit_bound="12" type="int16"/>
</bitset>

DynamicTypeBuilderFactory* m_factory = DynamicTypeBuilderFactory::get_instance();
DynamicTypeBuilder_ptr builder_ptr = m_factory->create_bitset_builder();
builder_ptr->add_member(0, "a", m_factory->create_byte_builder()->build());
builder_ptr->add_member(1, "b", m_factory->create_bool_builder()->build());
builder_ptr->add_member(3, "c", m_factory->create_uint16_builder()->build());
builder_ptr->add_member(4, "d", m_factory->create_int16_builder()->build());
builder_ptr->apply_annotation_to_member(0, ANNOTATION_BIT_BOUND_ID, "value", "3");
builder_ptr->apply_annotation_to_member(0, ANNOTATION_POSITION_ID, "value", "0");
builder_ptr->apply_annotation_to_member(1, ANNOTATION_BIT_BOUND_ID, "value", "1");
builder_ptr->apply_annotation_to_member(1, ANNOTATION_POSITION_ID, "value", "3");
builder_ptr->apply_annotation_to_member(3, ANNOTATION_BIT_BOUND_ID, "value", "10");
builder_ptr->apply_annotation_to_member(3, ANNOTATION_POSITION_ID, "value", "8"); // 4 empty
builder_ptr->apply_annotation_to_member(4, ANNOTATION_BIT_BOUND_ID, "value", "12");
builder_ptr->apply_annotation_to_member(4, ANNOTATION_POSITION_ID, "value", "18");
builder_ptr->set_name("MyBitSet");

A bitfield without name is an inaccessible set of bits. Bitfields can specify their management type to ease their modification and access. The bitfield’s bit_bound is mandatory and cannot be bigger than 64.

Bitsets can inherit from another bitsets:

XML C++ 
<bitset name="ParentBitSet">
    <bitfield name="a" bit_bound="3"/>
    <bitfield name="b" bit_bound="1"/>
</bitset>

<bitset name="ChildBitSet" baseType="ParentBitSet">
    <bitfield name="c" bit_bound="30"/>
    <bitfield name="d" bit_bound="13"/>
</bitset>

DynamicTypeBuilderFactory* m_factory = DynamicTypeBuilderFactory::get_instance();
DynamicTypeBuilder_ptr builder_ptr = m_factory->create_bitset_builder();
builder_ptr->add_member(0, "a", m_factory->create_byte_builder()->build());
builder_ptr->add_member(1, "b", m_factory->create_bool_builder()->build());
builder_ptr->apply_annotation_to_member(0, ANNOTATION_BIT_BOUND_ID, "value", "3");
builder_ptr->apply_annotation_to_member(0, ANNOTATION_POSITION_ID, "value", "0");
builder_ptr->apply_annotation_to_member(1, ANNOTATION_BIT_BOUND_ID, "value", "1");
builder_ptr->apply_annotation_to_member(1, ANNOTATION_POSITION_ID, "value", "3");
builder_ptr->set_name("ParentBitSet");

DynamicTypeBuilder_ptr child_ptr = m_factory->create_child_struct_builder(builder_ptr.get());
child_ptr->add_member(3, "c", m_factory->create_uint16_builder()->build());
child_ptr->add_member(4, "d", m_factory->create_int16_builder()->build());
child_ptr->apply_annotation_to_member(3, ANNOTATION_BIT_BOUND_ID, "value", "10");
child_ptr->apply_annotation_to_member(3, ANNOTATION_POSITION_ID, "value", "8"); // 4 empty
child_ptr->apply_annotation_to_member(4, ANNOTATION_BIT_BOUND_ID, "value", "12");
child_ptr->apply_annotation_to_member(4, ANNOTATION_POSITION_ID, "value", "18");
child_ptr->set_name("ChildBitSet");

Bitmask

The <bitmask> type is defined by its name and inner bit_values.

Example:

XML C++ 
<bitmask name="MyBitMask" bit_bound="8">
    <bit_value name="flag0" position="0"/>
    <bit_value name="flag1"/>
    <bit_value name="flag2" position="2"/>
    <bit_value name="flag5" position="5"/>
</bitmask>

DynamicTypeBuilderFactory* m_factory = DynamicTypeBuilderFactory::get_instance();
DynamicTypeBuilder_ptr builder_ptr = m_factory->create_bitmask_builder(8);
builder_ptr->add_empty_member(0, "flag0");
builder_ptr->add_empty_member(1, "flag1");
builder_ptr->add_empty_member(2, "flag2");
builder_ptr->add_empty_member(5, "flag5");
builder_ptr->set_name("MyBitMask");

The bitmask can specify its bit_bound, this is, the number of bits that the type will manage. Internally will be converted to the minimum type that allows to store them. The maximum allowed bit_bound is 64. Bit_values can define their position inside the bitmask.

Member types

Member types are any type that can belong to a <struct> or a <union>, or be aliased by a <typedef>.

Basic types

The identifiers of the available basic types are:

boolean int64 float128
byte uint16 string
char uint32 wstring
wchar uint64  
int16 float32  
int32 float64  

All of them are defined as follows:

XML C++ 
<member name="my_long" type="int64"/>

DynamicTypeBuilder_ptr long_long_builder = DynamicTypeBuilderFactory::get_instance()->create_int64_builder();
long_long_builder->set_name("my_long");
DynamicType_ptr long_long_type = DynamicTypeBuilderFactory::get_instance()->create_type(long_long_builder.get());

Arrays

Arrays are defined in the same way as any other member type but add the attribute arrayDimensions. The format of this dimensions attribute is the size of each dimension separated by commas.

Example:

XML C++ 
<member name="long_array" type="int32" arrayDimensions="2,3,4"/>

std::vector<uint32_t> lengths = { 2, 3, 4 };
DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr array_builder = DynamicTypeBuilderFactory::get_instance()->create_array_builder(long_builder.get(), lengths);
array_builder->set_name("long_array");
DynamicType_ptr array_type = DynamicTypeBuilderFactory::get_instance()->create_type(array_builder.get());

It’s IDL analog would be:

long long_array[2][3][4];

Sequences

Sequences are defined by its name, its content type, and its sequenceMaxLength. The type of its content should be defined by its type attribute.

Example:

XML C++ 
<typedef name="my_sequence_inner" type="int32" sequenceMaxLength="2"/>
<struct name="SeqSeqStruct">
    <member name="my_sequence_sequence" type="nonBasic" nonBasicTypeName="my_sequence_inner" sequenceMaxLength="3"/>
</struct>

uint32_t child_len = 2;
DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr seq_builder = DynamicTypeBuilderFactory::get_instance()->create_sequence_builder(long_builder.get(),
    child_len);
uint32_t length = 3;
DynamicTypeBuilder_ptr seq_seq_builder = DynamicTypeBuilderFactory::get_instance()->create_sequence_builder(
    seq_builder.get(), length);
seq_seq_builder->set_name("my_sequence_sequence");
DynamicType_ptr seq_type = DynamicTypeBuilderFactory::get_instance()->create_type(seq_seq_builder.get());

The example shows a sequence with sequenceMaxLength 3 of sequences with sequenceMaxLength 2 with <int32> contents. As IDL would be:

sequence<sequence<long,2>,3> my_sequence_sequence;

Note that the inner sequence has been defined before.

Maps

Maps are similar to sequences, but they need to define two types instead of one. One type defines its key_type, and the other type defines its elements types. Again, both types can be defined as attributes or as members, but when defined as members, they should be contained in another XML element (<key_type> and <type> respectively).

Example:

XML C++ 
<typedef name="my_map_inner" type="int32" key_type="int32" mapMaxLength="2"/>
<struct name="MapMapStruct">
    <member name="my_map_map" type="nonBasic" nonBasicTypeName="my_map_inner" key_type="int32" mapMaxLength="2"/>
</struct>

uint32_t length = 2;
DynamicTypeBuilder_ptr long_builder = DynamicTypeBuilderFactory::get_instance()->create_int32_builder();
DynamicTypeBuilder_ptr map_builder = DynamicTypeBuilderFactory::get_instance()->create_map_builder(long_builder.get(),
    long_builder.get(), length);

DynamicTypeBuilder_ptr map_map_builder = DynamicTypeBuilderFactory::get_instance()->create_map_builder(long_builder.get(),
    map_builder.get(), length);
map_map_builder->set_name("my_map_map");
DynamicType_ptr map_type = DynamicTypeBuilderFactory::get_instance()->create_type(map_map_builder.get());

Is equivalent to the IDL:

map<long,map<long,long,2>,2> my_map_map;

Complex types

Once defined, complex types can be used as members in the same way a basic or array type would be.

Example:

<struct name="OtherStruct">
    <member name="my_enum" type="nonBasic" nonBasicTypeName="MyEnum"/>
    <member name="my_struct" type="nonBasic" nonBasicTypeName="MyStruct" arrayDimensions="5"/>
</struct>

Usage

In the application that will make use of XML Types, it’s mandatory to load the XML file that defines the types before trying to instantiate DynamicPubSubTypes of these types. It’s important to remark that only <struct> types generate usable DynamicPubSubType instances.

// Load the XML File
XMLP_ret ret = XMLProfileManager::loadXMLFile("types.xml");
// Create the "MyStructPubSubType"
DynamicPubSubType *pbType = XMLProfileManager::CreateDynamicPubSubType("MyStruct");
// Create a "MyStruct" instance
DynamicData* data = DynamicDataFactory::get_instance()->create_data(pbType->GetDynamicType());

Participant profiles

Participant profiles allow declaring Participant configuration from an XML file. All the configuration options for the participant belong to the <rtps> label. The attribute profile_name will be the name that the Domain will associate to the profile to load it as shown in Loading and applying profiles.

<participant profile_name="part_profile_name">
    <rtps>
        <name>Participant Name</name> <!-- String -->

        <defaultUnicastLocatorList>
            <!-- LOCATOR_LIST -->
            <locator>
                <udpv4/>
            </locator>
        </defaultUnicastLocatorList>

        <defaultMulticastLocatorList>
            <!-- LOCATOR_LIST -->
            <locator>
                <udpv4/>
            </locator>
        </defaultMulticastLocatorList>

        <sendSocketBufferSize>8192</sendSocketBufferSize> <!-- uint32 -->

        <listenSocketBufferSize>8192</listenSocketBufferSize>  <!-- uint32 -->

        <builtin>
            <!-- BUILTIN -->
        </builtin>

        <port>
            <portBase>7400</portBase> <!-- uint16 -->
            <domainIDGain>200</domainIDGain> <!-- uint16 -->
            <participantIDGain>10</participantIDGain> <!-- uint16 -->
            <offsetd0>0</offsetd0> <!-- uint16 -->
            <offsetd1>1</offsetd1> <!-- uint16 -->
            <offsetd2>2</offsetd2> <!-- uint16 -->
            <offsetd3>3</offsetd3> <!-- uint16 -->
        </port>

        <participantID>99</participantID>   <!-- int32 -->

        <throughputController>
            <bytesPerPeriod>8192</bytesPerPeriod> <!-- uint32 -->
            <periodMillisecs>1000</periodMillisecs> <!-- uint32 -->
        </throughputController>

        <userTransports>
            <transport_id>TransportId1</transport_id> <!-- string -->
            <transport_id>TransportId2</transport_id> <!-- string -->
        </userTransports>

        <useBuiltinTransports>false</useBuiltinTransports> <!-- boolean -->

        <propertiesPolicy>
            <!-- PROPERTIES_POLICY -->
        </propertiesPolicy>

        <allocation>
            <!-- ALLOCATION -->
        </allocation>

    </rtps>
</participant>

Note

List with the possible configuration parameter:

Name Description Values Default
<name> Participant’s name. It’s not the same field that profile_name. string_255  
<defaultUnicastLocatorList> List of default input unicast locators. It expects a LocatorListType. LocatorListType  
<defaultMulticastLocatorList> List of default input multicast locators. It expects a LocatorListType. LocatorListType  
<sendSocketBufferSize> Size in bytes of the output socket buffer. If the value is zero then FastRTPS will use the default size from the configuration of the sockets, using a minimum size of 65536 bytes. uint32 0
<listenSocketBufferSize> Size in bytes of the input socket buffer. If the value is zero then FastRTPS will use the default size from the configuration of the sockets, using a minimum size of 65536 bytes. uint32 0
<builtin> Built-in parameters. Explained in the Built-in parameters section. Built-in parameters  
<port> Allows defining the port parameters and gains related to the RTPS protocol. Explained in the Port section. Port  
<participantID> Participant’s identifier. Typically it will be automatically generated by the Domain. int32 0
<throughputController> Allows defining a maximum throughput. Explained in the Throughput section. Throughput  
<userTransports> Transport descriptors to be used by the participant. List <string>  
<useBuiltinTransports> Boolean field to indicate to the system that the participant will use the default builtin transport independently of its <userTransports>. bool true
<propertiesPolicy> Additional configuration properties. It expects a PropertiesPolicyType. PropertiesPolicyType  
<allocation> Configuration regarding allocation behavior. It expects a Participant allocation parameters Participant allocation parameters  

Port Configuration

Name Description Values Default
<portBase> Base port. uint16 7400
<domainIDGain> Gain in domainId. uint16 250
<participantIDGain> Gain in participantId. uint16 2
<offsetd0> Multicast metadata offset. uint16 0
<offsetd1> Unicast metadata offset. uint16 10
<offsetd2> Multicast user data offset. uint16 1
<offsetd3> Unicast user data offset. uint16 11

Participant allocation parameters

This section of the Participant's rtps configuration allows defining parameters related with allocation behavior on the participant.

<allocation>
    <remote_locators>
        <max_unicast_locators>4</max_unicast_locators> <!-- uint32 -->
        <max_multicast_locators>1</max_multicast_locators> <!-- uint32 -->
    </remote_locators>
    <total_participants>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_participants>
    <total_readers>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_readers>
    <total_writers>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_writers>
</allocation>
Name Description Values Default
<max_unicast_locators> Maximum number of unicast locators expected on a remote entity. It is recommended to use the maximum number of network interfaces found on any machine the participant will connect to. UInt32 4
<max_multicast_locators> Maximum number of multicast locators expected on a remote entity. May be set to zero to disable multicast traffic. UInt32 1
<total_participants> Participant Allocation Configuration related to the total number of participants in the domain (local and remote). Allocation Configuration  
<total_readers> Participant Allocation Configuration related to the total number of readers on each participant (local and remote). Allocation Configuration  
<total_writers> Participant Allocation Configuration related to the total number of writers on each participant (local and remote). Allocation Configuration  

Built-in parameters

This section of the Participant's rtps configuration allows defining built-in parameters.

<builtin>
    <discovery_config>

        <discoveryProtocol>NONE</discoveryProtocol> <!-- DiscoveryProtocol enum -->

        <EDP>SIMPLE</EDP>  <!-- string -->

        <leaseDuration>
            <!-- DURATION -->
        </leaseDuration>

        <leaseAnnouncement>
            <!-- DURATION -->
        </leaseAnnouncement>

        <initialAnnouncements>
            <!-- INITIAL_ANNOUNCEMENTS -->
        </initialAnnouncements>

        <simpleEDP>
            <PUBWRITER_SUBREADER>true</PUBWRITER_SUBREADER>  <!-- boolean -->
            <PUBREADER_SUBWRITER>true</PUBREADER_SUBWRITER>  <!-- boolean -->
        </simpleEDP>

        <staticEndpointXMLFilename>filename.xml</staticEndpointXMLFilename>  <!-- string -->

    </discovery_config>

    <avoid_builtin_multicast>true</avoid_builtin_multicast>

    <use_WriterLivelinessProtocol>false</use_WriterLivelinessProtocol>  <!-- boolean -->

    <domainId>4</domainId> <!-- uint32 -->

    <metatrafficUnicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </metatrafficUnicastLocatorList>

    <metatrafficMulticastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </metatrafficMulticastLocatorList>

    <initialPeersList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </initialPeersList>

    <readerHistoryMemoryPolicy>PREALLOCATED_WITH_REALLOC</readerHistoryMemoryPolicy>

    <writerHistoryMemoryPolicy>PREALLOCATED_WITH_REALLOC</writerHistoryMemoryPolicy>

    <mutation_tries>55</mutation_tries>
</builtin>
Name Description Values Default
<discovery_config> This is the main tag where discovery-related settings can be configured. discovery_config  
<avoid_builtin_multicast> Restricts metatraffic multicast traffic to PDP only. Boolean true
<use_WriterLivelinessProtocol> Indicates to use the WriterLiveliness protocol. Boolean true
<domainId> DomainId to be used by the RTPSParticipant. UInt32 0
<metatrafficUnicastLocatorList> Metatraffic Unicast Locator List List of LocatorListType  
<metatrafficMulticastLocatorList> Metatraffic Multicast Locator List List of LocatorListType  
<initialPeersList> Initial peers. List of LocatorListType  
<readerHistoryMemoryPolicy> Memory policy for builtin readers. PREALLOCATED, PREALLOCATED_WITH_REALLOC, DYNAMIC PREALLOCATED
<writerHistoryMemoryPolicy> Memory policy for builtin writers. PREALLOCATED, PREALLOCATED_WITH_REALLOC, DYNAMIC PREALLOCATED
<mutation_tries> Number of different ports to try if reader’s physical port is already in use. UInt32 100

discovery_config

Name Description Values Default
<discoveryProtocol> Indicates which kind of PDP protocol the participant must use. SIMPLE, CLIENT, SERVER, BACKUP SIMPLE
<EDP>
  • If set to SIMPLE, <simpleEDP> would be used.
  • If set to STATIC, StaticEDP based on an XML file would be used with the contents of <staticEndpointXMLFilename>.
 SIMPLE, STATIC SIMPLE
<simpleEDP> Attributes of the SimpleEDP protocol simpleEDP  
<leaseDuration> Indicates how long this RTPSParticipant should consider remote RTPSParticipants alive. DurationType 130 s
<leaseAnnouncement> The period for the RTPSParticipant to send its Discovery Message to all other discovered RTPSParticipants as well as to all Multicast ports. DurationType 40 s
<initialAnnouncements> Allows the user to configure the number and period of the initial RTPSparticipant’s Discovery messages. Initial Announcements  
<staticEndpointXMLFilename> StaticEDP XML filename. Only necessary if <EDP> is set to STATIC string  

simpleEDP

Name Description Values Default
<PUBWRITER_SUBREADER> Indicates if the participant must use Publication Writer and Subscription Reader. Boolean true
<PUBREADER_SUBWRITER> Indicates if the participant must use Publication Reader and Subscription Writer. Boolean true

Initial Announcements

Name Description Values Default
<count> Number of Discovery Messages to send at the period specified by <period>. After these announcements, the RTPSParticipant will continue sending its Discovery Messages at the <leaseAnnouncement> rate. Uint32 0
<period> The period for the RTPSParticipant to send its first <count> Discovery Messages. DurationType 500 ms

Publisher profiles

Publisher profiles allow declaring Publisher configuration from an XML file. The attribute profile_name is the name that the Domain associates to the profile to load it as shown in the Loading and applying profiles section.

<publisher profile_name="pub_profile_name">
    <topic>
        <!-- TOPIC_TYPE -->
    </topic>

    <qos>
        <!-- QOS -->
    </qos>

    <times> <!-- writerTimesType -->
        <initialHeartbeatDelay>
            <!-- DURATION -->
        </initialHeartbeatDelay>
        <heartbeatPeriod>
            <!-- DURATION -->
        </heartbeatPeriod>
        <nackResponseDelay>
            <!-- DURATION -->
        </nackResponseDelay>
        <nackSupressionDuration>
            <!-- DURATION -->
        </nackSupressionDuration>
    </times>

    <unicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </unicastLocatorList>

    <multicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </multicastLocatorList>

    <throughputController>
        <bytesPerPeriod>8192</bytesPerPeriod> <!-- uint32 -->
        <periodMillisecs>1000</periodMillisecs> <!-- uint32 -->
    </throughputController>

    <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>

    <propertiesPolicy>
        <!-- PROPERTIES_POLICY -->
    </propertiesPolicy>

    <userDefinedID>55</userDefinedID> <!-- Int16 -->

    <entityID>66</entityID> <!-- Int16 -->

    <matchedSubscribersAllocation>
        <initial>0</initial> <!-- uint32 -->
        <maximum>0</maximum> <!-- uint32 -->
        <increment>1</increment> <!-- uint32 -->
    </matchedSubscribersAllocation>

</publisher>

Note

Name Description Values Default
<topic> Topic Type configuration of the publisher. Topic Type  
<qos> Publisher QOS configuration. QOS  
<times> It allows configuring some time related parameters of the publisher. Times  
<unicastLocatorList> List of input unicast locators. It expects a LocatorListType. List of LocatorListType  
<multicastLocatorList> List of input multicast locators. It expects a LocatorListType. List of LocatorListType  
<throughputController> Limits the output bandwidth of the publisher. Throughput  
<historyMemoryPolicy> Memory allocation kind for publisher’s history. PREALLOCATED, PREALLOCATED_WITH_REALLOC, DYNAMIC PREALLOCATED
<propertiesPolicy> Additional configuration properties. PropertiesPolicyType  
<userDefinedID> Used for StaticEndpointDiscovery. Int16 -1
<entityID> EntityId of the endpoint. Int16 -1
<matchedSubscribersAllocation> Publisher Allocation Configuration related to the number of matched subscribers. Allocation Configuration  

Times

Name Description Values Default
<initialHeartbeatDelay> Initial heartbeat delay. DurationType ~45 ms
<heartbeatPeriod> Periodic HB period. DurationType 3 s
<nackResponseDelay> Delay to apply to the response of a ACKNACK message. DurationType ~45 ms
<nackSupressionDuration> This time allows the RTPSWriter to ignore nack messages too soon after the data has been sent. DurationType 0 ms

Subscriber profiles

Subscriber profiles allow declaring Subscriber configuration from an XML file. The attribute profile_name is the name that the Domain associates to the profile to load it as shown in Loading and applying profiles.

<subscriber profile_name="sub_profile_name">
    <topic>
        <!-- TOPIC_TYPE -->
    </topic>

    <qos>
        <!-- QOS -->
    </qos>

    <times> <!-- readerTimesType -->
        <initialAcknackDelay>
            <!-- DURATION -->
        </initialAcknackDelay>
        <heartbeatResponseDelay>
            <!-- DURATION -->
        </heartbeatResponseDelay>
    </times>

    <unicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </unicastLocatorList>

    <multicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4/>
        </locator>
    </multicastLocatorList>

    <expectsInlineQos>true</expectsInlineQos> <!-- boolean -->

    <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>

    <propertiesPolicy>
        <!-- PROPERTIES_POLICY -->
    </propertiesPolicy>

    <userDefinedID>55</userDefinedID> <!-- Int16 -->

    <entityID>66</entityID> <!-- Int16 -->

    <matchedPublishersAllocation>
        <initial>0</initial> <!-- uint32 -->
        <maximum>0</maximum> <!-- uint32 -->
        <increment>1</increment> <!-- uint32 -->
    </matchedPublishersAllocation>

</subscriber>

Note

Name Description Values Default
<topic> Topic Type configuration of the subscriber. Topic Type  
<qos> Subscriber QOS configuration. QOS  
<times> It allows configuring some time related parameters of the subscriber. Times  
<unicastLocatorList> List of input unicast locators. It expects a LocatorListType. List of LocatorListType  
<multicastLocatorList> List of input multicast locators. It expects a LocatorListType. List of LocatorListType  
<expectsInlineQos> It indicates if QOS is expected inline. Boolean false
<historyMemoryPolicy> Memory allocation kind for subscriber’s history. PREALLOCATED, PREALLOCATED_WITH_REALLOC, DYNAMIC PREALLOCATED
<propertiesPolicy> Additional configuration properties. PropertiesPolicyType  
<userDefinedID> Used for StaticEndpointDiscovery. Int16 -1
<entityID> EntityId of the endpoint. Int16 -1
<matchedPublishersAllocation> Subscriber Allocation Configuration related to the number of matched publishers. Allocation Configuration  

Times

Name Description Values Default
<initialAcknackDelay> Initial AckNack delay. DurationType ~45 ms
<heartbeatResponseDelay> Delay to be applied when a heartbeat message is received. DurationType ~4.5 ms

Common

In the above profiles, some types are used in several different places. To avoid too many details, some of that places have a tag like LocatorListType that indicates that field is defined in this section.

LocatorListType

It represents a list of Locator_t. LocatorListType is normally used as an anonymous type, this is, it hasn’t its own label. Instead, it is used inside other configuration parameter labels that expect a list of locators and give it sense, for example, in <defaultUnicastLocatorList>. The locator kind is defined by its own tag and can take the values <udpv4>, <tcpv4>, <udpv6>, and <tcpv6>:

<defaultUnicastLocatorList>
    <locator>
        <udpv4>
            <!-- Access as physical, typical UDP usage -->
            <port>7400</port> <!-- uint32 -->
            <address>192.168.1.41</address>
        </udpv4>
    </locator>
    <locator>
        <tcpv4>
            <!-- Both physical and logical (port), useful in TCP transports -->
            <physical_port>5100</physical_port> <!-- uint16 -->
            <port>7400</port> <!-- uint16 -->
            <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
            <wan_address>80.80.99.45</wan_address>
            <address>192.168.1.55</address>
        </tcpv4>
    </locator>
    <locator>
        <udpv6>
            <port>8844</port>
            <address>::1</address>
        </udpv6>
    </locator>
    <locator>
        <tcpv6>
            <!-- Both physical and logical (port), useful in TCP transports -->
            <physical_port>5100</physical_port> <!-- uint16 -->
            <port>7400</port> <!-- uint16 -->
            <address>fe80::55e3:290:165:5af8</address>
        </tcpv6>
    </locator>
</defaultUnicastLocatorList>

In this example, there are one locator of each kind in <defaultUnicastLocatorList>.

Let’s see each possible Locator’s field in detail:

Name Description Values Default
<port> RTPS port number of the locator. Physical port in UDP, logical port in TCP. Uint32 0
<physical_port> TCP’s physical port. Uint32 0
<address> IP address of the locator. string with expected format “”
<unique_lan_id> The LAN ID uniquely identifies the LAN the locator belongs to (TCPv4 only). string (16 bytes)  
<wan_address> WAN IPv4 address (TCPv4 only). string with IPv4 Format 0.0.0.0

PropertiesPolicyType

PropertiesPolicyType (XML label <propertiesPolicy>) allows defining a set of generic properties. It’s useful at defining extended or custom configuration parameters.

<propertiesPolicy>
    <properties>
        <property>
            <name>Property1Name</name> <!-- string -->
            <value>Property1Value</value> <!-- string -->
            <propagate>false</propagate> <!-- boolean -->
        </property>
        <property>
            <name>Property2Name</name> <!-- string -->
            <value>Property2Value</value> <!-- string -->
            <propagate>true</propagate> <!-- boolean -->
        </property>
    </properties>
</propertiesPolicy>
Name Description Values Default
<name> Name to identify the property. string  
<value> Property’s value. string  
<propagate> Indicates if it is going to be serialized along with the object it belongs to. Boolean false

DurationType

DurationType expresses a period of time and it’s commonly used as an anonymous type, this is, it hasn’t its own label. Instead, it is used inside other configuration parameter labels that give it sense, like <leaseAnnouncement> or <leaseDuration>.

<discovery_config>
    <leaseDuration>INFINITE</leaseDuration> <!-- string -->

    <leaseDuration>
        <sec>500</sec> <!-- int32 -->
        <nanosec>0</nanosec> <!-- uint32 -->
    </leaseDuration>

    <leaseAnnouncement>
        <sec>1</sec> <!-- int32 -->
        <nanosec>856000</nanosec> <!-- uint32 -->
    </leaseAnnouncement>
</discovery_config>

Duration time can be defined through <sec> plus <nanosec> labels (see table below). An infinite value can be specified by using the values DURATION_INFINITY, DURATION_INFINITE_SEC and DURATION_INFINITE_NSEC.

Name Description Values Default
<sec> Number of seconds. Int32 0
<nanosec> Number of nanoseconds. UInt32 0

Topic Type

The topic name and data type are used as meta-data to determine whether Publishers and Subscribers can exchange messages. There is a deeper explanation of the “topic” field here: Topic information.

<topic>
    <kind>NO_KEY</kind> <!-- string -->
    <name>TopicName</name> <!-- string -->
    <dataType>TopicDataTypeName</dataType> <!-- string -->
    <historyQos>
        <kind>KEEP_LAST</kind> <!-- string -->
        <depth>20</depth> <!-- uint32 -->
    </historyQos>
    <resourceLimitsQos>
        <max_samples>5</max_samples> <!-- unint32 -->
        <max_instances>2</max_instances> <!-- unint32 -->
        <max_samples_per_instance>1</max_samples_per_instance> <!-- unint32 -->
        <allocated_samples>20</allocated_samples> <!-- unint32 -->
    </resourceLimitsQos>
</topic>
Name Description Values Default
<kind> It defines the Topic’s kind NO_KEY, WITH_KEY NO_KEY
<name> It defines the Topic’s name. Must be unique. string_255  
<dataType> It references the Topic’s data type. string_255  
<historyQos> It controls the behavior of Fast RTPS when the value of an instance changes before it is finally communicated to some of its existing DataReader entities. HistoryQos  
<resourceLimitsQos> It controls the resources that Fast RTPS can use in order to meet the requirements imposed by the application and other QoS settings. ResourceLimitsQos  

HistoryQoS

It controls the behavior of Fast RTPS when the value of an instance changes before it is finally communicated to some of its existing DataReader entities.

Name Description Values Default
<kind> See description below. KEEP_LAST, KEEP_ALL KEEP_LAST
<depth>   UInt32 1000
If the <kind> is set to KEEP_LAST, then Fast RTPS will only attempt to keep the latest values of the instance and discard the older ones.
If the <kind> is set to KEEP_ALL, then Fast RTPS will attempt to maintain and deliver all the values of the instance to existing subscribers.
The setting of <depth> must be consistent with the ResourceLimitsQos <max_samples_per_instance>. For these two QoS to be consistent, they must verify that depth <= max_samples_per_instance.

ResourceLimitsQos

It controls the resources that Fast RTPS can use in order to meet the requirements imposed by the application and other QoS settings.

Name Description Values Default
<max_samples> It must verify that max_samples >= max_samples_per_instance. UInt32 5000
<max_instances> It defines the maximum number of instances. UInt32 10
<max_samples_per_instance> It must verify that HistoryQos depth <= max_samples_per_instance. UInt32 400
<allocated_samples> It controls the maximum number of samples to be stored. UInt32 100

QOS

The quality of service (QoS) handles the restrictions applied to the application.

<qos> <!-- readerQosPoliciesType -->
    <durability>
        <kind>VOLATILE</kind> <!-- string -->
    </durability>

    <liveliness>
        <kind>AUTOMATIC</kind> <!-- string -->
	<lease_duration>
	  <sec>1</sec>
	</lease_duration>
	<announcement_period>
	  <sec>1</sec>
	</announcement_period>
    </liveliness>

    <reliability>
        <kind>BEST_EFFORT</kind>
    </reliability>

    <partition>
        <names>
            <name>part1</name> <!-- string -->
            <name>part2</name> <!-- string -->
        </names>
    </partition>

    <deadline>
        <period>1</period>
    </deadline>

    <lifespan>
        <duration>
            <sec>1</sec>
        </duration>
    </lifespan>

    <disablePositiveAcks>
        <enabled>true</enabled>
    </disablePositiveAcks>
</qos>
Name Description Values Default
<durability> It is defined in Setting the data durability kind section. VOLATILE, TRANSIENT_LOCAL TRANSIENT VOLATILE
<liveliness> Defines the liveliness of the publisher. Liveliness  
<reliability> It is defined in Reliability section. RELIABLE, BEST_EFFORT RELIABLE
<partition> It allows the introduction of a logical partition concept inside the physical partition induced by a domain.   List <string>
<deadline> It is defined in Deadline section. Deadline period as a DurationType c_TimeInfinite
<lifespan> It is defined in Lifespan section. Lifespan duration as a DurationType c_TimeInfinite
<disablePositiveAcks> It is defined in section Disable positive acks   It is disabled by default and duration is set to c_TimeInfinite

Throughput Configuration

Throughput Configuration allows to limit the output bandwidth.

Name Description Values Default
<bytesPerPeriod> Packet size in bytes that this controller will allow in a given period. UInt32 4294967295
<periodMillisecs> Window of time in which no more than <bytesPerPeriod> bytes are allowed. UInt32 0

Allocation Configuration

Allocation Configuration allows to control the allocation behavior of internal collections for which the number of elements depends on the number of entities in the system.

For instance, there are collections inside a publisher which depend on the number of subscribers matching with it.

See Tuning allocations for detailed information on how to tune allocation related parameters.

Name Description Values Default
<initial> Number of elements for which space is initially allocated. UInt32 0
<maximum> Maximum number of elements for which space will be allocated. UInt32 0 (means no limit)
<increment> Number of new elements that will be allocated when more space is necessary. UInt32 1

Example

In this section, there is a full XML example with all possible configuration. It can be used as a quick reference, but it may not be valid due to incompatibility or exclusive properties. Don’t take it as a working example.

<profiles>
    <transport_descriptors>
        <transport_descriptor>
            <transport_id>ExampleTransportId1</transport_id>
            <type>TCPv4</type>
            <sendBufferSize>8192</sendBufferSize>
            <receiveBufferSize>8192</receiveBufferSize>
            <TTL>250</TTL>
            <maxMessageSize>16384</maxMessageSize>
            <maxInitialPeersRange>100</maxInitialPeersRange>
            <interfaceWhiteList>
                <address>192.168.1.41</address>
                <address>127.0.0.1</address>
            </interfaceWhiteList>
            <wan_addr>80.80.55.44</wan_addr>
            <keep_alive_frequency_ms>5000</keep_alive_frequency_ms>
            <keep_alive_timeout_ms>25000</keep_alive_timeout_ms>
            <max_logical_port>200</max_logical_port>
            <logical_port_range>20</logical_port_range>
            <logical_port_increment>2</logical_port_increment>
            <listening_ports>
                <port>5100</port>
                <port>5200</port>
            </listening_ports>
        </transport_descriptor>
        <transport_descriptor>
            <transport_id>ExampleTransportId2</transport_id>
            <type>UDPv6</type>
        </transport_descriptor>
    </transport_descriptors>

    <types>
        <type> <!-- Types can be defined in its own type of tag or sharing the same tag -->
            <enum name="MyAloneEnumType">
                <enumerator name="A" value="0"/>
                <enumerator name="B" value="1"/>
                <enumerator name="C" value="2"/>
            </enum>
        </type>
        <type>
            <enum name="MyEnumType">
                <enumerator name="A" value="0"/>
                <enumerator name="B" value="1"/>
                <enumerator name="C" value="2"/>
            </enum>

            <typedef name="MyAlias1" type="nonBasic" nonBasicTypeName="MyEnumType"/>

            <typedef name="MyAlias2" type="int32" arrayDimensions="2,2"/>

            <struct name="MyStruct1">
                <member name="first" type="int32"/>
                <member name="second" type="int64"/>
            </struct>

            <union name="MyUnion1">
                <discriminator type="byte"/>
                <case>
                    <caseDiscriminator value="0"/>
                    <caseDiscriminator value="1"/>
                    <member name="first" type="int32"/>
                </case>
                <case>
                    <caseDiscriminator value="2"/>
                    <member name="second" type="nonBasic" nonBasicTypeName="MyStruct"/>
                </case>
                <case>
                    <caseDiscriminator value="default"/>
                    <member name="third" type="int64"/>
                </case>
            </union>

            <!-- All possible members struct type -->
            <struct name="MyFullStruct">
                <!-- Primitives & basic -->
                <member name="my_bool" type="boolean"/>
                <member name="my_byte" type="byte"/>
                <member name="my_char" type="char8"/>
                <member name="my_wchar" type="char16"/>
                <member name="my_short" type="int16"/>
                <member name="my_long" type="int32"/>
                <member name="my_longlong" type="int64"/>
                <member name="my_unsignedshort" type="uint16"/>
                <member name="my_unsignedlong" type="uint32"/>
                <member name="my_unsignedlonglong" type="uint64"/>
                <member name="my_float" type="float32"/>
                <member name="my_double" type="float64"/>
                <member name="my_longdouble" type="float128"/>
                <member name="my_string" type="string"/>
                <member name="my_wstring" type="wstring"/>
                <member name="my_boundedString" type="string" stringMaxLength="41925"/>
                <member name="my_boundedWString" type="wstring" stringMaxLength="41925"/>

                <!-- long long_array[2][3][4]; -->
                <member name="long_array" arrayDimensions="2,3,4" type="int32"/>

                <!-- map<long,map<long,long,2>,2> my_map_map; -->
                <!-->
                <typdefe name="my_map_inner" type="int32" key_type="int32" mapMaxLength="2"/>
                <-->
                <member name="my_map_map" type="nonBasic" nonBasicTypeName="my_map_inner" key_type="int32" mapMaxLength="2"/>

                <!-- Complex types -->
                <member name="my_other_struct" type="nonBasic" nonBasicTypeName="OtherStruct"/>
            </struct>
        </type>
    </types>

    <participant profile_name="part_profile_example">
        <rtps>
            <name>Participant Name</name> <!-- String -->

            <defaultUnicastLocatorList>
                <locator>
                    <udpv4>
                        <!-- Access as physical, like UDP -->
                        <port>7400</port>
                        <address>192.168.1.41</address>
                    </udpv4>
                </locator>
                <locator>
                    <tcpv4>
                        <!-- Both physical and logical (port), like TCP -->
                        <physical_port>5100</physical_port>
                        <port>7400</port>
                        <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                        <wan_address>80.80.99.45</wan_address>
                        <address>192.168.1.55</address>
                    </tcpv4>
                </locator>
                <locator>
                    <udpv6>
                        <port>8844</port>
                        <address>::1</address>
                    </udpv6>
                </locator>
            </defaultUnicastLocatorList>

            <defaultMulticastLocatorList>
                <locator>
                    <udpv4>
                        <!-- Access as physical, like UDP -->
                        <port>7400</port>
                        <address>192.168.1.41</address>
                    </udpv4>
                </locator>
                <locator>
                    <tcpv4>
                        <!-- Both physical and logical (port), like TCP -->
                        <physical_port>5100</physical_port>
                        <port>7400</port>
                        <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                        <wan_address>80.80.99.45</wan_address>
                        <address>192.168.1.55</address>
                    </tcpv4>
                </locator>
                <locator>
                    <udpv6>
                        <port>8844</port>
                        <address>::1</address>
                    </udpv6>
                </locator>
            </defaultMulticastLocatorList>

            <sendSocketBufferSize>8192</sendSocketBufferSize>

            <listenSocketBufferSize>8192</listenSocketBufferSize>

            <builtin>
                <discovery_config>

                    <discoveryProtocol>NONE</discoveryProtocol>

                    <EDP>SIMPLE</EDP>

                    <leaseDuration>INFINITE</leaseDuration>

                    <leaseAnnouncement>
                        <sec>1</sec>
                        <nanosec>856000</nanosec>
                    </leaseAnnouncement>

                    <simpleEDP>
                        <PUBWRITER_SUBREADER>true</PUBWRITER_SUBREADER>
                        <PUBREADER_SUBWRITER>true</PUBREADER_SUBWRITER>
                    </simpleEDP>

                    <staticEndpointXMLFilename>filename.xml</staticEndpointXMLFilename>

                </discovery_config>

                <use_WriterLivelinessProtocol>false</use_WriterLivelinessProtocol>

                <domainId>4</domainId>

                <metatrafficUnicastLocatorList>
                    <locator>
                        <udpv4>
                            <!-- Access as physical, like UDP -->
                            <port>7400</port>
                            <address>192.168.1.41</address>
                        </udpv4>
                    </locator>
                    <locator>
                        <tcpv4>
                            <!-- Both physical and logical (port), like TCP -->
                            <physical_port>5100</physical_port>
                            <port>7400</port>
                            <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                            <wan_address>80.80.99.45</wan_address>
                            <address>192.168.1.55</address>
                        </tcpv4>
                    </locator>
                    <locator>
                        <udpv6>
                            <port>8844</port>
                            <address>::1</address>
                        </udpv6>
                    </locator>
                </metatrafficUnicastLocatorList>

                <metatrafficMulticastLocatorList>
                    <locator>
                        <udpv4>
                            <!-- Access as physical, like UDP -->
                            <port>7400</port>
                            <address>192.168.1.41</address>
                        </udpv4>
                    </locator>
                    <locator>
                        <tcpv4>
                            <!-- Both physical and logical (port), like TCP -->
                            <physical_port>5100</physical_port>
                            <port>7400</port>
                            <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                            <wan_address>80.80.99.45</wan_address>
                            <address>192.168.1.55</address>
                        </tcpv4>
                    </locator>
                    <locator>
                        <udpv6>
                            <port>8844</port>
                            <address>::1</address>
                        </udpv6>
                    </locator>
                </metatrafficMulticastLocatorList>

                <initialPeersList>
                    <locator>
                        <udpv4>
                            <!-- Access as physical, like UDP -->
                            <port>7400</port>
                            <address>192.168.1.41</address>
                        </udpv4>
                    </locator>
                    <locator>
                        <tcpv4>
                            <!-- Both physical and logical (port), like TCP -->
                            <physical_port>5100</physical_port>
                            <port>7400</port>
                            <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                            <wan_address>80.80.99.45</wan_address>
                            <address>192.168.1.55</address>
                        </tcpv4>
                    </locator>
                    <locator>
                        <udpv6>
                            <port>8844</port>
                            <address>::1</address>
                        </udpv6>
                    </locator>
                </initialPeersList>

                <readerHistoryMemoryPolicy>PREALLOCATED_WITH_REALLOC</readerHistoryMemoryPolicy>

                <writerHistoryMemoryPolicy>PREALLOCATED</writerHistoryMemoryPolicy>
            </builtin>

            <port>
                <portBase>7400</portBase>
                <domainIDGain>200</domainIDGain>
                <participantIDGain>10</participantIDGain>
                <offsetd0>0</offsetd0>
                <offsetd1>1</offsetd1>
                <offsetd2>2</offsetd2>
                <offsetd3>3</offsetd3>
            </port>

            <participantID>99</participantID>

            <throughputController>
                <bytesPerPeriod>8192</bytesPerPeriod>
                <periodMillisecs>1000</periodMillisecs>
            </throughputController>

            <userTransports>
                <transport_id>TransportId1</transport_id>
                <transport_id>TransportId2</transport_id>
            </userTransports>

            <useBuiltinTransports>false</useBuiltinTransports>

            <propertiesPolicy>
                <properties>
                    <property>
                        <name>Property1Name</name>
                        <value>Property1Value</value>
                        <propagate>false</propagate>
                    </property>
                    <property>
                        <name>Property2Name</name>
                        <value>Property2Value</value>
                        <propagate>false</propagate>
                    </property>
                </properties>
            </propertiesPolicy>
        </rtps>
    </participant>

    <publisher profile_name="pub_profile_example">
        <topic>
            <kind>WITH_KEY</kind>
            <name>TopicName</name>
            <dataType>TopicDataTypeName</dataType>
            <historyQos>
                <kind>KEEP_LAST</kind>
                <depth>20</depth>
            </historyQos>
            <resourceLimitsQos>
                <max_samples>5</max_samples>
                <max_instances>2</max_instances>
                <max_samples_per_instance>1</max_samples_per_instance>
                <allocated_samples>20</allocated_samples>
            </resourceLimitsQos>
        </topic>

        <qos> <!-- writerQosPoliciesType -->
            <durability>
                <kind>VOLATILE</kind>
            </durability>
            <liveliness>
                <kind>AUTOMATIC</kind>
                <lease_duration>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </lease_duration>
                <announcement_period>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </announcement_period>
            </liveliness>
            <reliability>
                <kind>BEST_EFFORT</kind>
                <max_blocking_time>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </max_blocking_time>
            </reliability>
            <partition>
                <names>
                    <name>part1</name>
                    <name>part2</name>
                </names>
            </partition>
            <publishMode>
                <kind>ASYNCHRONOUS</kind>
            </publishMode>
            <disablePositiveAcks>
                <enabled>true</enabled>
                    <duration>
                    <sec>1</sec>
                </duration>
            </disablePositiveAcks>
        </qos>

        <times>
            <initialHeartbeatDelay>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </initialHeartbeatDelay>
            <heartbeatPeriod>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </heartbeatPeriod>
            <nackResponseDelay>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </nackResponseDelay>
            <nackSupressionDuration>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </nackSupressionDuration>
        </times>

        <unicastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
            <locator>
                <tcpv4>
                    <!-- Both physical and logical (port), like TCP -->
                    <physical_port>5100</physical_port>
                    <port>7400</port>
                    <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                    <wan_address>80.80.99.45</wan_address>
                    <address>192.168.1.55</address>
                </tcpv4>
            </locator>
            <locator>
                <udpv6>
                    <port>8844</port>
                    <address>::1</address>
                </udpv6>
            </locator>
        </unicastLocatorList>

        <multicastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
            <locator>
                <tcpv4>
                    <!-- Both physical and logical (port), like TCP -->
                    <physical_port>5100</physical_port>
                    <port>7400</port>
                    <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                    <wan_address>80.80.99.45</wan_address>
                    <address>192.168.1.55</address>
                </tcpv4>
            </locator>
            <locator>
                <udpv6>
                    <port>8844</port>
                    <address>::1</address>
                </udpv6>
            </locator>
        </multicastLocatorList>

        <throughputController>
            <bytesPerPeriod>8192</bytesPerPeriod>
            <periodMillisecs>1000</periodMillisecs>
        </throughputController>

        <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>

        <propertiesPolicy>
            <properties>
                <property>
                    <name>Property1Name</name>
                    <value>Property1Value</value>
                    <propagate>false</propagate>
                </property>
                <property>
                    <name>Property2Name</name>
                    <value>Property2Value</value>
                    <propagate>false</propagate>
                </property>
            </properties>
        </propertiesPolicy>

        <userDefinedID>45</userDefinedID>

        <entityID>76</entityID>
    </publisher>

    <subscriber profile_name="sub_profile_example">
        <topic>
            <kind>WITH_KEY</kind>
            <name>TopicName</name>
            <dataType>TopicDataTypeName</dataType>
            <historyQos>
                <kind>KEEP_LAST</kind>
                <depth>20</depth>
            </historyQos>
            <resourceLimitsQos>
                <max_samples>5</max_samples>
                <max_instances>2</max_instances>
                <max_samples_per_instance>1</max_samples_per_instance>
                <allocated_samples>20</allocated_samples>
            </resourceLimitsQos>
        </topic>

        <qos>
            <durability>
                <kind>PERSISTENT</kind>
            </durability>
            <liveliness>
                <kind>MANUAL_BY_PARTICIPANT</kind>
                <lease_duration>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </lease_duration>
                <announcement_period>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </announcement_period>
            </liveliness>
            <reliability>
                <kind>BEST_EFFORT</kind>
                <max_blocking_time>
                    <sec>1</sec>
                    <nanosec>856000</nanosec>
                </max_blocking_time>
            </reliability>
            <partition>
                <names>
                    <name>part1</name>
                    <name>part2</name>
                </names>
            </partition>
        </qos>

        <times>
            <initialAcknackDelay>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </initialAcknackDelay>
            <heartbeatResponseDelay>
                <sec>1</sec>
                <nanosec>856000</nanosec>
            </heartbeatResponseDelay>
        </times>

        <unicastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
            <locator>
                <tcpv4>
                    <!-- Both physical and logical (port), like TCP -->
                    <physical_port>5100</physical_port>
                    <port>7400</port>
                    <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                    <wan_address>80.80.99.45</wan_address>
                    <address>192.168.1.55</address>
                </tcpv4>
            </locator>
            <locator>
                <udpv6>
                    <port>8844</port>
                    <address>::1</address>
                </udpv6>
            </locator>
        </unicastLocatorList>

        <multicastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
            <locator>
                <tcpv4>
                    <!-- Both physical and logical (port), like TCP -->
                    <physical_port>5100</physical_port>
                    <port>7400</port>
                    <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
                    <wan_address>80.80.99.45</wan_address>
                    <address>192.168.1.55</address>
                </tcpv4>
            </locator>
            <locator>
                <udpv6>
                    <port>8844</port>
                    <address>::1</address>
                </udpv6>
            </locator>
        </multicastLocatorList>

        <expectsInlineQos>true</expectsInlineQos>

        <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>

        <propertiesPolicy>
            <properties>
                <property>
                    <name>Property1Name</name>
                    <value>Property1Value</value>
                    <propagate>false</propagate>
                </property>
                <property>
                    <name>Property2Name</name>
                    <value>Property2Value</value>
                    <propagate>false</propagate>
                </property>
            </properties>
        </propertiesPolicy>

        <userDefinedID>55</userDefinedID>

        <entityID>66</entityID>
    </subscriber>
</profiles>