dds::pub::AnyDataWriter Class Reference

Typeless base class for the typed DataWriter. More...

#include "AnyDataWriter.hpp"

Inherits dds::core::Entity.

Inherited by dds::pub::DataWriter< T >.

Public Member Functions
void	assert_liveliness ()
void	close ()
void	enable ()
const dds::core::InstanceHandle	instance_handle () const
bool	is_nil () const
const dds::core::status::LivelinessLostStatus	liveliness_lost_status ()
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
AnyDataWriter &	operator<< (const dds::pub::qos::DataWriterQos &qos)
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)
void	retain ()
const dds::core::status::StatusMask	status_changes ()
const dds::topic::TopicDescription &	topic_description () const
void	wait_for_acknowledgments (const dds::core::Duration &timeout)

Detailed Description

Typeless base class for the typed DataWriter.

DataWriters are created type specific (fi DataWriter<Foo::Bar> writer). However, there are many places in the API (and possibly application) where the type can not be known while still some DataWriter has to be passed around, stored or even typeless functionality called.
Main examples in the API that need typeless DataWriter are: Publisher, PublisherListener and DomainParticipantListener.

Definition at line 48 of file AnyDataWriter.hpp.

Member Function Documentation

assert_liveliness()

void dds::pub::AnyDataWriter::assert_liveliness

(

)

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

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

Entities' 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.

liveliness_lost_status()

const dds::core::status::LivelinessLostStatus dds::pub::AnyDataWriter::liveliness_lost_status

(

)

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

offered_deadline_missed_status()

const dds::core::status::OfferedDeadlineMissedStatus dds::pub::AnyDataWriter::offered_deadline_missed_status

(

)

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

offered_incompatible_qos_status()

const dds::core::status::OfferedIncompatibleQosStatus dds::pub::AnyDataWriter::offered_incompatible_qos_status

(

)

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

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

ref	the 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<<()

AnyDataWriter& dds::pub::AnyDataWriter::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

qos

the qos

Exceptions

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,

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

ref	the other Reference object

Returns

true when equal

operator>>()

const AnyDataWriter& dds::pub::AnyDataWriter::operator>>

(

dds::pub::qos::DataWriterQos &

qos

)

const

Gets the DataWriterQos setting for this instance.

Returns

the qos

Exceptions

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.

publication_matched_status()

const dds::core::status::PublicationMatchedStatus dds::pub::AnyDataWriter::publication_matched_status

(

)

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::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::UnsupportedError	OpenSplice is configured not to maintain the information about “associated” subscriptions.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

publisher()

const dds::pub::Publisher& dds::pub::AnyDataWriter::publisher

(

)

const

Get the Publisher that owns this DataWriter.

Returns

the Publisher

Exceptions

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.

qos() [1/2]

dds::pub::qos::DataWriterQos dds::pub::AnyDataWriter::qos

(

)

const

Gets the DataWriterQos setting for this instance.

Returns

the qos

Exceptions

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.

qos() [2/2]

void dds::pub::AnyDataWriter::qos

(

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

qos

the qos

Exceptions

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,

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:

• dds::core::status::StatusMask::inconsistent_topic()
• dds::core::status::StatusMask::offered_deadline_missed()
• dds::core::status::StatusMask::requested_deadline_missed()
• dds::core::status::StatusMask::offered_incompatible_qos()
• dds::core::status::StatusMask::requested_incompatible_qos()
• dds::core::status::StatusMask::sample_lost()
• dds::core::status::StatusMask::sample_rejected()
• dds::core::status::StatusMask::data_on_readers()
• dds::core::status::StatusMask::data_available()
• dds::core::status::StatusMask::liveliness_lost()
• dds::core::status::StatusMask::liveliness_changed()
• dds::core::status::StatusMask::publication_matched()
• dds::core::status::StatusMask::subscription_matched()

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_description()

const dds::topic::TopicDescription& dds::pub::AnyDataWriter::topic_description

(

)

const

Get the TopicDescription associated with this DataWriter.

Returns

the TopicDescription

Exceptions

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.

wait_for_acknowledgments()

void dds::pub::AnyDataWriter::wait_for_acknowledgments

(

const dds::core::Duration &

timeout

)

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

timeout

the time out duration

Exceptions

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::TimeoutError	Not all data is acknowledged before timeout elapsed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

---

The documentation for this class was generated from the following file:

• dds/pub/AnyDataWriter.hpp