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.

Library settings¶

This section is devoted to general settings that are not constraint to specific entities (like participants, subscribers, publishers) or functionality (like transports or types). All of them are gathered under the library_settings profile.

    <library_settings>
        <intraprocess_delivery>FULL</intraprocess_delivery> <!-- OFF | USER_DATA_ONLY | FULL -->
    </library_settings>

Currently only the Intra-process delivery feature is comprised here.

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

LOCATOR_LIST means it expects a LocatorListType.
PROPERTIES_POLICY means that the label is a PropertiesPolicyType block.
DURATION means it expects a DurationType.
For BUILTIN details, please refer to Built-in parameters.
For ALLOCATION details, please refer to Participant allocation parameters.

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

        <ignoreParticipantFlags>FILTER_DIFFERENT_HOST</ignoreParticipantFlags> <!-- ParticipantFlags 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
`<ignoreParticipantFlags>`	Restricts metatraffic using several filtering criteria.	ignoreParticipantFlags	No filtering.
`<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.	historyMemoryPolicy	`PREALLOCATED`
`<writerHistoryMemoryPolicy>`	Memory policy for builtin writers.	historyMemoryPolicy	`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`

ignoreParticipantFlags

FILTER_DIFFERENT_HOST all metadata from another host would be discarded.
FILTER_DIFFERENT_PROCESS all metadata from another process on the same host would be discarded.
FILTER_SAME_PROCESS all metadata from our own process would be discarded.
FILTER_DIFFERENT_PROCESS | FILTER_SAME_PROCESS all metadata from our own host would be discarded.

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

LOCATOR_LIST means it expects a LocatorListType.
PROPERTIES_POLICY means that the label is a PropertiesPolicyType block.
DURATION means it expects a DurationType.
For QOS details, please refer to QOS.
TOPIC_TYPE is detailed in section Topic Type.

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.	historyMemoryPolicy	`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

LOCATOR_LIST means it expects a LocatorListType.
PROPERTIES_POLICY means that the label is a PropertiesPolicyType block.
DURATION means it expects a DurationType.
For QOS details, please refer to QOS.
TOPIC_TYPE is detailed in section Topic Type.

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.	historyMemoryPolicy	`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

History Memory Policy Configuration¶

Controls the allocation behavior of the change histories.

PREALLOCATED: As the history gets larger, memory is allocated in chunks. Each chunk accommodates a number of changes, and no more allocations are done until that chunk is full. Provides minimum number of dynamic allocations at the cost of increased memory footprint. Maximum payload size of changes must be appropriately configured, as history will not be able to accommodate changes with larger payload after the allocation.
PREALLOCATED_WITH_REALLOC: Like PREALLOCATED, but preallocated memory can be reallocated to accommodate changes with larger payloads than the defined maximum.
DYNAMIC: Every change gets a fresh new allocated memory of the correct size. It minimizes the memory footprint, at the cost of increased number of dynamic allocations.
DYNAMIC_REUSABLE: Like DYNAMIC, but instead of deallocating the memory when the change is removed from the history, it is reused for a future change, reducing the amount of dynamic allocations. If the new change has larger payload, it will be reallocated to accommodate the new size.

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>

<!-->CONF-LIBRARY-SETTINGS<-->
    <library_settings>
        <intraprocess_delivery>FULL</intraprocess_delivery> <!-- OFF | USER_DATA_ONLY | FULL -->
    </library_settings>