Template Class DataWriter

Inheritance Relationships

Base Type

  • public TAnyDataWriter< detail::DataWriter >

Derived Types

  • public DDS::BytesDataWriter (exhale_interface_interfaceDDS_1_1BytesDataWriter)

  • public DDS::KeyedBytesDataWriter (exhale_interface_interfaceDDS_1_1KeyedBytesDataWriter)

  • public DDS::KeyedStringDataWriter (exhale_interface_interfaceDDS_1_1KeyedStringDataWriter)

  • public DDS::StringDataWriter (exhale_interface_interfaceDDS_1_1StringDataWriter)

Class Documentation

template<typename T>
class DataWriter : public TAnyDataWriter<detail::DataWriter>

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

A DataWriter is attached to exactly one Publisher.

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

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

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

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

// Default creation of a DataWriter
dds::domain::DomainParticipant participant(org::opensplice::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

See also

DataWriter concept

Note

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

Subclassed by DDS::BytesDataWriter, DDS::KeyedBytesDataWriter, DDS::KeyedStringDataWriter, DDS::StringDataWriter

Public Types

using Listener = DataWriterListener<T>

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

Public Functions

OMG_DDS_REF_TYPE_PROTECTED_DC (DataWriter, dds::pub::TAnyDataWriter, detail::DataWriter) OMG_DDS_IMPLICIT_REF_BASE(DataWriter) OMG_DDS_API void write(const T &sample)

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.

Implicit Publisher It is expected to provide a Publisher when creating a DataWriter. However, it is allowed to provide dds::core::null. When dds::core::null is provided, then an implicit Publisher is created with a default QoS and the DomainParticipant from the provided Topic.

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

Restictions on QoS policies

Parameters

  • pub – the Publisher that will contain this DataWriter (or dds::core::null for an implicit publisher)

  • topic – the Topic associated with this DataWriter

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation. Create a new DataWriter for the desired Topic, using the given Publisher and DataWriterQos and attaches the optionally specified DataWriterListener to it.

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

  • sample – the sample to be written

  • timestamp – the timestamp used for this sample

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::TimeoutError – Either 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.

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

  • sample – the sample to be written

  • instance – the handle representing the instance written

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

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

  • sample – the sample to be written

  • instance – the handle representing the instance written

  • timestamp – the timestamp to use for this sample

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

template<typename FWIterator> OMG_DDS_API void write (const FWIterator &begin, const FWIterator &end)

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.

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

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

  • i – the instance to write

  • i – the instance to write

  • timestamp – the timestamp for this sample

  • begin – An iterator pointing to the beginning of a sequence of Samples or a sequence of TopicInstances

  • end – An iterator pointing to the end of a sequence of Samples or a sequence of TopicInstances

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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. This operation modifies the value of a data instance and provides a value for the source_timestamp explicitly.

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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. This operation writes a series of typed Samples or TopicInstances.

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

template<typename FWIterator> OMG_DDS_API void 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

  • begin – an iterator pointing to the beginning of a sequence of TopicInstances

  • end – an iterator pointing to the end of a sequence of TopicInstances

  • timestamp – the time stamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

template<typename SamplesFWIterator, typename HandlesFWIterator> OMG_DDS_API void 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_begin – an iterator pointing to the beginning of a sequence of samples

  • data_end – an iterator pointing to the end of a sequence of samples

  • handle_begin – an iterator pointing to the beginning of a sequence of InstanceHandles

  • handle_end – an iterator pointing to the end of a sequence of InstanceHandles

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

template<typename SamplesFWIterator, typename HandlesFWIterator> OMG_DDS_API void 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_begin – an iterator pointing to the beginning of a sequence of samples

  • data_end – an iterator pointing to the end of a sequence of samples

  • handle_begin – an iterator pointing to the beginning of a sequence of InstanceHandles

  • handle_end – an iterator pointing to the end of a sequence of InstanceHandles

  • timestamp – the time stamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

OMG_DDS_API DataWriter & operator<< (const T &data)
OMG_DDS_API DataWriter & operator<< (const std::pair< T, dds::core::Time > &data)
OMG_DDS_API DataWriter & operator<< (const std::pair< T, ::dds::core::InstanceHandle > &data)
OMG_DDS_APIconst::dds::core::InstanceHandle 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

key – the key of the instance to register

Throws
Returns

the instance handle

OMG_DDS_APIconst::dds::core::InstanceHandle 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

  • key – the key of the instance to register

  • timestamp – the timestamp used for registration

Throws
Returns

the instance handle

OMG_DDS_API DataWriter & 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

i – the instance to unregister

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

  • i – the instance to unregister

  • timestamp – the timestamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

key – sample of the instance to dispose

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

  • key – sample of the instance to dispose

  • timestamp – the timestamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

i – the instance to dispose

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

  • i – the instance to dispose

  • timestamp – the timestamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

key – sample of the instance to dispose

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API DataWriter & 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

  • key – sample of the instance to dispose

  • timestamp – the timestamp

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::NotEnabledError – The DataWriter has not yet been enabled.

  • dds::core::PreconditionNotMetError – The handle has not been registered with this DataWriter.

  • dds::core::TimeoutError – Either 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.

Returns

a reference to the DataWriter

OMG_DDS_API 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 TopicInstance is added as parameter to be able to overload this operation.

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

  • i – [out] A topic instance to set the handle and sample key fields of

  • h – [in] The instance handle

  • sample – [out] A sample to set the key fields of

  • h – [in] The instance handle

Throws
Returns

The given topic instance with the handle and key fields set

Returns

The given sample with the key fields set

OMG_DDS_API dds::core::InstanceHandle 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

key – the sample

Throws
Returns

the instance handle

OMG_DDS_API DataWriter & operator<< (const 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

qos – the qos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

  • dds::core::ImmutablePolicyError – The parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataWriter.

  • dds::core::InconsistentPolicyError – The parameter qos contains conflicting QosPolicy settings,

OMG_DDS_API void listener (DataWriterListener< T > *listener, const ::dds::core::status::StatusMask &mask)

Get the Topic associated with this 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.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed. Register a listener with the DataWriter.

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::UnsupportedError – A status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the Topic

Parameters

  • listener – the listener

  • mask – the mask defining the events for which the listener will be notified.

OMG_DDS_API DataWriterListener< T > * listener () const

Get the listener of this DataWriter.

See also listener information.

Throws

dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

Returns

the listener