3.5.3. Topic¶
A Topic
is a specialization of the broader concept of TopicDescription.
A Topic represents a single data flow between Publisher
and Subscriber, providing:
The name to identify the data flow.
The data type that is transmitted on that flow.
The QoS values related to the data itself.
The behavior of the Topic can be modified with the QoS values
specified on TopicQos.
The QoS values can be set at the creation of the Topic,
or modified later with the Topic::set_qos()
member function.
Like other Entities, Topic accepts a Listener that will be notified of status changes on the Topic.
Please refer to Creating a Topic for more information about how to create a Topic
.
3.5.3.1. TopicQos¶
TopicQos
controls the behavior of the Topic.
Internally it contains the following QosPolicy
objects:
QosPolicy class |
Accessor |
Mutable |
---|---|---|
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
||
Yes |
Refer to the detailed description of each QosPolicy-api class for more information about their usage and default values.
The QoS value of a previously created Topic can be modified using the
Topic::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 Topic with default TopicQos
Topic* topic =
participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic)
{
// Error
return;
}
// Get the current QoS or create a new one from scratch
TopicQos qos = topic->get_qos();
// Modify QoS attributes
// (...)
// Assign the new Qos to the object
topic->set_qos(qos);
3.5.3.1.1. Default TopicQos¶
The default TopicQos refers to the value returned by the
get_default_topic_qos()
member function on the DomainParticipant instance.
The special value TOPIC_QOS_DEFAULT
can be used as QoS argument on create_topic()
or Topic::set_qos()
member functions to indicate that the current default TopicQos
should be used.
When the system starts, the default TopicQos is equivalent to the default constructed
value TopicQos()
.
The default TopicQos can be modified at any time using the
get_default_topic_qos()
member function on the DomainParticipant instance.
Modifying the default TopicQos will not affect already existing Topic
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
TopicQos qos_type1 = participant->get_default_topic_qos();
// Modify QoS attributes
// (...)
// Set as the new default TopicQos
if (participant->set_default_topic_qos(qos_type1) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// Create a Topic with the new default TopicQos.
Topic* topic_with_qos_type1 =
participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic_with_qos_type1)
{
// Error
return;
}
// Get the current QoS or create a new one from scratch
TopicQos qos_type2;
// Modify QoS attributes
// (...)
// Set as the new default TopicQos
if (participant->set_default_topic_qos(qos_type2) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// Create a Topic with the new default TopicQos.
Topic* topic_with_qos_type2 =
participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic_with_qos_type2)
{
// Error
return;
}
// Resetting the default TopicQos to the original default constructed values
if (participant->set_default_topic_qos(TOPIC_QOS_DEFAULT)
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// The previous instruction is equivalent to the following
if (participant->set_default_topic_qos(TopicQos())
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
get_default_topic_qos()
member function also accepts the value TOPIC_QOS_DEFAULT
as input argument.
This will reset the current default TopicQos to default constructed
value TopicQos()
.
// 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 TopicQos
TopicQos custom_qos;
// Modify QoS attributes
// (...)
// Create a topic with a custom TopicQos
Topic* topic = participant->create_topic("TopicName", "DataTypeName", custom_qos);
if (nullptr == topic)
{
// Error
return;
}
// Set the QoS on the topic to the default
if (topic->set_qos(TOPIC_QOS_DEFAULT) != ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
// The previous instruction is equivalent to the following:
if (topic->set_qos(participant->get_default_topic_qos())
!= ReturnCode_t::RETCODE_OK)
{
// Error
return;
}
Note
The value TOPIC_QOS_DEFAULT
has different meaning depending on where it is used:
On
create_topic()
andTopic::set_qos()
it refers to the default TopicQos as returned byget_default_topic_qos()
.On
get_default_topic_qos()
it refers to the default constructedTopicQos()
.