<<reference-type>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached dds::sub::Subscriber. More...

#include "dds/sub/DataReader.hpp"

Inheritance diagram for dds::sub::DataReader< T >:

Classes
class	ManipulatorSelector
	A Selector class enabling the streaming API. More...

class	Selector
	The Selector class is used by the DataReader to compose read and take operations. More...

Public Member Functions
	DataReader (const dds::sub::Subscriber &sub, const dds::topic::Topic< T > &topic)
	Create a DataReader. More...

	DataReader (const dds::sub::Subscriber &sub, const dds::topic::Topic< T > &topic, const dds::sub::qos::DataReaderQos &the_qos, dds::sub::DataReaderListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
	Create a DataReader. More...

	DataReader (const dds::sub::Subscriber &sub, const dds::topic::Topic< T > &topic, const dds::sub::qos::DataReaderQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
	Create a DataReader. More...

	DataReader (const dds::sub::Subscriber &sub, const dds::topic::ContentFilteredTopic< T > &topic)
	Create a DataReader for a dds::topic::ContentFilteredTopic. More...

	DataReader (const dds::sub::Subscriber &sub, const dds::topic::ContentFilteredTopic< T > &topic, const dds::sub::qos::DataReaderQos &the_qos, dds::sub::DataReaderListener< T > *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
	Create a DataReader for a dds::topic::ContentFilteredTopic. More...

	DataReader (const dds::sub::Subscriber &sub, const dds::topic::ContentFilteredTopic< T > &topic, const dds::sub::qos::DataReaderQos &the_qos, std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
	Create a DataReader for a dds::topic::ContentFilteredTopic with a listener. More...

const dds::sub::status::DataState &	default_filter_state ()
	Returns the default state for read/take operations. More...

DataReader &	default_filter_state (const dds::sub::status::DataState &state)
	Set the default state filter for read/take operations. More...

DataReader &	operator>> (dds::sub::LoanedSamples< T > &ls)
	Use the stream operator to take samples, placing them into a LoanedSamples container. More...

ManipulatorSelector	operator>> (bool(*manipulator)(ReadModeDummyType))
	Use the stream operator to read or take samples. More...

template<typename Functor >
ManipulatorSelector	operator>> (Functor f)
	Use the stream operator to dictate the behavior of the read or take operation. More...

LoanedSamples< T >	read ()
	Read all samples using the default filter state. More...

LoanedSamples< T >	take ()
	Take all samples using the default filter state. More...

template<typename SamplesFWIterator >
uint32_t	read (SamplesFWIterator sfit, int32_t max_samples)
	Read up to max_samples samples using the default filter state. More...

template<typename SamplesFWIterator >
uint32_t	take (SamplesFWIterator sfit, int32_t max_samples)
	Take up to max_samples samples using the default filter state. More...

template<typename SamplesBIIterator >
uint32_t	read (SamplesBIIterator sbit)
	Read all samples available in the reader cache using the default filter state. More...

template<typename SamplesBIIterator >
uint32_t	take (SamplesBIIterator sbit)
	Take all samples available in the reader cache samples using the default filter state. More...

Selector	select ()
	Get a Selector to perform complex data selections, such as per-instance selection, content and status filtering. More...

T &	key_value (T &key_holder, const dds::core::InstanceHandle &handle)
	Retrieve the instance key that corresponds to an instance handle. More...

dds::topic::TopicInstance< T > &	key_value (dds::topic::TopicInstance< T > &key_holder, const dds::core::InstanceHandle &handle)
	Retrieve the instance key that corresponds to an instance handle. More...

dds::core::InstanceHandle	lookup_instance (const T &key_holder) const
	Retrieve the InstanceHandle that corresponds to an instance key holder. More...

dds::topic::TopicDescription< DataType >	topic_description () const
	Returns the dds::topic::TopicDescription associated with the DataReader. More...

const dds::sub::Subscriber &	subscriber () const
	Returns the Subscriber to which the DataReader belongs. More...

void	listener (Listener *the_listener, const dds::core::status::StatusMask &event_mask)
	Sets the listener associated with this reader. More...

Listener *	listener () const
	Returns the listener currently associated with this DataReader. More...

void	set_listener (std::shared_ptr< Listener > the_listener, const dds::core::status::StatusMask &event_mask)
	Sets the listener associated with this reader. More...

void	set_listener (std::shared_ptr< Listener > the_listener)
	Sets the listener associated with this reader. More...

std::shared_ptr< Listener >	get_listener () const
	Returns the listener currently associated with this DataReader. More...

const dds::sub::qos::DataReaderQos	qos () const
	Get the QoS associated with this reader. More...

void	qos (const dds::sub::qos::DataReaderQos &the_qos)
	Set the QoS associated with this reader. More...

DataReader &	operator<< (const dds::sub::qos::DataReaderQos &the_qos)
	Set the QoS associated with this reader. More...

DataReader &	operator>> (dds::sub::qos::DataReaderQos &the_qos)
	Get the QoS associated with this reader. More...

void	wait_for_historical_data (const dds::core::Duration &max_wait)
	Waits until all "historical" data is received for DataReaders that have a non-VOLATILE Durability Qos kind. More...

dds::core::status::LivelinessChangedStatus	liveliness_changed_status () const
	Get the LivelinessChangedStatus for this DataReader. More...

dds::core::status::SampleRejectedStatus	sample_rejected_status () const
	Get the SampleRejectedStatus for this DataReader. More...

dds::core::status::SampleLostStatus	sample_lost_status () const
	Get the SampleLostStatus for this DataReader. More...

dds::core::status::RequestedDeadlineMissedStatus	requested_deadline_missed_status ()
	Get the RequestedDeadlineMissedStatus for this DataReader. More...

dds::core::status::RequestedIncompatibleQosStatus	requested_incompatible_qos_status () const
	Get the RequestedIncompatibleQosStatus for this DataReader. More...

dds::core::status::SubscriptionMatchedStatus	subscription_matched_status () const
	Get the SubscriptionMatchedStatus for this DataReader. More...

rti::core::status::DataReaderCacheStatus	datareader_cache_status () const
	<<extension>> Get the DataReaderCacheStatus for this DataReader More...

rti::core::status::DataReaderProtocolStatus	datareader_protocol_status () const
	<<extension>> Get the DataReaderProtocolStatus for this DataReader More...

rti::core::status::DataReaderProtocolStatus	matched_publication_datareader_protocol_status (const dds::core::InstanceHandle &publication_handle)
	<<extension>> Get the DataReaderProtocolStatus for this DataReader More...

void	acknowledge_all ()
	<<extension>> Acknowledge all previously accessed samples More...

void	acknowledge_all (const AckResponseData &response_data)
	<<extension>> Acknowledge all previously accessed samples More...

void	acknowledge_sample (const dds::sub::SampleInfo &sample_info)
	<<extension>> Acknowledge a single sample explicitly More...

void	acknowledge_sample (const dds::sub::SampleInfo &sample_info, const AckResponseData &response_data)
	<<extension>> Acknowledge a single sample explicitly More...

void	close_contained_entities ()
	<<extension>> Closes all the entities created from this DataReader More...

rti::core::Result< dds::sub::LoanedSamples< T > >	read_noexcept () noexcept
	<<extension>> Alternative to read() that doesn't throw exceptions. More...

rti::core::Result< dds::sub::LoanedSamples< T > >	take_noexcept () noexcept
	<<extension>> Alternative to take() that doesn't throw exceptions. More...

bool	read (T &sample)
	<<extension>> Copies the next not-previously-accessed valid data value from the DataReader via a read operation. More...

bool	read (T &sample, dds::sub::SampleInfo &sample_info)
	<<extension>> Copies the next not-previously-accessed data value from the DataReader via a read operation. More...

bool	take (T &sample)
	<<extension>> Copies the next not-previously-accessed valid data value from the DataReader via a take operation. More...

bool	take (T &sample, dds::sub::SampleInfo &sample_info)
	<<extension>> Copies the next not-previously-accessed data value from the DataReader via a take operation. More...

bool	is_data_consistent (const T &sample, const dds::sub::SampleInfo &sample_info)
	<<extension>> Checks if the sample has been overwritten by the DataWriter More...

bool	is_data_consistent (const rti::sub::LoanedSample< T > &sample)
	<<extension>> Checks if the sample has been overwritten by the DataWriter More...

const std::string &	topic_name () const
	<<extension>> Get the topic name associated with this DataReader More...

const std::string &	type_name () const
	<<extension>> Get the type name associated with this DataReader More...

void	close ()
	Close this DataReader. More...

Public Member Functions inherited from dds::core::Entity
void	enable ()
	Enables this entity (if it was created disabled) More...

const dds::core::status::StatusMask	status_changes ()
	Retrieves the list of communication statuses that are triggered. More...

const dds::core::InstanceHandle	instance_handle () const
	Get the instance handle that represents this entity. More...

void	close ()
	Forces the destruction of this entity. More...

void	retain ()
	Disables the automatic destruction of this entity. More...

Related Functions
(Note that these are not member functions.)
bool	read (dds::sub::ReadModeDummyType)
	The stream manipulator to indicate that the reader should read samples as opposed to taking the samples. More...

bool	take (dds::sub::ReadModeDummyType)
	The stream manipulator to indicate that the reader should take samples as opposed to reading the samples. More...

dds::sub::functors::MaxSamplesManipulatorFunctor	max_samples (uint32_t n)
	Stream manipulator to set the maximum number of samples to read or take. More...

dds::sub::functors::ContentFilterManipulatorFunctor	content (const dds::sub::Query &query)
	Stream manipulator to set a Query to use during the subsequent read/take operation. More...

dds::sub::functors::ConditionManipulatorFunctor	condition (const dds::sub::cond::ReadCondition &condition)
	Stream manipulator to set a QueryCondition to use during the subsequent read/take operation. More...

dds::sub::functors::StateFilterManipulatorFunctor	state (const dds::sub::status::DataState &s)
	Stream manipulator to specify the DataState of the samples that should be read/taken. More...

dds::sub::functors::InstanceManipulatorFunctor	instance (const dds::core::InstanceHandle &h)
	Stream manipulator to specify the instance whose samples should be read or taken. More...

dds::sub::functors::NextInstanceManipulatorFunctor	next_instance (const dds::core::InstanceHandle &h)
	Stream manipulator to specify the samples belonging to the 'next' instance after the provided instance handle should be accessed. More...

void	ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle)
	Instructs RTI Connext to locally ignore a subscription. More...

template<typename FwdIterator >
void	ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end)
	Instructs RTI Connext to locally ignore subscriptions. More...

template<typename T >
const ::dds::core::InstanceHandleSeq	matched_publications (const dds::sub::DataReader< T > &reader)
	Retrieve the list of publications currently "associated" with a DataReader. More...

template<typename T , typename FwdIterator >
FwdIterator	matched_publications (const dds::sub::DataReader< T > &reader, FwdIterator begin, FwdIterator end)
	Retrieve the list of publications currently "associated" with a DataReader. More...

template<typename T >
const dds::topic::PublicationBuiltinTopicData	matched_publication_data (const dds::sub::DataReader< T > &reader, const dds::core::InstanceHandle &handle)
	This operation retrieves the information on a publication that is currently "associated" with the DataReader. More...

template<typename T >
dds::topic::ParticipantBuiltinTopicData	matched_publication_participant_data (const dds::sub::DataReader< T > &reader, const dds::core::InstanceHandle &handle)
	<<extension>> This operation retrieves the information on the discovered dds::domain::DomainParticipant associated with the publication that is currently matching with the dds::sub::DataReader. More...

template<typename T >
bool	is_matched_publication_alive (const dds::sub::DataReader< T > &reader, const dds::core::InstanceHandle &handle)
	<<extension>> Check if a matched publication is alive. More...

template<typename T >
std::vector< dds::topic::PublicationBuiltinTopicData >	matched_publication_data (const dds::sub::DataReader< T > &reader)
	<<extension>> Obtain the PublicationBuiltinTopicData for all of the publications matched with a DataReader. More...

template<typename Reader , typename FwdIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const std::string &topic_name, FwdIterator begin, uint32_t max_size)
	This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic name. More...

template<typename Reader , typename BinIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const std::string &topic_name, BinIterator begin)
	This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic name. More...

template<typename READER , typename T , typename FwdIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const dds::topic::TopicDescription< T > &topic_description, FwdIterator begin, uint32_t max_size)

template<typename READER , typename T , typename BinIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const dds::topic::TopicDescription< T > &topic_description, BinIterator begin)
	This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching TopicDescription. More...

template<typename AnyDataReaderBackInsertIterator >
uint32_t	find_datareaders (dds::sub::Subscriber subscriber, AnyDataReaderBackInsertIterator begin)
	<<extension>> Retrieve all the dds::sub::DataReader created from this dds::sub::Subscriber More...

template<typename AnyDataReaderForwardIterator >
uint32_t	find_datareaders (dds::sub::Subscriber subscriber, AnyDataReaderForwardIterator begin, uint32_t max_size)
	<<extension>> Retrieve all the readers created from a subscriber. More...

template<typename Reader >
Reader	find_datareader_by_topic_name (dds::sub::Subscriber subscriber, const std::string &topic_name)
	<<extension>> Retrieves a dds::sub::DataReader with the given topic name within the dds::sub::Subscriber More...

template<typename Reader >
Reader	find_datareader_by_name (dds::sub::Subscriber subscriber, const std::string &datareader_name)
	<<extension>> Retrieves a dds::sub::DataReader with the given name within the dds::sub::Subscriber More...

template<typename Reader , typename T >
Reader	find_datareader_by_topic_description (const dds::sub::Subscriber &subscriber, const dds::topic::TopicDescription< T > &topic_description)
	<<extension>> Retrieves a dds::sub::DataReader with the given TopicDescription within the dds::sub::Subscriber More...

template<typename Reader >
Reader	find_datareader_by_name (dds::domain::DomainParticipant participant, const std::string &datareader_name)
	<<extension>> Retrieves a dds::sub::DataReader within the dds::domain::DomainParticipant with the given name More...

Related Functions inherited from dds::core::Entity
template<typename TO , typename FROM >
TO	polymorphic_cast (const FROM &from)
	Downcasts an Entity to a subclass. More...

Detailed Description

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

<<reference-type>> Allows the application to: (1) declare the data it wishes to receive (i.e. make a subscription) and (2) access the data received by the attached dds::sub::Subscriber.

Template Parameters

T	The topic-type that the DataReader subscribes to

QoS:: dds::sub::qos::DataReaderQos

Status:: dds::core::status::StatusMask::data_available();
dds::core::status::StatusMask::liveliness_changed(), dds::core::status::LivelinessChangedStatus;
dds::core::status::StatusMask::requested_deadline_missed(), dds::core::status::RequestedDeadlineMissedStatus;
dds::core::status::StatusMask::requested_incompatible_qos(), dds::core::status::RequestedIncompatibleQosStatus;
dds::core::status::StatusMask::sample_lost(), dds::core::status::SampleLostStatus;
dds::core::status::StatusMask::sample_rejected(), dds::core::status::SampleRejectedStatus;
dds::core::status::StatusMask::subscription_matched(), dds::core::status::SubscriptionMatchedStatus;

Listener:: dds::sub::DataReaderListener

A dds::sub::DataReader refers to exactly one TopicDescription (either a dds::topic::Topic, a dds::topic::ContentFilteredTopic or a MultiTopic) that identifies the data to be read.

The subscription has a unique resulting type. The data-reader may give access to several instances of the resulting type, which can be distinguished from each other by their key.

The following operations may be called even if the dds::sub::DataReader is not enabled. Other operations will fail with the value dds::core::NotEnabledError if called on a disabled dds::sub::DataReader:

dds::sub::DataReader::qos(const dds::sub::qos::DataReaderQos&), dds::sub::DataReader::qos() const, dds::sub::DataReader::set_listener, dds::sub::DataReader::get_listener, dds::core::Entity::enable, dds::core::cond::StatusCondition::StatusCondition(const dds::core::Entity&), dds::core::Entity::status_changes(), dds::sub::DataReader::liveliness_changed_status, dds::sub::DataReader::requested_deadline_missed_status, dds::sub::DataReader::requested_incompatible_qos_status, dds::sub::DataReader::sample_lost_status, dds::sub::DataReader::sample_rejected_status, dds::sub::DataReader::subscription_matched_status

All sample-accessing operations may fail with the expection dds::core::PreconditionNotMetError as described in dds::sub::CoherentAccess::CoherentAccess().

See also: Operations Allowed in Listener Callbacks; Access to data samples; DataReader Use Cases; Entity Use Cases

Examples: Foo_subscriber.cxx.

Constructor & Destructor Documentation

◆ DataReader() [1/6]

template<typename T >

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

inline

Create a DataReader.

It uses the default DataReaderQos, and no listener.

Parameters

sub	the Subscriber owning this DataReader.
topic	the Topic associated with this DataReader.

◆ DataReader() [2/6]

template<typename T >

dds::sub::DataReader< T >::DataReader	(	const dds::sub::Subscriber &	sub,
		const dds::topic::Topic< T > &	topic,
		const dds::sub::qos::DataReaderQos &	the_qos,
		dds::sub::DataReaderListener< T > *	the_listener = `NULL`,
		const dds::core::status::StatusMask &	mask = `dds::core::status::StatusMask::all()`
	)

inline

Create a DataReader.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

When a DataReader is created, only those transports already registered are available to the DataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.

MT Safety:: UNSAFE. If the qos parameter is omitted it is not safe to create the datareader while another thread may be simultaneously calling dds::sub::Subscriber::default_datareader_qos(dds::sub::qos::DataReaderQos).

Precondition: If sub is enabled, the topic must be enabled. If it is not, this operation will fail and no DataReader will be created.; The given dds::topic::Topic must have been created from the same participant as this subscriber. If it was created from a different participant no DataReader will be created.

Parameters

sub	the Subscriber owning this DataReader.
topic	the Topic associated with this DataReader.
the_qos	the QoS settings for this DataReader.
the_listener	the listener.
mask	the event mask associated to the DataReader listener.

See also: Specifying QoS on entities for information on setting QoS before entity creation; dds::sub::qos::DataReaderQos for rules on consistency among QoS; dds::core::QosProvider::datareader_qos(); dds::sub::qos::DataReaderQos::operator=(const dds::topic::qos::TopicQos&) which allows assigning the contents of a TopicQos into a DataReaderQos; listener()

◆ DataReader() [3/6]

template<typename T >

dds::sub::DataReader< T >::DataReader	(	const dds::sub::Subscriber &	sub,
		const dds::topic::Topic< T > &	topic,
		const dds::sub::qos::DataReaderQos &	the_qos,
		std::shared_ptr< Listener >	the_listener,
		const dds::core::status::StatusMask &	mask = `dds::core::status::StatusMask::all()`
	)

inline

Create a DataReader.

When a DataReader is created, only those transports already registered are available to the DataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.

MT Safety:: UNSAFE. If the qos parameter is omitted it is not safe to create the datareader while another thread may be simultaneously calling dds::sub::Subscriber::default_datareader_qos(dds::sub::qos::DataReaderQos).

Precondition: If sub is enabled, the topic must be enabled. If it is not, this operation will fail and no DataReader will be created.; The given dds::topic::Topic must have been created from the same participant as this subscriber. If it was created from a different participant no DataReader will be created.

Parameters

sub	the Subscriber owning this DataReader.
topic	the Topic associated with this DataReader.
the_qos	the QoS settings for this DataReader.
the_listener	A shared_ptr to the listener. See set_listener() for more information.
mask	Indicates which status updates the listener will receive

See also: Specifying QoS on entities for information on setting QoS before entity creation; dds::sub::qos::DataReaderQos for rules on consistency among QoS; dds::core::QosProvider::datareader_qos(); dds::sub::qos::DataReaderQos::operator=(const dds::topic::qos::TopicQos&) which allows assigning the contents of a TopicQos into a DataReaderQos

◆ DataReader() [4/6]

template<typename T >

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

inline

Create a DataReader for a dds::topic::ContentFilteredTopic.

This DataReader will only receive that data that matches the Filter associated with the ContentFilteredTopic. The QoS will be set to sub.default_datareader_qos().

Parameters

sub	the Subscriber owning this DataReader.
topic	the content filtered topic

◆ DataReader() [5/6]

template<typename T >

dds::sub::DataReader< T >::DataReader	(	const dds::sub::Subscriber &	sub,
		const dds::topic::ContentFilteredTopic< T > &	topic,
		const dds::sub::qos::DataReaderQos &	the_qos,
		dds::sub::DataReaderListener< T > *	the_listener = `NULL`,
		const dds::core::status::StatusMask &	mask = `dds::core::status::StatusMask::all()`
	)

inline

Create a DataReader for a dds::topic::ContentFilteredTopic.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

This DataReader will only receive that data that mathes the Filter associated with the ContentFilteredTopic.

Parameters

sub	the subscriber owning this DataReader.
topic	the content filtered topic.
the_qos	the QoS settings for this DataReader.
the_listener	the listener.
mask	the event mask associated to the DataReader listener.

◆ DataReader() [6/6]

template<typename T >

dds::sub::DataReader< T >::DataReader	(	const dds::sub::Subscriber &	sub,
		const dds::topic::ContentFilteredTopic< T > &	topic,
		const dds::sub::qos::DataReaderQos &	the_qos,
		std::shared_ptr< Listener >	the_listener,
		const dds::core::status::StatusMask &	mask = `dds::core::status::StatusMask::all()`
	)

inline

Create a DataReader for a dds::topic::ContentFilteredTopic with a listener.

This DataReader will only receive that data that mathes the Filter associated with the ContentFilteredTopic.

Parameters

sub	the subscriber owning this DataReader.
topic	the content filtered topic.
the_qos	the QoS settings for this DataReader.
the_listener	the listener.
mask	the event mask associated to the DataReader listener.

Member Function Documentation

◆ default_filter_state() [1/2]

template<typename T >

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

inline

Returns the default state for read/take operations.

If left as default, it is set to dds::sub::status::DataState::any().

◆ default_filter_state() [2/2]

template<typename T >

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

inline

Set the default state filter for read/take operations.

Parameters

state the state mask that will be used to read/take samples.

◆ operator>>() [1/4]

template<typename T >

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

inline

Use the stream operator to take samples, placing them into a LoanedSamples container.

For example:

reader >> loaned_samples;

If you want to read samples, instead of take, you must use the stream manipulator read(dds::sub::ReadModeDummyType) and operator>>(bool(*manipulator)(ReadModeDummyType))

For example:

reader >> read >> loaned_samples;

dds::sub::DataReader::read

LoanedSamples< T > read()

Read all samples using the default filter state.

Definition: TDataReader.hpp:991

Parameters

ls	The LoanedSamples container to put the taken samples into

See also: operator>>(bool(*manipulator)(ReadModeDummyType)); operator>>(Functor f); Accessing Received Data

◆ operator>>() [2/4]

template<typename T >

ManipulatorSelector dds::sub::DataReader< T >::operator>> ( bool(*)(ReadModeDummyType) manipulator )

inline

Use the stream operator to read or take samples.

The read and take manipulators are defined externally to make it possible to control whether the stream operators reads or takes.

This stream operator can be chained together with operator>>(Functor f) to set other various properties of the read/take operation.

It is used as follows:

dr >> read >> loanedSamples;

dr >> take >> loanedSamples;

dds::sub::DataReader::take

LoanedSamples< T > take()

Take all samples using the default filter state.

Definition: TDataReader.hpp:1004

If either the read or take manipulator is not passed into the stream, the default behavior is to take.

Parameters

manipulator Either read or take

See also: operator>>(Functor f); operator>>(dds::sub::LoanedSamples<T>& ls); ReadModeDummyType; Accessing Received Data

◆ operator>>() [3/4]

template<typename T >

template<typename Functor >

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

inline

Use the stream operator to dictate the behavior of the read or take operation.

There are a number of pre-defined stream manipulators (functions which return a functor that will be used by the stream operator). They dictate how the samples will be read or taken:

max_samples: Read/Take up to a maximum number of samples
content: Read/Take using a Query
condition: Read/Take using a dds::sub::cond::ReadCondition
state: Read/Take only samples with a specific DataState
instance: Read/Take a specific instance
next_instance: Read/Take the next instance after a specified instance

For example, to read up to 10 samples that have not been read before:

dr >> read
   >> max_samples(10)
   >> state(DataState::new_data())
   >> loanedSamples;

Parameters

f	Each of the stream manipulators listed above return a Functor that will be passed to the stream operator. These Functors do not need to be accessed by the user directly. They should instead be passed indirectly via the return value of one of the provided stream manipulators.

See also: dds::sub::max_samples(uint32_t n); dds::sub::content(const dds::sub::Query& query); dds::sub::condition(const dds::sub::cond::ReadCondition& query_condition); dds::sub::state(const dds::sub::status::DataState& s); dds::sub::instance(const dds::core::InstanceHandle& h); dds::sub::next_instance(const dds::core::InstanceHandle& h); Accessing Received Data

◆ read() [1/5]

template<typename T >

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

inline

Read all samples using the default filter state.

This operation offers the same functionality and API as dds::sub::DataReader::take except that the samples returned remain in the dds::sub::DataReader such that they can be retrieved again by means of a read or take operation.

Please refer to the documentation of dds::sub::DataReader::take for details on the number of samples returned as well as the order in which the samples appear in these sequences.

The act of reading a sample changes its sample_state to dds::sub::status::SampleState::read(). If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to be dds::sub::status::ViewState::not_new_view(). It will not affect the instance_state of the instance.

Once the application completes its use of the samples, it must 'return the loan' to the dds::sub::DataReader by calling the dds::sub::LoanedSamples::return_loan() operation. The dds::sub::LoanedSamples destructor also takes care of returning the loan for you, so calling dds::sub::LoanedSamples::return_loan() explicitly is not required.

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the dds::sub::SampleInfo objects after the call to dds::sub::LoanedSamples::return_loan(). Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call dds::sub::LoanedSamples::return_loan() at some point, you do not have to do so before the next dds::sub::DataReader::take call. However, failure to return the loan will eventually deplete the dds::sub::DataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the dds::sub::DataReader is specified by the dds::core::policy::ResourceLimits and the rti::core::policy::DataReaderResourceLimits.

Important: If the samples "returned" by this method are loaned from RTI Connext (see dds::sub::DataReader::take for more information on memory loaning), it is important that their contents not be changed. Because the memory in which the data is stored belongs to the middleware, any modifications made to the data will be seen the next time the same samples are read or taken; the samples will no longer reflect the state that was received from the network.

Exceptions

One	of the Standard Exceptions, dds::core::PreconditionNotMetError, dds::core::NotEnabledError.

See also: dds::sub::DataReader::take; Accessing Received Data; select()

◆ take() [1/5]

template<typename T >

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

inline

Take all samples using the default filter state.

The operation will return the list of samples received by the dds::sub::DataReader since the last dds::sub::DataReader::take operation that matches the specified SampleStateMask, ViewStateMask and InstanceStateMask.

This operation may fail with dds::core::Error if the rti::core::policy::DataReaderResourceLimits::max_outstanding_reads limit has been exceeded.

The actual number of samples returned depends on the information that has been received by the middleware as well as the dds::core::policy::History, dds::core::policy::ResourceLimits, rti::core::policy::DataReaderResourceLimits and the characteristics of the data-type that is associated with the dds::sub::DataReader:

In the case where the dds::core::policy::History::kind is dds::core::policy::HistoryKind::KEEP_LAST, the call will return at most dds::core::policy::History::depth samples for each ALIVE instance and (dds::core::policy::History::depth +1) samples for each NOT_ALIVE instance. The extra sample is an invalid sample (dds::sub::SampleInfo::valid is FALSE) that is used to indicate the instance state transition from ALIVE to NOT_ALIVE.

The maximum number of samples returned is limited by dds::core::policy::ResourceLimits::max_samples, and by rti::core::policy::DataReaderResourceLimits::max_samples_per_read.

For multiple instances, the number of samples returned is additionally limited by the product (dds::core::policy::ResourceLimits::max_samples_per_instance
- dds::core::policy::ResourceLimits::max_instances)

If rti::core::policy::DataReaderResourceLimits::max_infos is limited, the number of samples returned may also be limited if insufficient dds::sub::SampleInfo resources are available.

If the read or take succeeds and the number of samples returned has been limited (by means of a maximum limit, as listed above, or insufficient dds::sub::SampleInfo resources), the call will complete successfully and provide those samples the reader is able to return. The user may need to make additional calls, or return outstanding loaned buffers in the case of insufficient resources, in order to access remaining samples.

Note that in the case where the dds::topic::Topic associated with the dds::sub::DataReader is bound to a data-type that has no key definition, then there will be at most one instance in the dds::sub::DataReader. So the per-sample limits will apply.

The act of taking a sample removes it from RTI Connext so it cannot be read or taken again. If the sample belongs to the most recent generation of the instance, it will also set the view_state of the sample's instance to dds::sub::status::ViewState::not_new_view(). It will not affect the instance_state of the sample's instance.

Once the application completes its use of the samples it must 'return the loan' to the dds::sub::DataReader by calling the dds::sub::LoanedSamples::return_loan() operation. The dds::sub::LoanedSamples destructor also takes care of returning the loan for you, so calling dds::sub::LoanedSamples::return_loan() explicitly is not required.

Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the dds::sub::SampleInfo objects after the call to dds::sub::LoanedSamples::return_loan(). Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.

Note: While you must call dds::sub::LoanedSamples::return_loan() at some point, you do not have to do so before the next dds::sub::DataReader::take call. However, failure to return the loan will eventually deplete the dds::sub::DataReader of the buffers it needs to receive new samples and eventually samples will start to be lost. The total number of buffers available to the dds::sub::DataReader is specified by the dds::core::policy::ResourceLimits and the rti::core::policy::DataReaderResourceLimits.

To copy samples from the reader instead of taking a loan, you can use any of the read or take operations that receive an iterator to a container in which to copy the samples:

The order of the samples returned to the caller depends on the dds::core::policy::Presentation.

If dds::core::policy::Presentation::access_scope is dds::core::policy::PresentationAccessScopeKind_def::INSTANCE, the returned collection is a list where samples belonging to the same data instance are consecutive.

If dds::core::policy::Presentation::access_scope is dds::core::policy::PresentationAccessScopeKind_def::TOPIC and dds::core::policy::Presentation::ordered_access is set to false, then the returned collection is a list where samples belonging to the same data instance are consecutive.

If dds::core::policy::Presentation::access_scope is dds::core::policy::PresentationAccessScopeKind_def::TOPIC and dds::core::policy::Presentation::ordered_access is set to true, then the returned collection is a list where the relative order of samples as they were written by a DataWriter is preserved also across different instances. In other words, changes made by a single DataWriter are made available to subscribers in the same order in which they occur. Samples belonging to the same instance may or may not be consecutive. This is because, to preserve order within a single DataWriter, it may be necessary to mix samples from different instances.

If dds::core::policy::Presentation::access_scope is dds::core::policy::PresentationAccessScopeKind_def::GROUP and dds::core::policy::Presentation::ordered_access is set to false, then the returned collection is a list where samples belonging to the same data instance are consecutive.

If dds::core::policy::Presentation::access_scope is dds::core::policy::PresentationAccessScopeKind_def::GROUP and dds::core::policy::Presentation::ordered_access is set to true, then changes made to instances by a set of DataWriters attached to a common Publisher are made available in the order in which they were written. For this to happen, the application must take the samples using the Subscriber's dds::sub::CoherentAccess::CoherentAccess() and dds::sub::CoherentAccess::end() operations (see the "Ordered Access" section in the "PRESENTATION QosPolicy" section of the Core Libraries User's Manual).

In all of the above cases, the relative order between the samples of one instance is consistent with the DESTINATION_ORDER policy:

If dds::core::policy::DestinationOrder::kind is dds::core::policy::DestinationOrderKind::BY_RECEPTION_TIMESTAMP, samples belonging to the same instances will appear in the relative order in which there were received (FIFO, earlier samples ahead of the later samples).

If dds::core::policy::DestinationOrder::kind is dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP, samples belonging to the same instances will appear in the relative order implied by the source_timestamp (FIFO, smaller values of source_timestamp ahead of the larger values).

In addition to the collection of samples, the read and take operations also use a collection of dds::sub::SampleInfo structures.

Some elements in the returned collection may not have valid data. If the instance_state in the dds::sub::SampleInfo is dds::sub::status::InstanceState::not_alive_disposed() or dds::sub::status::InstanceState::not_alive_no_writers(), then the last sample for that instance in the collection (that is, the one whose dds::sub::SampleInfo has sample_rank==0) does not contain valid data.

Samples that contain no data do not count towards the limits imposed by the dds::core::policy::ResourceLimits. The act of reading/taking a sample sets its sample_state to dds::sub::status::SampleState::read().

If the sample belongs to the most recent generation of the instance, it will also set the view_state of the instance to dds::sub::status::ViewState::not_new_view(). It will not affect the instance_state of the instance.

For an example on how take can be used, please refer to the Accessing Received Data "receive example".

Exceptions

One	of the Standard Exceptions, dds::core::PreconditionNotMetError, dds::core::NotEnabledError.

See also: dds::sub::DataReader::read; Accessing Received Data; select()

Examples: Foo_subscriber.cxx.

◆ read() [2/5]

template<typename T >

template<typename SamplesFWIterator >

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

inline

Read up to max_samples samples using the default filter state.

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

Template Parameters

SamplesFWIterator A forward iterator whose value type is dds::sub::Sample<T>

Parameters

sfit	samples forward iterator
max_samples	the maximum number of samples to read

Returns: uint32_t the number of read samples.

See also: read(); Accessing Received Data

◆ take() [2/5]

template<typename T >

template<typename SamplesFWIterator >

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

inline

Take up to max_samples samples using the default filter state.

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

Template Parameters

SamplesFWIterator A forward iterator whose value type is dds::sub::Sample<T>

Parameters

sfit	samples forward iterator.
max_samples	the maximum number of samples to take.

Returns: uint32_t The number of taken samples.

See also: take(); Accessing Received Data

◆ read() [3/5]

template<typename T >

template<typename SamplesBIIterator >

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

inline

Read all samples available in the reader cache using the default filter state.

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.

Template Parameters

SamplesBIIterator A back-inserting iterator whose value type is dds::sub::Sample<T>.

Parameters

sbit	samples back-inserting iterator.

Returns: uint32_t the number of read samples.

For example:

std::vector<Foo> samples;
// inserts copies of all available samples at the end of 'samples'
uint32_t count = reader.read(std::back_inserter(samples));
assert(count == samples.size());

Note: This function should not be confused with read(T& sample), an extension function that reads a single sample and assigns it to the argument.

See also: read(); Accessing Received Data

◆ take() [3/5]

template<typename T >

template<typename SamplesBIIterator >

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

inline

Take all samples available in the reader cache samples using the default filter state.

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.

Template Parameters

SamplesBIIterator A back-inserting iterator whose value type is dds::sub::Sample<T>

Parameters

sbit	samples back-inserting iterator.

Returns: the number of taken samples.

Note: This function should not be confused with take(T& sample), an extension function that takes a single sample and assigns it to the argument.

See also: take(); Accessing Received Data

◆ select()

template<typename T >

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

inline

Get a Selector to perform complex data selections, such as per-instance selection, content and status filtering.

The selector can be used as follows:

LoanedSamples<Foo> samples = reader.select()
    .instance(handle)
    .content(query)
    .state(state)
    .take();

This shows how samples can be taken by selecting a specific instance, then filtering by state and content.

Note that when the application wants to access all available samples it can simply call DataReader::read() or DataReader::take().

Returns: A Selector, typically used in-line to configure it and finally call Selector::read() or Selector::take().

See also: Selector, for the different parameters that can be set to configure what samples to read or take.; Selecting what samples to read

◆ key_value() [1/2]

template<typename T >

T & dds::sub::DataReader< T >::key_value	(	T &	key_holder,
		const dds::core::InstanceHandle &	handle
	)

inline

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance.

For keyed data types, this operation may fail with dds::core::InvalidArgumentError if the handle does not correspond to an existing data-object known to the DataReader.

Parameters

key_holder A user data type specific key holder of type T whose key fields are filled by this operation. If T has no key, this operation has no effect.

handle The instance whose key is to be retrieved. If T has a key, handle must represent an existing instance of type T known to the DataReader. Otherwise, this method will fail with dds::core::InvalidArgumentError. If T has a key and handle is dds::core::InstanceHandle::nil(), this method will fail with dds::core::InvalidArgumentError. If T has a key and handle represents an instance of another type or an instance of type T that has been unregistered, this method will fail with dds::core::InvalidArgumentError. If T has no key, this method has no effect.

◆ key_value() [2/2]

template<typename T >

dds::topic::TopicInstance< T > & dds::sub::DataReader< T >::key_value	(	dds::topic::TopicInstance< T > &	key_holder,
		const dds::core::InstanceHandle &	handle
	)

inline

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance.

For keyed data types, this operation may fail with dds::core::InvalidArgumentError if the handle does not correspond to an existing data-object known to the DataReader.

Parameters

key_holder A TopicInstance whose sample's key fields are filled by this operation. If T does not have a key, this method has no effect.

handle The instance whose key is to be retrieved. If T has a key, handle must represent an existing instance of type T known to the DataReader. Otherwise, this method will fail with dds::core::InvalidArgumentError. If T has a key and handle is dds::core::InstanceHandle::nil(), this method will fail with dds::core::InvalidArgumentError. If T has a key and handle represents an instance of another type or an instance of type T that has been unregistered, this method will fail with dds::core::InvalidArgumentError. If T has no key, this method has no effect.

◆ lookup_instance()

template<typename T >

dds::core::InstanceHandle dds::sub::DataReader< T >::lookup_instance ( const T & key_holder ) const

inline

Retrieve the InstanceHandle that corresponds to an instance key holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. If the instance is unknown to the DataReader, or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value dds::core::InstanceHandle::nil().

Parameters

key_holder <<in>> a user data type specific key holder.

Returns: the instance handle associated with this instance. If T has no key, this method has no effect and returns dds::core::InstanceHandle::nil()

◆ topic_description()

template<typename T >

dds::topic::TopicDescription< DataType > dds::sub::DataReader< T >::topic_description ( ) const

inline

Returns the dds::topic::TopicDescription associated with the DataReader.

Returns that same TopicDescription that was used to create the dds::sub::DataReader.

Returns: TopicDescription associated with the dds::sub::DataReader.

◆ subscriber()

template<typename T >

const dds::sub::Subscriber & dds::sub::DataReader< T >::subscriber ( ) const

inline

Returns the Subscriber to which the DataReader belongs.

◆ listener() [1/2]

template<typename T >

void dds::sub::DataReader< T >::listener	(	Listener *	the_listener,
		const dds::core::status::StatusMask &	event_mask
	)

inline

Sets the listener associated with this reader.

[DEPRECATED] The use of set_listener() is recommended. Unlike this function, set_listener receives a shared_ptr which simplifies the management of listener's lifecycle.

Parameters

the_listener	The DataReaderListener to set
event_mask	The dds::core::status::StatusMask associated with the listener

◆ listener() [2/2]

template<typename T >

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

inline

Returns the listener currently associated with this DataReader.

[DEPRECATED] Prefer get_listener() instead of this function.

If there's no listener it returns NULL.

◆ set_listener() [1/2]

template<typename T >

void dds::sub::DataReader< T >::set_listener	(	std::shared_ptr< Listener >	the_listener,
		const dds::core::status::StatusMask &	event_mask
	)

inline

Sets the listener associated with this reader.

The DataReader will hold a shared_ptr to the listener argument, ensuring that it is not deleted at least until this DataReader is deleted or the listener is reset with set_listener(nullptr).

Warning: It's recommended that the listener implementation doesn't hold a permanent reference to the reader. If it does, the application needs to manually reset the listener or manually close this DataReader to ensure that there is no cycle that prevents the destruction of these two objects.

Parameters

the_listener	A shared pointer to the listener to receive status updates or `nullptr` to reset the current listener and stop receiving status updates.
event_mask	A mask that indicates which status updates will be notified to the listener

◆ set_listener() [2/2]

template<typename T >

void dds::sub::DataReader< T >::set_listener ( std::shared_ptr< Listener > the_listener )

inline

Sets the listener associated with this reader.

If the_listener is not nullptr, this overload is equivalent to:

reader.set_listener(the_listener, dds::core::status::StatusMask::all());

dds::core::status::StatusMask::all

static const StatusMask all()

All the bits are set.

Definition: State.hpp:168

If the_listener is nullptr, it is equivalent to:

reader.set_listener(nullptr, dds::core::status::StatusMask::none());

dds::core::status::StatusMask::none

static const StatusMask none()

No bits are set.

Definition: State.hpp:176

Parameters

the_listener A shared pointer to the listener to receive status updates or nullptr to reset the current listener and stop receiving status updates.

◆ get_listener()

template<typename T >

std::shared_ptr< Listener > dds::sub::DataReader< T >::get_listener ( ) const

inline

Returns the listener currently associated with this DataReader.

Returns: The shared pointer to the current listener or nullptr if there is currently no listener associated to this entity.

◆ qos() [1/2]

template<typename T >

const dds::sub::qos::DataReaderQos dds::sub::DataReader< T >::qos ( ) const

inline

Get the QoS associated with this reader.

◆ qos() [2/2]

template<typename T >

void dds::sub::DataReader< T >::qos ( const dds::sub::qos::DataReaderQos & the_qos )

inline

Set the QoS associated with this reader.

This operation modifies the QoS of the DataReader.

The dds::core::policy::UserData, dds::core::policy::Deadline, dds::core::policy::LatencyBudget, dds::core::policy::TimeBasedFilter, dds::core::policy::ReaderDataLifecycle can be changed. The other policies are immutable.

Parameters

the_qos The DataReaderQos to be set to. Policies must be consistent. Immutable policies cannot be changed after the DataReader is enabled. dds::sub::Subscriber::default_datareader_qos() can be used to set the QoS of the DataReader to match the current default DataReaderQos set in the Subscriber.

Exceptions

dds::core::ImmutablePolicyError,or dds::core::InconsistentPolicyError.,

See also: dds::sub::qos::DataReaderQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

◆ operator<<()

template<typename T >

DataReader & dds::sub::DataReader< T >::operator<< ( const dds::sub::qos::DataReaderQos & the_qos )

inline

Set the QoS associated with this reader.

Parameters

the_qos the new qos for this DataReader.

See also: qos(const dds::sub::qos::DataReaderQos& qos)

◆ operator>>() [4/4]

template<typename T >

DataReader & dds::sub::DataReader< T >::operator>> ( dds::sub::qos::DataReaderQos & the_qos )

inline

Get the QoS associated with this reader.

Parameters

the_qos the object to populate with the qos for this DataWriter.

See also: qos()

◆ wait_for_historical_data()

template<typename T >

void dds::sub::DataReader< T >::wait_for_historical_data ( const dds::core::Duration & max_wait )

inline

Waits until all "historical" data is received for DataReaders that have a non-VOLATILE Durability Qos kind.

This operation is intended only for dds::sub::DataReader entities that have a non-VOLATILE Durability QoS kind.

As soon as an application enables a non-VOLATILE dds::sub::DataReader, it will start receiving both "historical" data (i.e., the data that was written prior to the time the dds::sub::DataReader joined the domain) as well as any new data written by the dds::pub::DataWriter entities. 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 dds::sub::DataReader::wait_for_historical_data operations.

dds::sub::DataReader::wait_for_historical_data() blocks the calling thread until either all "historical" data is received, or until the duration specified by the max_wait parameter elapses, whichever happens first. It will return immediately if no DataWriters have been discovered at the time the operation is called; therefore it is advisable to make sure at least one dds::pub::DataWriter has been discovered before calling this operation. (One way to do this is by using dds::sub::DataReader::subscription_matched_status.)

A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.

Parameters

max_wait <<in>> Timeout value.

Exceptions

One	of the Standard Exceptions, dds::core::TimeoutError or dds::core::NotEnabledError.

◆ liveliness_changed_status()

template<typename T >

dds::core::status::LivelinessChangedStatus dds::sub::DataReader< T >::liveliness_changed_status ( ) const

inline

Get the LivelinessChangedStatus for this DataReader.

See also: dds::core::status::LivelinessChangedStatus

◆ sample_rejected_status()

template<typename T >

dds::core::status::SampleRejectedStatus dds::sub::DataReader< T >::sample_rejected_status ( ) const

inline

Get the SampleRejectedStatus for this DataReader.

See also: dds::core::status::SampleRejectedStatus

◆ sample_lost_status()

template<typename T >

dds::core::status::SampleLostStatus dds::sub::DataReader< T >::sample_lost_status ( ) const

inline

Get the SampleLostStatus for this DataReader.

See also: dds::core::status::SampleLostStatus

◆ requested_deadline_missed_status()

template<typename T >

dds::core::status::RequestedDeadlineMissedStatus dds::sub::DataReader< T >::requested_deadline_missed_status ( )

inline

Get the RequestedDeadlineMissedStatus for this DataReader.

See also: dds::core::status::RequestedDeadlineMissedStatus

◆ requested_incompatible_qos_status()

template<typename T >

dds::core::status::RequestedIncompatibleQosStatus dds::sub::DataReader< T >::requested_incompatible_qos_status ( ) const

inline

Get the RequestedIncompatibleQosStatus for this DataReader.

See also: dds::core::status::RequestedIncompatibleQosStatus

◆ subscription_matched_status()

template<typename T >

dds::core::status::SubscriptionMatchedStatus dds::sub::DataReader< T >::subscription_matched_status ( ) const

inline

Get the SubscriptionMatchedStatus for this DataReader.

See also: dds::core::status::SubscriptionMatchedStatus

◆ datareader_cache_status()

template<typename T >

rti::core::status::DataReaderCacheStatus datareader_cache_status ( ) const

<<extension>> Get the DataReaderCacheStatus for this DataReader

Note: This function is an extension, it must be called via the extensions() member function

See also: rti::core::status::DataReaderCacheStatus

◆ datareader_protocol_status()

template<typename T >

rti::core::status::DataReaderProtocolStatus datareader_protocol_status ( ) const

<<extension>> Get the DataReaderProtocolStatus for this DataReader

Note: This function is an extension, it must be called via the extensions() member function

See also: rti::core::status::DataReaderProtocolStatus

◆ matched_publication_datareader_protocol_status()

template<typename T >

rti::core::status::DataReaderProtocolStatus matched_publication_datareader_protocol_status ( const dds::core::InstanceHandle & publication_handle )

<<extension>> Get the DataReaderProtocolStatus for this DataReader

Note: This function is an extension, it must be called via the extensions() member function

See also: rti::core::status::DataReaderProtocolStatus

◆ acknowledge_all() [1/2]

template<typename T >

void acknowledge_all ( )

<<extension>> Acknowledge all previously accessed samples

Note: This function is an extension, it must be called via the extensions() member function

Applicable only when dds::core::policy::Reliability::acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::APPLICATION_EXPLICIT

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values rti::core::RtpsReliableReaderProtocol::samples_per_app_ack and rti::core::RtpsReliableReaderProtocol::app_ack_period.

Exceptions

One	of the Standard Exceptions

◆ acknowledge_all() [2/2]

template<typename T >

void acknowledge_all ( const AckResponseData & response_data )

<<extension>> Acknowledge all previously accessed samples

Note: This function is an extension, it must be called via the extensions() member function

Applicable only when dds::core::policy::Reliability::acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::APPLICATION_EXPLICIT

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values rti::core::RtpsReliableReaderProtocol::samples_per_app_ack and rti::core::RtpsReliableReaderProtocol::app_ack_period.

The maximum length of the response is configured using rti::core::policy::DataReaderResourceLimits::max_app_ack_response_length.

Parameters

response_data <<in>> Response data sent to dds::pub::DataWriter upon acknowledgment

Exceptions

One	of the Standard Exceptions

◆ acknowledge_sample() [1/2]

template<typename T >

void acknowledge_sample ( const dds::sub::SampleInfo & sample_info )

<<extension>> Acknowledge a single sample explicitly

Note: This function is an extension, it must be called via the extensions() member function

Applicable only when dds::core::policy::Reliability::acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::APPLICATION_EXPLICIT

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values rti::core::RtpsReliableReaderProtocol::samples_per_app_ack and rti::core::RtpsReliableReaderProtocol::app_ack_period.

Parameters

sample_info <<in>> dds::sub::SampleInfo identifying the sample being acknowledged.

Exceptions

One	of the Standard Exceptions

◆ acknowledge_sample() [2/2]

template<typename T >

void acknowledge_sample	(	const dds::sub::SampleInfo &	sample_info,
		const AckResponseData &	response_data
	)

<<extension>> Acknowledge a single sample explicitly

Note: This function is an extension, it must be called via the extensions() member function

Applicable only when dds::core::policy::Reliability::acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::APPLICATION_EXPLICIT

A call to this method does not necessarily trigger the sending of an AppAck RTPS message from the DataReader to the DataWriter. How and when AppAck messages are sent can be configured using the QoS values rti::core::RtpsReliableReaderProtocol::samples_per_app_ack and rti::core::RtpsReliableReaderProtocol::app_ack_period.

The maximum length of the response is configured using rti::core::policy::DataReaderResourceLimits::max_app_ack_response_length

Parameters

sample_info	<<in>> dds::sub::SampleInfo identifying the sample being acknowledged.
response_data	<<in>> Response data sent to dds::pub::DataWriter upon acknowledgment (via dds::pub::DataWriterListener::on_application_acknowledgment)

Exceptions

One	of the Standard Exceptions

◆ close_contained_entities()

template<typename T >

void close_contained_entities ( )

<<extension>> Closes all the entities created from this DataReader

Note: Calling this function explicitly is not necessary to close a DataReader.

Deletes all contained dds::sub::cond::ReadCondition, dds::sub::cond::QueryCondition, and rti::sub::TopicQuery objects.

The operation will fail with dds::core::PreconditionNotMetError if the any of the contained entities is in a state where it cannot be deleted.

MT Safety:: UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.

Exceptions

One	of the Standard Exceptions, or dds::core::PreconditionNotMetError

◆ read_noexcept()

template<typename T >

rti::core::Result< dds::sub::LoanedSamples< T > > read_noexcept ( )

noexcept

<<extension>> Alternative to read() that doesn't throw exceptions.

This operation behaves exactly like read() but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Example:

// Call the extension function
auto result = reader->read_noexcept();
if (result.is_ok()) {
    for (const auto& sample : result.get()) {
       // ...
    }
}

Returns: A Result that contains the LoanedSamples if the operation was succesful. When an error occurs, the Result contains the return code.

◆ take_noexcept()

template<typename T >

rti::core::Result< dds::sub::LoanedSamples< T > > take_noexcept ( )

noexcept

<<extension>> Alternative to take() that doesn't throw exceptions.

Note: This function is an extension, it must be called via the extensions() member function

This operation behaves exactly like take() but is guaranteed to not throw exceptions.

As an extension function, it must be accessed with the extensions() method or with the -> operator. Since extensions() can throw if the object is not a valid reference, the -> operator is recommended.

Example:

// Call the extension function
auto result = reader->take_noexcept();
if (result.is_ok()) {
    for (const auto& sample : result.get()) {
       // ...
    }
}

Returns: A Result that contains the LoanedSamples if the operation was succesful. When an error occurs, the Result contains the return code.

◆ read() [4/5]

template<typename T >

bool read ( T & sample )

<<extension>> Copies the next not-previously-accessed valid data value from the DataReader via a read operation.

Note: This function is an extension, it must be called via the extensions() member function

This function ignores SampleInfo and therefore also skips samples with invalid data.

Parameters

sample The sample where to copy the values of the next unread sample if the function returned true, or undefinded values otherwise.

Returns: True if there was an unread sample

See also: read(T& sample, dds::sub::SampleInfo& sample_info)

◆ read() [5/5]

template<typename T >

bool read	(	T &	sample,
		dds::sub::SampleInfo &	sample_info
	)

<<extension>> Copies the next not-previously-accessed data value from the DataReader via a read operation.

Note: This function is an extension, it must be called via the extensions() member function

Returns: True if there was an unread sample

This operation copies the next not-previously-accessed data value from the dds::sub::DataReader. This operation also copies the corresponding dds::sub::SampleInfo. The implied order among the samples stored in the dds::sub::DataReader is the same as for the dds::sub::DataReader::read operation.

The dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) operation is semantically equivalent to the dds::sub::DataReader::read operation, where the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

Note: Calling dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) from the dds::sub::DataReaderListener::on_data_available() callback reads only one sample of potentially many samples in the reader queue, because dds::sub::DataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) in a loop within the on_data_available callback until dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) returns false . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use dds::sub::DataReader::read rather than dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) in order to read more than one sample at a time.)

Exceptions

One	of the Standard Exceptions, dds::core::NotEnabledError.

See also: dds::sub::DataReader::read

◆ take() [4/5]

template<typename T >

bool take ( T & sample )

<<extension>> Copies the next not-previously-accessed valid data value from the DataReader via a take operation.

Note: This function is an extension, it must be called via the extensions() member function

This function ignores SampleInfo and therefore also skips samples with invalid data.

Parameters

sample The sample where to copy the values of the next unread sample if the function returned true, or undefinded values otherwise.

Returns: True if there was an unread sample to take. When this returns false, the argument is not modified.

Example:

Foo sample;

bool read_new_sample = reader.extensions().take(sample);

Foo

An example topic-type.

Definition: types.dxx:34

See also: take(T& sample, dds::sub::SampleInfo& sample_info)

◆ take() [5/5]

template<typename T >

bool take	(	T &	sample,
		dds::sub::SampleInfo &	sample_info
	)

<<extension>> Copies the next not-previously-accessed data value from the DataReader via a take operation.

Note: This function is an extension, it must be called via the extensions() member function

This operation copies the next not-previously-accessed data value from the dds::sub::DataReader and 'removes' it from the dds::sub::DataReader so that it is no longer accessible. This operation also copies the corresponding dds::sub::SampleInfo. This operation is analogous to the dds::sub::DataReader::read(T& sample, dds::sub::SampleInfo& sample_info) except for the fact that the sample is removed from the dds::sub::DataReader.

The dds::sub::DataReader::take(T& sample, dds::sub::SampleInfo& sample_info) operation is semantically equivalent to the dds::sub::DataReader::take operation, where the sample_states=NOT_READ, the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

Note: Calling dds::sub::DataReader::take(T& sample, dds::sub::SampleInfo& sample_info) from the dds::sub::DataReaderListener::on_data_available() callback retrieves only one sample of potentially many samples in the reader queue, because dds::sub::DataReaderListener::on_data_available() is triggered only once when new samples arrive in the queue. Therefore, it is recommended that you call dds::sub::DataReader::take(T& sample, dds::sub::SampleInfo& sample_info) in a loop within the on_data_available callback until dds::sub::DataReader::take(T& sample, dds::sub::SampleInfo& sample_info) returns false . This ensures that all samples in the reader queue are serviced by application logic. (You may also choose to use the dds::sub::DataReader::take rather than dds::sub::DataReader::take(T& sample, dds::sub::SampleInfo& sample_info) in order to take more than one sample at a time.)

Exceptions

One	of the Standard Exceptions,

dds::core::NotEnabledError.

See also: dds::sub::DataReader::take

◆ is_data_consistent() [1/2]

template<typename T >

bool is_data_consistent	(	const T &	sample,
		const dds::sub::SampleInfo &	sample_info
	)

<<extension>> Checks if the sample has been overwritten by the DataWriter

Note: This function is an extension, it must be called via the extensions() member function

Parameters

sample	Sample to be validated
sample_info	dds::sub::SampleInfo object received with the sample

See also: dds::sub::DataReader::is_data_consistent

◆ is_data_consistent() [2/2]

template<typename T >

bool is_data_consistent ( const rti::sub::LoanedSample< T > & sample )

<<extension>> Checks if the sample has been overwritten by the DataWriter

Note: This function is an extension, it must be called via the extensions() member function

When a sample is received via Zero Copy transfer over shared memory, the sample can be reused by the DataWriter once it is removed from the DataWriter's send queue. Since there is no synchronization between the DataReader and the DataWriter, the sample could be overwritten by the DataWriter before it is processed by the DataReader. The dds::sub::DataReader::is_data_consistent operation can be used after processing the sample to check if it was overwritten by the DataWriter.

A precondition for using this operation is to set rti::core::DataWriterShmemRefTransferModeSettings::enable_data_consistency_check to true.

Warning: This operation cannot be used when the data type is annotated with @language_binding(FLAT_DATA). Reading a FlatData sample delivered with Zero Copy transfer over shared memory while the DataWriter is overwriting it is undefined behavior. An application-level synchronization mechanism is required in this case.

Parameters

sample <<in>> Sample to be validated

Returns: true if the sample is consistent (i.e., the sample has not been overwritten by the DataWriter)

Exceptions

One	of the Standard Exceptions or dds::core::PreconditionNotMetError.

◆ topic_name()

template<typename T >

const std::string & topic_name ( ) const

<<extension>> Get the topic name associated with this DataReader

Note: This function is an extension, it must be called via the extensions() member function

◆ type_name()

template<typename T >

const std::string & type_name ( ) const

<<extension>> Get the type name associated with this DataReader

Note: This function is an extension, it must be called via the extensions() member function

Examples: Foo.hpp.

◆ close()

template<typename T >

void close ( )

Close this DataReader.

Friends And Related Function Documentation

◆ read()

template<typename T >

bool read ( dds::sub::ReadModeDummyType )

Usage:

reader >> read >> loaned_samples;

See also: dds::sub::DataReader::operator >>(bool(*manipulator)(ReadModeDummyType))

◆ take()

template<typename T >

bool take ( dds::sub::ReadModeDummyType )

Usage:

reader >> take >> loaned_samples;

The default mode to access samples is to take, so the above is equivalent to:

reader >> loaned_samples;

See also: dds::sub::DataReader::operator >>(bool(*manipulator)(ReadModeDummyType))

◆ max_samples()

template<typename T >

dds::sub::functors::MaxSamplesManipulatorFunctor max_samples ( uint32_t n )

Use this function to set the maximum number of samples to read/take by passing it to the DataReader::operator >>(Functor f) operator.

Parameters

n	The maximum number of samples to take

See also: dds::sub::DataReader::operator >>(Functor f)

◆ content()

template<typename T >

dds::sub::functors::ContentFilterManipulatorFunctor content ( const dds::sub::Query & query )

The effect of using this manipulator is that the subsequent read/take will filter the samples based on the Query's expression. If the DataReader has no samples that meet the constraints, the read/take will not return any data.

If this stream manipulator comes before a call to the condition(const dds::sub::cond::QueryCondition& query_condition) manipulator then it will be overridden and will not have any effect on the read or take operation. Similarly, if this operation follows a call to condition(), then the previously set QueryCondition will be cleared.

Parameters

query The Query to use during the read/take

See also: dds::sub::DataReader::operator >>(Functor f); dds::sub::condition(const dds::sub::cond::QueryCondition& query_condition)

◆ condition()

template<typename T >

dds::sub::functors::ConditionManipulatorFunctor condition ( const dds::sub::cond::ReadCondition & condition )

The effect of using this manipulator is that the subsequent read/take will filter the samples based on the QueryConditions's expression and state. If the DataReader has no samples that meet the constraints, the read/take will not return any data.

If this stream manipulator comes before a call to the content(const dds::sub::Query& query) manipulator then it will be overridden and will not have any effect on the read or take operation. Similarly, if this operation follows a call to content() and/or state(const dds::sub::status::DataState& s), then the previously set Query and DataState will be cleared.

This manipulator is effectively a combination of the content and state manipulators.

For example:

reader >> read
       >> content(dds::sub::Query(system.reader, "foo = 7"))
       >> state(dds::sub::status::DataState::new_data())
       >> samples;

is equivalent to:

reader >> read
       >> condition(Query(system.reader, "foo = 7"), DataState()::new_data())
       >> samples;

Parameters

condition The QueryCondition to use during the read/take

See also: dds::sub::DataReader::operator >>(Functor f); content(const dds::sub::Query& query)

References dds::sub::condition().

◆ state()

template<typename T >

dds::sub::functors::StateFilterManipulatorFunctor state ( const dds::sub::status::DataState & s )

By setting the dds::sub::status::DataState you can specify the state of the samples that should be read or taken. The DataState of a sample encapsulates the dds::sub::status::SampleState, dds::sub::status::ViewState, and dds::sub::status::InstanceState of a sample.

If this stream manipulator comes before a call to the condition(const dds::sub::cond::QueryCondition& query_condition) manipulator then it will be overridden and will not have any effect on the read or take operation.

Parameters

s	The DataState of the samples to be read or taken

See also: dds::sub::DataReader::operator >>(Functor f)

◆ instance()

template<typename T >

dds::sub::functors::InstanceManipulatorFunctor instance ( const dds::core::InstanceHandle & h )

This operation causes the subsequent read or take operation to access only samples belonging the single specified instance whose handle is h.

Upon successful completion, the data collection will contain samples all belonging to the same instance. The corresponding SampleInfo verifies SampleInfo.instance_handle() == h.

The subsequent read/take operation will be semantically equivalent to a read or take without specifying the instance, except in building the collection, the DataReader will check that the sample belongs to the specified instance and otherwise it will not place the sample in the returned collection.

The subsequent read/take may operation may fail with dds::core::InvalidArgumentError if the InstanceHandle does not correspond to an existing data-object known to the DataReader.

Parameters

h	The handle of the instance to access

See also: dds::sub::DataReader::operator >>(Functor f)

◆ next_instance()

template<typename T >

dds::sub::functors::NextInstanceManipulatorFunctor next_instance ( const dds::core::InstanceHandle & h )

This operation causes the subsequent read or take operation to access only samples belonging a single instance whose handle is considered 'next' after the provided InstanceHandle h.

The accessed samples will all belong to the 'next' instance with InstanceHandle 'greater' than the specified previous handle that has available samples.

This operation implies the existence of a total order 'greater-than' relationship between the instance handles. The specifics of this relationship are not all important and are implementation specific. The important thing is that, according to the middleware, all instances are ordered relative to each other. This ordering is between the instance handles; It should not depend on the state of the instance (e.g. whether it has data or not) and must be defined even for instance handles that do not correspond to instances currently managed by the dds::sub::DataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.

The behavior of dds::sub::DataReader::Selector::next_instance is 'as if' the dds::sub::DataReader invoked dds::sub::instance(const dds::core::InstanceHandle& h), passing the smallest instance_handle among all the ones that: (a) are greater than previous_handle, and (b) have available samples (i.e. samples that meet the constraints imposed by the specified states).

The special value dds::core::InstanceHandle::nil() is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == dds::core::InstanceHandle::nil() will return the samples for the instance which has the smallest instance_handle among all the instances that contain available samples.

Note: The operation dds::sub::DataReader::Selector::next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == dds::core::InstanceHandle::nil(), examines the samples returned, and then uses the instance_handle returned in the dds::sub::SampleInfo as the value of the previous_handle argument to the next call to dds::sub::DataReader::Selector::next_instance. The iteration continues until the read/take operation doesn't return any more samples. This application-driven iteration is required to ensure that all samples on the reader queue are read.

Note that it is possible to call the dds::sub::DataReader::Selector::next_instance operation with a previous_handle that does not correspond to an instance currently managed by the dds::sub::DataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the dds::sub::DataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a dds::sub::status::InstanceState::not_alive_no_writers() instance, returns the loan (at which point the instance information may be removed, and thus the handle becomes invalid), and tries to read the next instance.

Parameters

h	The reference instance. The instance after this one will be selected

See also: dds::sub::DataReader::operator >>(Functor f)

◆ ignore() [1/2]

template<typename T >

void ignore	(	dds::domain::DomainParticipant &	participant,
		const dds::core::InstanceHandle &	handle
	)

A subscription is defined by the association of a topic name, user data, and partition set on the dds::sub::Subscriber (see dds::topic::SubscriptionBuiltinTopicData). After this call, any data received related to that subscription's dds::sub::DataReader will be ignored.

This operation can be used to ignore local and remote DataReaders.

The subscription to ignore is identified by the handle argument.

To ignore a remote DataReader, the handle can be obtained from the dds::sub::SampleInfo retrieved when reading data samples from the built-in dds::sub::DataReader for the subscription topic.

To ignore a local DataReader, the handle can be obtained by calling dds::core::Entity::instance_handle() for the local DataReader.

There is no way to reverse this operation.

Exceptions

One	of the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::NotEnabledError

See also: dds::topic::SubscriptionBuiltinTopicData; dds::topic::subscription_topic_name(); dds::sub::builtin_subscriber

Parameters

participant	The DomainParticipant for which the remote entity will be ignored
handle	The InstanceHandle of the remote entity that has to be ignored

◆ ignore() [2/2]

template<typename FwdIterator >

void ignore	(	dds::domain::DomainParticipant &	participant,
		FwdIterator	begin,
		FwdIterator	end
	)

Parameters

participant	The DomainParticipant for which the remote entity will be ignored
begin	A forward iterator to the initial position in a dds::core::InstanceHandleSeq holding the handles to the remote DataReaders to be ignored.
end	A forward iterator to the final position in a dds::core::InstanceHandleSeq holding the handles to the remote DataReaders to be ignored.

See also: ignore(dds::domain::DomainParticipant&, const dds::core::InstanceHandle&);

References dds::sub::begin(), dds::sub::end(), and dds::sub::ignore().

◆ matched_publications() [1/2]

template<typename T >

const ::dds::core::InstanceHandleSeq matched_publications ( const dds::sub::DataReader< T > & reader )

A publication is considered to be matching if all of the following criteria are true:

The publication is within the same domain as this subscription.
The publication has a matching dds::topic::Topic.
The publication has compatible QoS.
If the applications are using partitions, the publication shares a common partition with this subscription.
The dds::domain::DomainParticipant has not indicated that the publication's dds::domain::DomainParticipant should be "ignored" by means of the dds::pub::ignore API.
If the subscription is using a dds::topic::ContentFilteredTopic and the publication is using the rti::core::policy::MultiChannel, there is an intersection between at least one of the associated filters.
If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the reader has completed the key exchange with the writer.

The handles returned in the publication_handles list are the ones that are used by the RTI Connext implementation to locally identify the corresponding matched dds::pub::DataWriter entities. These handles match the ones that appear in the instance_handle field of the dds::sub::SampleInfo when reading the dds::topic::publication_topic_name() builtin topic.

This API may return the publication handles of publications that are not alive. dds::sub::DataReader::is_matched_publication_alive can be used to check the liveliness of the remote publication.

Exceptions

One	of the Standard Exceptions, or dds::core::OutOfResourcesError if the sequence is too small and the system cannot resize it, or dds::core::NotEnabledError

Template Parameters

T	The topic-type that the DataReader subscribes to

Parameters

reader The reader whose publications are being retrieved

Returns: An InstanceHandleSeq containing the InstanceHandles of the matched publications for the provided DataReader

◆ matched_publications() [2/2]

template<typename T , typename FwdIterator >

FwdIterator matched_publications	(	const dds::sub::DataReader< T > &	reader,
		FwdIterator	begin,
		FwdIterator	end
	)

A publication is considered to be matching if all of the following criteria are true:

The publication is within the same domain as this subscription.
The publication has a matching dds::topic::Topic.
The publication has compatible QoS.
If the applications are using partitions, the publication shares a common partition with this subscription.
The dds::domain::DomainParticipant has not indicated that the publication's dds::domain::DomainParticipant should be "ignored" by means of the dds::pub::ignore API.
If the subscription is using a dds::topic::ContentFilteredTopic and the publication is using the rti::core::policy::MultiChannel, there is an intersection between at least one of the associated filters.
If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the reader has completed the key exchange with the writer.

The handles returned in the publication_handles list are the ones that are used by the RTI Connext implementation to locally identify the corresponding matched dds::pub::DataWriter entities. These handles match the ones that appear in the instance_handle field of the dds::sub::SampleInfo when reading the dds::topic::publication_topic_name() builtin topic.

This API may return the publication handles of publications that are not alive. dds::sub::DataReader::is_matched_publication_alive can be used to check the liveliness of the remote publication.

Exceptions

One	of the Standard Exceptions, or dds::core::OutOfResourcesError if the sequence is too small and the system cannot resize it, or dds::core::NotEnabledError

Template Parameters

T	The topic-type that the DataReader subscribes to
FwdIterator	A forward iterator whose value type is dds::core::InstanceHandle

Parameters

reader	The reader whose publications are being retrieved
begin	A forward iterator to the beginning position in the destination container of matching InstanceHandles
end	A forward iterator to the ending position in the destination container of matching InstanceHandles

Returns: An iterator placed at the last position in the container where a InstanceHandle was inserted

References dds::sub::begin(), dds::sub::end(), and dds::sub::matched_publications().

◆ matched_publication_data() [1/2]

template<typename T >

const dds::topic::PublicationBuiltinTopicData matched_publication_data	(	const dds::sub::DataReader< T > &	reader,
		const dds::core::InstanceHandle &	handle
	)

The publication_handle must correspond to a publication currently associated with the dds::sub::DataReader. Otherwise, the operation will fail with dds::core::InvalidArgumentError. Use the operation dds::sub::matched_publications to find the publications that are currently matched with the dds::sub::DataReader.

Note: This operation does not retrieve the dds::topic::PublicationBuiltinTopicData::type. This information is available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the dds::sub::DataReader<dds::topic::PublicationBuiltinTopicData>).

Exceptions

One	of the Standard Exceptions or dds::core::NotEnabledError

Template Parameters

T	The topic-type that the DataReader subscribes to

Parameters

reader	The reader associated with the publication whose data is being retrieved
handle	The InstanceHandle Handle to a specific publication associated with the DataWriter. Must correspond to a publication currently associated with the DataReader.

Returns: The dds::topic::PublicationBuiltinTopicData of the publication that is associated with the provided handle

◆ matched_publication_participant_data()

template<typename T >

dds::topic::ParticipantBuiltinTopicData matched_publication_participant_data	(	const dds::sub::DataReader< T > &	reader,
		const dds::core::InstanceHandle &	handle
	)

Note: This is a standalone function in the namespace rti::sub

The publication_handle must correspond to a publication currently associated with the dds::sub::DataReader. Otherwise, the operation will fail with dds::core::InvalidArgumentError. The operation may also fail with dds::core::PreconditionNotMetError if the publication corresponds to the same dds::domain::DomainParticipant that the DataReader belongs to. Use the operation dds::sub::matched_publications to find the publications that are currently matched with the dds::sub::DataReader.

Exceptions

One	of the Standard Exceptions or dds::core::NotEnabledError

Template Parameters

T	The topic-type that the DataReader subscribes to

Parameters

reader	The reader to lookup the matched participant data of
handle	The InstanceHandle to a specific publication. Must correspond to a publication currently associated with the DataReader. This handle is available in the dds::sub::SampleInfo::publication_handle()

Returns: The dds::topic::ParticipantBuiltinTopicData of the DomainParticipant of a matched publication of a dds::sub::DataReader

◆ is_matched_publication_alive()

template<typename T >

bool is_matched_publication_alive	(	const dds::sub::DataReader< T > &	reader,
		const dds::core::InstanceHandle &	handle
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

T	The topic-type that the DataReader subscribes to.

Parameters

reader	The DataReader.
handle	The dds::core::InstanceHandle of the matched publication.

This API is used for querying the endpoint liveliness of a matched publication. A matched publication will be marked as not alive if the liveliness that it committed to through its LIVELINESS QoS policy was not respected. Note that if the participant associated with the matched publication loses liveliness, the dds::core::InstanceHandle will become invalid and this function will fail with dds::core::InvalidArgumentError.

of the matched publication. See dds::sub::matched_publications for a description of what is considered a matched publication.

Exceptions

One	of the Standard Exceptions

Returns: A boolean indicating whether or not the matched publication is alive.

◆ matched_publication_data() [2/2]

template<typename T >

std::vector< dds::topic::PublicationBuiltinTopicData > matched_publication_data ( const dds::sub::DataReader< T > & reader )

Note: This is a standalone function in the namespace rti::sub

This API retrieves the matched subscription data from all of the publications currently matched a DataReader.

Template Parameters

T	The topic-type that the DataReader subscribes to.

Parameters

reader The DataReader.

Returns: A std::vector containing all of the matched publication data.

◆ find() [1/4]

template<typename Reader , typename FwdIterator >

uint32_t find	(	const dds::sub::Subscriber &	subscriber,
		const std::string &	topic_name,
		FwdIterator	begin,
		uint32_t	max_size
	)

Use this operation on the built-in dds::sub::Subscriber (Built-in Topics) to access the built-in dds::sub::DataReader entities for the built-in topics.

The built-in dds::sub::DataReader is created when this operation is called on a built-in topic for the first time. The built-in dds::sub::DataReader is deleted automatically when the dds::domain::DomainParticipant is deleted.

To ensure that builtin dds::sub::DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin dds::sub::DataReader before the dds::domain::DomainParticipant is enabled. Looking up builtin dds::sub::DataReader may implicitly register builtin transports due to creation of dds::sub::DataReader (see Built-in Transport Plugins for details on when a builtin transport is registered). Therefore, if you are want to modify builtin transport properties, do so before using this operation.

Therefore the suggested sequence when looking up builtin DataReaders is:

Create a disabled dds::domain::DomainParticipant.
(optional) Modify builtin transport properties
Call dds::sub::builtin_subscriber().
Call dds::sub::find().
Call enable() on the DomainParticipant.

The returned dds::sub::DataReader may be enabled or disabled.

If more than one dds::sub::DataReader is attached to the dds::sub::Subscriber, this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a dds::sub::DataReader in one thread while another thread is simultaneously creating or destroying that dds::sub::DataReader.

Template Parameters

Reader	The type of the reader. It can be dds::sub::AnyDataReader, or an instantiation of dds::sub::DataReader<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
FwdIterator	The type of forward iterator passed to this function

Parameters

subscriber	The dds::sub::Subscriber the DataReader belongs to
topic_name	Name of the dds::topic::Topic associated with the DataReader that is to be looked up.
begin	A forward iterator to the position in the destination container where the DataReaders will be copied into
max_size	Only 1 DataReader will be returned from this function

Returns: The number of DataReaders that were found (either 0 or 1)

References dds::sub::begin().

◆ find() [2/4]

template<typename Reader , typename BinIterator >

uint32_t find	(	const dds::sub::Subscriber &	subscriber,
		const std::string &	topic_name,
		BinIterator	begin
	)

Use this operation on the built-in dds::sub::Subscriber (Built-in Topics) to access the built-in dds::sub::DataReader entities for the built-in topics.

The built-in dds::sub::DataReader is created when this operation is called on a built-in topic for the first time. The built-in dds::sub::DataReader is deleted automatically when the dds::domain::DomainParticipant is deleted.

To ensure that builtin dds::sub::DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin dds::sub::DataReader before the dds::domain::DomainParticipant is enabled. Looking up builtin dds::sub::DataReader may implicitly register builtin transports due to creation of dds::sub::DataReader (see Built-in Transport Plugins for details on when a builtin transport is registered). Therefore, if you are want to modify builtin transport properties, do so before using this operation.

Therefore the suggested sequence when looking up builtin DataReaders is:

Create a disabled dds::domain::DomainParticipant.
(optional) Modify builtin transport properties
Call dds::sub::builtin_subscriber().
Call dds::sub::find().
Call enable() on the DomainParticipant.

The returned dds::sub::DataReader may be enabled or disabled.

If more than one dds::sub::DataReader is attached to the dds::sub::Subscriber, this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a dds::sub::DataReader in one thread while another thread is simultaneously creating or destroying that dds::sub::DataReader.

Template Parameters

Reader	The type of the reader. It can be dds::sub::AnyDataReader, or an instantiation of dds::sub::DataReader<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
BinIterator	The type of back-inserting iterator passed to this function

Parameters

subscriber	The dds::sub::Subscriber the DataReader belongs to
topic_name	Name of the dds::topic::Topic associated with the DataReader that is to be looked up.
begin	A back-inserting iterator to the position in the destination container to insert the found DataReader into

Returns: The number of DataReaders that were found (either 0 or 1)

References dds::sub::begin().

◆ find() [3/4]

template<typename READER , typename T , typename FwdIterator >

uint32_t find	(	const dds::sub::Subscriber &	subscriber,
		const dds::topic::TopicDescription< T > &	topic_description,
		FwdIterator	begin,
		uint32_t	max_size
	)

See also: find(const dds::sub::Subscriber& subscriber,const std::string& topic_name,FwdIterator begin,uint32_t max_size)

References dds::sub::begin(), and dds::sub::find().

◆ find() [4/4]

template<typename READER , typename T , typename BinIterator >

uint32_t find	(	const dds::sub::Subscriber &	subscriber,
		const dds::topic::TopicDescription< T > &	topic_description,
		BinIterator	begin
	)

See also: uint32_t find(const dds::sub::Subscriber& subscriber,const std::string& topic_name,BinIterator begin)

References dds::sub::begin(), and dds::sub::find().

◆ find_datareaders() [1/2]

template<typename AnyDataReaderBackInsertIterator >

uint32_t find_datareaders	(	dds::sub::Subscriber	subscriber,
		AnyDataReaderBackInsertIterator	begin
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

AnyDataReaderBackInsertIterator Type of the back-inserting iterator passed into this function, whose value_type must be dds::sub::AnyDataReader.

Parameters

subscriber	The dds::sub::Subscriber the DataReaders belong to
begin	A back-inserting iterator to the position in the destination container to insert the found DataReaders into

Returns: The number of found DataReaders

See also: Looking up DataReaders

References rti::sub::begin().

◆ find_datareaders() [2/2]

template<typename AnyDataReaderForwardIterator >

uint32_t find_datareaders	(	dds::sub::Subscriber	subscriber,
		AnyDataReaderForwardIterator	begin,
		uint32_t	max_size
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

AnyDataReaderForwardIterator A forward iterator whose value_type is dds::sub::AnyDataReader

Parameters

subscriber	The dds::sub::Subscriber the readers belong to
begin	A forward iterator to the position in the destination container where to begin copying the found readers into.
max_size	The maximum number of readers to return

Returns: The number of found readers

See also: Looking up DataReaders

References rti::sub::begin().

◆ find_datareader_by_topic_name()

template<typename Reader >

Reader find_datareader_by_topic_name	(	dds::sub::Subscriber	subscriber,
		const std::string &	topic_name
	)

Note: This is a standalone function in the namespace rti::sub

Use this operation on the built-in dds::sub::Subscriber (Built-in Topics) to access the built-in dds::sub::DataReader entities for the built-in topics.

The built-in dds::sub::DataReader is created when this operation is called on a built-in topic for the first time. The built-in dds::sub::DataReader is deleted automatically when the dds::domain::DomainParticipant is deleted.

To ensure that builtin dds::sub::DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin dds::sub::DataReader before the dds::domain::DomainParticipant is enabled. Looking up builtin dds::sub::DataReader may implicitly register builtin transports due to creation of dds::sub::DataReader (see Built-in Transport Plugins for details on when a builtin transport is registered). Therefore, if you are want to modify builtin transport properties, do so before using this operation.

Therefore the suggested sequence when looking up builtin DataReaders is:

Create a disabled dds::domain::DomainParticipant.
(optional) Modify builtin transport properties
Call dds::sub::builtin_subscriber().
Call dds::sub::find().
Call enable() on the DomainParticipant.

The returned dds::sub::DataReader may be enabled or disabled.

If more than one dds::sub::DataReader is attached to the dds::sub::Subscriber, this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a dds::sub::DataReader in one thread while another thread is simultaneously creating or destroying that dds::sub::DataReader.

Template Parameters

Reader The type of the reader. It can be dds::sub::AnyDataReader, or an instantiation of dds::sub::DataReader<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)

Parameters

subscriber	The dds::sub::Subscriber that created the DataReader to find
topic_name	Topic name of the DataReader to find

Returns: The DataReader with the given topic name, or dds::core::null if it doesn't exist

See also: Looking up DataReaders

References dds::core::null.

◆ find_datareader_by_name() [1/2]

template<typename Reader >

Reader find_datareader_by_name	(	dds::sub::Subscriber	subscriber,
		const std::string &	datareader_name
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

Reader The type of the reader. It can be dds::sub::AnyDataReader, or an instantiation of dds::sub::DataReader<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)

Every dds::sub::DataReader in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.

This operation retrieves the dds::sub::DataReader within the dds::sub::Subscriber whose name matches the one specified. If there are several dds::sub::DataReader with the same name within the dds::sub::Subscriber, the operation returns the first matching occurrence.

Parameters

subscriber	The dds::sub::Subscriber that created the DataReader to find
datareader_name	Entity name of the DataReader to find

Returns: The DataReader with the given name, or dds::core::null if it doesn't exist

See also: Looking up DataReaders

References dds::core::null.

◆ find_datareader_by_topic_description()

template<typename Reader , typename T >

Reader find_datareader_by_topic_description	(	const dds::sub::Subscriber &	subscriber,
		const dds::topic::TopicDescription< T > &	topic_description
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

Reader	The type of the reader returned, for example, dds::sub::DataReader<Foo>, or dds::sub::AnyDataReader
T	The topic-type

Parameters

subscriber	The Subscriber to which the DataReader belongs
topic_description	The TopicDescription identifying the DataReader to find

Returns: The found DataReader, or dds::core::null if it doesn't exist

References dds::core::null.

◆ find_datareader_by_name() [2/2]

template<typename Reader >

Reader find_datareader_by_name	(	dds::domain::DomainParticipant	participant,
		const std::string &	datareader_name
	)

Note: This is a standalone function in the namespace rti::sub

Template Parameters

Reader The type of the reader. It can be dds::sub::AnyDataReader, or an instantiation of dds::sub::DataReader<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)

Every dds::sub::DataReader in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

Every dds::sub::Subscriber in the system has an entity name which is also configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a dds::sub::DataReader within a dds::sub::Subscriber given the specified name which encodes both to the dds::sub::DataReader and the dds::sub::Subscriber name.

If there are several dds::sub::DataReader with the same name within the corresponding dds::sub::Subscriber this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the dds::sub::Subscriber to which the dds::sub::DataReader belongs and the entity name of of the dds::sub::DataReader itself, separated by a double colon "::". For example: MySubscriberName::MyDataReaderName

The plain name contains the dds::sub::DataReader name only. In this situation it is implied that the dds::sub::DataReader belongs to the implicit dds::sub::Subscriber so the use of a plain name is equivalent to specifying a fully qualified name with the dds::sub::Subscriber name part being "implicit". For example: the plain name "MyDataReaderName" is equivalent to specifiying the fully qualified name "implicit::MyDataReaderName"

The dds::sub::DataReader is only looked up within the dds::sub::Subscriber specified in the fully qualified name, or within the implicit dds::sub::Subscriber if the name was not fully qualified.

Parameters

participant	The dds::domain::DomainParticipant within which the dds::sub::DataReader exists
datareader_name	EntityName of the DataReader to find

Returns: The first reader with the given name or dds::core::null if it is not found.

See also: rti::sub::find_datareader_by_name(const dds::sub::Subscriber&, const std::string&)

References dds::core::null.

Classes

Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ DataReader() [1/6]

◆ DataReader() [2/6]

◆ DataReader() [3/6]

◆ DataReader() [4/6]

◆ DataReader() [5/6]

◆ DataReader() [6/6]

Member Function Documentation

◆ default_filter_state() [1/2]

◆ default_filter_state() [2/2]

◆ operator>>() [1/4]

◆ operator>>() [2/4]

◆ operator>>() [3/4]

◆ read() [1/5]

◆ take() [1/5]

◆ read() [2/5]

◆ take() [2/5]

◆ read() [3/5]

◆ take() [3/5]

◆ select()

◆ key_value() [1/2]

◆ key_value() [2/2]

◆ lookup_instance()

◆ topic_description()

◆ subscriber()

◆ listener() [1/2]

◆ listener() [2/2]

◆ set_listener() [1/2]

◆ set_listener() [2/2]

◆ get_listener()

◆ qos() [1/2]

◆ qos() [2/2]

◆ operator<<()

◆ operator>>() [4/4]

◆ wait_for_historical_data()

◆ liveliness_changed_status()

◆ sample_rejected_status()

◆ sample_lost_status()

◆ requested_deadline_missed_status()

◆ requested_incompatible_qos_status()

◆ subscription_matched_status()

◆ datareader_cache_status()

◆ datareader_protocol_status()

◆ matched_publication_datareader_protocol_status()

◆ acknowledge_all() [1/2]

◆ acknowledge_all() [2/2]

◆ acknowledge_sample() [1/2]

◆ acknowledge_sample() [2/2]

◆ close_contained_entities()

◆ read_noexcept()

◆ take_noexcept()

◆ read() [4/5]

◆ read() [5/5]

◆ take() [4/5]

◆ take() [5/5]

◆ is_data_consistent() [1/2]

◆ is_data_consistent() [2/2]

◆ topic_name()

◆ type_name()

◆ close()

Friends And Related Function Documentation

◆ read()

◆ take()

◆ max_samples()

◆ content()

◆ condition()

◆ state()

◆ instance()

◆ next_instance()

◆ ignore() [1/2]

◆ ignore() [2/2]

◆ matched_publications() [1/2]

◆ matched_publications() [2/2]

◆ matched_publication_data() [1/2]

◆ matched_publication_participant_data()

◆ is_matched_publication_alive()