.. include:: ../../03-exports/aliases.include .. include:: ../../03-exports/aliases-api.include .. include:: ../../03-exports/roles.include .. _participantprofiles: DomainParticipant profiles -------------------------- The |DomainParticipant| profiles allow the definition of the configuration of |DomainParticipants-api| through XML files. These profiles are defined within the ```` XML tags. .. _domainparticipantattributes: DomainParticipant XML attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ```` element has two attributes defined: ``profile_name`` and ``is_default_profile``. .. list-table:: :header-rows: 1 :align: left * - Name - Description - Use * - ``profile_name`` - Sets the name under which the ```` profile is registered in the DDS Domain, |br| so that it can be loaded later by the |DomainParticipantFactory-api|, as shown in |br| :ref:`loadingapplyingprofiles`. - Mandatory * - ``is_default_profile`` - Sets the ```` profile as the default profile. Thus, if a default profile |br| exists, it will be used when no other DomainParticipant profile is specified at the |br| DomainParticipant's creation. - Optional .. _domainparticipantconfig: DomainParticipant configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ```` element has two child elements: ```` and ````. All the DomainParticipant configuration options belong to the ```` element, except for the DDS |DomainId-api| which is defined by the ```` element. Below a list with the configuration XML elements is presented: +----------------+----------------------------------------------------------------------------+--------------+---------+ | Name | Description | Values | Default | +================+============================================================================+==============+=========+ | ```` | DomainId to be used by the DomainParticipant. | ``uint32_t`` | 0 | +----------------+----------------------------------------------------------------------------+--------------+---------+ | ```` | *Fast DDS* DomainParticipant configurations. |br| | :ref:`RTPS` | | | | See :ref:`RTPS`. | | | +----------------+----------------------------------------------------------------------------+--------------+---------+ .. _RTPS: RTPS element type """"""""""""""""" The following is a list with all the possible child XML elements of the ```` element. These elements allow the user to define the DomainParticipant configuration. .. |PartAlloc| replace:: :ref:`DomainParticipantAllocationType ` .. |PolicyType| replace:: :ref:`PropertiesPolicyType ` +--------------------------------------+------------------------------------------------+--------------------+---------+ | Name | Description | Values | Default | +======================================+================================================+====================+=========+ | ```` | The DomainParticipant's name. | ``string_255`` | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | List of default reception unicast locators |br|| ```` | | | | for user data traffic (see |br| | | | | | ```` |br| | | | | | defined in :ref:`builtin`). |br| | | | | | It expects a :ref:`LocatorListType`. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | List of default reception multicast |br| | ```` | | | | locators for user data traffic (see |br| | | | | | ```` |br| | | | | | defined in :ref:`builtin`). |br| | | | | | It expects a :ref:`LocatorListType`. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Size in bytes of the send socket buffer. |br| | ``uint32_t`` | 0 | | | If the value is zero then *Fast DDS* will |br| | | | | | use the system default socket size. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Size in bytes of the reception socket |br| | ``uint32_t`` | 0 | | | buffer. If the value is zero then |br| | | | | | *Fast DDS* will use the system default |br| | | | | | socket size. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | |WireProtocolConfigQos::builtin-api| | :ref:`builtin` | | | | public data member of the |br| | | | | | |WireProtocolConfigQos-api| | | | | | class. |br| | | | | | See the | | | | | :ref:`builtin` section. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Allows defining the port and gains related |br|| `Port`_ | | | | to the RTPS protocol. See the `Port`_ section. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | DomainParticipant's identifier. Typically |br| | ``int32_t`` | 0 | | | it will be automatically generated by the |br| | | | | | |DomainParticipantFactory|. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Limits middleware's bandwidth usage. |br| | :ref:`Throughput` | | | | See the :ref:`Throughput` section. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Transport descriptors to be used by the |br| | ``List `` | | | | DomainParticipant. See |br| | | | | | :ref:`transportdescriptors`. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Boolean field to indicate the system |br| | ``bool`` | true | | | whether the DomainParticipant will use the |br|| | | | | default | | | | | |WireProtocolConfigQos::builtin-api| | | | | | transport instead |br| | | | | | of its ````. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Configuration option to determine which |br| | ``string_255`` | DEFAULT | | | transports will be instantiated if the |br| | | | | | ``useBuiltinTransports`` is set to true. |br| | | | | | See :ref:`rtps_layer_builtin_transports`. |br| | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Additional configuration properties. |br| | |PolicyType| | | | | It expects a |PolicyType|. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ```` | Configuration regarding allocation behavior. | |PartAlloc| | | | | |br| It expects a |br| |PartAlloc|. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ | ````| Defined flow controller descriptors. |br| ||FlowControllersQos|| | | | See :ref:`flowcontrollers_xml`. | | | +--------------------------------------+------------------------------------------------+--------------------+---------+ **Example** .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML-PARTICIPANT<--> :end-before: <--> :lines: 2-3, 5-93, 95 .. note:: - :class:`LOCATOR_LIST` means a :ref:`LocatorListType` is expected. - :class:`PROPERTIES_POLICY` means that the label is a :ref:`PropertiesPolicyType` block. - For :class:`BUILTIN` details, please refer to :ref:`builtin`. - For :class:`ALLOCATION` details, please refer to :ref:`ParticipantAllocationType`. .. _Port: Port Configuration ****************** According to the `RTPS standard `_ (Section 9.6.1.1), the |RTPSParticipants-api|' discovery traffic unicast listening ports are calculated using the following equation: :math:`7400 + 250 * DomainId + 10 + 2 * ParticipantId`. Therefore the following parameters can be specified: +------------------------------+------------------------------------------------------+-----------------+--------------+ | Name | Description | Values | Default | +==============================+======================================================+=================+==============+ | ```` | Base ``port``. | ``uint16_t`` | 7400 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Gain in DomainId. | ``uint16_t`` | 250 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Gain in |WireProtocolConfigQos::participant_id-api|. | ``uint16_t`` | 2 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Multicast metadata offset. | ``uint16_t`` | 0 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Unicast metadata offset. | ``uint16_t`` | 10 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Multicast user data offset. | ``uint16_t`` | 1 | +------------------------------+------------------------------------------------------+-----------------+--------------+ | ```` | Unicast user data offset. | ``uint16_t`` | 11 | +------------------------------+------------------------------------------------------+-----------------+--------------+ .. warning:: Changing these default parameters may break compatibility with other RTPS compliant implementations, as well as with other *Fast DDS* applications with default port settings. .. _ParticipantAllocationType: ParticipantAllocationType **************************** The ``ParticipantAllocationType`` defines the ```` element, which allows setting of the parameters related with the allocation behavior on the DomainParticipant. Please refer to :ref:`participantresourcelimitsqos` for a detailed documentation on DomainParticipants allocation configuration. .. list-table:: :header-rows: 1 :align: left * - Name - Description - Values - Default * - ```` - Defines the limits for the remote locators' collections. |br| See :ref:`remotelocatorsallocationattributes`. - ```` |br| ```` - * - ```` - Child element of ````. |br| Maximum number of unicast locators expected on a |br| remote entity. It is recommended to use the maximum |br| number of network interfaces available on the machine |br| on which DomainParticipant is running. |br| See :ref:`remotelocatorsallocationattributes`. - ``uint32_t`` - 4 * - ```` - Child element of ````. |br| Maximum number of multicast locators expected on a |br| remote entity. May be set to zero to disable multicast |br| traffic. See :ref:`remotelocatorsallocationattributes`. - ``uint32_t`` - 1 * - ```` - DomainParticipant :ref:`CommonAlloc` to specify the |br| total number of DomainParticipants in the domain |br| (local and remote). See |br| :ref:`ResourceLimitedContainerConfig`. - :ref:`CommonAlloc` - * - ```` - DomainParticipant :ref:`CommonAlloc` to specify the |br| total number of DataReader on each DomainParticipant |br| (local and remote). See |br| :ref:`ResourceLimitedContainerConfig`. - :ref:`CommonAlloc` - * - ```` - DomainParticipant :ref:`CommonAlloc` related to the |br| total number of DataWriters on each DomainParticipant |br| (local and remote). See :ref:`resourcelimitedcontainerconfig`. - :ref:`CommonAlloc` - * - ```` - Maximum size of the partitions submessage. |br| Set to zero for no limit. |br| See :ref:`sendbuffersallocationattributes`. - ``uint32_t`` - * - ```` - Maximum size of the user data submessage. |br| Set to zero for no limit. See |br| :ref:`sendbuffersallocationattributes`. - ``uint32_t`` - * - ```` - Maximum size of the properties submessage. |br| Set to zero for no limit. See |br| :ref:`sendbuffersallocationattributes`. - ``uint32_t`` - **Example** .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML-PARTICIPANT-ALLOCATION<--> :end-before: <--> .. _builtin: Builtin parameters ******************** By calling the |DomainParticipantQos::wire_protocol-api| member function of the |DomainParticipantQos-api|, it is possible to access the |WireProtocolConfigQos::builtin-api| public data member of the |WireProtocolConfigQos-api| class. This section specifies the available XML members for the configuration of this |WireProtocolConfigQos::builtin-api| parameters. .. Some large words outside of table. Then table fit maximum line length .. |loclist| replace:: A set of ```` |br| members. |br| See :ref:`LocatorListType` .. |mempol| replace:: :ref:`HistoryMemoryPolicy ` .. |mempoldefault| replace:: |PREALLOCATED-xml-api| +---------------------------------------+--------------------------------------+---------------------+-----------------+ | Name | Description | Values | Default | +=======================================+======================================+=====================+=================+ | ```` | This is the main element within |br| | :ref:`dconf` | | | | which discovery-related |br| | | | | | settings can be configured. |br| | | | | | See :ref:`discovery`. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Restricts multicast metatraffic |br| | ``bool`` | :class:`true` | | | to PDP only. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Indicates whether to use the |br| | ``bool`` | :class:`true` | | | DataWriterLiveliness protocol. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Metatraffic Unicast Locator List. | |loclist| | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Metatraffic Multicast Locator List. | |loclist| | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | The list of IP-port address |br| | |loclist| | | | | pairs of all other |br| | | | | | |DomainParticipants| with which |br| | | | | | a |DomainParticipant| will |br| | | | | | communicate. See |br| | | | | | :ref:`Simple Initial Peers` | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Memory policy for DataReaders. |br| | |mempol| | |mempoldefault| | | | See :ref:`historyqospolicykind`. | | | | | | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Memory policy for DataWriters. |br| | |mempol| | |mempoldefault| | | | See :ref:`historyqospolicykind`. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Maximum DataReader's History |br| | ``uint32_t`` | 512 | | | payload size. Allows to reserve |br| | | | | | all the required memory at |br| | | | | | DataReader initialization. |br| | | | | | See :ref:`memorymanagementpolicy`. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Maximum DataWriter's History |br| | ``uint32_t`` | 512 | | | payload size. Allows to reserve |br| | | | | | all the required memory at |br| | | | | | DataWriter initialization. |br| | | | | | See :ref:`memorymanagementpolicy`. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ | ```` | Number of different ports |br| | ``uint32_t`` | 100 | | | to try if DataReader's physical |br| | | | | | port is already in use. | | | +---------------------------------------+--------------------------------------+---------------------+-----------------+ **Example** .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML-BUILTIN<--> :end-before: <--> .. _dconf: discovery_config ################ Through the ```` element, *Fast DDS* allows the configuration of the discovery mechanism via an XML file. Please refer to the :ref:`discovery` section for more detail on the various types of discovery mechanisms and configurable settings. +---------------------------------+------------------------------------------------+---------------------+-------------+ | Name | Description | Values | Default | +=================================+================================================+=====================+=============+ | ```` | Indicates which discovery protocol |br| | |SIMPLE| | |SIMPLE| | | | the DomainParticipant will use. |br| +---------------------+ | | | See :ref:`disc_mechanisms`. | |CLIENT| | | | | +---------------------+ | | | | |SERVER| | | | | +---------------------+ | | | | |BACKUP| | | | | +---------------------+ | | | | |NONE| | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | Restricts metatraffic using several |br| | :ref:`partfiltering`| |NO_FILTER| | | | filtering criteria. | | | | | See :ref:`discovery_ignore_flags`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | If set to |SIMPLE|, ```` |br| | |SIMPLE| | |SIMPLE| | | | element would be used. |br| +---------------------+ | | | If set to ``STATIC``, |EDPStatic| will be |br| | ``STATIC`` | | | | performed, configured with the contents |br| | | | | | of the XML file set in | | | | | ````. |br| | | | | | See :ref:`discovery`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | Attributes of the Simple Discovery |br| | :ref:`sedp` | | | | Protocol. See :ref:`Simple EDP Attributes`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | Indicates how long the DomainParticipant |br| | :ref:`DurationType` | 20s | | | should consider remote DomainParticipants |br| | | | | | alive. | | | | | See :ref:`discovery_lease_dur`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | The period for the DomainParticipant to |br| | :ref:`DurationType` | 3s | | | send its discovery message to all other |br| | | | | | discovered DomainParticipants as well as |br| | | | | | to all Multicast ports. | | | | | See :ref:`discovery_lease_announ`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | Allows the user to configure the number |br| | :ref:`InitAnnounce` | | | | and period of the DomainParticipant's initial | | | | | |br| discovery messages. | | | | | See :ref:`Initial Announcements`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ | ```` | The XML filename with the static EDP |br| | ``string`` | | | | configuration. Only necessary if |br| | | | | | the ```` member is set to |br| | | | | | ``STATIC``. See :ref:`discovery_static`. | | | +---------------------------------+------------------------------------------------+---------------------+-------------+ .. _partfiltering: ignoreParticipantFlags ++++++++++++++++++++++ +----------------------------------------------------+-----------------------------------------------------------------+ | Possible values | Description | +====================================================+=================================================================+ | |NO_FILTER| | All Discovery traffic is processed. | +----------------------------------------------------+-----------------------------------------------------------------+ | |FILTER_DIFFERENT_HOST| | Discovery traffic from another host is discarded. | +----------------------------------------------------+-----------------------------------------------------------------+ | |FILTER_DIFFERENT_PROCESS| | Discovery traffic from another process on the same host is |br| | | | discarded. | +----------------------------------------------------+-----------------------------------------------------------------+ | |FILTER_SAME_PROCESS| | Discovery traffic from DomainParticipant's own process is |br| | | | discarded. | +----------------------------------------------------+-----------------------------------------------------------------+ | |FILTER_DIFFERENT_PROCESS| | |FILTER_SAME_PROCESS| | Discovery traffic from DomainParticipant's own host is |br| | | | discarded. | +----------------------------------------------------+-----------------------------------------------------------------+ .. _sedp: simpleEDP ++++++++++ +---------------------------+------------------------------------------------------------+-------------+---------------+ | Name | Description | Values | Default | +===========================+============================================================+=============+===============+ | ```` | Indicates if the participant must use |br| | ``bool`` | ``true`` | | | Publication DataWriter and Subscription DataReader. | | | +---------------------------+------------------------------------------------------------+-------------+---------------+ | ```` | Indicates if the participant must use |br| | ``bool`` | ``true`` | | | Publication DataReader and Subscription DataWriter. | | | +---------------------------+------------------------------------------------------------+-------------+---------------+ .. _InitAnnounce: Initial Announcements ###################### +--------------+-----------------------------------------------------------------------+---------------------+---------+ | Name | Description | Values | Default | +==============+=======================================================================+=====================+=========+ | ```` | Number of initial discovery messages to send at the period | ``uint32_t`` | 5 | | | specified by |br| | | | | | ````. After these announcements, the DomainParticipant will | | | | | continue |br| | | | | | sending its discovery messages at the ```` rate. | | | +--------------+-----------------------------------------------------------------------+---------------------+---------+ | ```` | The period for the DomainParticipant to send its discovery messages. | :ref:`DurationType` | 100 ms | +--------------+-----------------------------------------------------------------------+---------------------+---------+