#ifndef OMG_DDS_TTOPIC_TOPIC_HPP_
#define OMG_DDS_TTOPIC_TOPIC_HPP_
/* Copyright 2010, Object Management Group, Inc.
* Copyright 2010, PrismTech, Corp.
* Copyright 2010, Real-Time Innovations, Inc.
* All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include <dds/core/conformance.hpp>
#include <dds/core/types.hpp>
#include <dds/core/ref_traits.hpp>
#include <dds/domain/DomainParticipant.hpp>
#include <dds/topic/qos/TopicQos.hpp>
#include <dds/topic/TopicDescription.hpp>
#include <dds/topic/AnyTopic.hpp>
namespace dds
{
namespace topic
{
template <typename T, template <typename Q> class DELEGATE>
class Topic;
template <typename T>
class TopicListener;
}
}
/**
* @brief
* 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.
*
* <b><i>Example</i></b>
* @code{.cpp}
* // Default creation of a Topic
* dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
* dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
*
* // The Topic can be used to create readers and writers
* // DataReader
* dds::sub::Subscriber subscriber(participant);
* dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
* // DataWriter
* dds::pub::Publisher publisher(participant);
* dds::pub::DataWriter<Foo::Bar> writer(publisher, topic);
* @endcode
*
* @see for more information: @ref DCPS_Modules_TopicDefinition "Topic Definition"
*/
template <typename T, template <typename Q> class DELEGATE>
class dds::topic::Topic : public dds::topic::TAnyTopic< DELEGATE<T> >
{
public:
/**
* Convenience typedef for the type of the data sample.
*/
typedef T DataType;
/**
* Local convenience typedef for dds::topic::TopicListener.
*/
typedef TopicListener<T> Listener;
public:
OMG_DDS_REF_TYPE_PROTECTED_DC_T(Topic, ::dds::topic::TAnyTopic, T, DELEGATE)
OMG_DDS_IMPLICIT_REF_BASE(Topic)
OMG_DDS_COMPLETE_RULE_OF_FIVE_VIRTUAL_DEFAULT(Topic)
public:
/**
* Create a new Topic.
*
* This operation creates a reference to a new or existing Topic under the given name,
* for a specific data type.
*
* <i>QoS</i><br>
* The Topic will be created with the QoS values specified on the last
* successful call to @link dds::domain::DomainParticipant::default_topic_qos(const ::dds::topic::qos::TopicQos& qos)
* dp.default_topic_qos(qos) @endlink or, if the call was never made, the
* @ref anchor_dds_topic_qos_defaults "default" values.
*
* <i>Existing Topic Name</i><br>
* 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.
*
* <i>Local Proxy</i><br>
* 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.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the name of the Topic to be created
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
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 and type_name.
*
* <i>QoS</i><br>
* The Topic will be created with the QoS values specified on the last
* successful call to @link dds::domain::DomainParticipant::default_topic_qos(const ::dds::topic::qos::TopicQos& qos)
* dp.default_topic_qos(qos) @endlink or, if the call was never made, the
* @ref anchor_dds_topic_qos_defaults "default" values.
*
* <i>Existing Topic Name</i><br>
* 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.
*
* <i>Local Proxy</i><br>
* 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.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the topic's name
* @param type_name a local alias of the data type
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
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.
*
* <i>QoS</i><br>
* A possible application pattern to construct the TopicQos for the
* Topic is to:
* @code{.cpp}
* // 1) Retrieve the QosPolicy settings on the associated DomainParticipant
* dds::topic::qos::TopicQos topicQos = participant.default_datareader_qos();
* // 2) Selectively modify QosPolicy settings as desired.
* topicQos << dds::core::policy::Durability::Transient();
* // 3) Use the resulting QoS to construct the DataReader.
* dds::topic::Topic<Foo::Bar> topic(participant, "TopicName", topicQos);
* @endcode
*
* <i>Existing Topic Name</i><br>
* 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.
*
* <i>Local Proxy</i><br>
* 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.
*
* <i>Listener</i><br>
* The following statuses are applicable to the TopicListener:
* - dds::core::status::StatusMask::inconsistent_topic()
*
* See @ref DCPS_Modules_Infrastructure_Listener "listener concept",
* @ref anchor_dds_topic_listener_commstatus "communication status" and
* @ref anchor_dds_topic_listener_commpropagation "communication propagation"
* for more information.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the topic's name
* @param qos the topic listener
* @param listener the topic listener
* @param mask the listener event mask
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
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 and type_name.
*
* <i>QoS</i><br>
* A possible application pattern to construct the TopicQos for the
* Topic is to:
* @code{.cpp}
* // 1) Retrieve the QosPolicy settings on the associated DomainParticipant
* dds::topic::qos::TopicQos topicQos = participant.default_datareader_qos();
* // 2) Selectively modify QosPolicy settings as desired.
* topicQos << dds::core::policy::Durability::Transient();
* // 3) Use the resulting QoS to construct the DataReader.
* dds::topic::Topic<Foo::Bar> topic(participant, "TopicName", "TypeName", topicQos);
* @endcode
*
* <i>Existing Topic Name</i><br>
* 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.
*
* <i>Local Proxy</i><br>
* 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.
*
* <i>Listener</i><br>
* The following statuses are applicable to the TopicListener:
* - dds::core::status::StatusMask::inconsistent_topic()
*
* See @ref DCPS_Modules_Infrastructure_Listener "listener concept",
* @ref anchor_dds_topic_listener_commstatus "communication status" and
* @ref anchor_dds_topic_listener_commpropagation "communication propagation"
* for more information.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the topic's name
* @param type_name a local alias of the data type
* @param qos the topic listener
* @param listener the topic listener
* @param mask the listener event mask
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
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());
#if defined (OMG_DDS_X_TYPE_DYNAMIC_TYPES_SUPPORT)
/**
* Create a new topic with a dynamic type description. Notice that in this
* case the data type has to be DynamicData, so the Topic type will be
* Topic<DynamicData>.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the topic's name. The QoS will be set to
* dp.default_topic_qos().
* @param type the topic type
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
Topic(const dds::domain::DomainParticipant& dp,
const std::string& topic_name,
const dds::core::xtypes::DynamicType type);
/**
* Create a new topic with a dynamic type description. Notice that in this
* case the data type has to be DynamicData, so the Topic type will be
* Topic<DynamicData>.
*
* @param dp the domain participant on which the topic will be defined
* @param topic_name the topic's name
* @param type the topic type
* @param qos the topic listener
* @param listener the topic listener
* @param mask the listener event mask
* @throws 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.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
Topic(const dds::domain::DomainParticipant& dp,
const std::string& topic_name,
const dds::core::xtypes::DynamicType type
const dds::topic::qos::TopicQos& qos,
dds::topic::TopicListener<T>* listener = NULL,
const dds::core::status::StatusMask& mask = dds::core::status::StatusMask::none());
#endif /* OMG_DDS_X_TYPE_DYNAMIC_TYPES_SUPPORT */
public:
/**
* 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().
*
* @anchor anchor_dds_topic_listener_commstatus
* <i>Communication Status</i><br>
* 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:
* - dds::core::status::StatusMask::inconsistent_topic()
*
* 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.
*
* @anchor anchor_dds_topic_listener_commpropagation
* <i>Status Propagation</i><br>
* 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 @ref DCPS_Modules_Infrastructure_Listener "listener information".
*
* @param listener the listener
* @param event_mask the mask defining the events for which the listener
* will be notified.
* @throws dds::core::Error
* An internal error has occurred.
* @throws dds::core::NullReferenceError
* The entity was not properly created and references to dds::core::null.
* @throws dds::core::AlreadyClosedError
* The entity has already been closed.
* @throws dds::core::UnsupportedError
* A status was selected that cannot be supported because
* the infrastructure does not maintain the required connectivity information.
* @throws dds::core::OutOfResourcesError
* The Data Distribution Service ran out of resources to
* complete this operation.
*/
void listener(Listener* listener,
const ::dds::core::status::StatusMask& event_mask);
/**
* Get the listener of this Topic.
*
* See also @ref DCPS_Modules_Infrastructure_Listener "listener information".
*
* @return the listener
* @throws dds::core::NullReferenceError
* The entity was not properly created and references to dds::core::null.
*/
Listener* listener() const;
};
#endif /* OMG_DDS_TTOPIC_TOPIC_HPP_ */
