3.4.1. Subscriber¶
The Subscriber
acts on behalf of one or several DataReader objects
that belong to it.
It serves as a container that allows grouping different DataReader objects under
a common configuration given by the SubscriberQos of the Subscriber.
DataReader objects that belong to the same Subscriber
do not have any other relation among each other beyond the SubscriberQos
of the Subscriber
and act independently otherwise.
Specifically, a Subscriber can host DataReader objects
for different topics and data types.
3.4.1.1. SubscriberQos¶
SubscriberQos
controls the behavior of the Subscriber.
Internally it contains the following QosPolicy
objects:
QosPolicy class |
Accessor/Mutator |
Mutable |
---|---|---|
Yes |
||
Yes |
||
Yes |
||
Yes |
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 Subscriber can be modified using the
Subscriber::set_qos()
member function.
// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
// Error
return;
}
// Create a Subscriber with default SubscriberQos
Subscriber* subscriber =
participant->create_subscriber(SUBSCRIBER_QOS_DEFAULT);
if (nullptr == subscriber)
{
// Error
return;
}
// Get the current QoS or create a new one from scratch
SubscriberQos qos = subscriber->get_qos();
// Modify QoS attributes
qos.entity_factory().autoenable_created_entities = false;
// Assign the new Qos to the object
subscriber->set_qos(qos);
3.4.1.1.1. Default SubscriberQos¶
The default SubscriberQos refers to the value returned by the
get_default_subscriber_qos()
member function
on the DomainParticipant instance.
The special value SUBSCRIBER_QOS_DEFAULT
can be used as QoS argument on
create_subscriber()
or Subscriber::set_qos()
member functions to indicate that the current default SubscriberQos
should be used.
When the system starts, the default SubscriberQos is equivalent to the default constructed
value SubscriberQos()
.
The default SubscriberQos can be modified at any time using the
set_default_subscriber_qos()
member function on the
DomainParticipant instance.
Modifying the default SubscriberQos will not affect already existing
Subscriber instances.
// Create a DomainParticipant in the desired domain
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
SubscriberQos qos_type1 = participant->get_default_subscriber_qos();
// Modify QoS attributes
// (...)
// Set as the new default SubscriberQos
if (participant->set_default_subscriber_qos(qos_type1) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// Create a Subscriber with the new default SubscriberQos.
Subscriber* subscriber_with_qos_type1 =
participant->create_subscriber(SUBSCRIBER_QOS_DEFAULT);
if (nullptr == subscriber_with_qos_type1)
{
// Error
return;
}
// Get the current QoS or create a new one from scratch
SubscriberQos qos_type2;
// Modify QoS attributes
// (...)
// Set as the new default SubscriberQos
if (participant->set_default_subscriber_qos(qos_type2) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// Create a Subscriber with the new default SubscriberQos.
Subscriber* subscriber_with_qos_type2 =
participant->create_subscriber(SUBSCRIBER_QOS_DEFAULT);
if (nullptr == subscriber_with_qos_type2)
{
// Error
return;
}
// Resetting the default SubscriberQos to the original default constructed values
if (participant->set_default_subscriber_qos(SUBSCRIBER_QOS_DEFAULT)
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// The previous instruction is equivalent to the following
if (participant->set_default_subscriber_qos(SubscriberQos())
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
set_default_subscriber_qos()
member function also accepts
the special value SUBSCRIBER_QOS_DEFAULT
as input argument.
This will reset the current default SubscriberQos to default constructed
value SubscriberQos()
.
// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
// Error
return;
}
// Create a custom SubscriberQos
SubscriberQos custom_qos;
// Modify QoS attributes
// (...)
// Create a subscriber with a custom SubscriberQos
Subscriber* subscriber = participant->create_subscriber(custom_qos);
if (nullptr == subscriber)
{
// Error
return;
}
// Set the QoS on the subscriber to the default
if (subscriber->set_qos(SUBSCRIBER_QOS_DEFAULT) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// The previous instruction is equivalent to the following:
if (subscriber->set_qos(participant->get_default_subscriber_qos())
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
Note
The value SUBSCRIBER_QOS_DEFAULT
has different meaning depending on where it is used:
On
create_subscriber()
andSubscriber::set_qos()
it refers to the default SubscriberQos as returned byget_default_subscriber_qos()
.On
set_default_subscriber_qos()
it refers to the default constructedSubscriberQos()
.