RTI Connext Modern C++ API  Version 6.1.1
dds::topic::Topic< T > Class Template Reference

<<reference-type>> Topic is the most basic description of the data to be published and subscribed. More...

#include <dds/topic/Topic.hpp>

Inheritance diagram for dds::topic::Topic< T >:
dds::topic::TopicDescription< T > dds::core::Entity

Public Member Functions

 Topic (const dds::domain::DomainParticipant &the_participant, const std::string &topic_name)
 Creates a new topic. More...
 
 Topic (const dds::domain::DomainParticipant &dp, const std::string &topic_name, const std::string &the_type_name)
 Creates a new topic. More...
 
 Topic (const dds::domain::DomainParticipant &dp, const std::string &topic_name, const dds::topic::qos::TopicQos &the_qos, dds::topic::TopicListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Creates a new Topic. More...
 
 Topic (const dds::domain::DomainParticipant &participant, const std::string &topic_name, const std::string &type_name, const dds::topic::qos::TopicQos &the_qos, dds::topic::TopicListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a new topic. More...
 
 Topic (const dds::domain::DomainParticipant &the_participant, const std::string &topic_name, const dds::core::xtypes::DynamicType &type)
 Create a new topic with a dynamic type description. More...
 
 Topic (const dds::domain::DomainParticipant &the_participant, const std::string &topic_name, const dds::core::xtypes::DynamicType &type, const dds::topic::qos::TopicQos &the_qos, dds::topic::TopicListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a new topic with a dynamic type description. More...
 
 Topic (const dds::domain::DomainParticipant &dp, const std::string &topic_name, const dds::topic::qos::TopicQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Creates a new Topic. More...
 
 Topic (const dds::domain::DomainParticipant &participant, const std::string &topic_name, const std::string &type_name, const dds::topic::qos::TopicQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a new topic. More...
 
 Topic (const dds::domain::DomainParticipant &the_participant, const std::string &topic_name, const dds::core::xtypes::DynamicType &type, const dds::topic::qos::TopicQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a new topic with a dynamic type description. More...
 
void listener (Listener *the_listener, const ::dds::core::status::StatusMask &event_mask)
 Sets the listener. More...
 
Listenerlistener () const
 Gets the listener. More...
 
void set_listener (std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
 Sets the listener associated with this topic. More...
 
void set_listener (std::shared_ptr< Listener > the_listener)
 Sets the listener associated with this topic. More...
 
std::shared_ptr< Listenerget_listener () const
 Returns the listener currently associated with this topic. More...
 
const dds::topic::qos::TopicQos qos () const
 Gets the current TopicQos for this Topic. More...
 
void qos (const dds::topic::qos::TopicQos &the_qos)
 Sets the TopicQos setting for this Topic. More...
 
dds::core::status::InconsistentTopicStatus inconsistent_topic_status () const
 Retrieve the current InconsistentTopicStatus of this Topic. More...
 
- Public Member Functions inherited from dds::topic::TopicDescription< T >
const std::string & name () const
 Gets the topic name. More...
 
const std::string & type_name () const
 Gets the type name. More...
 
const dds::domain::DomainParticipantparticipant () const
 Gets the related dds::domain::DomainParticipant. More...
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled) More...
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered. More...
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity. More...
 
void close ()
 Forces the destruction of this entity. More...
 
void retain ()
 Disables the automatic destruction of this entity. More...
 

Related Functions

(Note that these are not member functions.)

template<typename FwdIterator >
int32_t discover_any_topic (const dds::domain::DomainParticipant &participant, FwdIterator begin, int32_t max_size)
 Retrieves the topics discovered in a DomainParticipant. More...
 
template<typename BinIterator >
int32_t discover_any_topic (const dds::domain::DomainParticipant &participant, BinIterator begin)
 Retrieves the topics discovered in a DomainParticipant. More...
 
dds::topic::TopicBuiltinTopicData discover_topic_data (const dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &topic_handle)
 Gets the information about a discovered topic. More...
 
template<typename FwdIterator >
int32_t discover_topic_data (const dds::domain::DomainParticipant &participant, FwdIterator begin, const dds::core::InstanceHandleSeq &handles)
 Gets the information about several topics. More...
 
template<typename FwdIterator >
int32_t discover_topic_data (const dds::domain::DomainParticipant &participant, FwdIterator begin, int32_t max_size)
 Gets the information about all topics. More...
 
template<typename BinIterator >
int32_t discover_topic_data (const dds::domain::DomainParticipant &participant, BinIterator begin)
 Gets the information about all topics. More...
 
void ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle)
 Instructs a DomainParticipant to ignore a topic. More...
 
template<typename FwdIterator >
void ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end)
 Ignores a range of topics. More...
 
template<typename TOPIC >
TOPIC find (const dds::domain::DomainParticipant &participant, const std::string &topic_name)
 Looks up a Topic from a DomainParticipant. More...
 
template<typename AnyTopicBackInsertIterator >
uint32_t find_topics (dds::domain::DomainParticipant participant, AnyTopicBackInsertIterator begin)
 <<extension>> Retrieve all the dds::topic::Topic created from this dds::domain::DomainParticipant More...
 
template<typename AnyTopicForwardIterator >
uint32_t find_topics (dds::domain::DomainParticipant participant, AnyTopicForwardIterator begin, uint32_t max_size)
 <<extension>> Retrieve all the dds::topic::Topic created from this dds::domain::DomainParticipant More...
 

Detailed Description

template<typename T>
class dds::topic::Topic< T >

<<reference-type>> Topic is the most basic description of the data to be published and subscribed.

Template Parameters
TThe type associated to this topic. It must be a type such that dds::topic::is_topic_type<T>::value is true (see dds::topic::is_topic_type). Valid types are IDL-generated types, the built-in types and dds::core::xtypes::DynamicData.
QoS:
dds::topic::qos::TopicQos
Status:
dds::core::status::StatusMask::inconsistent_topic(), dds::core::status::InconsistentTopicStatus
Listener:
TopicListener

A dds::topic::Topic is identified by its name, which must be unique in the whole domain. In addition (by virtue of extending TopicDescription) it fully specifies the type of the data that can be communicated when publishing or subscribing to the dds::topic::Topic.

dds::topic::Topic is the only TopicDescription that can be used for publications and therefore associated with a dds::pub::DataWriter.

The following operations may be called even if the dds::topic::Topic is not enabled. Other operations will fail with the value dds::core::NotEnabledError if called on a disabled dds::topic::Topic:

See also
Operations Allowed in Listener Callbacks
Examples:
Foo_publisher.cxx, and Foo_subscriber.cxx.

Constructor & Destructor Documentation

◆ Topic() [1/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant the_participant,
const std::string &  topic_name 
)
inline

Creates a new topic.

This constructor automatically deduces the type name, uses the default TopicQos and doesn't set a listener.

Parameters
the_participantThe domain participant on which the topic will be defined.
topic_nameThe topic name.

◆ Topic() [2/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant dp,
const std::string &  topic_name,
const std::string &  the_type_name 
)
inline

Creates a new topic.

This constructor uses the default TopicQos and doesn't set a listener.

Parameters
dpThe domain participant on which the topic will be defined.
topic_nameThe topic name.
the_type_nameThe name to register the type with

◆ Topic() [3/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant dp,
const std::string &  topic_name,
const dds::topic::qos::TopicQos the_qos,
dds::topic::TopicListener< T > *  the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Creates a new Topic.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

This constructor deduces the type name automatically

◆ Topic() [4/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant participant,
const std::string &  topic_name,
const std::string &  type_name,
const dds::topic::qos::TopicQos the_qos,
dds::topic::TopicListener< T > *  the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a new topic.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

Parameters
participantThe domain participant on which the topic will be defined.
topic_nameThe Topic name. Must not exceed 255 characters.
type_nameThe name given to the type T
the_qosThe Qos settings for this Topic
the_listenerthe topic listener (default: NULL)
maskthe event mask associated to the DataReader listener.
See also
Specifying QoS on entities for information on setting QoS before entity creation
dds::topic::qos::TopicQos for rules on consistency among QoS
dds::core::QosProvider
dds::domain::DomainParticipant::default_topic_qos()
listener()

◆ Topic() [5/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant the_participant,
const std::string &  topic_name,
const dds::core::xtypes::DynamicType type 
)
inline

Create a new topic with a dynamic type description.

This constructor uses a dynamic type description, the default TopicQos and doesn't set a listener.

◆ Topic() [6/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant the_participant,
const std::string &  topic_name,
const dds::core::xtypes::DynamicType type,
const dds::topic::qos::TopicQos the_qos,
dds::topic::TopicListener< T > *  the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a new topic with a dynamic type description.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

Notice that in this case the data type T has to be DynamicData. Thus the Topic type will be Topic<DynamicData>.

Parameters
the_participantthe domain participant on which the topic will be defined.
topic_namethe topic's name.
typeThe DynamicType that describes the type for the DynamicData samples of this topic.
the_qosThe Qos settings for this Topic
the_listenerthe topic listener (default: NULL)
maskthe event mask associated to the DataReader listener.
See also
dds::core::xtypes::DynamicData
rti::domain::register_type()

◆ Topic() [7/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant dp,
const std::string &  topic_name,
const dds::topic::qos::TopicQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Creates a new Topic.

This constructor deduces the type name automatically.

◆ Topic() [8/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant participant,
const std::string &  topic_name,
const std::string &  type_name,
const dds::topic::qos::TopicQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a new topic.

Parameters
participantThe domain participant on which the topic will be defined.
topic_nameThe Topic name. Must not exceed 255 characters.
type_nameThe name given to the type T
the_qosThe Qos settings for this Topic
the_listenerA shared_ptr to the listener. See set_listener() for more information.
maskIndicates which status updates the listener will receive
See also
Specifying QoS on entities for information on setting QoS before entity creation
dds::topic::qos::TopicQos for rules on consistency among QoS
dds::core::QosProvider
dds::domain::DomainParticipant::default_topic_qos()
listener()

◆ Topic() [9/9]

template<typename T>
dds::topic::Topic< T >::Topic ( const dds::domain::DomainParticipant the_participant,
const std::string &  topic_name,
const dds::core::xtypes::DynamicType type,
const dds::topic::qos::TopicQos the_qos,
std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a new topic with a dynamic type description.

Notice that in this case the data type T has to be DynamicData. Thus the Topic type will be Topic<DynamicData>.

Parameters
the_participantthe domain participant on which the topic will be defined.
topic_namethe topic's name.
typeThe DynamicType that describes the type for the DynamicData samples of this topic.
the_qosThe Qos settings for this Topic
the_listenerA shared_ptr to the listener. See set_listener() for more information.
maskIndicates which status updates the listener will receive
See also
dds::core::xtypes::DynamicData
rti::domain::register_type()

Member Function Documentation

◆ listener() [1/2]

template<typename T>
void dds::topic::Topic< T >::listener ( Listener the_listener,
const ::dds::core::status::StatusMask event_mask 
)
inline

Sets the listener.

[DEPRECATED] The use of set_listener() is recommended. Unlike this function, set_listener receives a shared_ptr which simplifies the management of listener's lifecycle.

Parameters
the_listenerthe topic listener
event_maskChanges of communication status to be invoked on the listener

◆ listener() [2/2]

template<typename T>
Listener* dds::topic::Topic< T >::listener ( ) const
inline

Gets the listener.

[DEPRECATED] Prefer get_listener() instead of this function.

Returns the listener or NULL if there's no listener attached.

◆ set_listener() [1/2]

template<typename T>
void dds::topic::Topic< T >::set_listener ( std::shared_ptr< Listener the_listener,
const dds::core::status::StatusMask event_mask 
)
inline

Sets the listener associated with this topic.

The topic will hold a shared_ptr to the listener argument, ensuring that it is not deleted at least until this topic is deleted or the listener is reset with set_listener(nullptr).

Warning
It's recommended that the listener implementation doesn't hold a permanent reference to the topic. If it does, the application needs to manually reset the listener or manually close this topic to ensure that there is no cycle that prevents the destruction of these two objects.
Parameters
the_listenerA shared pointer to the listener to receive status updates or nullptr to reset the current listener and stop receiving status updates.
event_maskA mask that indicates which status updates will be notified to the listener

◆ set_listener() [2/2]

template<typename T>
void dds::topic::Topic< T >::set_listener ( std::shared_ptr< Listener the_listener)
inline

Sets the listener associated with this topic.

If the_listener is not nullptr, this overload is equivalent to:

topic.set_listener(the_listener, dds::core::status::StatusMask::all());

If the_listener is nullptr, it is equivalent to:

topic.set_listener(nullptr, dds::core::status::StatusMask::none());
Parameters
the_listenerA shared pointer to the listener to receive status updates or nullptr to reset the current listener and stop receiving status updates.

◆ get_listener()

template<typename T>
std::shared_ptr<Listener> dds::topic::Topic< T >::get_listener ( ) const
inline

Returns the listener currently associated with this topic.

Returns
The shared pointer to the current listener or nullptr if there is currently no listener associated to this entity.

◆ qos() [1/2]

template<typename T>
const dds::topic::qos::TopicQos dds::topic::Topic< T >::qos ( ) const
inline

Gets the current TopicQos for this Topic.

◆ qos() [2/2]

template<typename T>
void dds::topic::Topic< T >::qos ( const dds::topic::qos::TopicQos the_qos)
inline

Sets the TopicQos setting for this Topic.

Parameters
the_qosSet of policies to be applied to the Topic. Immutable policies cannot be changed after this entity has been enabled.
Exceptions
dds::core::ImmutablePolicyErrorif the_qos contains a different value for an immutable policy.
dds::core::InconsistentPolicyErrorif some policies are inconsistent.
See also
dds::topic::qos::TopicQos for rules on consistency among QoS policies
set_qos (abstract)
dds::domain::DomainParticipant::default_topic_qos()
dds::core::QosProvider::topic_qos()

◆ inconsistent_topic_status()

template<typename T>
dds::core::status::InconsistentTopicStatus dds::topic::Topic< T >::inconsistent_topic_status ( ) const
inline

Retrieve the current InconsistentTopicStatus of this Topic.

Friends And Related Function Documentation

◆ discover_any_topic() [1/2]

template<typename FwdIterator >
int32_t discover_any_topic ( const dds::domain::DomainParticipant participant,
FwdIterator  begin,
int32_t  max_size 
)
related

Retrieves the topics discovered in a DomainParticipant.

Template Parameters
FwdIteratorA forward iterator whose value type is dds::core::InstanceHandle
Parameters
participantThe DomainParticipant where to look up the discovered topics
beginThe beginning of the range where to insert the InstanceHandles that correspond to the discovered topics
max_sizeThe maximum number of topics to insert or dds::core::LENGTH_UNLIMITED

◆ discover_any_topic() [2/2]

template<typename BinIterator >
int32_t discover_any_topic ( const dds::domain::DomainParticipant participant,
BinIterator  begin 
)
related

Retrieves the topics discovered in a DomainParticipant.

This is equivalent to discover_any_topic(participant, begin, dds::core::LENGTH_UNLIMITED)

◆ discover_topic_data() [1/4]

template<typename T>
dds::topic::TopicBuiltinTopicData discover_topic_data ( const dds::domain::DomainParticipant participant,
const dds::core::InstanceHandle topic_handle 
)
related

Gets the information about a discovered topic.

Returns dds::topic::TopicBuiltinTopicData for the specified dds::topic::Topic.

This operation retrieves information on a dds::topic::Topic that has been discovered by the local Participant and must not have been "ignored" by means of the dds::topic::ignore() operation.

The topic_handle must correspond to such a topic. Otherwise, the operation will fail with dds::core::PreconditionNotMetError.

This call is not supported for remote topics. If a remote topic_handle is used, the operation will fail with dds::core::UnsupportedError.

Use the operation dds::topic::discover_any_topic() to find the topics that are currently discovered.

Parameters
participantThe DomainParticipant where to look up the topic information
topic_handle<<in>> dds::core::InstanceHandle of dds::topic::Topic.
Exceptions
Oneof the Standard Exceptions, dds::core::PreconditionNotMetError or dds::core::NotEnabledError
See also
dds::topic::TopicBuiltinTopicData
dds::topic::discover_any_topic()

◆ discover_topic_data() [2/4]

template<typename FwdIterator >
int32_t discover_topic_data ( const dds::domain::DomainParticipant participant,
FwdIterator  begin,
const dds::core::InstanceHandleSeq handles 
)
related

Gets the information about several topics.

◆ discover_topic_data() [3/4]

template<typename FwdIterator >
int32_t discover_topic_data ( const dds::domain::DomainParticipant participant,
FwdIterator  begin,
int32_t  max_size 
)
related

Gets the information about all topics.

Template Parameters
Aforward iterator whose value type is dds::topic::TopicBuiltinTopicData
Parameters
participantThe DomainParticipant where to look up all the topics
beginThe beginning of a range where to copy the topic data
max_sizeThe maximum number of items to copy or dds::core::LENGTH_UNLIMITED

◆ discover_topic_data() [4/4]

template<typename BinIterator >
int32_t discover_topic_data ( const dds::domain::DomainParticipant participant,
BinIterator  begin 
)
related

Gets the information about all topics.

◆ ignore() [1/2]

template<typename T>
void ignore ( dds::domain::DomainParticipant participant,
const dds::core::InstanceHandle handle 
)
related

Instructs a DomainParticipant to ignore a topic.

Instructs RTI Connext to locally ignore a dds::topic::Topic.

This means it will locally ignore any publication, or subscription to the dds::topic::Topic.

There is no way to reverse this operation.

This operation can be used to save local resources when the application knows that it will never publish or subscribe to data under certain topics.

The dds::topic::Topic to ignore is identified by the handle argument. This is the handle of a dds::topic::Topic that appears in the dds::sub::SampleInfo retrieved when reading data samples from the built-in dds::sub::DataReader for the dds::topic::Topic.

Parameters
participantThe DomainParticipant where to ignore the topic
handle<<in>> Handle of the dds::topic::Topic to be ignored.
Exceptions
Oneof the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::NotEnabledError
See also
dds::topic::TopicBuiltinTopicData
dds::topic::topic_topic_name()
dds::sub::builtin_subscriber

◆ ignore() [2/2]

template<typename FwdIterator >
void ignore ( dds::domain::DomainParticipant participant,
FwdIterator  begin,
FwdIterator  end 
)
related

◆ find()

template<typename TOPIC >
TOPIC find ( const dds::domain::DomainParticipant participant,
const std::string &  topic_name 
)
related

Looks up a Topic from a DomainParticipant.

Template Parameters
TOPICThe topic to find; it can be one of the following:
Parameters
participantThe DomainParticipant that contains the Topic
topic_nameThe topic name
Returns
A reference to an existing Topic in this participant or an empty reference (i.e. equals to dds::core::null) if it doesn't exist.
Exceptions
dds::core::InvalidDowncastErrorIf the concrete type of the topic description identified by topic_name is not TOPIC. For example, if the topic_name identifies a topic of type Bar, but the template parameter was dds::topic::Topic<Foo>.

The participant doesn't need to be enabled. The returned topic may be enabled or disabled.

◆ find_topics() [1/2]

template<typename AnyTopicBackInsertIterator >
uint32_t find_topics ( dds::domain::DomainParticipant  participant,
AnyTopicBackInsertIterator  begin 
)
related

<<extension>> Retrieve all the dds::topic::Topic created from this dds::domain::DomainParticipant

Note
This is a standalone function in the namespace rti::topic
Template Parameters
AnyTopicBackInsertIteratorType of the back-inserting iterator, whose value_type is dds::topic::AnyTopic.
Parameters
participantThe dds::domain::DomainParticipant the Topics belong to
beginA back-inserting iterator to the position in the destination container to insert the found Topics into
Returns
The number of found Topics

◆ find_topics() [2/2]

template<typename AnyTopicForwardIterator >
uint32_t find_topics ( dds::domain::DomainParticipant  participant,
AnyTopicForwardIterator  begin,
uint32_t  max_size 
)
related

<<extension>> Retrieve all the dds::topic::Topic created from this dds::domain::DomainParticipant

Note
This is a standalone function in the namespace rti::topic
Template Parameters
AnyTopicBackInsertIteratorType of the back-inserting iterator, whose value_type is dds::topic::AnyTopic.
Parameters
participantThe dds::domain::DomainParticipant the Topics belong to
beginA forward iterator to the position in the destination container to insert the found Topics in
max_sizeThe maximum number of Topics to return
Returns
The number of found Topics