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 |
---|---|---|
Yes |
||
Yes |
||
No |
||
No |
||
No* |
||
No |
||
No |
||
No |
||
No |
||
No |
||
No |
||
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:
Retrieve the internal
DomainParticipantQos
by the means ofDomainParticipant::get_qos()
.Perform the desired modifications.
Update the
DomainParticipantQos
by the means ofDomainParticipant::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:
On
create_participant()
andDomainParticipant::set_qos()
it refers to the default DomainParticipantQos as returned byget_default_participant_qos()
.On
set_default_participant_qos()
it refers to the default constructedDomainParticipantQos()
.
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.