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

#include "AnyDataReader.hpp"

Inheritance diagram for dds::sub::AnyDataReader:

Public Member Functions
void	close ()

void	enable ()

const dds::core::InstanceHandle	instance_handle () const

bool	is_nil () const

dds::core::status::LivelinessChangedStatus	liveliness_changed_status ()

template<typename R >
bool	operator!= (const R &ref) const

bool	operator!= (const null_type nil) const

DELEGATE *	operator-> ()

const DELEGATE *	operator-> () const

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

template<typename R >
bool	operator== (const R &ref) const

bool	operator== (const null_type) const

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

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

void	qos (const dds::sub::qos::DataReaderQos &qos)

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

const dds::core::status::StatusMask	status_changes ()

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

dds::core::status::SubscriptionMatchedStatus	subscription_matched_status ()

const dds::topic::TopicDescription &	topic_description () const

void	wait_for_historical_data (const dds::core::Duration &timeout)

void	wait_for_historical_data_w_condition (const std::string &filter_expression, const std::vector< std::string > &filter_parameters, const dds::core::Time &min_source_timestamp, const dds::core::Time &max_source_timestamp, const dds::core::policy::ResourceLimits &resource_limits, const dds::core::Duration &timeout)

Detailed Description

Typeless base class for the typed DataReader.

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

See also: dds::sub::DataReader

Definition at line 50 of file AnyDataReader.hpp.

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

Definition at line 68 of file EntityImpl.hpp.

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

In addition to the general description, the enable operation on a dds::sub::Subscriber has special meaning in specific usecases. This applies only to Subscribers with PresentationQoS coherent-access set to true with access-scope set to group.

In this case the subscriber is always created in a disabled state, regardless of the auto-enable created entities setting on the corresponding participant. While the subscriber remains disabled, DataReaders can be created that will participate in coherent transactions of the subscriber.

See dds::sub::CoherentAccess for more information.

All DataReaders will also be created in a disabled state. Coherency with group access-scope requires data to be delivered as a transaction, atomically, to all eligible readers. Therefore data should not be delivered to any single DataReader immediately after it's created, as usual, but only after the application has finished creating all DataReaders for a given Subscriber. At this point, the application should enable the Subscriber which in turn enables all its DataReaders.

Note that for a dds::pub::DataWriter which has a corresponding dds::pub::Publisher with a PresentationQoS with coherent-access set to true and access-scope set to topic or group that the HistoryQoS of the dds::pub::DataWriter should be set to keep-all otherwise the enable operation will fail.

See dds::pup::DataWriter for more information.

Returns: void

Exceptions

dds::core::PreconditionNotMetError Entities' factory is not enabled.

Definition at line 44 of file EntityImpl.hpp.

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

Definition at line 60 of file EntityImpl.hpp.

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

Definition at line 143 of file ReferenceImpl.hpp.

◆ liveliness_changed_status()

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

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

Definition at line 108 of file AnyDataReaderImpl.hpp.

◆ operator!=() [1/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

Definition at line 100 of file ReferenceImpl.hpp.

◆ operator!=() [2/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.

Definition at line 157 of file ReferenceImpl.hpp.

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

Definition at line 180 of file ReferenceImpl.hpp.

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

Definition at line 188 of file ReferenceImpl.hpp.

◆ operator<<()

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

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

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 DataReader.
dds::core::InconsistentPolicyError	The parameter qos contains conflicting QosPolicy settings,

Definition at line 89 of file AnyDataReaderImpl.hpp.

◆ operator==() [1/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

Definition at line 83 of file ReferenceImpl.hpp.

◆ operator==() [2/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.

Definition at line 150 of file ReferenceImpl.hpp.

◆ operator>>()

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

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

Definition at line 98 of file AnyDataReaderImpl.hpp.

◆ qos() [1/2]

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

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

Definition at line 73 of file AnyDataReaderImpl.hpp.

◆ qos() [2/2]

void dds::sub::AnyDataReader::qos ( const dds::sub::qos::DataReaderQos & qos )

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

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 DataReader.
dds::core::InconsistentPolicyError	The parameter qos contains conflicting QosPolicy settings,

Definition at line 81 of file AnyDataReaderImpl.hpp.

◆ requested_deadline_missed_status()

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

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

Definition at line 132 of file AnyDataReaderImpl.hpp.

◆ requested_incompatible_qos_status()

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

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

Definition at line 140 of file AnyDataReaderImpl.hpp.

◆ 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

Definition at line 76 of file EntityImpl.hpp.

◆ sample_lost_status()

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

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

Definition at line 124 of file AnyDataReaderImpl.hpp.

◆ sample_rejected_status()

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

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 ‘consumed’ (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::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.

Definition at line 116 of file AnyDataReaderImpl.hpp.

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

Definition at line 52 of file EntityImpl.hpp.

◆ subscriber()

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

Get the Subscriber that owns this DataReader.

Returns: the Subscriber

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.

Definition at line 47 of file AnyDataReaderImpl.hpp.

◆ subscription_matched_status()

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

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::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::UnsupportedError	OpenSplice is configured not to maintain the information about “associated” publications.

Definition at line 148 of file AnyDataReaderImpl.hpp.

◆ topic_description()

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

Get the TopicDescription associated with this DataReader.

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.

Definition at line 55 of file AnyDataReaderImpl.hpp.

◆ wait_for_historical_data()

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

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

timeout the time to wait for historical data (can be dds::core::Duration::infinite())

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::NotEnabledError	The entity has not yet been enabled.
dds::core::TimeoutError	Not all data is received before timeout elapsed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::PreconditionNotMetError	Can happen when requesting conditional alignment on non-volatile readers or Historical data request already in progress or complete.

Definition at line 64 of file AnyDataReaderImpl.hpp.

◆ wait_for_historical_data_w_condition()

void dds::sub::AnyDataReader::wait_for_historical_data_w_condition	(	const std::string &	filter_expression,
		const std::vector< std::string > &	filter_parameters,
		const dds::core::Time &	min_source_timestamp,
		const dds::core::Time &	max_source_timestamp,
		const dds::core::policy::ResourceLimits &	resource_limits,
		const dds::core::Duration &	timeout
	)

This operation will block the application thread until all historical data that matches the supplied conditions is received.

Note: This is a proprietary OpenSplice extension.; This operation only makes sense when the receiving node has configured its durability service as an On_Request alignee. (See also the description of the OpenSplice/DurabilityService/NameSpaces/Policy[] attribute in the Deployment Guide.) Otherwise the Durability Service will not distinguish between separate reader requests and still inject the full historical data set in each reader.; Additionally, when creating the DataReader, the DurabilityQos.kind of the DataReaderQos needs to be set to VOLATILE, to ensure that historical data that potentially is available already at creation time is not immediately delivered to the DataReader at that time.

This operation is similar to the AnyDataReader::wait_for_historical_data operation, but instead of inserting all historical data into the DataReader, only data that matches the conditions expressed by the parameters to this operation is inserted.

By using filter_expression and filter_parameters , data can be selected or discarded based on content. The filter_expression must adhere to SQL syntax of the WHERE clause as described here, DCPS Queries and Filters.
Constraints on the age of data can be set by using the min_source_timestamp and max_source_timestamp parameters. Only data published within this timeframe will be selected. Note that dds::core::Time::invalid() is also accepted as a lower or upper timeframe limit. The amount of selected data can be further reduced by the resource_limits parameter. This QosPolicy allows to set a limit on the number of samples, instances and samples per instance that are to be received.

Call
This is a proprietary operation and can be called by using the operator->.

dds::sub::DataReader<Foo::Bar> reader(subscriber);
reader->wait_for_historical_data_w_condition(
                                 "ID > 15",
                                 std::vector<std::string>(),
                                 dds::core::Time::invalid(),
                                 dds::core::Time::invalid(),
                                 dds::core::policy::ResourceLimits(),
                                 dds::core::Duration::infinite());

Parameters

filter_expression	The SQL expression (subset of SQL), which defines the filtering criteria (NULL when no SQL filtering is needed).
filter_parameters	Sequence of strings with the parameter values used in the SQL expression (i.e., the number of n tokens in the expression). The number of values in expression_parameters must be equal to or greater than the highest referenced n token in the filter_expression (e.g. if %1 and %8 are used as parameters in the filter_expression, the expression_parameters should contain at least n + 1 = 9 values).
min_source_timestamp	Filter out all data published before this time. The special constant dds::core::Time::invalid() can be used when no minimum filter is needed.
max_source_timestamp	Filter out all data published after this time. The special constant dds::core::Time::invalid() can be used when no maximum filter is needed.
resource_limits	Specifies limits on the maximum amount of historical data that may be received.
timeout	The time to wait for historical data (can be dds::core::Duration::infinite())

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::NotEnabledError	The entity has not yet been enabled.
dds::core::TimeoutError	Not all data is received before timeout elapsed.
dds::core::PreconditionNotMetError	No Durability service is available or a different request for historical data is already being processed. Not all data is received before timeout elapsed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::PreconditionNotMetError	Can happen when requesting conditional alignment on non-volatile readers or Historical data request already in progress or complete.

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

include/dcps/C++/isocpp2/dds/sub/AnyDataReader.hpp
include/dcps/C++/isocpp2/dds/sub/detail/AnyDataReaderImpl.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ close()

◆ enable()

◆ instance_handle()

◆ is_nil()

◆ liveliness_changed_status()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator<<()

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator>>()

◆ qos() [1/2]

◆ qos() [2/2]

◆ requested_deadline_missed_status()

◆ requested_incompatible_qos_status()

◆ retain()

◆ sample_lost_status()

◆ sample_rejected_status()

◆ status_changes()

◆ subscriber()

◆ subscription_matched_status()

◆ topic_description()

◆ wait_for_historical_data()

◆ wait_for_historical_data_w_condition()