Namespace dds::pub¶

namespace pub¶

Typedefs

typedef ::dds::pub::detail::AnyDataWriter AnyDataWriter¶

typedef dds::pub::detail::CoherentSet CoherentSet¶

typedef dds::pub::detail::Publisher Publisher¶

typedef dds::pub::detail::SuspendedPublication SuspendedPublication¶

Functions

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

Ignore publications.

Parameters

dp – the DomainParticipant for which the remote entity will be ignored
begin – an iterator indicating the beginning of a sequence of InstanceHandles of the remote Entity that has to be ignored
end – an iterator indicating the end of a sequence of InstanceHandles of the remote Entity that has to be ignored

template<typename T> ::dds::core::InstanceHandleSeq matched_subscriptions(const dds::pub::DataWriter<T> &dw)¶

This operation retrieves the list of subscriptions currently “associated” with the DataWriter. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the dds::sub::ignore operation on the DomainParticipant class.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataReader entities. You can access more detailed information about a particular subscription by passing its subscription_handle to either the dds::pub::matched_subscription_data operation or to the read with instance operation on the built-in reader for the “DCPSSubscription” topic.

See Builtin Topics for more information.

Parameters

dw – the DataWriter

Throws

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::NotEnabledError – The DataWriter has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

a sequence of handles

template<typename T, typename FwdIterator> uint32_t matched_subscriptions(const dds::pub::DataWriter<T> &dw, FwdIterator begin, uint32_t max_size)¶

This operation retrieves the list of subscriptions currently “associated” with the DataWriter. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the dds::sub::ignore operation on the DomainParticipant class.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataReader entities. You can access more detailed information about a particular subscription by passing its subscription_handle to either the dds::pub::matched_subscription_data operation or to the read with instance operation on the built-in reader for the “DCPSSubscription” topic.

See Builtin Topics for more information.

Parameters

dw – the DataWriter
begin – an iterator indicating the beginning of a sequence of instance handles in which to put the matched subscriptions
max_size – the maximum number of matched subscriptions to return

Throws

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::NotEnabledError – The DataWriter has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the number of matched subscriptions returned

template<typename T> const dds::topic::SubscriptionBuiltinTopicData matched_subscription_data(const dds::pub::DataWriter<T> &dw, const ::dds::core::InstanceHandle &h)¶

This operation retrieves information on the specified subscription that is currently “associated” with the DataWriter. That is, a subscription with a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the dds::sub::ignore operation on the DomainParticipant class.

The subscription_handle must correspond to a subscription currently associated with the DataWriter, otherwise the operation will fail and throw InvalidArgumentError. The operation dds::pub::matched_subscriptions can be used to find the subscriptions that are currently matched with the DataWriter.

The operation may fail if the infrastructure does not locally maintain the connectivity information. In such cases the operation will throw UnsupportedError.

See also DCPS_Builtin_Topics and DCPS_Builtin_Topics_SubscriptionData.

Parameters

dw – the DataWriter
h – the InstanceHandle

Throws

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::NotEnabledError – The DataWriter has not yet been enabled.
dds::core::UnsupportedError – The information about “associated” subscriptions are not maintained.
dds::core::InvalidArgumentError – Subscription not associated with the DataWriter.
dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the SubscriptionBuiltinTopicData

template<typename WRITER, typename FwdIterator> uint32_t find(const dds::pub::Publisher &pub, const std::string &topic_name, FwdIterator begin, uint32_t max_size)¶

This function retrieves previously-created DataWriters belonging to the Publisher that is attached to a Topic with a matching topic_name. If no such DataWriter exists, the operation will return an empty container.

Parameters

pub – the Publisher to find an associated DataWriter for
topic_name – the topic name
begin – a iterator for a sequence in which to put found DataWriters
max_size – the maximum number of DataWriters to return

Returns

the total number of elements found. Notice that at most max_size will be copied using the provided iterator

template<typename WRITER, typename BinIterator> uint32_t find(const dds::pub::Publisher &pub, const std::string &topic_name, BinIterator begin)¶

This function retrieves previously-created DataWriters belonging to the Publisher that is attached to a Topic with a matching topic_name. If no such DataWriter exists, the operation will return an empty container.

Parameters

pub – the Publisher to find an associated DataWriter for
topic_name – the topic name
begin – a back insertion iterator for a sequence in which to put found DataWriters

Returns

the total number of elements found. Notice that at most max_size will be copied using the provided iterator.

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

Ignore publications.

Parameters

dp – the DomainParticipant for which the remote entity will be ignored
handle – the InstanceHandle of the remote entity that has to be ignored

class AnyDataWriterListener¶

#include <AnyDataWriterListener.hpp>

AnyDataWriter events Listener.

Because Publisher and DomainParticipant do not have knowledge of data types, they have to use non-data-type-listeners. In other words Any* listeners.

See also

dds::pub::PublisherListener

See also

dds::domain::DomainParticipantListener

Subclassed by dds::pub::NoOpAnyDataWriterListener, dds::pub::PublisherListener

class NoOpAnyDataWriterListener : public virtual dds::pub::AnyDataWriterListener ¶

#include <AnyDataWriterListener.hpp>

AnyDataWriter events Listener.

This listener is just like AnyDataWriterListener, 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.

See also

dds::pub::AnyDataWriterListener

See also

dds::pub::NoOpPublisherListener

Subclassed by dds::pub::NoOpPublisherListener

template<typename T, template<typename Q> class DELEGATE> class DataWriter : public dds::pub::TAnyDataWriter<DELEGATE<T>>¶

#include <DataWriter.hpp>

DataWriter allows the application to set the value of the sample to be published under a given Topic.

A DataWriter is attached to exactly one Publisher.

A DataWriter is bound to exactly one Topic and therefore to exactly one data type. The Topic must exist prior to the DataWriter’s creation. DataWriter is an abstract class. It must be specialized for each particular application data type. For a fictional application data type Bar (defined in the module Foo) the specialized class would be dds::pub::DataWriter<Foo::Bar>.

The pre-processor generates from IDL type descriptions the application DataWriter<type> classes. For each application data type that is used as Topic data type, a typed class DataWriter<type> is derived from the AnyDataWriter class.

For instance, for an application, the definitions are located in the Foo.idl file. The pre-processor will generate a ccpp_Foo.h include file.

General note: The name ccpp_Foo.h is derived from the IDL file Foo.idl, that defines Foo::Bar, for all relevant DataWriter<Foo::Bar> operations.

// Default creation of a DataWriter
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::pub::Publisher publisher(participant);
dds::pub::DataWriter<Foo::Bar> writer(publisher, topic);

// Default write of a sample on the DataWriter
Foo::Bar sample;
writer.write(sample);

See also

for more information: Publication concept

See also

for more information: DataWriter concept

Note

Apart from idl files, Google protocol buffers are also supported. For the API itself, it doesn’t matter if the type header files were generated from idl or protocol buffers. The resulting API usage and includes remain the same.

template<typename T> class DataWriterListener¶

#include <DataWriterListener.hpp>

DataWriter events Listener.

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

The DataWriterListener 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 DataWriterListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::pub::DataWriterListener<Foo::Bar>
{
public:
    virtual void on_offered_deadline_missed (
        dds::pub::DataWriter<Foo::Bar>& writer,
        const dds::core::status::OfferedDeadlineMissedStatus& status)
    {
        std::cout << "on_offered_deadline_missed" << std::endl;
    }

    virtual void on_offered_incompatible_qos (
        dds::pub::DataWriter<Foo::Bar>& writer,
        const dds::core::status::OfferedIncompatibleQosStatus& status)
    {
        std::cout << "on_offered_incompatible_qos" << std::endl;
    }

    virtual void on_liveliness_lost (
        dds::pub::DataWriter<Foo::Bar>& writer,
        const dds::core::status::LivelinessLostStatus& status)
    {
        std::cout << "on_liveliness_lost" << std::endl;
    }

    virtual void on_publication_matched (
        dds::pub::DataWriter<Foo::Bar>& writer,
        const dds::core::status::PublicationMatchedStatus& status)
    {
        std::cout << "on_publication_matched" << std::endl;
    }
};

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

See also

for more information: Data Writer

See also

for more information: Listener information

Subclassed by dds::pub::NoOpDataWriterListener< T >

template<typename T> class NoOpDataWriterListener : public virtual dds::pub::DataWriterListener<T>¶

#include <DataWriterListener.hpp>

DataWriter events Listener.

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

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

See also

dds::pub::DataWriterListener

class PublisherListener : public virtual dds::pub::AnyDataWriterListener ¶

#include <PublisherListener.hpp>

Publisher events Listener.

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

The PublisherListener 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 PublisherListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::pub::PublisherListener
{
public:
    virtual void on_offered_deadline_missed (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::OfferedDeadlineMissedStatus& status)
    {
        std::cout << "on_offered_deadline_missed" << std::endl;
    }

    virtual void on_offered_incompatible_qos (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::OfferedIncompatibleQosStatus& status)
    {
        std::cout << "on_offered_incompatible_qos" << std::endl;
    }

    virtual void on_liveliness_lost (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::LivelinessLostStatus& status)
    {
        std::cout << "on_liveliness_lost" << std::endl;
    }

    virtual void on_publication_matched (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::PublicationMatchedStatus& status)
    {
        std::cout << "on_publication_matched" << std::endl;
    }
};

// Create Publisher with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::pub::Publisher publisher(participant,
                              participant.default_publisher_qos(),
                              new ExampleListener(),
                              dds::core::status::StatusMask::all());

See also

for more information: Publisher

See also

for more information: Listener information

Subclassed by dds::domain::DomainParticipantListener, dds::pub::NoOpPublisherListener

class NoOpPublisherListener : public virtual dds::pub::PublisherListener, public virtual dds::pub::NoOpAnyDataWriterListener ¶

#include <PublisherListener.hpp>

Publisher events Listener.

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

class ExampleListener : public virtual dds::pub::NoOpPublisherListener
{
   // Not necessary to implement any Listener operations.
};

See also

dds::pub::PublisherListener

Subclassed by dds::domain::NoOpDomainParticipantListener

template<typename DELEGATE> class TAnyDataWriter : public dds::core::TEntity<DELEGATE>¶

#include <TAnyDataWriter.hpp>

Typeless base class for the typed DataWriter.

DataWriters are created type specific (fi DataWriter<Foo::Bar> writer). However, there are many places in the API (and possibly application) where the type can not be known while still some DataWriter

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

Main examples in the API that need typeless

DataWriter are: Publisher, PublisherListener and DomainParticipantListener.

template<typename DELEGATE> class TCoherentSet : public dds::core::Value<DELEGATE>¶

#include <TCoherentSet.hpp>

Class for RAII way of beginning/ending coherent publication sets.

A coherent set is a set of modifications that must be propagated in such a way that they are interpreted at the receivers’ side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.

A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the Publisher or one of its Subscribers may change, a late-joining DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.

The support for coherent changes enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen atomically by the readers. This is useful in cases where the values are inter-related. For example, if there are two data instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in such a way the reader can see both together; otherwise, it may, for example, erroneously interpret that the aircraft is on a collision course.

See also

for more information: Publication

See also

dds::pub::Publisher

template<typename DELEGATE> class TPublisher : public dds::core::TEntity<DELEGATE>¶

#include <TPublisher.hpp>

The Publisher acts on the behalf of one or several DataWriter objects that belong to it.

When it is informed of a change to the data associated with one of its DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the Publisher and the DataWriter.

See also

for more information: Publisher

template<typename DELEGATE> class TSuspendedPublication : public dds::core::Value<DELEGATE>¶

#include <TSuspendedPublication.hpp>

Class for RAII way of suspending/resuming publication.

Suspended publication indicates to the Service that the application is about to make multiple modifications using DataWriter objects belonging to the Publisher.

It is a hint to the Service so it can optimize its performance by, e.g., holding the dissemination of the modifications and then batching them. It is not required that the Service use this hint in any way.

When a Suspended publication is started, it must be matched by a corresponding call to SuspendedPublication::resume() or the destruction of the SuspendedPublication object (which is an implicit resume), indicating that the set of modifications has completed. If the Publisher is deleted before the resume, any suspended updates yet to be published will be discarded.

This object suspends the publication of all DataWriter objects contained by the given Publisher. The data written, disposed or unregistered by a DataWriter is stored in the history buffer of the DataWriter and therefore, depending on its QoS settings, the following operations may block (see the operation descriptions for more information):

dds::pub::DataWriter.write (and its overloaded counterparts).
dds::pub::DataWriter.operator<< (and its overloaded counterparts).
dds::pub::DataWriter.unregister_instance (and its overloaded counterparts).
dds::pub::DataWriter.dispose_instance (and its overloaded counterparts).

See also

for more information: Publication

See also

dds::pub::Publisher

namespace detail¶

Typedefs

typedef dds::pub::TAnyDataWriter<org::eclipse::cyclonedds::pub::AnyDataWriterDelegate> AnyDataWriter¶

typedef dds::pub::TCoherentSet<org::eclipse::cyclonedds::pub::CoherentSetDelegate> CoherentSet¶

typedef dds::pub::TPublisher<org::eclipse::cyclonedds::pub::PublisherDelegate> Publisher¶

typedef dds::pub::TSuspendedPublication<org::eclipse::cyclonedds::pub::SuspendedPublicationDelegate> SuspendedPublication¶

template<typename T> class DataWriter : public org::eclipse::cyclonedds::pub::AnyDataWriterDelegate¶

Private Members

dds::pub::Publisher pub_¶

dds::topic::Topic<T> topic_¶

namespace qos¶

Typedefs

typedef dds::pub::qos::detail::DataWriterQos DataWriterQos¶

typedef dds::pub::qos::detail::PublisherQos PublisherQos¶

class DataWriterQos : public dds::core::EntityQos<org::eclipse::cyclonedds::pub::qos::DataWriterQosDelegate>

#include <DataWriterQos.hpp>

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

A QosPolicy can be set when the DataWriter is created or modified with the set qos operation. Both operations take the DataWriterQos 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::UserData	Additional information (info)	UserData::UserData(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::OwnershipStrength	Ownership strenght (info)	OwnershipStrength::OwnershipStrength(0)
dds::core::policy::WriterDataLifecycle	Dispose with unregister or not (info)	WriterDataLifecycle::AutoDisposeUnregisteredInstances()
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
dds::core::policy::WriterBatching	Writer data batching	dds::core::policy::WriterBatching::DoNotBatchUpdates()

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

See also

for more information: DCPS_QoS

class PublisherQos : public dds::core::EntityQos<org::eclipse::cyclonedds::pub::qos::PublisherQosDelegate>

#include <PublisherQos.hpp>

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

A QosPolicy can be set when the Publisher is created or modified with the set qos operation. Both operations take the PublisherQos 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::Presentation	Data-instance change dependencies (info)	Presentation::InstanceAccessScope(coherent=false, ordered=false)
dds::core::policy::Partition	Active partitions (info)	Partition::Partition(empty)
dds::core::policy::GroupData	Additional information (info)	GroupData::GroupData(empty)
dds::core::policy::EntityFactory	Create enabled (info)	EntityFactory::AutoEnable()

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

See also

for more information: DCPS_QoS

namespace detail¶