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
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
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. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will throw UnsupportedError.

See also DCPS_Builtin_Topics and DCPS_Builtin_Topics_SubscriptionData.

Parameters
Throws
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

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 >

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

See also

dds::domain::NoOpDomainParticipantListener

Subclassed by dds::pub::NoOpPublisherListener

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

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

template<typename DELEGATE>
class TAnyDataWriter
#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
#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
#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
#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

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

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