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

DataReader allows the applicatin to access published sample data. More...

#include "DataReader.hpp"

Inherits dds::sub::AnyDataReader.

Classes

class  ManipulatorSelector
 
class  Selector
 

Public Types

typedef ::dds::sub::DataReaderListener< T > Listener
 

Public Member Functions

 DataReader (const dds::sub::Subscriber &sub, const ::dds::topic::ContentFilteredTopic< T > &topic)
 
 DataReader (const dds::sub::Subscriber &sub, const ::dds::topic::ContentFilteredTopic< T > &topic, const dds::sub::qos::DataReaderQos &qos, dds::sub::DataReaderListener< T > *listener=NULL, const dds::core::status::StatusMask &mask=::dds::core::status::StatusMask::none())
 
 DataReader (const dds::sub::Subscriber &sub, const ::dds::topic::Topic< T > &topic)
 
 DataReader (const dds::sub::Subscriber &sub, const ::dds::topic::Topic< T > &topic, const dds::sub::qos::DataReaderQos &qos, dds::sub::DataReaderListener< T > *listener=NULL, const dds::core::status::StatusMask &mask=::dds::core::status::StatusMask::none())
 
void close ()
 
dds::sub::status::DataState default_filter_state ()
 
DataReader & default_filter_state (const dds::sub::status::DataState &state)
 
void enable ()
 
const dds::core::InstanceHandle instance_handle () const
 
bool is_nil () const
 
dds::topic::TopicInstance< T > key_value (const dds::core::InstanceHandle &h)
 
T & key_value (T &sample, const dds::core::InstanceHandle &h)
 
Listener * listener () const
 
void listener (Listener *listener, const dds::core::status::StatusMask &event_mask)
 
dds::core::status::LivelinessChangedStatus liveliness_changed_status ()
 
const dds::core::InstanceHandle lookup_instance (const T &key) const
 
bool operator!= (const null_type nil) const
 
template<typename R >
bool operator!= (const R &ref) const
 
DELEGATE * operator-> ()
 
const DELEGATE * operator-> () const
 
AnyDataReader & operator<< (const dds::sub::qos::DataReaderQos &qos)
 
bool operator== (const null_type) const
 
template<typename R >
bool operator== (const R &ref) const
 
DataReader & operator>> (dds::sub::LoanedSamples< T > &ls)
 
const AnyDataReader & operator>> (dds::sub::qos::DataReaderQos &qos) const
 
template<typename Functor >
ManipulatorSelector operator>> (Functor f)
 
ManipulatorSelector operator>> (ManipulatorSelector &(manipulator)(ManipulatorSelector &))
 
dds::sub::qos::DataReaderQos qos () const
 
void qos (const dds::sub::qos::DataReaderQos &qos)
 
LoanedSamples< T > read ()
 
template<typename SamplesBIIterator >
uint32_t read (SamplesBIIterator sbit)
 
template<typename SamplesFWIterator >
uint32_t read (SamplesFWIterator sfit, uint32_t max_samples)
 
dds::core::status::RequestedDeadlineMissedStatus requested_deadline_missed_status ()
 
dds::core::status::RequestedIncompatibleQosStatus requested_incompatible_qos_status ()
 
void retain ()
 
dds::core::status::SampleLostStatus sample_lost_status ()
 
dds::core::status::SampleRejectedStatus sample_rejected_status ()
 
Selector select ()
 
const dds::core::status::StatusMask status_changes ()
 
const dds::sub::Subscriber & subscriber () const
 
dds::core::status::SubscriptionMatchedStatus subscription_matched_status ()
 
LoanedSamples< T > take ()
 
template<typename SamplesBIIterator >
uint32_t take (SamplesBIIterator sbit)
 
template<typename SamplesFWIterator >
uint32_t take (SamplesFWIterator sfit, uint32_t max_samples)
 
const dds::topic::TopicDescription & topic_description () const
 
void wait_for_historical_data (const dds::core::Duration &timeout)
 

Detailed Description

template<typename T>
class dds::sub::DataReader< T >

DataReader allows the applicatin to access published sample data.

A DataReader allows the application:

  • to declare the data it wishes to receive (i.e., make a subscription)
  • to access the data received by the attached Subscriber

A DataReader refers to exactly one TopicDescription (either a Topic, a ContentFilteredTopic or a MultiTopic) that identifies the samples to be read. The Topic must exist prior to the DataReader creation.

A DataReader is attached to exactly one Subscriber which acts as a factory for it.

The DataReader may give access to several instances of the data type, which are distinguished from each other by their key.

The pre-processor generates from IDL type descriptions the application DataReader<type> classes. For each application data type that is used as Topic data type, a typed class DataReader<type> is derived from the AnyDataReader 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 DataReader<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.

Example

// Default creation of a DataReader
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
// Default read of a sample on the DataReader
dds::sub::LoanedSamples<Foo::Bar> samples;
samples = reader.read();
// Default way of accessing the loaned samples
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
const dds::sub::Sample<Foo::Bar>& sample = *it;
const Foo::Bar& data = sample.data();
const dds::sub::SampleInfo& info = sample.info();
// Use sample data and meta information.
}
}
// Like the name says, the read samples are loans from the DataReader. The loan
// was automatically returned when the LoanedSamples went out of scope.
See also
Subscription concept
DataReader concept

Definition at line 34 of file DataReader.hpp.

Member Typedef Documentation

◆ Listener

template<typename T>
typedef ::dds::sub::DataReaderListener<T> dds::sub::DataReader< T >::Listener

Local convenience typedef for dds::sub::DataReaderListener.

Definition at line 112 of file DataReader.hpp.

Constructor & Destructor Documentation

◆ DataReader() [1/4]

template<typename T>
dds::sub::DataReader< T >::DataReader ( const dds::sub::Subscriber &  sub,
const ::dds::topic::Topic< T > &  topic 
)

Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic, using the given Subscriber.

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

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

◆ DataReader() [2/4]

template<typename T>
dds::sub::DataReader< T >::DataReader ( const dds::sub::Subscriber &  sub,
const ::dds::topic::Topic< T > &  topic,
const dds::sub::qos::DataReaderQos &  qos,
dds::sub::DataReaderListener< T > *  listener = NULL,
const dds::core::status::StatusMask &  mask = ::dds::core::status::StatusMask::none() 
)

Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic, using the given Subscriber and DataReaderQos and attaches the optionally specified DataReaderListener to it.

QoS
A possible application pattern to construct the DataReaderQos for the DataReader is to:

// 1) Retrieve the QosPolicy settings on the associated Topic
dds::topic::qos::TopicQos topicQos = topic.qos();
// 2) Retrieve the default DataReaderQos from the related Subscriber
dds::sub::qos::DataReaderQos readerQos = subscriber.default_datareader_qos();
// 3) Combine those two lists of QosPolicy settings by overwriting DataReaderQos
// policies that are also present TopicQos
readerQos = topicQos;
// 4) Selectively modify QosPolicy settings as desired.
readerQos << dds::core::policy::Durability::Transient();
// 5) Use the resulting QoS to construct the DataReader.
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic, readerQos);

Listener
The following statuses are applicable to the DataReaderListener:

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

Parameters
subthe Subscriber that will contain this DataReader
topicthe Topic, ContentFilteredTopic or MultiTopic associated with this DataReader
qosthe DataReader qos.
listenerthe DataReader 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.

◆ DataReader() [3/4]

template<typename T>
dds::sub::DataReader< T >::DataReader ( const dds::sub::Subscriber &  sub,
const ::dds::topic::ContentFilteredTopic< T > &  topic 
)

Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic, using the given Subscriber.

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

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

◆ DataReader() [4/4]

template<typename T>
dds::sub::DataReader< T >::DataReader ( const dds::sub::Subscriber &  sub,
const ::dds::topic::ContentFilteredTopic< T > &  topic,
const dds::sub::qos::DataReaderQos &  qos,
dds::sub::DataReaderListener< T > *  listener = NULL,
const dds::core::status::StatusMask &  mask = ::dds::core::status::StatusMask::none() 
)

Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic, using the given Subscriber and DataReaderQos and attaches the optionally specified DataReaderListener to it.

QoS
A possible application pattern to construct the DataReaderQos for the DataReader is to:

// 1) Retrieve the QosPolicy settings on the associated Topic
dds::topic::qos::TopicQos topicQos = topic.qos();
// 2) Retrieve the default DataReaderQos from the related Subscriber
dds::sub::qos::DataReaderQos readerQos = subscriber.default_datareader_qos();
// 3) Combine those two lists of QosPolicy settings by overwriting DataReaderQos
// policies that are also present TopicQos
readerQos = topicQos;
// 4) Selectively modify QosPolicy settings as desired.
readerQos << dds::core::policy::Durability::Transient();
// 5) Use the resulting QoS to construct the DataReader.
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic, readerQos);

Listener
The following statuses are applicable to the DataReaderListener:

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

Parameters
subthe Subscriber that will contain this DataReader
topicthe Topic, ContentFilteredTopic or MultiTopic associated with this DataReader
qosthe DataReader qos.
listenerthe DataReader 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

◆ 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

◆ default_filter_state() [1/2]

template<typename T>
dds::sub::status::DataState dds::sub::DataReader< T >::default_filter_state ( )

Returns the default state filter for read/take operations.

The default value of default_filter_state is dds::sub::status::DataState::any().

Returns
the default state to filter for

◆ default_filter_state() [2/2]

template<typename T>
DataReader& dds::sub::DataReader< T >::default_filter_state ( const dds::sub::status::DataState &  state)

Set the default state filter for read/take operations.

Default State Filter
The default_filter_state indicates what the dds::sub::status::DataState of samples should be for the read to filter them out of the total data samples pool.

This filter can be overruled by using dds::sub::DataReader::Selector::state or dds::sub::DataReader::ManipulatorSelector::state during the actual read action.

Parameters
statethe state mask that will be used to read/take samples

◆ 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::sub::DataReader< T >::key_value ( 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 DataReader. If the implementation is not able to check invalid handles, then the result in this situation is unspecified.

Parameters
hThe instance handle
Returns
A 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 DataReader has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataReader.

◆ key_value() [2/2]

template<typename T>
T& dds::sub::DataReader< 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 DataReader. 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 DataReader has not yet been enabled.
dds::core::PreconditionNotMetErrorThe handle has not been registered with this DataReader.

◆ listener() [1/2]

template<typename T>
Listener* dds::sub::DataReader< T >::listener ( ) const

Get the listener of this DataReader.

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::sub::DataReader< T >::listener ( Listener *  listener,
const dds::core::status::StatusMask &  event_mask 
)

Register a listener with the DataReader.

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

Be aware that the SUBSCRIPTION_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 DataReaderListener, the SubscriberListener of the containing Subscriber is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the SubscriberListener of the containing Subscriber and a DataReader specific behaviour when needed. In case the communication status is not activated in the mask of the SubscriberListener 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.

The statuses DATA_ON_READERS_STATUS and DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a get_<status_name>_status operation and they are mutually exclusive. When new information becomes available to a DataReader, the Data Distribution Service will first look in an attached and activated SubscriberListener or DomainParticipantListener (in that order) for the DATA_ON_READERS_STATUS. In case the DATA_ON_READERS_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener or DomainParticipant Listener for the DATA_AVAILABLE_STATUS (in that order).

See also listener information.

Parameters
listenerthe listener
event_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_changed_status()

dds::core::status::LivelinessChangedStatus dds::sub::AnyDataReader::liveliness_changed_status ( )
inherited

This operation obtains the LivelinessChangedStatus object of the DataReader.

This object contains the information whether the liveliness of one or more DataWriter objects that were writing instances read by the DataReader has changed. In other words, some DataWriter have become "alive" or "not alive".

The LivelinessChangedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the LivelinessChangedStatus
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>
const dds::core::InstanceHandle dds::sub::DataReader< T >::lookup_instance ( const T &  key) const

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

The instance handle can be used in read operations that operate on a specific instance. Note that DataReader instance handles are local, and are not interchangeable with DataWriter instance handles nor with instance handles of an other DataReader.

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.

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

AnyDataReader& dds::sub::AnyDataReader::operator<< ( const dds::sub::qos::DataReaderQos &  qos)
inherited

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

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 DataReader, which can only be set before the DataReader 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 DataReader.
dds::core::InconsistentPolicyErrorThe 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
refthe other Reference object
Returns
true when equal

◆ operator>>() [1/4]

template<typename T>
DataReader& dds::sub::DataReader< T >::operator>> ( dds::sub::LoanedSamples< T > &  ls)

This operation reads a sequence of typed samples from the DataReader by means of the shift operator.

What samples are read depends on what default state filter has been set (default any).

This operation reads a sequence of typed samples from the DataReader<type>. The data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples, which in turn contains the actual data and meta information.

The memory used for storing the sample may be loaned by the middleware thus allowing zero copy operations.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
dds::sub::LoanedSamples<Foo::Bar> samples;
reader >> samples;
}
// The LoanedSamples went out of scope, meaning the loan was returned.

Take
The default behaviour of the DataReader stream operator>> is to read samples. It can be explicitly stated if the operator should do a read or take.

reader >> dds::sub::read >> samples;
reader >> dds::sub::take >> samples;

These are two of the available convenience manipulators (see next paragraph).

Manipulators
Manipulators are defined externally to make it possible to control which data is read and whether the streaming operators reads or takes.

Available convenience stream manipulators:

  • dds::sub::read
  • dds::sub::take
  • dds::sub::max_samples
  • dds::sub::content
  • dds::sub::state
  • dds::sub::instance
  • dds::sub::next_instance

The manipulators can be concatenated:

// Take (iso read) a maximum of 3 new samples of a certain instance.
reader >> dds::sub::take
>> dds::sub::max_samples(3)
>> dds::sub::state(dds::sub::status::DataState::new_data())
>> dds::sub::instance(someValidInstanceHandle)
>> samples;

Please be aware that using pre-set filters on the DataReader and then call read() or take() on that reader explicitly will perform better than having to create Manipulators for every read (which is what essentially happens in the code example above). Performance can be increase by creating a manipulator up front and using that multiple times (see dds::sub::DataReader::ManipulatorSelector).

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the SampleInfo that communicates a change in the instance_state of an instance for which there is no ‘real’ sample available.

For example, when an application always ‘takes’ all available samples of a particular instance, there is no sample available to report the disposal of that instance. In such a case the DataReader will insert a dummy sample into the data_values sequence to accompany the SampleInfo element in the info_seq sequence that communicates the disposal of the instance.

The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it also sets the view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the instance_state of the instance.

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 DataReader has not yet been enabled.

◆ operator>>() [2/4]

const AnyDataReader& dds::sub::AnyDataReader::operator>> ( dds::sub::qos::DataReaderQos &  qos) const
inherited

Gets the DataReaderQos 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.

◆ operator>>() [3/4]

template<typename T>
template<typename Functor >
ManipulatorSelector dds::sub::DataReader< T >::operator>> ( Functor  f)

This operation reads a sequence of typed samples from the DataReader by means of the shift operator.

What samples are read depends on what default state filter has been set (default any).

This operation reads a sequence of typed samples from the DataReader<type>. The data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples, which in turn contains the actual data and meta information.

The memory used for storing the sample may be loaned by the middleware thus allowing zero copy operations.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
dds::sub::LoanedSamples<Foo::Bar> samples;
reader >> samples;
}
// The LoanedSamples went out of scope, meaning the loan was returned.

Take
The default behaviour of the DataReader stream operator>> is to read samples. It can be explicitly stated if the operator should do a read or take.

reader >> dds::sub::read >> samples;
reader >> dds::sub::take >> samples;

These are two of the available convenience manipulators (see next paragraph).

Manipulators
Manipulators are defined externally to make it possible to control which data is read and whether the streaming operators reads or takes.

Available convenience stream manipulators:

  • dds::sub::read
  • dds::sub::take
  • dds::sub::max_samples
  • dds::sub::content
  • dds::sub::state
  • dds::sub::instance
  • dds::sub::next_instance

The manipulators can be concatenated:

// Take (iso read) a maximum of 3 new samples of a certain instance.
reader >> dds::sub::take
>> dds::sub::max_samples(3)
>> dds::sub::state(dds::sub::status::DataState::new_data())
>> dds::sub::instance(someValidInstanceHandle)
>> samples;

Please be aware that using pre-set filters on the DataReader and then call read() or take() on that reader explicitly will perform better than having to create Manipulators for every read (which is what essentially happens in the code example above). Performance can be increase by creating a manipulator up front and using that multiple times (see dds::sub::DataReader::ManipulatorSelector).

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the SampleInfo that communicates a change in the instance_state of an instance for which there is no ‘real’ sample available.

For example, when an application always ‘takes’ all available samples of a particular instance, there is no sample available to report the disposal of that instance. In such a case the DataReader will insert a dummy sample into the data_values sequence to accompany the SampleInfo element in the info_seq sequence that communicates the disposal of the instance.

The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it also sets the view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the instance_state of the instance.

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 DataReader has not yet been enabled.

◆ operator>>() [4/4]

template<typename T>
ManipulatorSelector dds::sub::DataReader< T >::operator>> ( ManipulatorSelector &  manipulator)(ManipulatorSelector &)

This operation reads a sequence of typed samples from the DataReader by means of the shift operator.

What samples are read depends on what default state filter has been set (default any).

This operation reads a sequence of typed samples from the DataReader<type>. The data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples, which in turn contains the actual data and meta information.

The memory used for storing the sample may be loaned by the middleware thus allowing zero copy operations.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
dds::sub::LoanedSamples<Foo::Bar> samples;
reader >> samples;
}
// The LoanedSamples went out of scope, meaning the loan was returned.

Take
The default behaviour of the DataReader stream operator>> is to read samples. It can be explicitly stated if the operator should do a read or take.

reader >> dds::sub::read >> samples;
reader >> dds::sub::take >> samples;

These are two of the available convenience manipulators (see next paragraph).

Manipulators
Manipulators are defined externally to make it possible to control which data is read and whether the streaming operators reads or takes.

Available convenience stream manipulators:

  • dds::sub::read
  • dds::sub::take
  • dds::sub::max_samples
  • dds::sub::content
  • dds::sub::state
  • dds::sub::instance
  • dds::sub::next_instance

The manipulators can be concatenated:

// Take (iso read) a maximum of 3 new samples of a certain instance.
reader >> dds::sub::take
>> dds::sub::max_samples(3)
>> dds::sub::state(dds::sub::status::DataState::new_data())
>> dds::sub::instance(someValidInstanceHandle)
>> samples;

Please be aware that using pre-set filters on the DataReader and then call read() or take() on that reader explicitly will perform better than having to create Manipulators for every read (which is what essentially happens in the code example above). Performance can be increase by creating a manipulator up front and using that multiple times (see dds::sub::DataReader::ManipulatorSelector).

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the SampleInfo that communicates a change in the instance_state of an instance for which there is no ‘real’ sample available.

For example, when an application always ‘takes’ all available samples of a particular instance, there is no sample available to report the disposal of that instance. In such a case the DataReader will insert a dummy sample into the data_values sequence to accompany the SampleInfo element in the info_seq sequence that communicates the disposal of the instance.

The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it also sets the view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the instance_state of the instance.

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 DataReader has not yet been enabled.

◆ qos() [1/2]

dds::sub::qos::DataReaderQos dds::sub::AnyDataReader::qos ( ) const
inherited

Gets the DataReaderQos 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::sub::AnyDataReader::qos ( const dds::sub::qos::DataReaderQos &  qos)
inherited

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

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 DataReader, which can only be set before the DataReader 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 DataReader.
dds::core::InconsistentPolicyErrorThe parameter qos contains conflicting QosPolicy settings,

◆ read() [1/3]

template<typename T>
LoanedSamples<T> dds::sub::DataReader< T >::read ( )

This operation reads a sequence of typed samples from the DataReader.

What samples are read depends on what default state filter has been set (default any).

This operation reads a sequence of typed samples from the DataReader<type>. The data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples, which in turn contains the actual data and meta information.

The memory used for storing the sample may be loaned by the middleware thus allowing zero copy operations.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
// Read the available samples.
dds::sub::LoanedSamples<Foo::Bar> samples;
samples = reader.read();
// Access the information.
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
const dds::sub::Sample<Foo::Bar>& sample = *it;
}
}
// The LoanedSamples went out of scope, meaning the loan resources were taken care of.

Selectors
What data is read already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the SampleInfo that communicates a change in the instance_state of an instance for which there is no ‘real’ sample available.

For example, when an application always ‘takes’ all available samples of a particular instance, there is no sample available to report the disposal of that instance. In such a case the DataReader will insert a dummy sample into the data_values sequence to accompany the SampleInfo element in the info_seq sequence that communicates the disposal of the instance.

The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If the sample belongs to the most recent generation of the instance, it also sets the view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the instance_state of the instance.

Returns
The samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ read() [2/3]

template<typename T>
template<typename SamplesBIIterator >
uint32_t dds::sub::DataReader< T >::read ( SamplesBIIterator  sbit)

This operation reads a sequence of typed samples from the DataReader.

What samples are read depends on what default state filter has been set (default any).

The samples are copied into the application provided container using a back-inserting iterator. Notice that as a consequence of using a back-inserting iterator, this operation may allocate memory to resize the underlying container.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
// Prepare container to store samples in
std::vector<dds::sub::Sample<Foo::Bar> > samples;
std::back_insert_iterator< std::vector<dds::sub::Sample<Foo::Bar> > > bi(samples);
// Read and copy the available samples into the vector by means of the iterator
uint32_t len = reader.read(bi);
// Access the information.
std::vector<dds::sub::Sample<Space::Type1> >::iterator iter = samples.begin();
for (iter = samples.begin(); iter != samples.end(); ++iter) {
const dds::sub::Sample<Foo::Bar>& sample = *iter;
}

Selectors
What data is read already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data.
Look here for more information.

Parameters
sbitBack-inserting container iterator
Returns
The number of samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ read() [3/3]

template<typename T>
template<typename SamplesFWIterator >
uint32_t dds::sub::DataReader< T >::read ( SamplesFWIterator  sfit,
uint32_t  max_samples 
)

This operation reads a sequence of typed samples from the DataReader.

What samples are read depends on what default state filter has been set (default any).

The samples are copied into the application provided container using the forward iterator parameter.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
// Prepare container to store samples in
const uint32_t MAX_SAMPLES (3)
std::vector<dds::sub::Sample<Foo::Bar> > samples(MAX_SAMPLES);
std::vector<dds::sub::Sample<Foo::Bar> >::iterator iter = samples.begin();
// Read and copy the available samples into the vector by means of the iterator
uint32_t len = reader.read(iter, MAX_SAMPLES);
// Access the information.
for (iter = samples.begin(); iter != samples.end(); ++iter) {
const dds::sub::Sample<Foo::Bar>& sample = *iter;
}

Selectors
What data is read already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data.
Look here for more information.

Parameters
sfitForward-inserting container iterator
max_samplesMaximum samples to read and copy into the given container
Returns
The number of samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ requested_deadline_missed_status()

dds::core::status::RequestedDeadlineMissedStatus dds::sub::AnyDataReader::requested_deadline_missed_status ( )
inherited

This operation obtains the RequestedDeadlineMissedStatus object of the DataReader.

This object contains the information whether the deadline that the DataReader was expecting through its dds::core::policy::Deadline QosPolicy was not respected for a specific instance.

The RequestedDeadlineMissedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the RequestedDeadlineMissedStatus
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.

◆ requested_incompatible_qos_status()

dds::core::status::RequestedIncompatibleQosStatus dds::sub::AnyDataReader::requested_incompatible_qos_status ( )
inherited

This operation obtains the RequestedIncompatibleQosStatus object of the DataReader.

This object contains the information whether a QosPolicy setting was incompatible with the offered QosPolicy setting.

The Request/Offering mechanism is applicable between the DataWriter and the DataReader. If the QosPolicy settings between DataWriter and DataReader are inconsistent, no communication between them is established. In addition the DataWriter will be informed via a REQUESTED_INCOMPATIBLE_QOS status change and the DataReader will be informed via an OFFERED_INCOMPATIBLE_QOS status change.

The RequestedIncompatibleQosStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the RequestedIncompatibleQosStatus
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.

◆ 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

◆ sample_lost_status()

dds::core::status::SampleLostStatus dds::sub::AnyDataReader::sample_lost_status ( )
inherited

This operation obtains the SampleLostStatus object of the DataReader.

This object contains information whether samples have been lost. This only applies when the dds::core::policy::Reliability QosPolicy is set to RELIABLE. If the ReliabilityQos Policy is set to BEST_EFFORT, the Data Distribution Service will not report the loss of samples.

The SampleLostStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the SampleLostStatus
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.

◆ sample_rejected_status()

dds::core::status::SampleRejectedStatus dds::sub::AnyDataReader::sample_rejected_status ( )
inherited

This operation obtains the SampleRejectedStatus object of the DataReader.

This object contains the information whether a received sample has been rejected. Samples may be rejected by the DataReader when it runs out of resource_limits to store incoming samples. Usually this means that old samples need to be "onsumed" (for example by "taking" them instead of "reading" them) to make room for newly incoming samples.

The SampleRejectedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the SampleRejectedStatus
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.

◆ select()

template<typename T>
Selector dds::sub::DataReader< T >::select ( )

Get a dds::sub::DataReader::Selector instance that acts on this DataReader.

The DataReader::read and DataReader::take read all samples that are available within the DataReader (provided that the default state filter hasn't been changed).

Selectors
A Selector can perform complex data selections, such as per-instance selection, content and status filtering, etc when reading or taking. Such a selector is returned by this operation. Setting filters on the Selector can be concatenated, resulting in the following example code.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
// Take a maximum of 3 new samples of a certain instance.
{
dds::sub::LoanedSamples<Foo::Bar> samples;
samples = reader.select()
.max_samples(3)
.state(dds::sub::status::DataState::new_data())
.instance(someValidInstanceHandle)
.take();
}

Please be aware that using pre-set filters on the DataReader and then call read() or take() on that reader explicitly will perform better than having to create Selectors for every read (which is what essentially happens in the code example above). Performance can be increase by creating a selector up front and using that multiple times (see dds::sub::DataReader::Selector).

Returns
A Selector that acts on the DataReader
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 DataReader has not yet been enabled.

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

◆ subscriber()

const dds::sub::Subscriber& dds::sub::AnyDataReader::subscriber ( ) const
inherited

Get the Subscriber that owns this DataReader.

Returns
the Subscriber
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.

◆ subscription_matched_status()

dds::core::status::SubscriptionMatchedStatus dds::sub::AnyDataReader::subscription_matched_status ( )
inherited

This operation obtains the SubscriptionMatchedStatus object of the DataReader.

This object contains the information whether a new match has been discovered for the current subscription, or whether an existing match has ceased to exist.

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

The operation may fail if the infrastructure does not hold the information necessary to fill in the SubscriptionMatchedStatus. 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 SubscriptionMatchedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.

Returns
the SubscriptionMatchedStatus
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::UnsupportedErrorOpenSplice is configured not to maintain the information about "associated" publications.

◆ take() [1/3]

template<typename T>
LoanedSamples<T> dds::sub::DataReader< T >::take ( )

This operation takes a sequence of typed samples from the DataReader.

The behaviour is identical to read except for that the samples are removed from the DataReader.

What samples are taken depends on what default state filter has been set (default any).

This operation takes a sequence of typed samples from the DataReader<type>. The data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples, which in turn contains the actual data and meta information.

The memory used for storing the sample may be loaned by the middleware thus allowing zero copy operations.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
{
// Take the available samples.
dds::sub::LoanedSamples<Foo::Bar> samples;
samples = reader.take();
// Access the information.
dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
for (it = samples.begin(); it != samples.end(); ++it) {
const dds::sub::Sample<Foo::Bar>& sample = *it;
}
}
// The LoanedSamples went out of scope, meaning the loan resources were taken care of.

Selectors
What data is taken, already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data.
Look here for more information.

Returns
The samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ take() [2/3]

template<typename T>
template<typename SamplesBIIterator >
uint32_t dds::sub::DataReader< T >::take ( SamplesBIIterator  sbit)

This operation takes a sequence of typed samples from the DataReader.

What samples are take depends on what default state filter has been set (default any).

The samples are copied into the application provided container using a back-inserting iterator. Notice that as a consequence of using a back-inserting iterator, this operation may allocate memory to resize the underlying container.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
// Prepare container to store samples in
std::vector<dds::sub::Sample<Foo::Bar> > samples;
std::back_insert_iterator< std::vector<dds::sub::Sample<Foo::Bar> > > bi(samples);
// Take and copy the available samples into the vector by means of the iterator
uint32_t len = reader.take(bi);
// Access the information.
std::vector<dds::sub::Sample<Space::Type1> >::iterator iter = samples.begin();
for (iter = samples.begin(); iter != samples.end(); ++iter) {
const dds::sub::Sample<Foo::Bar>& sample = *iter;
}

Selectors
What data is taken, already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data.
Look here for more information.

Parameters
sbitBack-inserting container iterator
Returns
The number of samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ take() [3/3]

template<typename T>
template<typename SamplesFWIterator >
uint32_t dds::sub::DataReader< T >::take ( SamplesFWIterator  sfit,
uint32_t  max_samples 
)

This operation takes a sequence of typed samples from the DataReader.

What samples are take depends on what default state filter has been set (default any).

The samples are copied into the application provided container using the forward iterator parameter.

If the DataReader has no samples that meet the constraints, the resulting dds::sub::LoanedSamples will be empty.

dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
dds::sub::Subscriber subscriber(participant);
dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
// Prepare container to store samples in
const uint32_t MAX_SAMPLES (3)
std::vector<dds::sub::Sample<Foo::Bar> > samples(MAX_SAMPLES);
std::vector<dds::sub::Sample<Foo::Bar> >::iterator iter = samples.begin();
// Take and copy the available samples into the vector by means of the iterator
uint32_t len = reader.take(iter, MAX_SAMPLES);
// Access the information.
for (iter = samples.begin(); iter != samples.end(); ++iter) {
const dds::sub::Sample<Foo::Bar>& sample = *iter;
}

Selectors
What data is taken, already depends on the default state filter. But it can be manipulated even more when using dds::sub::DataReader::select() operation.

Invalid Data
Some elements in the returned sequence may not have valid data: the valid_data field in the SampleInfo indicates whether the corresponding data value contains any meaningful data.
Look here for more information.

Parameters
sfitForward-inserting container iterator
max_samplesMaximum samples to take and copy into the given container
Returns
The number of samples in the LoanedSamples container
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 DataReader has not yet been enabled.

◆ topic_description()

const dds::topic::TopicDescription& dds::sub::AnyDataReader::topic_description ( ) const
inherited

Get the TopicDescription associated with this DataReader.

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.

◆ wait_for_historical_data()

void dds::sub::AnyDataReader::wait_for_historical_data ( const dds::core::Duration &  timeout)
inherited

This operation will block the application thread until all "historical" data is received.

This operation behaves differently for DataReader objects which have a non-VOLATILE dds::core::policy::Durability QosPolicy and for DataReader objects which have a VOLATILE dds::core::policy::Durability QosPolicy.

As soon as an application enables a non-VOLATILE DataReader it will start receiving both "historical" data, i.e. the data that was written prior to the time the DataReader joined the domain, as well as any new data written by the DataWriter objects. There are situations where the application logic may require the application to wait until all "historical" data is received. This is the purpose of the wait_for_historical_data operation.

As soon as an application enables a VOLATILE DataReader it will not start receiving "historical" data but only new data written by the DataWriter objects. By calling wait_for_historical_data the DataReader explicitly requests the Data Distribution Service to start receiving also the "historical" data and to wait until either all "historical" data is received, or the duration specified by the max_wait parameter has elapsed, whichever happens first.

Thread Blocking
The operation wait_for_historical_data blocks the calling thread until either all "historical" data is received, or the duration specified by the max_wait parameter elapses, whichever happens first. When the function returns normally, indicates that all the "historical" data was received. If the function throws TimeoutError, it indicates that max_wait elapsed before all the data was received.

Parameters
timeoutthe time to wait for historical data (can be dds::core::Duration::infinite())
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::NotEnabledErrorThe entity has not yet been enabled.
dds::core::TimeoutErrorNot all data is received before timeout elapsed.
dds::core::OutOfResourcesErrorThe Data Distribution Service ran out of resources to complete this operation.
The documentation for this class was generated from the following file:
dds::sub::Subscriber
A Subscriber is the object responsible for the actual reception of the data resulting from its subscr...
Definition: Subscriber.hpp:53
dds::sub::Subscriber::default_datareader_qos
dds::sub::qos::DataReaderQos default_datareader_qos() const
dds::sub::AnyDataReader::subscriber
const dds::sub::Subscriber & subscriber() const
dds::sub::Sample::data
const DataType & data() const
dds::sub::Sample
This class encapsulates the data and info meta-data associated with DDS samples.
Definition: Sample.hpp:30
dds::sub::DataReader::read
LoanedSamples< T > read()
dds::topic::qos::TopicQos
This struct provides the basic mechanism for an application to specify Quality of Service attributes ...
Definition: TopicQos.hpp:67
dds::sub::LoanedSamples
This class encapsulates and automates the management of loaned samples.
Definition: LoanedSamples.hpp:87
dds::core::policy::Durability::Transient
static Durability Transient()
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
Definition: array.hpp:30
dds::core::begin
T::iterator begin(T &t)
Definition: array.hpp:34
dds::sub::SampleInfo
The SampleInfo contains information pertaining to the associated Data value.
Definition: SampleInfo.hpp:61
dds::sub::LoanedSamples::end
const_iterator end() const
dds::core::end
T::iterator end(T &t)
Definition: array.hpp:39
dds::core::policy::EntityFactory::ManuallyEnable
static EntityFactory ManuallyEnable()
dds::sub::DataReader::take
LoanedSamples< T > take()
dds::sub::Sample::info
const SampleInfo & info() const
dds::sub::DataReader
DataReader allows the applicatin to access published sample data.
Definition: DataReader.hpp:34
dds::sub::LoanedSamples::begin
const_iterator begin() const
dds::topic::Topic
Topic is the most basic description of the data to be published and subscribed.
Definition: Topic.hpp:36
dds::sub::qos::DataReaderQos
This class provides the basic mechanism for an application to specify Quality of Service attributes f...
Definition: DataReaderQos.hpp:66
dds::sub::status::DataState::new_data
static DataState new_data()
Definition: DataState.hpp:631
dds::sub::LoanedSamples::const_iterator
DELEGATE< T >::const_iterator const_iterator
Definition: LoanedSamples.hpp:98
dds::domain::DomainParticipant
A DomainParticipant represents the local membership of the application in a Domain.
Definition: DomainParticipant.hpp:65