- Generated by
1.8.16
|
Cyclone ISO C++ API Reference Guide
|
Topic is the most basic description of the data to be published and subscribed. More...
#include "Topic.hpp"
Inherits dds::topic::AnyTopic.
Public Types | |
| typedef T | DataType |
| typedef TopicListener< T > | Listener |
Topic is the most basic description of the data to be published and subscribed.
A 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 Topic.
Topic is the only TopicDescription that can be used for publications and therefore associated with a DataWriter.
Example
| typedef T dds::topic::Topic< T >::DataType |
| typedef TopicListener<T> dds::topic::Topic< T >::Listener |
Local convenience typedef for dds::topic::TopicListener.
| dds::topic::Topic< T >::Topic | ( | const dds::domain::DomainParticipant & | dp, |
| const std::string & | topic_name | ||
| ) |
Create a new Topic.
This operation creates a reference to a new or existing Topic under the given name, for a specific data type.
QoS
The Topic will be created with the QoS values specified on the last successful call to dp.default_topic_qos(qos) or, if the call was never made, the default values.
Existing Topic Name
Before creating a new Topic, this operation performs a lookup_topicdescription for the specified topic_name. When a Topic is found with the same name in the current domain, the QoS and type_name of the found Topic are matched against the parameters qos and type_name. When they are the same, no Topic is created but a new proxy of the existing Topic is returned. When they are not exactly the same, no Topic is created and dds::core::Error is thrown.
Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. The deletion of a Topic object will not delete the Topic from the domain, just the local proxy is deleted.
| dp | the domain participant on which the topic will be defined |
| topic_name | the name of the Topic to be created |
| dds::core::Error | A other Topic with the same name but different type or QoS was detected in the current domain or another internal error has occurred. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
| dds::topic::Topic< T >::Topic | ( | const dds::domain::DomainParticipant & | dp, |
| const std::string & | topic_name, | ||
| const std::string & | type_name | ||
| ) |
Create a new Topic.
This operation creates a reference to a new or existing Topic under the given name, for a specific data type and type_name.
QoS
The Topic will be created with the QoS values specified on the last successful call to dp.default_topic_qos(qos) or, if the call was never made, the default values.
Existing Topic Name
Before creating a new Topic, this operation performs a lookup_topicdescription for the specified topic_name. When a Topic is found with the same name in the current domain, the QoS and type_name of the found Topic are matched against the parameters qos and type_name. When they are the same, no Topic is created but a new proxy of the existing Topic is returned. When they are not exactly the same, no Topic is created and dds::core::Error is thrown.
Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. The deletion of a Topic object will not delete the Topic from the domain, just the local proxy is deleted.
| dp | the domain participant on which the topic will be defined |
| topic_name | the topic's name |
| type_name | a local alias of the data type |
| dds::core::Error | A other Topic with the same name but different type or QoS was detected in the current domain or another internal error has occurred. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
| dds::topic::Topic< T >::Topic | ( | const dds::domain::DomainParticipant & | dp, |
| const std::string & | topic_name, | ||
| const dds::topic::qos::TopicQos & | qos, | ||
| dds::topic::TopicListener< T > * | listener = NULL, |
||
| const dds::core::status::StatusMask & | mask = dds::core::status::StatusMask::none() |
||
| ) |
Create a new Topic.
This operation creates a reference to a new or existing Topic under the given name, for a specific data type.
QoS
A possible application pattern to construct the TopicQos for the Topic is to:
Existing Topic Name
Before creating a new Topic, this operation performs a lookup_topicdescription for the specified topic_name. When a Topic is found with the same name in the current domain, the QoS and type_name of the found Topic are matched against the parameters qos and type_name. When they are the same, no Topic is created but a new proxy of the existing Topic is returned. When they are not exactly the same, no Topic is created and dds::core::Error is thrown.
Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. The deletion of a Topic object will not delete the Topic from the domain, just the local proxy is deleted.
Listener
The following statuses are applicable to the TopicListener:
See listener concept, communication status and communication propagation for more information.
| dp | the domain participant on which the topic will be defined |
| topic_name | the topic's name |
| qos | the topic listener |
| listener | the topic listener |
| mask | the listener event mask |
| dds::core::Error | A other Topic with the same name but different type or QoS was detected in the current domain or another internal error has occurred. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
| dds::topic::Topic< T >::Topic | ( | const dds::domain::DomainParticipant & | dp, |
| const std::string & | topic_name, | ||
| const std::string & | type_name, | ||
| const dds::topic::qos::TopicQos & | qos, | ||
| dds::topic::TopicListener< T > * | listener = NULL, |
||
| const dds::core::status::StatusMask & | mask = dds::core::status::StatusMask::none() |
||
| ) |
Create a new Topic.
This operation creates a reference to a new or existing Topic under the given name, for a specific data type and type_name.
QoS
A possible application pattern to construct the TopicQos for the Topic is to:
Existing Topic Name
Before creating a new Topic, this operation performs a lookup_topicdescription for the specified topic_name. When a Topic is found with the same name in the current domain, the QoS and type_name of the found Topic are matched against the parameters qos and type_name. When they are the same, no Topic is created but a new proxy of the existing Topic is returned. When they are not exactly the same, no Topic is created and dds::core::Error is thrown.
Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. The deletion of a Topic object will not delete the Topic from the domain, just the local proxy is deleted.
Listener
The following statuses are applicable to the TopicListener:
See listener concept, communication status and communication propagation for more information.
| dp | the domain participant on which the topic will be defined |
| topic_name | the topic's name |
| type_name | a local alias of the data type |
| qos | the topic listener |
| listener | the topic listener |
| mask | the listener event mask |
| dds::core::Error | A other Topic with the same name but different type or QoS was detected in the current domain or another internal error has occurred. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
|
inherited |
This function closes the entity and releases related resources.
Resource management for some reference types might involve relatively heavyweight operating- system resources — such as e.g., threads, mutexes, and network sockets — in addition to memory. These objects therefore provide a method close() that shall halt network communication (in the case of entities) and dispose of any appropriate operating-system resources.
Users of this PSM are recommended to call close on objects of all reference types once they are finished using them. In addition, implementations may automatically close objects that they deem to be no longer in use, subject to the following restrictions:
|
inherited |
This operation returns the DomainParticipant associated with the TopicDescription.
Note that there is exactly one DomainParticipant associated with each TopicDescription.
|
inherited |
Enable entity.
This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the dds::core::policy::EntityFactory QoS policy on the corresponding factory for the Entity.
Enabled entities are immediately activated at creation time meaning all their immutable QoS settings can no longer be changed. Disabled Entities are not yet activated, so it is still possible to change there immutable QoS settings. However, once activated the immutable QoS settings can no longer be changed.
Creating disabled entities can make sense when the creator of the Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.
The default setting of dds::core::policy::EntityFactory is such that, by default, it is not necessary to explicitly call enable on newly- created entities.
The enable operation is idempotent. Calling enable on an already- enabled Entity does not raise exceptions and has no effect.
If an Entity has not yet been enabled, the only operations that can be invoked on it are: the ones to set, get or copy the QosPolicy settings, the ones that set (or get) the listener, the ones that get the StatusCondition, the get_status_changes operation (although the status of a disabled entity never changes), and the ‘factory’ operations that create, delete or lookup other Entities. Other operations will throw the exception dds::core::NotEnabledError.
Entities created from a factory that is disabled are created disabled regardless of the setting of the dds::core::policy::EntityFactory Qos policy. Calling enable on an Entity whose factory is not enabled will fail and throw an dds::core::PreconditionNotMetError exception.
If the dds::core::policy::EntityFactory QoS policy has autoenable_created_entities set to TRUE, the enable operation on the factory will automatically enable all entities created from the factory.
The Listeners associated with an entity are not called until the entity is enabled. Conditions associated with an entity that is not enabled are inactive; that is, they have a trigger_value==false (dds::core::cond::Condition and dds::core::cond::WaitSet).
eg.
| dds::core::PreconditionNotMetError | Entities' factory is not enabled. |
|
inherited |
This operation obtains the InconsistentTopicStatus object of the Topic.
The InconsistentTopicStatus can also be monitored using a TopicListener or by using the associated StatusCondition.
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
|
inherited |
This operation returns the InstanceHandle_t that represents the Entity.
The relevant state of some Entity objects are distributed using built-in topics. Each built-in topic sample represents the state of a specific Entity and has a unique instance_handle. This operation returns the instance_handle of the built-in topic sample that represents the specified Entity.
Some Entities (dds::pub::Publisher and dds::sub::Subscriber) do not have a corresponding built-in topic sample, but they still have an instance_handle that uniquely identifies the Entity. The instance_handles obtained this way can also be used to check whether a specific Entity is located in a specific DomainParticipant (dds::domain::DomainParticipant::contains_entity()).
|
inherited |
Check if the referenced object is nil.
In other words, check if the reference is pointing to a null object.
| Listener* dds::topic::Topic< T >::listener | ( | ) | const |
Get the listener of this Topic.
See also listener information.
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| void dds::topic::Topic< T >::listener | ( | Listener * | listener, |
| const ::dds::core::status::StatusMask & | event_mask | ||
| ) |
Register a listener with the Topic.
This operation attaches a TopicListener to the Topic. Only one TopicListener can be attached to each Topic. If a TopicListener was already attached, the operation will replace it with the new one. When the listener is the NULL pointer, it represents a listener that is treated as a NOOP for all statuses activated in the bit mask.
Listener un-registration is performed by setting the listener to NULL and mask none().
Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated TopicListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get_<status_name>_status from inside the listener it will see the status already reset. An exception to this rule is the NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the TopicListener:
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant dds::core::status::StatusMask::none() can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant dds::core::status::StatusMask::all() can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification which are applicable to the PublisherListener.
Status Propagation
In case a communication status is not activated in the mask of the TopicListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a Topic specific behaviour when needed. In case the communication status is not activated in the mask of the DomainParticipantListener as well, the application is not notified of the change.
See also listener information.
| listener | the listener |
| event_mask | the mask defining the events for which the listener will be notified. |
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::UnsupportedError | A status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
|
inherited |
This operation returns the name used to create the TopicDescription.
|
inherited |
Special operator!= used to check if this reference object does not equal the dds::core::null reference.
The non-null-check can be done like this:
|
inherited |
Compares two Reference objects and returns true if they are not equal.
Inequality is based on the referential inequality of the object being pointed to.
| ref | the other Reference object |
|
inherited |
The operator->() is provided to be able to directly invoke functions on the delegate.
The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:
|
inherited |
The operator->() is provided to be able to directly invoke functions on the delegate.
The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:
|
inherited |
This operation replaces the existing set of QosPolicy settings for a Topic.
The parameter qos contains the object with the QosPolicy settings which is checked for self-consistency and mutability.
When the application tries to change a QosPolicy setting for an enabled Topic, which can only be set before the Topic is enabled, the operation will fail and a ImmutablePolicyError is thrown. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed.
When the qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and an InconsistentPolicyError is thrown.
| qos | the qos |
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
| dds::core::ImmutablePolicyError | The parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataReader. |
| dds::core::InconsistentPolicyError | The parameter qos contains conflicting QosPolicy settings, |
|
inherited |
Special operator== used to check if this reference object equals the dds::core::null reference.
The null-check can be done like this:
|
inherited |
Compares two Reference objects and returns true if they are equal.
Equality is based on the referential equality of the object being pointed.
| ref | the other Reference object |
|
inherited |
Gets the TopicQos setting for this instance.
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
|
inherited |
Gets the TopicQos setting for this instance.
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
|
inherited |
This operation replaces the existing set of QosPolicy settings for a Topic.
The parameter qos contains the object with the QosPolicy settings which is checked for self-consistency and mutability.
When the application tries to change a QosPolicy setting for an enabled Topic, which can only be set before the Topic is enabled, the operation will fail and a ImmutablePolicyError is thrown. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed.
When the qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and an InconsistentPolicyError is thrown.
| qos | the qos |
| dds::core::Error | An internal error has occurred. |
| dds::core::NullReferenceError | The entity was not properly created and references to dds::core::null. |
| dds::core::AlreadyClosedError | The entity has already been closed. |
| dds::core::OutOfResourcesError | The Data Distribution Service ran out of resources to complete this operation. |
| dds::core::ImmutablePolicyError | The parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataReader. |
| dds::core::InconsistentPolicyError | The parameter qos contains conflicting QosPolicy settings, |
|
inherited |
Retain the Entity, even when it goes out of scope.
This function indicates that references to this object may go out of scope but that the application expects to look it up again later. Therefore the Service must consider this object to be still in use and may not close it automatically.
|
inherited |
This operation returns a mask with the communication statuses in the Entity that are “triggered”.
This operation retrieves the list of communication statuses in the Entity that are triggered. That is the set of communication statuses whose value have changed since the last time the application called this operation. This operation shows whether a change has occurred even when the status seems unchanged because the status changed back to the original status.
When the Entity is first created or if the Entity is not enabled, all communication statuses are in the “un-triggered” state so the mask returned by the operation is empty.
The result value is a bit mask in which each bit shows which value has changed. The relevant bits represent one of the following statuses:
When the entity is first created, or if the entity is not enabled, all communication statuses are in the untriggered state so the list returned by the status_changes operation will be empty.
Each status bit is declared as a constant and can be used in an AND operation to check the status bit against the result of type StatusMask. Not all statuses are relevant to all Entity objects. See the respective Listener interfaces for each Entity for more information.
The list of statuses returned by the status_changes operation refers to the statuses that are triggered on the Entity itself, and does not include statuses that apply to contained entities.
|
inherited |
This operation returns the registered name of the data type associated with the TopicDescription.
1.8.16