Namespace dds::topic

namespace topic

Typedefs

typedef ::dds::topic::detail::AnyTopic AnyTopic
typedef dds::topic::detail::ParticipantBuiltinTopicData ParticipantBuiltinTopicData
typedef dds::topic::detail::TopicBuiltinTopicData TopicBuiltinTopicData
typedef dds::topic::detail::PublicationBuiltinTopicData PublicationBuiltinTopicData
typedef dds::topic::detail::SubscriptionBuiltinTopicData SubscriptionBuiltinTopicData
typedef dds::topic::detail::BuiltinTopicKey BuiltinTopicKey
typedef dds::topic::detail::Filter Filter
typedef ::dds::topic::detail::TopicDescription TopicDescription

Functions

template<typename TOPIC>
TOPIC discover(const dds::domain::DomainParticipant &dp, const std::string &topic_name, const dds::core::Duration &timeout)

This operation gives access to an specific existing (or ready to exist) enabled Topic, ContentFilteredTopic, MultiTopic, AnyTopic or TopicDescription based on its topic_name.

Topics that the application has indicated should be ‘ignored’ (by means of the dds::topic::ignore operation) will not appear in this list (note: the ignore feature is not yet supported).

If a Topic of the same topic_name already exists, it gives access to this Topic. Otherwise it waits (blocks the caller) until another mechanism creates it. This other mechanism can be another thread, a configuration tool, or some other Data Distribution Service utility. If after the specified timeout the Topic can still not be found, the caller gets unblocked and the returned Topic will be dds::core::null.

A Topic that is obtained by means of find_topic in a specific DomainParticipant can only be used to create DataReaders and DataWriters in that DomainParticipant.

This operation usually results in network look-ups.

For finding only locally created Topics, look here.

Parameters
  • dp – the DomainParticipant

  • name – the topic name to discover

  • timeout – the time out

Throws
template<typename ANYTOPIC, typename FwdIterator>
uint32_t discover(const dds::domain::DomainParticipant &dp, FwdIterator begin, uint32_t max_size)

This operation retrieves a list of Topics that have been discovered in the domain.

If the max_size of the given list is large enough, all discovered Topics will be present in that list. Otherwise, a random sub-set of max_size elements is returned.

Topics that the application has indicated should be ‘ignored’ (by means of the dds::topic::ignore operation) will not appear in this list (note: the ignore feature is not yet supported).

Because Topics of various different kinds can be retrieved, the list contains AnyTopics.

This operation usually results in network look-ups.

Parameters
  • dp – the DomainParticipant

  • begin – a forward iterator pointing to the beginning of a container in which to insert the topics

  • max_size – the maximum number of topics to return

template<typename ANYTOPIC, typename BinIterator>
uint32_t discover_all(const dds::domain::DomainParticipant &dp, BinIterator begin)

This operation retrieves a list of all Topics that have been discovered in the domain.

Topics that the application has indicated should be ‘ignored’ (by means of the dds::topic::ignore operation) will not appear in this list (note: the ignore feature is not yet supported).

Because Topics of various different kinds can be retrieved, the list contains AnyTopics.

This operation usually results in network look-ups.

Parameters
  • dp – the DomainParticipant

  • begin – a back inserting iterator pointing to the beginning of a container in which to insert the topics

template<typename FwdIterator>
void ignore(const dds::domain::DomainParticipant &dp, FwdIterator begin, FwdIterator end)

This operation allows an application to instruct the Service to locally ignore a remote domain participant. From that point onwards the Service will locally behave as if the remote participant did not exist. This means it will ignore any Topic, publication, or subscription that originates on that domain participant.

Parameters
  • dp – the DomainParticipant

  • begin – a forward iterator pointing to the beginning of a sequence of InstanceHandles to ignore

  • end – a forward iterator pointing to the end of a sequence of InstanceHandles to ignore

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

This operation gives access to a locally-created Topic, ContentFilteredTopic, MultiTopic, AnyTopic and TopicDescription with a matching name.

dds::topic::find will never create a Topic but returns a reference to an Topic proxy that already exists locally. When no local proxy exists, the returned Topic will be a dds::core::null object. The operation never blocks.

For discovering globally available Topics, look here.

Parameters
  • dp – the DomainParticipant to find the topic on

  • topic_name – the topic name to find

void ignore(const dds::domain::DomainParticipant &dp, const dds::core::InstanceHandle &handle)

This operation allows an application to instruct the Service to locally ignore a remote domain participant. From that point onwards the Service will locally behave as if the remote participant did not exist. This means it will ignore any Topic, publication, or subscription that originates on that domain participant.

Parameters
  • dp – the DomainParticipant

  • handle – the handle of the DomainParticipant to ignore

class AnyTopicListener
#include <AnyTopicListener.hpp>

AnyTopic events Listener.

Because the DomainParticipant does not have knowledge of data types, it has to use non-data-type-listeners. In other words Any* listeners.

This class is used as a base for other listeners and is not used on its own.

Subclassed by dds::domain::DomainParticipantListener, dds::topic::NoOpAnyTopicListener

template<typename T, template<typename Q> class DELEGATE = dds::topic::detail::ContentFilteredTopic>
class ContentFilteredTopic
template<typename T>
struct is_topic_type
#include <TopicTraits.hpp>

Support functionality to check if a given object type is a Topic.

if (dds::topic::is_topic_type<Foo::Bar>::value) {
    // Foo::Bar type is considered a Topic
} else {
    // Foo::Bar type is NOT considered a Topic
}

class NoOpAnyTopicListener : public virtual dds::topic::AnyTopicListener
#include <AnyTopicListener.hpp>

AnyTopic events Listener.

This listener is just like AnyTopicListener, except that the application doesn’t have to implement all operations.

This class is used as a base for other listeners and is not used on its own.

Subclassed by dds::domain::NoOpDomainParticipantListener

template<typename T>
class NoOpTopicListener : public virtual dds::topic::TopicListener<T>
#include <TopicListener.hpp>

Topic events Listener.

This listener is just like TopicListener, except that the application doesn’t have to implement all operations.

class ExampleListener : public virtual dds::topic::NoOpTopicListener<Foo::Bar>
{
   // Not necessary to implement any Listener operations.
};

template<typename DELEGATE>
class TAnyTopic
#include <TAnyTopic.hpp>

Typeless base class for the typed Topic.

Topics are created type specific (fi Topic<Foo::Bar> topic). However, there are a few places in the API (and possibly application) where the type can not be known while still some Topic

has to be passed around, stored or even typeless functionality called.

The main examples in the API that needs typeless

Topic is: DomainParticipantListener.

template<typename D>
class TBuiltinTopicKey
#include <TBuiltinTopicKey.hpp>

Global unique identifier of the Topic.

template<typename D>
class TFilter
#include <TFilter.hpp>

Filter objects contain SQL expressions that allow the application to specify a filter on the locally available data.

A Filter is used to create a ContentFilteredTopic.

See also

for more information: Topic Definition

SQL Expression

The SQL query string is set by expression which must be a subset of the SQL query language. In this query expression, parameters may be used, which must be set in the sequence of strings defined by the parameter query_parameters. A parameter is a string which can define an integer, float, string or enumeration. The number of values in query_parameters must be equal or greater than the highest referenced n token in the query_expression (e.g. if %1 and %8 are used as parameters in the query_expression, the query_parameters should at least contain n+1 = 9 values).

Look here for the specific query expression syntax.

template<typename T, template<typename Q> class DELEGATE>
class Topic
#include <TTopic.hpp>

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.

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

See also

for more information: Topic Definition

template<typename T>
struct topic_type_name
#include <TopicTraits.hpp>

Support functionality to get the default type_name of a Topic type.

std::string typeName = dds::topic::topic_type_name<Foo::Bar>::value();

template<typename T>
class TopicInstance
#include <TopicInstance.hpp>

A TopicInstance encapsulates a dds::sub::Sample and its associated dds::core::InstanceHandle.

See also

for more information: Topic Definition

See also

for more information: dds::sub::Sample

See also

for more information: dds::core::InstanceHandle

Private Members

::dds::core::InstanceHandle h_
T sample_
template<typename T>
class TopicListener
#include <TopicListener.hpp>

Topic events Listener.

Since a Topic is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type TopicListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the TopicListener class.

The TopicListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The TopicListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::topic::TopicListener<Foo::Bar>
{
public:
    virtual void on_inconsistent_topic (
        dds::topic::Topic<Foo::Bar>& topic,
        const dds::core::status::InconsistentTopicStatus& status)
    {
        std::cout << "on_inconsistent_topic" << std::endl;
    }
};

// Create Topic with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant,
                                  "TopicName",
                                  participant.default_topic_qos(),
                                  new ExampleListener(),
                                  dds::core::status::StatusMask::all());

See also

for more information: Topic

See also

for more information: Listener information

Subclassed by dds::topic::NoOpTopicListener< T >

template<typename D>
class TParticipantBuiltinTopicData
#include <TBuiltinTopic.hpp>

Class that contains information about available DomainParticipants within the system.

The DCPSParticipant topic communicates the existence of DomainParticipants by means of the ParticipantBuiltinTopicData datatype. Each ParticipantBuiltinTopicData sample in a Domain represents a DomainParticipant that participates in that Domain: a new ParticipantBuiltinTopicData instance is created when a newly-added DomainParticipant is enabled, and it is disposed when that DomainParticipant is deleted. An updated ParticipantBuiltinTopicData sample is written each time the DomainParticipant modifies its UserDataQosPolicy.

// Get builtin subscriber
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber builtinSubscriber = dds::sub::builtin_subscriber(participant);

// Get DCPSParticipant builtin reader (happy flow)
string name = "DCPSParticipant";
vector<dds::sub::DataReader<dds::topic::ParticipantBuiltinTopicData> > readersVector;
dds::sub::find<dds::sub::DataReader<dds::topic::ParticipantBuiltinTopicData>,
                      back_insert_iterator<vector<dds::sub::DataReader<dds::topic::ParticipantBuiltinTopicData> > > >(
          builtinSubscriber,
          name,
          back_inserter<vector<dds::sub::DataReader<dds::topic::ParticipantBuiltinTopicData> > >(readersVector));
dds::sub::DataReader<dds::topic::ParticipantBuiltinTopicData> builtinReader = readersVector[0];

// The builtinReader can now be used just as a normal dds::sub::DataReader to get
// dds::topic::ParticipantBuiltinTopicData samples.

See also

for more information: DCPS_Builtin_Topics

See also

for more information: DCPS_Builtin_Topics_ParticipantData

template<typename D>
class TPublicationBuiltinTopicData
#include <TBuiltinTopic.hpp>

Class that contains information about available DataWriters within the system.

The DCPSPublication topic communicates the existence of datawriters by means of the PublicationBuiltinTopicData datatype. Each PublicationBuiltinTopicData sample in a Domain represents a datawriter in that Domain: a new PublicationBuiltinTopicData instance is created when a newly-added DataWriter is enabled, and it is disposed when that DataWriter is deleted. An updated PublicationBuiltinTopicData sample is written each time the DataWriter (or the Publisher to which it belongs) modifies a QosPolicy that applies to the entities connected to it. Also will it be updated when the writer looses or regains its liveliness.

// Get builtin subscriber
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber builtinSubscriber = dds::sub::builtin_subscriber(participant);

// Get DCPSPublication builtin reader (happy flow)
string name = "DCPSPublication";
vector<dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData> > readersVector;
dds::sub::find<dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData>,
                      back_insert_iterator<vector<dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData> > > >(
          builtinSubscriber,
          name,
          back_inserter<vector<dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData> > >(readersVector));
dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData> builtinReader = readersVector[0];

// The builtinReader can now be used just as a normal dds::sub::DataReader to get
// dds::topic::PublicationBuiltinTopicData samples.

See also

for more information: DCPS_Builtin_Topics

See also

for more information: DCPS_Builtin_Topics_PublicationData

template<typename D>
class TSubscriptionBuiltinTopicData
#include <TBuiltinTopic.hpp>

Class that contains information about available DataReaders within the system.

The DCPSSubscription topic communicates the existence of datareaders by means of the SubscriptionBuiltinTopicData datatype. Each SubscriptionBuiltinTopicData sample in a Domain represents a datareader in that Domain: a new SubscriptionBuiltinTopicData instance is created when a newly-added DataReader is enabled, and it is disposed when that DataReader is deleted. An updated SubscriptionBuiltinTopicData sample is written each time the DataReader (or the Subscriber to which it belongs) modifies a QosPolicy that applies to the entities connected to it.

// Get builtin subscriber
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber builtinSubscriber = dds::sub::builtin_subscriber(participant);

// Get DCPSSubscription builtin reader (happy flow)
string name = "DCPSSubscription";
vector<dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData> > readersVector;
dds::sub::find<dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>,
                      back_insert_iterator<vector<dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData> > > >(
          builtinSubscriber,
          name,
          back_inserter<vector<dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData> > >(readersVector));
dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData> builtinReader = readersVector[0];

// The builtinReader can now be used just as a normal dds::sub::DataReader to get
// dds::topic::SubscriptionBuiltinTopicData samples.

See also

for more information: DCPS_Builtin_Topics

See also

for more information: DCPS_Builtin_Topics_SubscriptionData

template<typename D>
class TTopicBuiltinTopicData
#include <TBuiltinTopic.hpp>

Class that contains information about available Topics within the system.

The DCPSTopic topic communicates the existence of topics by means of the TopicBuiltinTopicData datatype. Each TopicBuiltinTopicData sample in a Domain represents a Topic in that Domain: a new TopicBuiltinTopicData instance is created when a newly-added Topic is enabled. However, the instance is not disposed when a Topic is deleted by its participant because a topic lifecycle is tied to the lifecycle of a Domain, not to the lifecycle of an individual participant. An updated TopicBuiltinTopicData sample is written each time a Topic modifies one or more of its QosPolicy values.

// Get builtin subscriber
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber builtinSubscriber = dds::sub::builtin_subscriber(participant);

// Get DCPSTopic builtin reader (happy flow)
string name = "DCPSTopic";
vector<dds::sub::DataReader<dds::topic::TopicBuiltinTopicData> > readersVector;
dds::sub::find<dds::sub::DataReader<dds::topic::TopicBuiltinTopicData>,
                      back_insert_iterator<vector<dds::sub::DataReader<dds::topic::TopicBuiltinTopicData> > > >(
          builtinSubscriber,
          name,
          back_inserter<vector<dds::sub::DataReader<dds::topic::TopicBuiltinTopicData> > >(readersVector));
dds::sub::DataReader<dds::topic::TopicBuiltinTopicData> builtinReader = readersVector[0];

// The builtinReader can now be used just as a normal dds::sub::DataReader to get
// dds::topic::TopicBuiltinTopicData samples.

See also

for more information: DCPS_Builtin_Topics

See also

for more information: DCPS_Builtin_Topics_TopicData

template<typename DELEGATE>
class TTopicDescription
#include <TTopicDescription.hpp>

This class is the base for Topic, ContentFilteredTopic and MultiTopic.

The TopicDescription attribute type_name defines an unique data type that is made available to the Data Distribution Service when a Topic

is created with that type.

TopicDescription has also a name that allows it to be retrieved locally.

See also

for more information: Topic Definition

namespace detail

Typedefs

typedef dds::topic::TAnyTopic<org::eclipse::cyclonedds::topic::AnyTopicDelegate> AnyTopic
typedef dds::topic::TParticipantBuiltinTopicData<org::eclipse::cyclonedds::topic::ParticipantBuiltinTopicDataDelegate> ParticipantBuiltinTopicData
typedef dds::topic::TTopicBuiltinTopicData<org::eclipse::cyclonedds::topic::TopicBuiltinTopicDataDelegate> TopicBuiltinTopicData
typedef dds::topic::TPublicationBuiltinTopicData<org::eclipse::cyclonedds::topic::PublicationBuiltinTopicDataDelegate> PublicationBuiltinTopicData
typedef dds::topic::TSubscriptionBuiltinTopicData<org::eclipse::cyclonedds::topic::SubscriptionBuiltinTopicDataDelegate> SubscriptionBuiltinTopicData
typedef dds::topic::TBuiltinTopicKey<org::eclipse::cyclonedds::topic::BuiltinTopicKeyDelegate> BuiltinTopicKey
typedef ::dds::topic::TFilter<::org::eclipse::cyclonedds::topic::FilterDelegate> Filter
typedef dds::topic::TTopicDescription<org::eclipse::cyclonedds::topic::TopicDescriptionDelegate> TopicDescription
template<typename T>
class Topic

Private Members

T sample_
namespace qos

Typedefs

typedef dds::topic::qos::detail::TopicQos TopicQos
class TopicQos : public dds::core::EntityQos<org::eclipse::cyclonedds::topic::qos::TopicQosDelegate>
#include <TopicQos.hpp>

This struct provides the basic mechanism for an application to specify Quality of Service attributes for a Topic.

A QosPolicy can be set when the Topic is created or modified with the set qos operation. Both operations take the TopicQos object as a parameter. There may be cases where several policies are in conflict. Consistency checking is performed each time the policies are modified when they are being created and, in case they are already enabled, via the set qos operation.

Attributes

QosPolicy

Desciption

Default Value

dds::core::policy::TopicData

Additional information (info)

TopicData::TopicData(empty)

dds::core::policy::Durability

Data storage settings for late joiners (info)

Durability::Volatile()

dds::core::policy::DurabilityService

Transient/persistent behaviour (info)

DurabilityService::DurabilityService()

dds::core::policy::Deadline

Period in which new sample is written (info)

Deadline::Deadline(infinite)

dds::core::policy::LatencyBudget

Used for optimization (info)

LatencyBudget::LatencyBudget(zero)

dds::core::policy::Liveliness

Liveliness assertion mechanism (info)

Liveliness::Automatic()

dds::core::policy::Reliability

Reliability settings (info)

Reliability::Reliable()

dds::core::policy::DestinationOrder

DataReader data order settings (info)

DestinationOrder::ReceptionTimestamp()

dds::core::policy::History

Data storage settings (info)

History::KeepLast(depth 1)

dds::core::policy::ResourceLimits

Maximum resource settings (info)

ResourceLimits::ResourceLimits(all unlimited)

dds::core::policy::TransportPriority

Priority hint for transport layer (info)

TransportPriority::TTransportPriority(0)

dds::core::policy::Lifespan

Maximum duration of validity of data (info)

Lifespan::Lifespan(infinite)

dds::core::policy::Ownership

Exclusive ownership or not (info)

Ownership::Shared()

dds::core::policy::DataRepresentation

Supported data representation kinds (info)

DataRepresentation::DataRepresentation(dds::core::policy::DataRepresentationId::XCDR1)

dds::core::policy::TypeConsistencyEnforcement

Type consistency enforcement policies (info)

dds::core::policy::TypeConsistencyKind::DISALLOW_TYPE_COERCION

Some QosPolicy have “immutable” semantics meaning that they can only be specified either at Topic creation time or prior to calling the enable operation on the Topic.

See also

for more information: DCPS_QoS

namespace detail