Contains the types and functions to support subscribing to topics. More...

Namespaces
	cond
	Contains Conditions specific to DataReaders.

	qos
	Contains DataReaderQos and SubscriberQos.

	status
	Contains DataState.

Classes
class	AnyDataReader
	<<reference-type>> This class provides an non-template holder for representing a DataReader of any type More...

class	AnyDataReaderListener
	The listener to notify status changes for a dds::sub::DataReader of a generic type. More...

class	CoherentAccess
	<<value-type>> Controls whether RTI Connext will preserve the groupings of changes made by the publishing application by means of begin_coherent_changes and end_coherent_changes. More...

class	DataReader
	<<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...

class	DataReaderListener
	The Listener to notify status changes for a dds::sub::DataReader. More...

class	GenerationCount
	<<value-type>> More...

class	LoanedSamples
	<<move-only-type>> Provides temporary access to a collection of samples (data and info) from a DataReader. More...

class	NoOpDataReaderListener
	A convenience implementation of DataReaderListener where all methods are overridden to do nothing. More...

class	NoOpSubscriberListener
	A convenience implementation of SubscriberListener where all methods are overridden to do nothing. More...

class	Query
	<<value-type>> Encapsulates a query for a dds::sub::cond::QueryCondition. More...

class	Rank
	<<value-type>> Contains the sample and generation ranks of a data-sample More...

class	ReadModeDummyType

class	Sample
	<<value-type>> This class encapsulate the data and meta-data associated with DDS samples. More...

class	SampleInfo
	<<value-type>> Information that accompanies each sample received by a DataReader More...

class	SharedSamples
	<<reference-type>> A sharable and container-safe version of LoanedSamples. More...

class	Subscriber
	<<reference-type>> A subscriber is the object responsible for actually receiving data from a subscription. More...

class	SubscriberListener
	The listener to notify status changes for a dds::sub::Subscriber. More...

Functions
template<typename T >
DataReader< T >	get (const AnyDataReader &any_reader)
	Same as AnyDataReader::get() More...

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

dds::sub::Subscriber	builtin_subscriber (const dds::domain::DomainParticipant &dp)
	Access the built-in Subscriber. 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 &sub, 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 AnyDataReaderFwdIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const dds::sub::status::DataState &data_state, AnyDataReaderFwdIterator begin, uint32_t max_size)
	Allows the application to access the AnyDataReaders that contain samples with the specified dds::sub::status::DataState. More...

template<typename AnyDataReaderBackInsertIterator >
uint32_t	find (const dds::sub::Subscriber &subscriber, const dds::sub::status::DataState &data_state, AnyDataReaderBackInsertIterator begin)
	Allows the application to access the AnyDataReaders that contain samples with the specified dds::sub::status::DataState. More...

template<typename T >
LoanedSamples< T >	move (LoanedSamples< T > &ls) OMG_NOEXCEPT
	Creates a new LoanedSamples instance by moving the contents of an existing one. More...

template<typename T >
LoanedSamples< T >::iterator	begin (LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::const_iterator	begin (const LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::iterator	end (LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::const_iterator	end (const LoanedSamples< T > &ls)

template<typename T >
void	swap (LoanedSamples< T > &ls1, LoanedSamples< T > &ls2) throw ()

Detailed Description

Contains the types and functions to support subscribing to topics.

Function Documentation

◆ get()

template<typename T >

DataReader< T > get ( const AnyDataReader & any_reader )

Same as AnyDataReader::get()

◆ read()

bool read ( dds::sub::ReadModeDummyType )

The stream manipulator to indicate that the reader should read samples as opposed to taking the samples.

Usage:

reader >> read >> loaned_samples;

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

◆ take()

bool take ( dds::sub::ReadModeDummyType )

The stream manipulator to indicate that the reader should take samples as opposed to reading the samples.

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

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

inline

Stream manipulator to set the maximum number of samples to read or take.

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

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

inline

Stream manipulator to set a Query to use during the subsequent read/take operation.

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

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

inline

Stream manipulator to set a QueryCondition to use during the subsequent read/take operation.

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)

Referenced by rti::sub::cond::create_query_condition_ex(), and dds::sub::cond::ReadCondition::create_read_condition_ex().

◆ state()

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

inline

Stream manipulator to specify the DataState of the samples that should be read/taken.

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

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

inline

Stream manipulator to specify the instance whose samples should be read or taken.

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

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

inline

Stream manipulator to specify the samples belonging to the 'next' instance after the provided instance handle should be accessed.

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]

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

Instructs RTI Connext to locally ignore a publication.

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

Referenced by ignore().

◆ ignore() [2/2]

template<typename FwdIterator >

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

Instructs RTI Connext to locally ignore subscriptions.

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 begin(), end(), and ignore().

◆ matched_publications() [1/2]

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.

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

Referenced by matched_publications().

◆ matched_publications() [2/2]

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.

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 begin(), and matched_publications().

◆ matched_publication_data()

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.

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

◆ builtin_subscriber()

dds::sub::Subscriber builtin_subscriber ( const dds::domain::DomainParticipant & dp )

Access the built-in Subscriber.

Each dds::domain::DomainParticipant contains several built-in dds::topic::Topic objects as well as corresponding dds::sub::DataReader objects to access them. All of these dds::sub::DataReader objects belong to a single built-in dds::sub::Subscriber.

The built-in Topics are used to communicate information about other dds::domain::DomainParticipant, dds::topic::Topic, dds::sub::DataReader, and dds::pub::DataWriter objects.

The built-in subscriber is created when this operation is called for the first time. The built-in subscriber is deleted automatically when the dds::domain::DomainParticipant is deleted.

Returns: The built-in dds::sub::Subscriber singleton.

See also: dds::topic::SubscriptionBuiltinTopicData; dds::topic::PublicationBuiltinTopicData; dds::topic::ParticipantBuiltinTopicData; dds::topic::TopicBuiltinTopicData

Parameters

dp	The DomainParticipant that the built-in subscriber belongs to.

◆ find() [1/6]

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.

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)

Referenced by find().

◆ find() [2/6]

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.

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)

◆ find() [3/6]

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
	)

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching TopicDescription.

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

References begin(), find(), and dds::topic::TopicDescription< T >::name().

◆ find() [4/6]

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.

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

References begin(), find(), and dds::topic::TopicDescription< T >::name().

◆ find() [5/6]

template<typename AnyDataReaderFwdIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	subscriber,
		const dds::sub::status::DataState &	data_state,
		AnyDataReaderFwdIterator	begin,
		uint32_t	max_size
	)

Allows the application to access the AnyDataReaders that contain samples with the specified dds::sub::status::DataState.

Allows the application to access the dds::sub::DataReader objects that contain samples with the specified sample_states, view_states and instance_states.

If the application is outside a begin_access()/end_access() block, or if the dds::core::policy::Presentation::access_scope of the dds::sub::Subscriber is dds::core::policy::PresentationAccessScopeKind_def::INSTANCE or dds::core::policy::PresentationAccessScopeKind_def::TOPIC, or if the dds::core::policy::Presentation::ordered_access of the dds::sub::Subscriber is false, the returned collection is a 'set' containing each dds::sub::DataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the dds::sub::Subscriber is dds::core::policy::PresentationAccessScopeKind_def::GROUP or dds::core::policy::PresentationAccessScopeKind_def::HIGHEST_OFFERED, and dds::core::policy::Presentation::ordered_access in the dds::sub::Subscriber is true, the returned collection is a 'list' of DataReaders where a DataReader may appear more than one time.

To retrieve the samples in the order they were published across DataWriters of the same group (dds::pub::Publisher configured with dds::core::policy::PresentationAccessScopeKind_def::GROUP), the application should read()/take() from each DataReader in the same order as it appears in the output sequence. The application will move to the next DataReader when the read()/take() operation does not return any data.

See also: Access to data samples; dds::sub::CoherentAccess::CoherentAccess(); dds::sub::CoherentAccess::end(); PRESENTATION

Template Parameters

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

Parameters

subscriber	The dds::sub::Subscriber the DataReaders belong to
data_state	The DataState describing what kinds of samples the returned DataReaders must contain
begin	A forward iterator to the position in the destination container where the DataReaders will be copied into. This container should be a container of AnyDataReaders, not typed DataReaders
max_size	The maximum number of DataReaders to return

Returns: The number of DataReaders that were found with a matching DataState

References begin(), dds::sub::status::DataState::instance_state(), dds::sub::status::DataState::sample_state(), and dds::sub::status::DataState::view_state().

◆ find() [6/6]

template<typename AnyDataReaderBackInsertIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	subscriber,
		const dds::sub::status::DataState &	data_state,
		AnyDataReaderBackInsertIterator	begin
	)

Allows the application to access the AnyDataReaders that contain samples with the specified dds::sub::status::DataState.

Allows the application to access the dds::sub::DataReader objects that contain samples with the specified sample_states, view_states and instance_states.

If the application is outside a begin_access()/end_access() block, or if the dds::core::policy::Presentation::access_scope of the dds::sub::Subscriber is dds::core::policy::PresentationAccessScopeKind_def::INSTANCE or dds::core::policy::PresentationAccessScopeKind_def::TOPIC, or if the dds::core::policy::Presentation::ordered_access of the dds::sub::Subscriber is false, the returned collection is a 'set' containing each dds::sub::DataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the dds::sub::Subscriber is dds::core::policy::PresentationAccessScopeKind_def::GROUP or dds::core::policy::PresentationAccessScopeKind_def::HIGHEST_OFFERED, and dds::core::policy::Presentation::ordered_access in the dds::sub::Subscriber is true, the returned collection is a 'list' of DataReaders where a DataReader may appear more than one time.

To retrieve the samples in the order they were published across DataWriters of the same group (dds::pub::Publisher configured with dds::core::policy::PresentationAccessScopeKind_def::GROUP), the application should read()/take() from each DataReader in the same order as it appears in the output sequence. The application will move to the next DataReader when the read()/take() operation does not return any data.

See also: Access to data samples; dds::sub::CoherentAccess::CoherentAccess(); dds::sub::CoherentAccess::end(); PRESENTATION

Template Parameters

AnyDataReaderBackInsertIterator A back-inserting iterator whose value_type is dds::sub::AnyDataReader

Parameters

subscriber	The dds::sub::Subscriber the DataReaders belong to
data_state	The DataState describing what kinds of samples the returned DataReaders must contain
begin	A back-inserting iterator to the position in the destination container to insert the found DataReaders into. This container should be a container of AnyDataReaders, not typed DataReaders

Returns: The number of DataReaders that were found with a matching DataState

References begin(), dds::sub::status::DataState::instance_state(), dds::sub::status::DataState::sample_state(), and dds::sub::status::DataState::view_state().

◆ move()

template<typename T >

LoanedSamples< T > move ( LoanedSamples< T > & ls )

Creates a new LoanedSamples instance by moving the contents of an existing one.

Note: in <<C++11>> you can directly use std::move.

The parameter object loses the ownership of the underlying samples and its state is reset as if it was default initialized. This function must be used to move any named LoanedSamples instance (lvalue) in and out of a function by-value. Using this function is not necessary if the original LoanedSamples is an rvalue. Moving is a very efficient operation and is guaranteed to not throw any exception.

Parameters