Skip to content

Latest commit

 

History

History
1560 lines (1270 loc) · 98.6 KB

xmlprofiles.rst

File metadata and controls

1560 lines (1270 loc) · 98.6 KB
Raw

XML profiles

The :ref:`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 :ref:`transportdescriptors` case) that is used to reference the XML profile during the creation of a Fast RTPS entity, :ref:`comm-transports-configuration`, or :ref:`dynamic-types`.

Making an XML

An XML file can contain several XML profiles. The available profile types are :ref:`transportdescriptors`, :ref:`xmldynamictypes`, :ref:`participantprofiles`, :ref:`publisherprofiles`, and :ref:`subscriberprofiles`.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->PROFILES-TRANSPORT-DESCRIPTORS<-->
    :lines: 1-6, 43-63

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

Finally, The :ref:`examplexml` 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.

.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-LOAD-APPLY-PROFILES
    :end-before: //!--

To load dynamic types from its declaration through XML see the :ref:`Usage` section of :ref:`xmldynamictypes`.

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.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-LIBRARY-SETTINGS<-->
    :end-before: <!--><-->

Currently only the :ref:`intraprocess-delivery` feature is comprised here.

Transport descriptors

This section allows creating transport descriptors to be referenced by the :ref:`participantprofiles`. 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:

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-TRANSPORT-DESCRIPTORS<-->
    :lines: 1, 11-39, 53

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. :class:`UDPv4`, :class:`UDPv6`, :class:`TCPv4`, :class:`TCPv6`, :class:`SHM` :class:`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 :ref:`whitelist-interfaces`. :ref:`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

:class:`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 :ref:`RTCP<rtcpdefinition>` 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 :ref:`RTCP<rtcpdefinition>` negotiations. (TCP only) uint16 100
<logical_port_range> The maximum number of logical ports per request to try during :ref:`RTCP<rtcpdefinition>` negotiations. (TCP only) uint16 20
<logical_port_increment> Increment between logical ports to try during :ref:`RTCP<rtcpdefinition>` 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). :ref:`tcp-tls`  
<segment_size> Size (in bytes) of the shared-memory segment. (OPTIONAL, SHM only). uint32 262144
<port_queue_capacity> Capacity (in number of messages) available to every Listener (OPTIONAL, SHM only). uint32 512
<healthy_check_timeout_ms> Maximum time-out (in milliseconds) used when checking whether a Listener is alive & OK (OPTIONAL, SHM only). uint32 1000
<rtps_dump_file> Complete path (including file) where RTPS messages will be stored for debugging purposes. An empty string indicates no trace will be performed (OPTIONAL, SHM only). string empty

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

There are more examples of transports descriptors in :ref:`comm-transports-configuration`.

TLS Configuration

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

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-TCP-TLS<-->
    :end-before: <!--><-->
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:

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-- STAND ALONE TYPES START -->
    :end-before: <!-- STAND ALONE TYPES END -->

Rooted:

.. literalinclude:: ../code/XMLTesterAux.xml
    :language: xml
    :start-after: <!-- ROOTED TYPES START -->
    :end-before: <!-- ROOTED TYPES END -->

Finally, each <type> tag can contain one or more :ref:`Type definitions <Type definition>`. 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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-DYN-ENUM<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-DYN-ENUM
    :end-before: //!--

Typedef

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

Example:

XML C++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-TYPEDEF<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-TYPEDEF
    :end-before: //!--

Struct

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

Example:

XML C++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-STRUCT<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-STRUCT
    :end-before: //!--

Structs can inherit from another structs:

XML C++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-STRUCT-INHERIT<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-STRUCT-INHERIT
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-UNION<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-UNION
    :end-before: //!--

Bitset

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

Example:

XML C++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-BITSET<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-BITSET
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-BITSET-INHERIT<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-BITSET-INHERIT
    :end-before: //!--

Bitmask

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

Example:

XML C++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-BITMASK<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-BITMASK
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-GENERIC<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-GENERIC
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-ARRAYS<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-ARRAYS
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-SEQUENCES<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-SEQUENCES
    :end-before: //!--

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++ 
.. literalinclude:: ../code/XMLTester.xml
  :language: xml
  :start-after: <!-->XML-MAPS<-->
  :end-before: <!--><-->


.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-MAPS
    :end-before: //!--

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:

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-COMPLEX<-->
    :end-before: <!--><-->

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.

.. literalinclude:: ../code/CodeTester.cpp
    :language: cpp
    :start-after: //XML-USAGE
    :end-before: //!--

Participant profiles

Participant profiles allow declaring :ref:`participantconfiguration` 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 :ref:`loadingapplyingprofiles`.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PARTICIPANT<-->
    :end-before: <!--><-->

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 :ref:`LocatorListType`. LocatorListType  
<defaultMulticastLocatorList> List of default input multicast locators. It expects a :ref:`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 :ref:`builtin` section. :ref:`builtin`  
<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 :ref:`PropertiesPolicyType`. :ref:`PropertiesPolicyType`  
<allocation> Configuration regarding allocation behavior. It expects a :ref:`ParticipantAllocationType` :ref:`ParticipantAllocationType`  

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 :class:`Participant's rtps` configuration allows defining parameters related with allocation behavior on the participant.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PARTICIPANT-ALLOCATION<-->
    :end-before: <!--><-->
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 :ref:`CommonAlloc` related to the total number of participants in the domain (local and remote). :ref:`CommonAlloc`  
<total_readers> Participant :ref:`CommonAlloc` related to the total number of readers on each participant (local and remote). :ref:`CommonAlloc`  
<total_writers> Participant :ref:`CommonAlloc` related to the total number of writers on each participant (local and remote). :ref:`CommonAlloc`  
<max_partitions> Maximum size of the partitions submessage. Zero for no limit. See :ref:`MessageMaxSize`. UInt32  
<max_user_data> Maximum size of the user data submessage. Zero for no limit. See :ref:`MessageMaxSize`. UInt32  
<max_properties> Maximum size of the properties submessage. Zero for no limit. See :ref:`MessageMaxSize`. UInt32  

Built-in parameters

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

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-BUILTIN<-->
    :end-before: <!--><-->
Name Description Values Default
<discovery_config> This is the main tag where discovery-related settings can be configured. :ref:`discovery_config <dconf>`  
<avoid_builtin_multicast> Restricts metatraffic multicast traffic to PDP only. Boolean :class:`true`
<use_WriterLivelinessProtocol> Indicates to use the WriterLiveliness protocol. Boolean :class:`true`
<domainId> DomainId to be used by the RTPSParticipant. UInt32 0
<metatrafficUnicastLocatorList> Metatraffic Unicast Locator List |loclist|  
<metatrafficMulticastLocatorList> Metatraffic Multicast Locator List |loclist|  
<initialPeersList> Initial peers. |loclist|  
<readerHistoryMemoryPolicy> Memory policy for builtin readers. |mempol| |mempoldefault|
<writerHistoryMemoryPolicy> Memory policy for builtin writers. |mempol| |mempoldefault|
<readerPayloadSize> Maximum payload size for builtin readers. UInt32 512
<writerPayloadSize> Maximum payload size for builtin writers. UInt32 512
<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. |protocol| :class:`SIMPLE`
<ignoreParticipantFlags> Restricts metatraffic using several filtering criteria. |filterlist| :class:`NO_FILTER`
<EDP>
  • If set to :class:`SIMPLE`, <simpleEDP> would be used.
  • If set to :class:`STATIC`, StaticEDP based on an XML file would be used with the contents of <staticEndpointXMLFilename>.
 :class:`SIMPLE`, :class:`STATIC` :class:`SIMPLE`
<simpleEDP> Attributes of the SimpleEDP protocol :ref:`simpleEDP <sedp>`  
<leaseDuration> Indicates how long this RTPSParticipant should consider remote RTPSParticipants alive. :ref:`DurationType` 20 s
<leaseAnnouncement> The period for the RTPSParticipant to send its Discovery Message to all other discovered RTPSParticipants as well as to all Multicast ports. :ref:`DurationType` 3 s
<initialAnnouncements> Allows the user to configure the number and period of the initial RTPSparticipant's Discovery messages. :ref:`Initial Announcements <InitAnnounce>`  
<staticEndpointXMLFilename> StaticEDP XML filename. Only necessary if <EDP> is set to :class:`STATIC` string  

ignoreParticipantFlags

Possible values Description
:class:`NO_FILTER` All Discovery traffic is processed
:class:`FILTER_DIFFERENT_HOST` Discovery traffic from another host is discarded
:class:`FILTER_DIFFERENT_PROCESS` Discovery traffic from another process on the same host is discarded
:class:`FILTER_SAME_PROCESS` Discovery traffic from participant's own process is discarded.
:class:`FILTER_DIFFERENT_PROCESS | FILTER_SAME_PROCESS` Discovery traffic from participant's own host is discarded.

simpleEDP

Name Description Values Default
<PUBWRITER_SUBREADER> Indicates if the participant must use Publication Writer and Subscription Reader. Boolean :class:`true`
<PUBREADER_SUBWRITER> Indicates if the participant must use Publication Reader and Subscription Writer. Boolean :class:`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 5
<period> The period for the RTPSParticipant to send its first <count> Discovery Messages. :ref:`DurationType` 100 ms

Publisher profiles

Publisher profiles allow declaring :ref:`Publisher configuration <pubsubconfiguration>` 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 :ref:`loadingapplyingprofiles` section.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PUBLISHER<-->
    :end-before: <!--><-->

Note

Name Description Values Default
<topic> :ref:`TopicType` configuration of the publisher. :ref:`TopicType`  
<qos> Publisher :ref:`CommonQOS` configuration. :ref:`CommonQOS`  
<times> It allows configuring some time related parameters of the publisher. :ref:`Times <pubtimes>`  
<unicastLocatorList> List of input unicast locators. It expects a :ref:`LocatorListType`. List of :ref:`LocatorListType`  
<multicastLocatorList> List of input multicast locators. It expects a :ref:`LocatorListType`. List of :ref:`LocatorListType`  
<throughputController> Limits the output bandwidth of the publisher. Throughput  
<historyMemoryPolicy> Memory allocation kind for publisher's history. :ref:`historyMemoryPolicy <mempol>` :class:`PREALLOCATED`
<propertiesPolicy> Additional configuration properties. :ref:`PropertiesPolicyType`  
<userDefinedID> Used for StaticEndpointDiscovery. Int16 -1
<entityID> EntityId of the endpoint. Int16 -1
<matchedSubscribersAllocation> Publisher :ref:`CommonAlloc` related to the number of matched subscribers. :ref:`CommonAlloc`  

Times

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

Subscriber profiles

Subscriber profiles allow declaring :ref:`Subscriber configuration <pubsubconfiguration>` from an XML file. The attribute profile_name is the name that the Domain associates to the profile to load it as shown in :ref:`loadingapplyingprofiles`.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-SUBSCRIBER<-->
    :end-before: <!--><-->

Note

Name Description Values Default
<topic> :ref:`TopicType` configuration of the subscriber. :ref:`TopicType`  
<qos> Subscriber :ref:`CommonQOS` configuration. :ref:`CommonQOS`  
<times> It allows configuring some time related parameters of the subscriber. :ref:`Times <subtimes>`  
<unicastLocatorList> List of input unicast locators. It expects a :ref:`LocatorListType`. List of :ref:`LocatorListType`  
<multicastLocatorList> List of input multicast locators. It expects a :ref:`LocatorListType`. List of :ref:`LocatorListType`  
<expectsInlineQos> It indicates if QOS is expected inline. Boolean :class:`false`
<historyMemoryPolicy> Memory allocation kind for subscriber's history. :ref:`historyMemoryPolicy <mempol>` :class:`PREALLOCATED`
<propertiesPolicy> Additional configuration properties. :ref:`PropertiesPolicyType`  
<userDefinedID> Used for StaticEndpointDiscovery. Int16 -1
<entityID> EntityId of the endpoint. Int16 -1
<matchedPublishersAllocation> Subscriber :ref:`CommonAlloc` related to the number of matched publishers. :ref:`CommonAlloc`  

Times

Name Description Values Default
<initialAcknackDelay> Initial AckNack delay. :ref:`DurationType` ~45 ms
<heartbeatResponseDelay> Delay to be applied when a heartbeat message is received. :ref:`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 :class:`LocatorListType` that indicates that field is defined in this section.

LocatorListType

It represents a list of :class:`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>:

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-LOCATOR-LIST<-->
    :end-before: <!--><-->

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

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PROPERTIES-POLICY<-->
    :end-before: <!--><-->
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 :class:`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>.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-DURATION<-->
    :end-before: <!--><-->

Duration time can be defined through <sec> plus <nanosec> labels (see table below). An infinite value can be specified by using the values :class:`DURATION_INFINITY`, :class:`DURATION_INFINITE_SEC` and :class:`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: :ref:`Topic_information`.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-TOPIC<-->
    :end-before: <!--><-->
Name Description Values Default
<kind> It defines the Topic's kind :class:`NO_KEY`, :class:`WITH_KEY` :class:`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. :ref:`HistoryQos <hQos>`  
<resourceLimitsQos> It controls the resources that Fast RTPS can use in order to meet the requirements imposed by the application and other QoS settings. :ref:`ResourceLimitsQos <rLsQos>`  

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. :class:`KEEP_LAST`, :class:`KEEP_ALL` :class:`KEEP_LAST`
<depth>   UInt32 1000
If the <kind> is set to :class:`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 :class:`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 :ref:`ResourceLimitsQos <rLsQos>` <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 :ref:`HistoryQos <hQos>` 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.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-QOS<-->
    :end-before: <!--><-->
Name Description Values Default
<durability> It is defined in :ref:`SettingDataDurability` section. :class:`VOLATILE`, :class:`TRANSIENT_LOCAL` :class:`TRANSIENT` :class:`VOLATILE`
<liveliness> Defines the liveliness of the publisher. :ref:`liveliness-qos`  
<reliability> It is defined in :ref:`reliability` section. :class:`RELIABLE`, :class:`BEST_EFFORT` :class:`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 :ref:`deadline-qos` section. Deadline period as a :ref:`DurationType` :class:`c_TimeInfinite`
<lifespan> It is defined in :ref:`lifespan-qos` section. Lifespan duration as a :ref:`DurationType` :class:`c_TimeInfinite`
<disablePositiveAcks> It is defined in section :ref:`disable-positive-acks-qos`   It is disabled by default and duration is set to :class:`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 :ref:`realtime-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

Submessage Size Limit

While some submessages have a fixed size (for example, SequenceNumber), others have a variable size depending on the data they contain. Processing a submessage requires having a memory chunk large enough to contain a copy of the submessage data. That is easy to handle when dealing with fixed variable submessages, as size is known and memory can be allocated beforehand. For variable size submessages on the other hand, two different strategies can be used:

  • Set a maximum size for the data container, which will be allocated beforehand during the participant's setup. This avoids dynamic allocations during message communication. However, any submessages with a larger payload than the defined maximum will not fit in, and will therefore be discarded.
  • Do not set any maximum size for the data container, and instead allocate the required memory dynamically upon submessage arrival (according to the size declared on the submessage header). This allows for any size of submessages, at the cost of dynamic allocations during message decoding.

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.

.. literalinclude:: ../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-EXAMPLE<-->
    :end-before: <!--><-->
    :lines: 2,4-