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

No

FlowControllersQos

flow_controllers()

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

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) !=
        ReturnCode_t::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) !=
        ReturnCode_t::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)
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (DomainParticipantFactory::get_instance()->set_default_participant_qos(DomainParticipantQos())
        != ReturnCode_t::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) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

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

Note

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