RTI Connext Modern C++ API  Version 5.3.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
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.
 
 Topic (const dds::domain::DomainParticipant &dp, const std::string &topic_name, const std::string &the_type_name)
 Creates a new topic.
 
 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.
 
 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.
 
 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.
 
 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.
 
void listener (Listener *the_listener, const ::dds::core::status::StatusMask &event_mask)
 Sets the listener.
 
Listenerlistener () const
 Gets the listener.
 
dds::topic::qos::TopicQos qos () const
 Gets the current TopicQos for this Topic.
 
void qos (const dds::topic::qos::TopicQos &the_qos)
 Sets the TopicQos setting for this Topic.
 
dds::core::status::InconsistentTopicStatus inconsistent_topic_status () const
 Retrieve the current InconsistentTopicStatus of this Topic.
 
- Public Member Functions inherited from dds::topic::TopicDescription< T >
const std::string & name () const
 Gets the topic name.
 
const std::string & type_name () const
 Gets the type name.
 
const
dds::domain::DomainParticipant
participant () const
 Gets the related dds::domain::DomainParticipant.
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled)
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered.
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity.
 
void close ()
 Forces the destruction of this entity.
 
void retain ()
 Disables the automatic destruction of this entity.
 

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.
 
template<typename BinIterator >
int32_t discover_any_topic (const dds::domain::DomainParticipant &participant, BinIterator begin)
 Retrieves the topics discovered in a DomainParticipant.
 
dds::topic::TopicBuiltinTopicData discover_topic_data (const dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &topic_handle)
 Gets the information about a discovered topic.
 
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.
 
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.
 
template<typename BinIterator >
int32_t discover_topic_data (const dds::domain::DomainParticipant &participant, BinIterator begin)
 Gets the information about all topics.
 
void ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle)
 Instructs a DomainParticipant to ignore a topic.
 
template<typename FwdIterator >
void ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end)
 Ignores a range of topics.
 
template<typename TOPIC >
TOPIC find (const dds::domain::DomainParticipant &participant, const std::string &topic_name)
 Looks up a Topic from a DomainParticipant.
 
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
 
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
 

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

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 behaves as the most general one where the type name is automatically deduced from dds::core::topic_type_name, it 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.
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 behaves as the most general one except that it 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
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.

This constructor behaves as the most general one except that the type name is automatically deduced from dds::core::topic_type_name

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.

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)
maskChanges of communication status to be invoked on the listener (default: all)
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()
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.

See Also
Topic(const dds::domain::DomainParticipant& the_participant, const std::string& topic_name, const dds::core::xtypes::DynamicType& type, const dds::topic::qos::TopicQos& qos, dds::topic::TopicListener<T>* listener, const dds::core::status::StatusMask& mask)
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.

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

The QoS will be set to dp.default_topic_qos().

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)
maskChanges of communication status to be invoked on the listener (default: all)
See Also
dds::core::xtypes::DynamicData
rti::domain::register_type()

Member Function Documentation

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

Sets the listener.

Parameters
the_listenerthe topic listener
event_maskChanges of communication status to be invoked on the listener
template<typename T>
Listener* dds::topic::Topic< T >::listener ( ) const
inline

Gets the listener.

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

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

Gets the current TopicQos for this Topic.

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

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

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

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
template<typename BinIterator >
int32_t discover_topic_data ( const dds::domain::DomainParticipant participant,
BinIterator  begin 
)
related

Gets the information about all topics.

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
template<typename FwdIterator >
void ignore ( dds::domain::DomainParticipant participant,
FwdIterator  begin,
FwdIterator  end 
)
related
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, for example dds::topic::Topic<Foo>.
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.

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

Warning
This function currently only supports looking up a Topic, not a TopicDescription, ContentFilteredTopic or AnyTopic.
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

Template Parameters
AnyTopicBackInsertIteratorType of the back-inserting iterator passed into this function
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
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

Template Parameters
AnyTopicForwardIteratorType of the forward iterator passed into this function
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

RTI Connext Modern C++ API Version 5.3.1 Copyright © Mon Feb 19 2018 Real-Time Innovations, Inc