Cyclone ISO C++ API Reference Guide
Public Types | Public Member Functions | List of all members
dds::pub::DataWriter< T > Class Template Reference

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

#include "DataWriter.hpp"

Inherits dds::pub::AnyDataWriter.

Public Types

typedef dds::pub::DataWriterListener< T > Listener
 

Public Member Functions

 DataWriter (const dds::pub::Publisher &pub, const ::dds::topic::Topic< T > &topic)
 
 DataWriter (const dds::pub::Publisher &pub, const ::dds::topic::Topic< T > &topic, const dds::pub::qos::DataWriterQos &qos, dds::pub::DataWriterListener< T > *listener=NULL, const dds::core::status::StatusMask &mask=::dds::core::status::StatusMask::none())
 
void assert_liveliness ()
 
void close ()
 
DataWriter & dispose_instance (const ::dds::core::InstanceHandle &i)
 
DataWriter & dispose_instance (const ::dds::core::InstanceHandle &i, const dds::core::Time &timestamp)
 
DataWriter & dispose_instance (const T &key)
 
DataWriter & dispose_instance (const T &key, const dds::core::Time &timestamp)
 
void enable ()
 
const dds::core::InstanceHandle instance_handle () const
 
bool is_nil () const
 
dds::topic::TopicInstance< T > & key_value (dds::topic::TopicInstance< T > &i, const ::dds::core::InstanceHandle &h)
 
T & key_value (T &sample, const ::dds::core::InstanceHandle &h)
 
DataWriterListener< T > * listener () const
 
void listener (DataWriterListener< T > *listener, const ::dds::core::status::StatusMask &mask)
 
const dds::core::status::LivelinessLostStatus liveliness_lost_status ()
 
dds::core::InstanceHandle lookup_instance (const T &key)
 
const dds::core::status::OfferedDeadlineMissedStatus offered_deadline_missed_status ()
 
const dds::core::status::OfferedIncompatibleQosStatus offered_incompatible_qos_status ()
 
bool operator!= (const null_type nil) const
 
template<typename R >
bool operator!= (const R &ref) const
 
DELEGATE * operator-> ()
 
const DELEGATE * operator-> () const
 
DataWriter & operator<< (const ::dds::pub::qos::DataWriterQos &qos)
 
AnyDataWriter & operator<< (const dds::pub::qos::DataWriterQos &qos)
 
DataWriter & operator<< (const std::pair< T, ::dds::core::InstanceHandle > &data)
 
DataWriter & operator<< (const std::pair< T, dds::core::Time > &data)
 
DataWriter & operator<< (const T &data)
 
bool operator== (const null_type) const
 
template<typename R >
bool operator== (const R &ref) const
 
const AnyDataWriter & operator>> (dds::pub::qos::DataWriterQos &qos) const
 
const dds::core::status::PublicationMatchedStatus publication_matched_status ()
 
const dds::pub::Publisher & publisher () const
 
dds::pub::qos::DataWriterQos qos () const
 
void qos (const dds::pub::qos::DataWriterQos &qos)
 
const ::dds::core::InstanceHandle register_instance (const T &key)
 
const ::dds::core::InstanceHandle register_instance (const T &key, const dds::core::Time &timestamp)
 
void retain ()
 
const dds::core::status::StatusMask status_changes ()
 
const dds::topic::Topic< T > & topic () const
 
const dds::topic::TopicDescription & topic_description () const
 
DataWriter & unregister_instance (const ::dds::core::InstanceHandle &i)
 
DataWriter & unregister_instance (const ::dds::core::InstanceHandle &i, const dds::core::Time &timestamp)
 
DataWriter & unregister_instance (const T &key)
 
DataWriter & unregister_instance (const T &key, const dds::core::Time &timestamp)
 
void wait_for_acknowledgments (const dds::core::Duration &timeout)
 
void write (const dds::topic::TopicInstance< T > &i)
 
void write (const dds::topic::TopicInstance< T > &i, const dds::core::Time &timestamp)
 
template<typename FWIterator >
void write (const FWIterator &begin, const FWIterator &end)
 
template<typename FWIterator >
void write (const FWIterator &begin, const FWIterator &end, const dds::core::Time &timestamp)
 
template<typename SamplesFWIterator , typename HandlesFWIterator >
void write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end)
 
template<typename SamplesFWIterator , typename HandlesFWIterator >
void write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end, const dds::core::Time &timestamp)
 
void write (const T &data, const ::dds::core::InstanceHandle &instance, const dds::core::Time &timestamp)
 
void write (const T &sample)
 
void write (const T &sample, const ::dds::core::InstanceHandle &instance)
 
void write (const T &sample, const dds::core::Time &timestamp)
 

Detailed Description

template<typename T>
class dds::pub::DataWriter< T >

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.

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.
// 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
Publication concept
DataWriter concept

Definition at line 89 of file DataWriter.hpp.

Member Typedef Documentation

◆ Listener

template<typename T>
typedef dds::pub::DataWriterListener<T> dds::pub::DataWriter< T >::Listener

Local convenience typedef for dds::pub::DataWriterListener.

Definition at line 96 of file DataWriter.hpp.

Constructor & Destructor Documentation

◆ DataWriter() [1/2]

template<typename T>
dds::pub::DataWriter< T >::DataWriter ( const dds::pub::Publisher &  pub,
const ::dds::topic::Topic< T > &  topic 
)

Create a new DataWriter for the desired Topic, using the given Publisher.

The DataWriter will be created with the QoS values specified on the last successful call to pub.default_datawriter_qos(qos) or, if the call was never made, the default values.

Parameters
pubthe Publisher that will contain this DataWriter
topicthe Topic associated with this DataWriter
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ DataWriter() [2/2]

template<typename T>
dds::pub::DataWriter< T >::DataWriter ( const dds::pub::Publisher &  pub,
const ::dds::topic::Topic< T > &  topic,
const dds::pub::qos::DataWriterQos &  qos,
dds::pub::DataWriterListener< T > *  listener = NULL,
const dds::core::status::StatusMask &  mask = ::dds::core::status::StatusMask::none() 
)

Create a new DataWriter for the desired Topic, using the given Publisher and DataWriterQos and attaches the optionally specified DataWriterListener to it.

QoS
A possible application pattern to construct the DataWriterQos for the DataWriter is to:

// 1) Retrieve the QosPolicy settings on the associated Topic
dds::topic::qos::TopicQos topicQos = topic.qos();
// 2) Retrieve the default DataWriterQos from the related Publisher
dds::pub::qos::DataWriterQos writerQos = publisher.default_datawriter_qos();
// 3) Combine those two lists of QosPolicy settings by overwriting DataWriterQos
// policies that are also present TopicQos
writerQos = topicQos;
// 4) Selectively modify QosPolicy settings as desired.
writerQos << dds::core::policy::WriterDataLifecycle::ManuallyDisposeUnregisteredInstances();
// 5) Use the resulting QoS to construct the DataWriter.
dds::pub::DataWriter<Foo::Bar> writer(publisher, topic, writerQos);

Listener
The following statuses are applicable to the DataWriterListener:

See listener concept, communication status and communication propagation for more information.

Parameters
pubthe Publisher that will contain this DataWriter
topicthe Topic associated with this DataWriter
qosthe DataWriter qos.
listenerthe DataWriter listener.
maskthe listener event mask.
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::InconsistentPolicyErrorThe parameter qos contains conflicting QosPolicy settings.

Member Function Documentation

◆ assert_liveliness()

void dds::pub::AnyDataWriter::assert_liveliness ( )
inherited

This operation asserts the liveliness for the DataWriter.

This operation will manually assert the liveliness for the DataWriter. This way, the Data Distribution Service is informed that the corresponding DataWriter is still alive. This operation is used in combination with the Liveliness QosPolicy set to Liveliness::ManualByParticipant or Liveliness::ManualByTopic.

Writing data via the write operation of a DataWriter will assert the liveliness on the DataWriter itself and its containing DomainParticipant. Therefore, assert_liveliness is only needed when not writing regularly.

The liveliness should be asserted by the application, depending on the LivelinessQosPolicy. Asserting the liveliness for this DataWriter can also be achieved by asserting the liveliness to the DomainParticipant.

Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe entity has not yet been enabled.

◆ close()

void dds::core::Entity::close ( )
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:

  • Any object to which the application has a direct reference is still in use.
  • Any object that has been explicitly retained is still in use
  • The creator of any object that is still in use is itself still in use.
Returns
void

◆ dispose_instance() [1/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::dispose_instance ( const ::dds::core::InstanceHandle &  i)

This operation requests the Data Distribution Service to mark the instance for deletion.

Detailed Description
This operation requests the Data Distribution Service to mark the instance for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DataReader and, dependent on the QosPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their dds::sub::status::InstanceState to not_alive_disposed state.

When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Effects on DataReaders
Actual deletion of the instance administration in a connected DataReader will be postponed until the following conditions have been met:

  • the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it.
    • A DataWriter can register an instance explicitly by using the special register_instance operations.
    • A DataWriter can register an instance implicitly by using no or the default (nil) InstanceHandle in any of the other DataWriter operations.
    • A DataWriter can unregister an instance explicitly by using one of the special unregister_instance operations.
    • A DataWriter will unregister all its contained instances implicitly when it is deleted.
    • When a DataReader detects a loss of liveliness in one of its connected DataWriters, it will consider all instances registered by that DataWriter as being implicitly unregistered.
  • and the application must have consumed all samples belonging to the instance, either implicitly or explicitly.
    • An application can consume samples explicitly by invoking the take operation, or one of its variants, on its DataReaders.
    • The DataReader can consume disposed samples implicitly when the autopurge_disposed_samples_delay of the ReaderData Lifecycle QosPolicy has expired.

The DataReader may also remove instances that haven’t been disposed first: this happens when the autopurge_nowriter_samples_delay of the ReaderDataLifecycle QosPolicy has expired after the instance is considered unregistered by all connected DataWriters (i.e. when it has a InstanceState of not_alive_no_writers.
See also dds::core::policy::ReaderDataLifecycle QosPolicy.

Effects on Transient/Persistent Stores
Actual deletion of the instance administration in the connected Transient and Persistent stores will be postponed until the following conditions have been met:

  • the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it. (See above.)
  • and the period of time specified by the service_cleanup_delay attribute in the DurabilityServiceQosPolicy on the Topic must have elapsed after the instance is considered unregistered by all connected DataWriters.

See also dds::core::policy::Durability QosPolicy.

Instance Handle
If handle is not nil, it must correspond to the value returned by "register_instance" or "register_instance_w_timestamp" when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently.

Blocking
If the dds::core::policy::History QosPolicy is set to KEEP_ALL, the dispose operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the dds::core::policy::ResourceLimits, is exceeded. In case the synchronous attribute value of the dds::core::policy::Reliability is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the dds::core::policy::Reliability configures the maximum time the dispose operation may block (either waiting for space to become available or data to be acknowledged). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the dispose operation will fail and throw TimeoutError.

Parameters
ithe instance to dispose
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ dispose_instance() [2/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::dispose_instance ( const ::dds::core::InstanceHandle &  i,
const dds::core::Time &  timestamp 
)

This operation requests the Data Distribution Service to mark the instance for deletion and provides a value for the source_timestamp explicitly.

Detailed Description
This operation requests the Data Distribution Service to mark the instance for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DataReader and, dependent on the QosPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their dds::sub::status::InstanceState to not_alive_disposed state.

When this operation is used, the application explicitly supplies the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Effects
This operation effects DataReaders and effects Transient/Persistent Stores.

Instance Handle
If handle is not nil, it must correspond to the value returned by "register_instance" or "register_instance_w_timestamp" when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently.

Blocking
This operation can be blocked (see dispose blocking).

Parameters
ithe instance to dispose
timestampthe timestamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ dispose_instance() [3/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::dispose_instance ( const T &  key)

This operation requests the Data Distribution Service to mark the instance for deletion.

Detailed Description
This operation requests the Data Distribution Service to mark the instance for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DataReader and, dependent on the QosPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their dds::sub::status::InstanceState to not_alive_disposed state.

When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Effects
This operation effects DataReaders and effects Transient/Persistent Stores.

Instance
The instance is identified by the key fields of the given typed data sample, instead of an InstanceHandle.

Blocking
This operation can be blocked (see dispose blocking).

Parameters
keysample of the instance to dispose
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ dispose_instance() [4/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::dispose_instance ( const T &  key,
const dds::core::Time &  timestamp 
)

This operation requests the Data Distribution Service to mark the instance for deletion and provides a value for the source_timestamp explicitly.

Detailed Description
This operation requests the Data Distribution Service to mark the instance for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DataReader and, dependent on the QosPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their dds::sub::status::InstanceState to not_alive_disposed state.

When this operation is used, the application explicitly supplies the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Effects
This operation effects DataReaders and effects Transient/Persistent Stores.

Instance
The instance is identified by the key fields of the given typed data sample, instead of an InstanceHandle.

Blocking
This operation can be blocked (see dispose blocking).

Parameters
keysample of the instance to dispose
timestampthe timestamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ enable()

void dds::core::Entity::enable ( )
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::domain::qos::DomainParticipantQos dpq;
dpq << dds::core::policy::EntityFactory::ManuallyEnable();
...
dds::sub::DataReader<Foo::Bar> dr(dp, topic, drqos);
dr.enable();
Returns
void
Exceptions
dds::core::PreconditionNotMetErrorEntities' factory is not enabled.

◆ instance_handle()

const dds::core::InstanceHandle dds::core::Entity::instance_handle ( ) const
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()).

Returns
dds::core::InstanceHandle Result value is the instance_handle of the built-in topic sample that represents the state of this Entity.

◆ is_nil()

template<typename DELEGATE>
bool dds::core::Reference< DELEGATE >::is_nil ( ) const
inherited

Check if the referenced object is nil.

In other words, check if the reference is pointing to a null object.

Returns
true if the referenced object is null.

◆ key_value() [1/2]

template<typename T>
dds::topic::TopicInstance<T>& dds::pub::DataWriter< T >::key_value ( dds::topic::TopicInstance< T > &  i,
const ::dds::core::InstanceHandle &  h 
)

This operation retrieves the key value of a specific instance.

This operation can be used to retrieve the instance key that corresponds to an instance_handle. The operation will only fill the fields that form the key inside the sample instance.

This operation may raise a InvalidArgumentError exception if the InstanceHandle does not correspond to an existing data-object known to the DataWriter. If the implementation is not able to check invalid handles, then the result in this situation is unspecified.

The TopicInstance is added as parameter to be able to overload this operation.

Parameters
[out]iA topic instance to set the handle and sample key fields of
[in]hThe instance handle
Returns
The given topic instance with the handle and key fields set
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::InvalidArgumentErrorThe InstanceHandle is not a valid handle.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.

◆ key_value() [2/2]

template<typename T>
T& dds::pub::DataWriter< T >::key_value ( T &  sample,
const ::dds::core::InstanceHandle &  h 
)

This operation retrieves the key value of a specific instance.

This operation can be used to retrieve the instance key that corresponds to an instance_handle. The operation will only fill the fields that form the key inside the sample instance.

This operation may raise a InvalidArgumentError exception if the InstanceHandle does not correspond to an existing data-object known to the DataWriter. If the implementation is not able to check invalid handles, then the result in this situation is unspecified.

The Sample is added as parameter to be able to overload this operation.

Parameters
[out]sampleA sample to set the key fields of
[in]hThe instance handle
Returns
The given sample with the key fields set
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::InvalidArgumentErrorThe InstanceHandle is not a valid handle.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.

◆ listener() [1/2]

template<typename T>
DataWriterListener<T>* dds::pub::DataWriter< T >::listener ( ) const

Get the listener of this DataWriter.

See also listener information.

Returns
the listener
Exceptions
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.

◆ listener() [2/2]

template<typename T>
void dds::pub::DataWriter< T >::listener ( DataWriterListener< T > *  listener,
const ::dds::core::status::StatusMask &  mask 
)

Register a listener with the DataWriter.

This operation attaches a DataWriterListener to the DataWriter. Only one DataWriterListener can be attached to each DataWriter. If a DataWriterListener 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 DataWriterListener 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 DataWriterListener:

Be aware that the PUBLICATION_MATCHED_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. 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 this case the operation will throw UnsupportedError.

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 DataWriterListener, the PublisherListener of the containing Publisher is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the PublisherListener of the containing Publisher and a DataWriter specific behaviour when needed. In case the communication status is not activated in the mask of the PublisherListener as well, the communication status will be propagated to the DomainParticipantListener of the containing DomainParticipant. In case the DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.

See also listener information.

Parameters
listenerthe listener
maskthe mask defining the events for which the listener will be notified.
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::UnsupportedErrorA status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ liveliness_lost_status()

const dds::core::status::LivelinessLostStatus dds::pub::AnyDataWriter::liveliness_lost_status ( )
inherited

This operation obtains the LivelinessLostStatus object of the DataWriter.

The LivelinessLostStatus contains the information whether the liveliness (that the DataWriter has committed through its Liveliness QosPolicy) was respected. This means that the status represents whether the DataWriter failed to actively signal its liveliness within the offered liveliness period. If the liveliness is lost, the DataReader objects will consider the DataWriter as no longer “alive”.

The LivelinessLostStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns
the LivelinessLostStatus
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ lookup_instance()

template<typename T>
dds::core::InstanceHandle dds::pub::DataWriter< T >::lookup_instance ( const T &  key)

This operation returns the value of the instance handle which corresponds to the instance_data.

The instance_data parameter is only used for the purpose of examining the fields that define the key. The instance handle can be used in any write, dispose or unregister operations (or their time stamped variants) that operate on a specific instance. Note that DataWriter instance handles are local, and are not interchangeable with DataReader instance handles nor with instance handles of an other DataWriter.

This operation does not register the instance in question. If the instance has not been previously registered or if for any other reason the Service is unable to provide an instance handle, the Service will return the default nil handle (InstanceHandle.is_nil() == true).

Parameters
keythe sample
Returns
the instance handle
Exceptions
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.

◆ offered_deadline_missed_status()

const dds::core::status::OfferedDeadlineMissedStatus dds::pub::AnyDataWriter::offered_deadline_missed_status ( )
inherited

This operation obtains the OfferedDeadlineMissedStatus object of the DataWriter.

The OfferedDeadlineMissedStatus contains the information whether the deadline (that the DataWriter has committed through its Deadline QosPolicy) was respected for each instance.

The OfferedDeadlineMissedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns
the OfferedDeadlineMissedStatus
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ offered_incompatible_qos_status()

const dds::core::status::OfferedIncompatibleQosStatus dds::pub::AnyDataWriter::offered_incompatible_qos_status ( )
inherited

This operation obtains the OfferedIncompatibleQosStatus object of the DataWriter.

The OfferedIncompatibleQosStatus contains the information whether a QosPolicy setting was incompatible with the requested QosPolicy setting.

This means that the status represents whether a DataReader object has been discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter.

The OfferedIncompatibleQosStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns
the OfferedIncompatibleQosStatus
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ operator!=() [1/2]

template<typename DELEGATE>
bool dds::core::Reference< DELEGATE >::operator!= ( const null_type  nil) const
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:

if (r != dds::core::null) {
// Use the dds reference object r
}
Returns
true if this reference is not null.

◆ operator!=() [2/2]

template<typename DELEGATE>
template<typename R >
bool dds::core::Reference< DELEGATE >::operator!= ( const R &  ref) const
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.

Parameters
refthe other Reference object
Returns
true when not equal

◆ operator->() [1/2]

template<typename DELEGATE>
DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( )
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:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();
Returns
a reference to delegate.

◆ operator->() [2/2]

template<typename DELEGATE>
const DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( ) const
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:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();
Returns
a reference to delegate.

◆ operator<<() [1/5]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::operator<< ( const ::dds::pub::qos::DataWriterQos &  qos)

This operation replaces the existing set of QosPolicy settings for a DataWriter.

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 DataWriter, which can only be set before the DataWriter 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.

Parameters
qosthe qos
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::ImmutablePolicyErrorThe parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataWriter.
dds::core::InconsistentPolicyErrorThe parameter qos contains conflicting QosPolicy settings,

◆ operator<<() [2/5]

AnyDataWriter& dds::pub::AnyDataWriter::operator<< ( const dds::pub::qos::DataWriterQos &  qos)
inherited

This operation replaces the existing set of QosPolicy settings for a DataWriter.

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 DataWriter, which can only be set before the DataWriter 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.

Parameters
qosthe qos
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::ImmutablePolicyErrorThe parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataWriter.
dds::core::InconsistentPolicyErrorThe parameter qos contains conflicting QosPolicy settings,

◆ operator<<() [3/5]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::operator<< ( const std::pair< T, ::dds::core::InstanceHandle > &  data)

This operation modifies the value of a data instance.

Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Before writing data to an instance, the instance may be registered with the "register_instance" or "register_instance_w_timestamp" The handle returned by one of the register_instance operations can be supplied to the parameter handle of the write operation. However, it is also possible to supply a default InstanceHandle (InstanceHandle.is_nil() == true), which means that the identity of the instance is automatically deduced from the instance_data (identified by the key).

Instance Handle
The default InstanceHandle (InstanceHandle.is_nil() == true) can be used for the parameter handle. This indicates the identity of the instance is automatically deduced from the instance_data (by means of the key).

If handle is not nil, it must correspond to the value returned by "register_instance" or "register_instance_w_timestamp" when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently.
If there is no correspondence between handle and sample, the result of the operation is unspecified.

Blocking
This operation can be blocked (see write blocking).

Parameters
samplethe sample to be written
instancethe handle representing the instance written
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ operator<<() [4/5]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::operator<< ( const std::pair< T, dds::core::Time > &  data)

This operation modifies the value of a data instance and provides a value for the source_timestamp explicitly.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Blocking
This operation can be blocked (see write blocking).

Parameters
samplethe sample to be written
timestampthe timestamp used for this sample
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ operator<<() [5/5]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::operator<< ( const T &  data)

This operation modifies the value of a data instance.

Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Blocking
If the dds::core::policy::History QosPolicy is set to KEEP_ALL, the write operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the dds::core::policy::ResourceLimits, is exceeded. In case the synchronous attribute value of the dds::core::policy::Reliability is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the dds::core::policy::Reliability configures the maximum time the write operation may block (either waiting for space to become available or data to be acknowledged). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the write operation will fail and throw TimeoutError.

Parameters
samplethe sample to be written
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ operator==() [1/2]

template<typename DELEGATE>
bool dds::core::Reference< DELEGATE >::operator== ( const  null_type) const
inherited

Special operator== used to check if this reference object equals the dds::core::null reference.

The null-check can be done like this:

if (r == dds::core::null) {
// Do not use the dds reference object r in its current state
}
Returns
true if this reference is null.

◆ operator==() [2/2]

template<typename DELEGATE>
template<typename R >
bool dds::core::Reference< DELEGATE >::operator== ( const R &  ref) const
inherited

Compares two Reference objects and returns true if they are equal.

Equality is based on the referential equality of the object being pointed.

Parameters
refthe other Reference object
Returns
true when equal

◆ operator>>()

const AnyDataWriter& dds::pub::AnyDataWriter::operator>> ( dds::pub::qos::DataWriterQos &  qos) const
inherited

Gets the DataWriterQos setting for this instance.

Returns
the qos
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ publication_matched_status()

const dds::core::status::PublicationMatchedStatus dds::pub::AnyDataWriter::publication_matched_status ( )
inherited

This operation obtains the PublicationMatchedStatus object of the DataWriter.

The PublicationMatchedStatus contains the information whether a new match has been discovered for the current publication, or whether an existing match has ceased to exist.

This means that the status represents that either a DataReader object has been discovered by the DataWriter with the same Topic and a compatible Qos, or that a previously discovered DataReader has ceased to be matched to the current DataWriter. A DataReader may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DataWriter or when either the DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the dds::sub::ignore or dds::pub::ignore operations.

The operation may fail if the infrastructure does not hold the information necessary to fill in the PublicationMatchedStatus. 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 this case the operation will throw UnsupportedError.

The PublicationMatchedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns
the PublicationMatchedStatus
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::UnsupportedErrorOpenSplice is configured not to maintain the information about “associated” subscriptions.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ publisher()

const dds::pub::Publisher& dds::pub::AnyDataWriter::publisher ( ) const
inherited

Get the Publisher that owns this DataWriter.

Returns
the Publisher
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.

◆ qos() [1/2]

dds::pub::qos::DataWriterQos dds::pub::AnyDataWriter::qos ( ) const
inherited

Gets the DataWriterQos setting for this instance.

Returns
the qos
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ qos() [2/2]

void dds::pub::AnyDataWriter::qos ( const dds::pub::qos::DataWriterQos &  qos)
inherited

This operation replaces the existing set of QosPolicy settings for a DataWriter.

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 DataWriter, which can only be set before the DataWriter 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.

Parameters
qosthe qos
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::ImmutablePolicyErrorThe parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataWriter.
dds::core::InconsistentPolicyErrorThe parameter qos contains conflicting QosPolicy settings,

◆ register_instance() [1/2]

template<typename T>
const ::dds::core::InstanceHandle dds::pub::DataWriter< T >::register_instance ( const T &  key)

This operation informs the Data Distribution Service that the application will be modifying a particular instance.

Detailed Description
This operation informs the Data Distribution Service that the application will be modifying a particular instance. This operation may be invoked prior to calling any operation that modifies the instance, such as write, unregister_instance or dispose_instance.
When the application does register the instance before modifying, the Data Distribution Service will handle the instance more efficiently. It takes as a parameter (instance_data) an instance (to get the key value) and returns a handle that can be used in successive DataWriter operations. In case of an error, a HANDLE_NIL handle (InstanceHandle.is_nil() == true) is returned.

The explicit use of this operation is optional as the application can directly call the write, unregister_instance or dispose_instance operations without InstanceHandle, which indicate that the sample should be examined to identify the instance.

When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Blocking
If the dds::core::policy::History QosPolicy is set to KEEP_ALL, the register_instance operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the dds::core::policy::ResourceLimits, is exceeded. In case the synchronous attribute value of the dds::core::policy::Reliability is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the dds::core::policy::Reliability configures the maximum time the register operation may block (either waiting for space to become available or data to be acknowledged). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the register_instance operation will fail will return a nil InstanceHandle.

Multiple Calls
If this operation is called for an already registered instance, it just returns the already allocated instance handle. This may be used to look up and retrieve the handle allocated to a given instance.

Key
The key is a typed Sample of which the key fields are set so that the instance can be identified.

Parameters
keythe key of the instance to register
Returns
the instance handle
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.

◆ register_instance() [2/2]

template<typename T>
const ::dds::core::InstanceHandle dds::pub::DataWriter< T >::register_instance ( const T &  key,
const dds::core::Time &  timestamp 
)

This operation will inform the Data Distribution Service that the application will be modifying a particular instance and provides a value for the source_timestamp explicitly.

Detailed Description
This operation informs the Data Distribution Service that the application will be modifying a particular instance. This operation may be invoked prior to calling any operation that modifies the instance, such as write, unregister_instance or dispose_instance.
When the application does register the instance before modifying, the Data Distribution Service will handle the instance more efficiently. It takes as a parameter (instance_data) an instance (to get the key value) and returns a handle that can be used in successive DataWriter operations. In case of an error, a HANDLE_NIL handle (InstanceHandle.is_nil() == true) is returned.

The explicit use of this operation is optional as the application can directly call the write, unregister_instance or dispose_instance operations without InstanceHandle, which indicate that the sample should be examined to identify the instance.

When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Blocking
This operation can be blocked (see register blocking).

Multiple Calls
If this operation is called for an already registered instance, it just returns the already allocated instance handle. The source_timestamp is ignored in that case.

Key
The key is a typed Sample of which the key fields are set so that the instance can be identified.

Parameters
keythe key of the instance to register
timestampthe timestamp used for registration
Returns
the instance handle
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.

◆ retain()

void dds::core::Entity::retain ( )
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.

Returns
void

◆ status_changes()

const dds::core::status::StatusMask dds::core::Entity::status_changes ( )
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.

Returns
dds::core::status::StatusMask a bit mask in which each bit shows which value has changed.

◆ topic()

template<typename T>
const dds::topic::Topic<T>& dds::pub::DataWriter< T >::topic ( ) const

Get the Topic associated with this DataWriter.

Returns
the Topic
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.

◆ topic_description()

const dds::topic::TopicDescription& dds::pub::AnyDataWriter::topic_description ( ) const
inherited

Get the TopicDescription associated with this DataWriter.

Returns
the TopicDescription
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.

◆ unregister_instance() [1/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::unregister_instance ( const ::dds::core::InstanceHandle &  i)

This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more.

Detailed Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more. Therefore, this operation reverses the action of "register_instance" or "register_instance_w_timestamp". register_instance or register_instance_w_timestamp.
It should only be called on an instance that is currently registered. This operation should be called just once per instance, regardless of how many times register_instance was called for that instance.
This operation also indicates that the Data Distribution Service can locally remove all information regarding that instance. The application should not attempt to use the handle, previously allocated to that instance, after calling this operation.

When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Effects
If, after unregistering, the application wants to modify (write or dispose) the instance, it has to register the instance again, or it has to use the default instance handle (InstanceHandle.is_nil() == true). This operation does not indicate that the instance should be deleted (that is the purpose of the dispose. This operation just indicates that the DataWriter no longer has “anything to say” about the instance. If there is no other DataWriter that has registered the instance as well, then the dds::sub::status::InstanceState in all connected DataReaders will be changed to not_alive_no_writers, provided this InstanceState was not already set to not_alive_disposed. In the last case the InstanceState will not be effected by the unregister_instance call, see also Sample info concept.

This operation can affect the ownership of the data instance. If the DataWriter was the exclusive owner of the instance, calling this operation will release that ownership, meaning ownership may be transferred to another, possibly lower strength, DataWriter.

The operation must be called only on registered instances. Otherwise the operation trow PreconditionNotMetError.

Blocking
If the dds::core::policy::History QosPolicy is set to KEEP_ALL, the unregister_instance operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the dds::core::policy::ResourceLimits, is exceeded. In case the synchronous attribute value of the dds::core::policy::Reliability is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the dds::core::policy::Reliability configures the maximum time the unregister operation may block (either waiting for space to become available or data to be acknowledged). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the unregister_instance operation will fail and throw TimeoutError.

Parameters
ithe instance to unregister
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ unregister_instance() [2/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::unregister_instance ( const ::dds::core::InstanceHandle &  i,
const dds::core::Time &  timestamp 
)

This operation will inform the Data Distribution Service that the application will not be modifying a particular instance any more and provides a value for the source_timestamp explicitly.

Detailed Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more. Therefore, this operation reverses the action of "register_instance" or "register_instance_w_timestamp". register_instance or register_instance_w_timestamp.
It should only be called on an instance that is currently registered. This operation should be called just once per instance, regardless of how many times register_instance was called for that instance.
This operation also indicates that the Data Distribution Service can locally remove all information regarding that instance. The application should not attempt to use the handle, previously allocated to that instance, after calling this operation.

When this operation is used, the application itself supplied the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Effects
See here for the unregister effects.

Blocking
This operation can be blocked (see unregister blocking).

Parameters
ithe instance to unregister
timestampthe timestamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ unregister_instance() [3/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::unregister_instance ( const T &  key)

This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more.

Detailed Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more. Therefore, this operation reverses the action of "register_instance" or "register_instance_w_timestamp". register_instance or register_instance_w_timestamp.
It should only be called on an instance that is currently registered. This operation should be called just once per instance, regardless of how many times register_instance was called for that instance.
This operation also indicates that the Data Distribution Service can locally remove all information regarding that instance. The application should not attempt to use the handle, previously allocated to that instance, after calling this operation.

When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Effects
See here for the unregister effects.

Blocking
This operation can be blocked (see unregister blocking).

Instance
The instance is identified by the key fields of the given typed data sample, instead of an InstanceHandle.

Parameters
keysample of the instance to dispose
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ unregister_instance() [4/4]

template<typename T>
DataWriter& dds::pub::DataWriter< T >::unregister_instance ( const T &  key,
const dds::core::Time &  timestamp 
)

This operation will inform the Data Distribution Service that the application will not be modifying a particular instance any more and provides a value for the source_timestamp explicitly.

Detailed Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more. Therefore, this operation reverses the action of "register_instance" or "register_instance_w_timestamp". register_instance or register_instance_w_timestamp.
It should only be called on an instance that is currently registered. This operation should be called just once per instance, regardless of how many times register_instance was called for that instance.
This operation also indicates that the Data Distribution Service can locally remove all information regarding that instance. The application should not attempt to use the handle, previously allocated to that instance, after calling this operation.

When this operation is used, the application itself supplied the value of the source_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

Effects
See here for the unregister effects.

Blocking
This operation can be blocked (see unregister blocking).

Instance
The instance is identified by the key fields of the given typed data sample, instead of an InstanceHandle.

Parameters
keysample of the instance to dispose
timestampthe timestamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ wait_for_acknowledgments()

void dds::pub::AnyDataWriter::wait_for_acknowledgments ( const dds::core::Duration &  timeout)
inherited

This operation blocks the calling thread until either all data written by the DataWriter is acknowledged by the local infrastructure, or until the duration specified by the timeout parameter elapses, whichever happens first.

Data is acknowledged by the local infrastructure when it does not need to be stored in its DataWriter’s local history. When a locally-connected subscription (including the networking service) has no more resources to store incoming samples it will start to reject these samples, resulting in their source DataWriters to store them temporarily in their own local history to be retransmitted at a later moment in time.
In such scenarios, the wait_for_acknowledgments operation will block until the DataWriter has retransmitted its entire history, which is therefore effectively empty, or until the timeout expires, whichever happens first. In the latter case, this operation will throw a TimeoutError.

Be aware that in case the operation returns normally, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered ‘on-route’ and will therefore eventually arrive (unless the networking service itself will crash). In contrast, if a DataWriter would still have data in it’s local history buffer when it terminates, this data is considered ‘lost’.

This operation is intended to be used only if one or more of the contained DataWriters has its ReliabilityQosPolicyKind set to RELIABLE. Otherwise the operation will return immediately, since best-effort DataWriters will never store rejected samples in their local history: they will just drop them and continue business as usual.

Parameters
timeoutthe time out duration
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::TimeoutErrorNot all data is acknowledged before timeout elapsed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.

◆ write() [1/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const dds::topic::TopicInstance< T > &  i)

This operation modifies the value of a data instance.

Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Topic Instance
A TopicInstance encapsulates a sample and its associated instance handle.

Parameters
ithe instance to write
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [2/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const dds::topic::TopicInstance< T > &  i,
const dds::core::Time &  timestamp 
)

This operation modifies the value of a data instance and provides a value for the source_timestamp explicitly.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Topic Instance
A TopicInstance encapsulates a sample and its associated instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
ithe instance to write
timestampthe timestamp for this sample
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [3/10]

template<typename T>
template<typename FWIterator >
void dds::pub::DataWriter< T >::write ( const FWIterator &  begin,
const FWIterator &  end 
)

This operation writes a series of typed Samples or TopicInstances.

Detailed Description
This operation takes a sequence of typed Samples or TopicInstances, which is determined by the template specialization.

It modifies the values of the given data instances. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Topic Instance
A TopicInstance encapsulates a typed Sample and its associated instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
beginAn iterator pointing to the beginning of a sequence of Samples or a sequence of TopicInstances
endAn iterator pointing to the end of a sequence of Samples or a sequence of TopicInstances
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [4/10]

template<typename T>
template<typename FWIterator >
void dds::pub::DataWriter< T >::write ( const FWIterator &  begin,
const FWIterator &  end,
const dds::core::Time &  timestamp 
)

This operation writes a series of typed Samples or TopicInstances and provides a value for the source_timestamp for these samples explicitly.

Detailed Description
This operation takes a sequence of typed Samples or TopicInstances, which is determined by the template specialization.

It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Topic Instance
A TopicInstance encapsulates a sample and its associated instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
beginan iterator pointing to the beginning of a sequence of TopicInstances
endan iterator pointing to the end of a sequence of TopicInstances
timestampthe time stamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [5/10]

template<typename T>
template<typename SamplesFWIterator , typename HandlesFWIterator >
void dds::pub::DataWriter< T >::write ( const SamplesFWIterator &  data_begin,
const SamplesFWIterator &  data_end,
const HandlesFWIterator &  handle_begin,
const HandlesFWIterator &  handle_end 
)

This operation writes a series of typed Samples and their parallel instance handles.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Instance Handle
See write instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
data_beginan iterator pointing to the beginning of a sequence of samples
data_endan iterator pointing to the end of a sequence of samples
handle_beginan iterator pointing to the beginning of a sequence of InstanceHandles
handle_endan iterator pointing to the end of a sequence of InstanceHandles
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [6/10]

template<typename T>
template<typename SamplesFWIterator , typename HandlesFWIterator >
void dds::pub::DataWriter< T >::write ( const SamplesFWIterator &  data_begin,
const SamplesFWIterator &  data_end,
const HandlesFWIterator &  handle_begin,
const HandlesFWIterator &  handle_end,
const dds::core::Time &  timestamp 
)

This operation writes a series of typed Samples or TopicInstances and provides a value for the source_timestamp for these samples explicitly.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Instance Handle
See write instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
data_beginan iterator pointing to the beginning of a sequence of samples
data_endan iterator pointing to the end of a sequence of samples
handle_beginan iterator pointing to the beginning of a sequence of InstanceHandles
handle_endan iterator pointing to the end of a sequence of InstanceHandles
timestampthe time stamp
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [7/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const T &  data,
const ::dds::core::InstanceHandle &  instance,
const dds::core::Time &  timestamp 
)

This operation modifies the value of a data instance and provides a value for the source_timestamp explicitly.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Instance Handle
See write instance handle.

Blocking
This operation can be blocked (see write blocking).

Parameters
samplethe sample to be written
instancethe handle representing the instance written
timestampthe timestamp to use for this sample
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [8/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const T &  sample)

This operation modifies the value of a data instance.

Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Blocking
If the dds::core::policy::History QosPolicy is set to KEEP_ALL, the write operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the dds::core::policy::ResourceLimits, is exceeded. In case the synchronous attribute value of the dds::core::policy::Reliability is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the dds::core::policy::Reliability configures the maximum time the write operation may block (either waiting for space to become available or data to be acknowledged). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the write operation will fail and throw TimeoutError.

Parameters
samplethe sample to be written
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [9/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const T &  sample,
const ::dds::core::InstanceHandle &  instance 
)

This operation modifies the value of a data instance.

Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Before writing data to an instance, the instance may be registered with the "register_instance" or "register_instance_w_timestamp" The handle returned by one of the register_instance operations can be supplied to the parameter handle of the write operation. However, it is also possible to supply a default InstanceHandle (InstanceHandle.is_nil() == true), which means that the identity of the instance is automatically deduced from the instance_data (identified by the key).

Instance Handle
The default InstanceHandle (InstanceHandle.is_nil() == true) can be used for the parameter handle. This indicates the identity of the instance is automatically deduced from the instance_data (by means of the key).

If handle is not nil, it must correspond to the value returned by "register_instance" or "register_instance_w_timestamp" when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently.
If there is no correspondence between handle and sample, the result of the operation is unspecified.

Blocking
This operation can be blocked (see write blocking).

Parameters
samplethe sample to be written
instancethe handle representing the instance written
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataWriter.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.

◆ write() [10/10]

template<typename T>
void dds::pub::DataWriter< T >::write ( const T &  sample,
const dds::core::Time &  timestamp 
)

This operation modifies the value of a data instance and provides a value for the source_timestamp explicitly.

Detailed Description
It modifies the values of the given data instances. When this operation is used, the application provides the value for the parameter source_timestamp that is made available to connected DataReader objects.
This timestamp is important for the interpretation of the dds::core::policy::DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Blocking
This operation can be blocked (see write blocking).

Parameters
samplethe sample to be written
timestampthe timestamp used for this sample
Exceptions
dds::core::ErrorAn internal error has occurred.
dds::core::NullReferenceErrorThe entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedErrorThe entity has already been closed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledErrorThe DataWriter has not yet been enabled.
dds::core::TimeoutErrorEither the current action overflowed the available resources as specified by the combination of the Reliability QosPolicy, History QosPolicy and ResourceLimits QosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max_blocking_time of the Reliability QosPolicy elapsed.
The documentation for this class was generated from the following file:
dds::pub::qos::DataWriterQos
This object provides the basic mechanism for an application to specify Quality of Service attributes ...
Definition: DataWriterQos.hpp:68
dds::pub::AnyDataWriter::publisher
const dds::pub::Publisher & publisher() const
dds::topic::qos::TopicQos
This struct provides the basic mechanism for an application to specify Quality of Service attributes ...
Definition: TopicQos.hpp:67
dds::pub::Publisher
The Publisher acts on the behalf of one or several DataWriter objects that belong to it.
Definition: Publisher.hpp:55
dds::pub::DataWriter
DataWriter allows the application to set the value of the sample to be published under a given Topic.
Definition: DataWriter.hpp:89
dds::domain::qos::DomainParticipantQos
This class provides the basic mechanism for an application to specify Quality of Service attributes f...
Definition: DomainParticipantQos.hpp:58
dds::core::policy::WriterDataLifecycle::ManuallyDisposeUnregisteredInstances
static WriterDataLifecycle ManuallyDisposeUnregisteredInstances()
dds::core::policy::EntityFactory::ManuallyEnable
static EntityFactory ManuallyEnable()
dds::pub::Publisher::default_datawriter_qos
Publisher & default_datawriter_qos(const dds::pub::qos::DataWriterQos &qos)
dds::topic::Topic
Topic is the most basic description of the data to be published and subscribed.
Definition: Topic.hpp:36
dds::pub::DataWriter::topic
const dds::topic::Topic< T > & topic() const
dds::domain::DomainParticipant
A DomainParticipant represents the local membership of the application in a Domain.
Definition: DomainParticipant.hpp:65