3.2.1. DomainParticipant

A DomainParticipant is the entry point of the application to a domain. Every DomainParticipant is linked to a single domain from its creation, and contains all the Entities related to that domain. It also acts as a factory for Publisher, Subscriber and Topic.

The behavior of the DomainParticipant can be modified with the QoS values specified on DomainParticipantQos. The QoS values can be set at the creation of the DomainParticipant, or modified later with DomainParticipant::set_qos() member function.

As an Entity, DomainParticipant accepts a DomainParticipantListener that will be notified of status changes on the DomainParticipant instance.

3.2.1.1. DomainParticipantQos

DomainParticipantQos controls the behavior of the DomainParticipant. Internally it contains the following QosPolicy objects:

QosPolicy class

Accessor/Mutator

Mutable

UserDataQosPolicy

user_data()

Yes

EntityFactoryQosPolicy

entity_factory()

Yes

ParticipantResourceLimitsQos

allocation()

No

PropertyPolicyQos

properties()

No

WireProtocolConfigQos

wire_protocol()

No*

TransportConfigQos

transport() and setup_transports()

No

FlowControllersQos

flow_controllers()

No

ThreadSettings

builtin_controllers_sender_thread()

No

ThreadSettings

timed_events_thread()

No

ThreadSettings

discovery_server_thread()

No

ThreadSettings

typelookup_service_thread()

No

ThreadSettings

security_log_thread()

No

Important

The only mutable field in WireProtocolConfigQos is m_DiscoveryServers, which is contained in discovery_config within builtin (see Modifying remote servers list at run time).

Important

Upon the call to create_participant(), if Fast DDS is compiled with statistics support (enabled by default, see CMake options), the internal DomainParticipantQos may differ from the input DomainParticipantQos (see Statistics Module Settings). This entails that applications willing to further modify the DomainParticipantQos after DomainParticipant creation should:

  1. Retrieve the internal DomainParticipantQos by the means of DomainParticipant::get_qos().

  2. Perform the desired modifications.

  3. Update the DomainParticipantQos by the means of DomainParticipant::set_qos().

Refer to the detailed description of each QosPolicy class for more information about their usage and default values.

The QoS value of a previously created DomainParticipant can be modified using the DomainParticipant::set_qos() member function. Trying to modify an immutable QosPolicy on an already enabled DomainParticipant will result on an error. In such case, no changes will be applied and the DomainParticipant will keep its previous DomainParticipantQos.

// Create a DomainParticipant with default DomainParticipantQos
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DomainParticipantQos qos = participant->get_qos();

// Modify QoS attributes
qos.entity_factory().autoenable_created_entities = false;

// Assign the new Qos to the object
participant->set_qos(qos);

3.2.1.1.1. Default DomainParticipantQos

The default DomainParticipantQos refers to the value returned by the get_default_participant_qos() member function on the DomainParticipantFactory singleton. The special value PARTICIPANT_QOS_DEFAULT can be used as QoS argument on create_participant() or DomainParticipant::set_qos() member functions to indicate that the current default DomainParticipantQos should be used.

When the system starts, the default DomainParticipantQos is equivalent to the default constructed value DomainParticipantQos(). The default DomainParticipantQos can be modified at any time using the set_default_participant_qos() member function on the DomainParticipantFactory singleton. Modifying the default DomainParticipantQos will not affect already existing DomainParticipant instances.

// Get the current QoS or create a new one from scratch
DomainParticipantQos qos_type1 = DomainParticipantFactory::get_instance()->get_default_participant_qos();

// Modify QoS attributes
// (...)

// Set as the new default TopicQos
if (DomainParticipantFactory::get_instance()->set_default_participant_qos(qos_type1) !=
        RETCODE_OK)
{
    // Error
    return;
}

// Create a DomainParticipant with the new default DomainParticipantQos.
DomainParticipant* participant_with_qos_type1 =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant_with_qos_type1)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DomainParticipantQos qos_type2;

// Modify QoS attributes
// (...)

// Set as the new default TopicQos
if (DomainParticipantFactory::get_instance()->set_default_participant_qos(qos_type2) !=
        RETCODE_OK)
{
    // Error
    return;
}

// Create a Topic with the new default TopicQos.
DomainParticipant* participant_with_qos_type2 =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant_with_qos_type2)
{
    // Error
    return;
}

// Resetting the default DomainParticipantQos to the original default constructed values
if (DomainParticipantFactory::get_instance()->set_default_participant_qos(PARTICIPANT_QOS_DEFAULT)
        != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (DomainParticipantFactory::get_instance()->set_default_participant_qos(DomainParticipantQos())
        != RETCODE_OK)
{
    // Error
    return;
}

set_default_participant_qos() member function also accepts the value PARTICIPANT_QOS_DEFAULT as input argument. This will reset the current default DomainParticipantQos to the default constructed value DomainParticipantQos().

// Create a custom DomainParticipantQos
DomainParticipantQos custom_qos;

// Modify QoS attributes
// (...)

// Create a DomainParticipant with a custom DomainParticipantQos

DomainParticipant* participant = DomainParticipantFactory::get_instance()->create_participant(0, custom_qos);
if (nullptr == participant)
{
    // Error
    return;
}

// Set the QoS on the participant to the default
if (participant->set_qos(PARTICIPANT_QOS_DEFAULT) != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following:
if (participant->set_qos(DomainParticipantFactory::get_instance()->get_default_participant_qos())
        != RETCODE_OK)
{
    // Error
    return;
}

Note

The value PARTICIPANT_QOS_DEFAULT has different meaning depending on where it is used:

3.2.1.2. DomainParticipantExtendedQos

DomainParticipantExtendedQos is an extension of DomainParticipantQos that includes both the DomainId and the DomainParticipantQos objects of a DomainParticipant. This class is useful for simplifying the creation and configuration of a DomainParticipant, as it allows specifying all necessary settings in a single object.

This DomainParticipantExtendedQos can be obtained from the loaded profiles with get_participant_extended_qos_from_profile() and then create DomainParticipant with those DomainParticipantExtendedQos. The QoS value of a previously created DomainParticipant can be modified similarly as when creating the DomainParticipant from DomainParticipantQos.

// Create a DomainParticipant with DomainParticipantExtendedQos from profile
DomainParticipantExtendedQos profile_extended_qos;
DomainParticipantFactory::get_instance()->get_participant_extended_qos_from_profile("participant_profile",
        profile_extended_qos);

DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(profile_extended_qos);
if (nullptr == participant)
{
    // Error
    return;
}

It is also possible to fill a DomainParticipantExtendedQos object directly from a raw XML string without the need to previously load any profile. Please refer to Get QoS from raw XML profiles section for more information.