Namespaces
	cond

	functors

	qos

	status

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

class	AnyDataReaderListener
	AnyDataReader events Listener. More...

class	CoherentAccess
	Class for RAII way of beginning/ending coherent access. More...

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

class	DataReaderListener
	DataReader events Listener. More...

class	GenerationCount
	Class to hold sample GenerationCount information and is part of dds::sub::SampleInfo. More...

class	LoanedSamples
	This class encapsulates and automates the management of loaned samples. More...

class	NoOpAnyDataReaderListener
	AnyDataReader events Listener. More...

class	NoOpDataReaderListener
	DataReader events Listener. More...

class	NoOpSubscriberListener
	Subscriber events Listener. More...

class	Query
	Query objects contain expressions that allow the application to specify a filter on the locally available data. More...

class	Rank
	Class to hold sample Rank information and is part of dds::sub::SampleInfo. More...

class	Sample
	This class encapsulates the data and info meta-data associated with DDS samples. More...

class	SampleInfo
	The SampleInfo contains information pertaining to the associated Data value. More...

class	SharedSamples
	This class encapsulates and automates the management of loaned samples. More...

class	Subscriber
	A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions. More...

class	SubscriberListener
	Subscriber events Listener. More...

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

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

template<typename READER , typename FwdIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const std::string &topic_name, FwdIterator begin, uint32_t max_size)

template<typename READER , typename BinIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const std::string &topic_name, BinIterator begin)

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

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

template<typename READER , typename FwdIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const dds::sub::status::DataState &data_state, FwdIterator begin, uint32_t max_size)

template<typename READER , typename BinIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const dds::sub::status::DataState &rs, BinIterator begin)

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

template<typename FwdIterator >
void	ignore (const dds::domain::DomainParticipant &dp, FwdIterator begin, FwdIterator end)

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

template<typename T >
const dds::topic::PublicationBuiltinTopicData	matched_publication_data (const dds::sub::DataReader< T > &dr, const ::dds::core::InstanceHandle &h)

template<typename T >
::dds::core::InstanceHandleSeq	matched_publications (const dds::sub::DataReader< T > &dr)

template<typename T , typename FwdIterator >
uint32_t	matched_publications (const dds::sub::DataReader< T > &dr, FwdIterator begin, uint32_t max_size)

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

template<typename T , template< typename Q > class D>
LoanedSamples< T, D >	move (LoanedSamples< T, D > &a)

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

template<typename SELECTOR >
SELECTOR &	read (SELECTOR &selector)

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

template<typename SELECTOR >
SELECTOR &	take (SELECTOR &selector)

Function Documentation

◆ builtin_subscriber()

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

This operation returns the built-in Subscriber associated with the given given DomainParticipant.

Each DomainParticipant contains several built-in Topic objects. The built-in Subscriber contains the corresponding DataReader objects to access them. All these DataReader objects belong to a single built-in Subscriber. Note that there is exactly one built-in Subscriber associated with each DomainParticipant.

See Builtin Topics for more information.

Parameters

dp	the domain participant

Returns: the built-in Subscriber

◆ content()

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

inline

Filter the samples by the query, read by the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. Normally, that would read all data samples that is available within the reader. However, it is possible to manipulate what samples are read.

By adding this operation as a selection in the read or as a manipulator in the read streaming operator, it is explicitly indicated that samples will be filtered according to the given dds::sub::Query.

// Assume data type has an element called long_1
dds::sub::Query query(reader, "long_1 > 1 and long_1 < 7");
// Read samples, filtered by content
reader >> dds::sub::dds::sub::content(query) >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>; Query

Definition at line 1455 of file DataReaderImpl.hpp.

◆ find() [1/6]

template<typename READER , typename FwdIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	sub,
		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. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub	the Subscriber for which to find a DataReader
topic_name	the topic name to find
begin	a forward iterator pointing to the start of a container in which to put the DataReaders
max_size	the number of DataReaders to return

Returns: the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

◆ find() [2/6]

template<typename READER , typename BinIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	sub,
		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. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub	the Subscriber for which to find a DataReader
topic_name	the topic name to find
begin	a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns: the total number of elements returned

◆ find() [3/6]

template<typename READER , typename T , typename FwdIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	sub,
		const dds::topic::TopicDescription &	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 topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub	the Subscriber for which to find a DataReader
topic_description	the topic description to find
begin	a forward iterator pointing to the start of a container in which to put the DataReaders
max_size	the number of DataReaders to return

Returns: the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

◆ find() [4/6]

template<typename READER , typename T , typename BinIterator >

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

This function retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return an empty container.

The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics (see Builtin Topics).

Parameters

sub	the Subscriber for which to find a DataReader
topic_description	the topic description to find
begin	a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns: the total number of elements returned

◆ find() [5/6]

template<typename READER , typename FwdIterator >

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

This operation allows the application to access the DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.

If the Presentation QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to ‘GROUP’, this operation should only be invoked inside a begin_access/end_access block. Otherwise it will throw error PreconditionNotMetError.

Depending on the setting of the dds::core::policy::Presentation QoSPolicy, the returned collection of DataReader objects may be:

a ‘set’ containing each DataReader at most once in no specified order,
a ‘list’ containing each DataReader one or more times in a specific order.

This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the ‘list’ and read or take exactly one sample from each DataReader. The patterns that an application should use to access data is fully described in dds::core::policy::Presentation.

Parameters

sub	the Subscriber for which to find a DataReader
data_state	the data_state to find
begin	a forward iterator pointing to the start of a container in which to put the DataReaders
max_size	the number of DataReaders to return

Returns: the total number of elements returned. Notice that at most max_size will be copied using the provided iterator

◆ find() [6/6]

template<typename READER , typename BinIterator >

uint32_t dds::sub::find	(	const dds::sub::Subscriber &	sub,
		const dds::sub::status::DataState &	rs,
		BinIterator	begin
	)

This operation allows the application to access the DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.

If the Presentation QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to ‘GROUP’, this operation should only be invoked inside a begin_access/end_access block. Otherwise it will throw error PreconditionNotMetError.

Depending on the setting of the dds::core::policy::Presentation QoSPolicy, the returned collection of DataReader objects may be:

a ‘set’ containing each DataReader at most once in no specified order,
a ‘list’ containing each DataReader one or more times in a specific order.

This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the ‘list’ and read or take exactly one sample from each DataReader. The patterns that an application should use to access data is fully described in dds::core::policy::Presentation.

Parameters

sub	the Subscriber for which to find a DataReader
data_state	the data_state to find
begin	a back inserting iterator pointing to the start of a container in which to put the DataReaders

Returns: the total number of elements returned

◆ ignore() [1/2]

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

Ignore subscriptions.

This operation allows an application to instruct the Service to locally ignore a remote subscription; a subscription is defined by the association of a topic name, and user data and partition set on the Subscriber. After this call, any data received related to that subscription will be ignored.

The DataReader to ignore is identified by the handle argument. This handle is the one that appears in the Sample retrieved when reading the data samples from the built-in DataReader to the "DCPSSubscription" topic.

This operation is not required to be reversible. The Service offers no means to reverse it.

Parameters

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

Exceptions

dds::core::OutOfResourcesError if the Service is unable to ignore the indicated participant because internal resource has been exhausted.

◆ ignore() [2/2]

template<typename FwdIterator >

void dds::sub::ignore	(	const dds::domain::DomainParticipant &	dp,
		FwdIterator	begin,
		FwdIterator	end
	)

Ignore subscriptions.

This operation is not yet implemented. It is scheduled for a future release.

Parameters

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

◆ instance()

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

inline

Filter the samples of an instance, read by the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. Normally, that would read all data samples that is available within the reader. However, it is possible to manipulate what samples are read.

By adding this operation as a selection in the read or as a manipulator in the read streaming operator, it is explicitly indicated that only samples of the given instance are read.

dds::core::InstanceHandle hdl = someValidInstanceHandle;
// Read samples, filtered by instance
reader >> dds::sub::instance(hdl) >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>; Instance Handle

Definition at line 1516 of file DataReaderImpl.hpp.

◆ matched_publication_data()

template<typename T >

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

This operation retrieves information on the specified publication that is currently “associated” with the DataReader. That is, a publication with a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant. The publication_handle must correspond to a publication currently associated with the DataReader, otherwise the operation will fail and throw InvalidArgumentError. The operation dds::sub::matched_publications can be used to find the publications that are currently matched with the DataReader.

The operation may fail if the infrastructure does not locally maintain the connectivity information. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will throw UnsupportedError.

Parameters

dr	the DataReader
h	the InstanceHandle

Returns: the PublicationBuiltinTopicData

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::NotEnabledError	The DataReader has not yet been enabled.
dds::core::UnsupportedError	OpenSplice is configured not to maintain the information about “associated” subscriptions.
dds::core::InvalidArgumentError	Publication not associated with the DataReader.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ matched_publications() [1/2]

template<typename T >

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

This operation retrieves the list of publications currently "associated" with the DataReader. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataWriter entities. You can access more detailed information about a particular publication by passing its publication_handle to either the dds::sub::matched_publication_data operation or to the read with instance operation on the built-in reader for the “DCPSPublication” topic.

Note: Be aware that since InstanceHandle_t is an opaque datatype, it does not necessarily mean that the handles obtained from the get_matched_publications operation have the same value as the ones that appear in the instance_handle field of the SampleInfo when retrieving the publication info through corresponding "DCPSPublications" built-in reader. You can’t just compare two handles to determine whether they represent the same publication. If you want to know whether two handles actually do represent the same publication, use both handles to retrieve their corresponding PublicationBuiltinTopicData samples and then compare the key field of both samples.

The operation may fail if the infrastructure does not locally maintain the connectivity information. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will throw UnsupportedError.

See Builtin Topics for more information.

Parameters

dr	the DataReader

Returns: a sequence of handles

Exceptions

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

◆ matched_publications() [2/2]

template<typename T , typename FwdIterator >

uint32_t dds::sub::matched_publications	(	const dds::sub::DataReader< T > &	dr,
		FwdIterator	begin,
		uint32_t	max_size
	)

This operation retrieves the list of publications currently "associated" with the DataReader. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the ignore_publication operation on the DomainParticipant.

The handles returned in the dds::core::InstanceHandleSeq are the ones that are used by the DDS implementation to locally identify the corresponding matched DataWriter entities. You can access more detailed information about a particular publication by passing its publication_handle to either the dds::sub::matched_publication_data operation or to the read with instance operation on the built-in reader for the “DCPSPublication” topic.

Note: Be aware that since InstanceHandle_t is an opaque datatype, it does not necessarily mean that the handles obtained from the get_matched_publications operation have the same value as the ones that appear in the instance_handle field of the SampleInfo when retrieving the publication info through corresponding "DCPSPublications" built-in reader. You can’t just compare two handles to determine whether they represent the same publication. If you want to know whether two handles actually do represent the same publication, use both handles to retrieve their corresponding PublicationBuiltinTopicData samples and then compare the key field of both samples.

The operation may fail if the infrastructure does not locally maintain the connectivity information. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will throw UnsupportedError.

See Builtin Topics for more information.

Parameters

dr	the DataReader
begin	an iterator indicating the beginning of a sequence of instance handles in which to put the matched subscriptions
max_size	the maximum number of matched subscriptions to return

Returns: the number of matched subscriptions returned

Exceptions

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

◆ max_samples()

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

inline

Limit the number of samples, read by the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. Normally, that would read all data samples that is available within the reader. However, it is possible to manipulate what samples are read.

By adding this operation as a selection in the read or as a manipulator in the read streaming operator, it is explicitly indicated that a maximum of n samples will be read.

// Read a maximum of three samples

reader >> dds::sub::max_samples(3) >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>

Definition at line 1425 of file DataReaderImpl.hpp.

◆ move()

template<typename T , template< typename Q > class D>

LoanedSamples< T, D > dds::sub::move ( LoanedSamples< T, D > & a )

Move loan and its ownership to a new LoanedSamples object.

Returns: LoanedSampless

Definition at line 82 of file LoanedSamplesImpl.hpp.

◆ next_instance()

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

inline

Filter the samples of the next instance, read by the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. Normally, that would read all data samples that is available within the reader. However, it is possible to manipulate what samples are read.

By adding this operation as a selection in the read or as a manipulator in the read streaming operator, it is explicitly indicated that only samples of the next instance of the given instance are read. When the given instance is a nil handle, then the first instance will be read.

// Read all samples, instance by instance
{
    dds::sub::LoanedSamples<Foo::Bar> samples;
    // Get sample(s) of first instance
    dds::core::InstanceHandle hdl; //nil
    reader >> dds::sub::next_instance(hdl) >> samples;
    while (samples.length() > 0) {
        // Handle the sample(s) of this instance (just the first one in this case)
        const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
        // Get sample(s) of the next instance
        hdl = sample.info().instance_handle();
        reader >> dds::sub::next_instance(hdl) >> samples;
    }
}

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>; Instance Handle

Definition at line 1556 of file DataReaderImpl.hpp.

◆ read()

template<typename SELECTOR >

SELECTOR& dds::sub::read ( SELECTOR & selector )

Indicate to do a read when using the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. The default of that operator is to read samples (not to take them). However, it is possible to manipulate if the samples are read or taken.

By adding this manipulator in the stream operator>>, it is explicitly indicated that the samples will be read and not taken.

// Read all samples implicitly
reader >> samples;
// Read all samples explicitly
reader >> dds::sub::read >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>

Definition at line 1371 of file DataReaderImpl.hpp.

◆ state()

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

inline

Filter the samples based on their state, read by the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. Normally, that would read all data samples that is available within the reader. However, it is possible to manipulate what samples are read.

By adding this operation as a selection in the read or as a manipulator in the read streaming operator, it is explicitly indicated that samples will be filtered according to the given dds::sub::status::DataState.

// DataState to filter only new data
dds::sub::status::DataState newData = dds::sub::status::DataState::new_data();
// Read samples, filtered by state
reader >> dds::sub::state(newData) >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader select(); DataReader stream operator>>; Query

Definition at line 1487 of file DataReaderImpl.hpp.

◆ take()

template<typename SELECTOR >

SELECTOR& dds::sub::take ( SELECTOR & selector )

Indicate to do a take when using the DataReader stream operator>>.

Reading data can be done by the DataReader stream operator>>. The default of that operator is to read samples (not to take them). However, it is possible to manipulate if the samples are read or taken.

By adding this manipulator in the stream operator>>, it is explicitly indicated that the samples will be taken and not read.

// Read all samples implicitly
reader >> samples;
// Take all samples explicitly
reader >> dds::sub::take >> samples;

Adding a manipulater operation in the stream operator>>, will create and use a dds::sub::DataReader::ManipulatorSelector implicitly.

See also: DataReader stream operator>>

Definition at line 1399 of file DataReaderImpl.hpp.

Namespaces

Classes

Functions

Function Documentation

◆ builtin_subscriber()

◆ content()

◆ find() [1/6]

◆ find() [2/6]

◆ find() [3/6]

◆ find() [4/6]

◆ find() [5/6]

◆ find() [6/6]

◆ ignore() [1/2]

◆ ignore() [2/2]

◆ instance()

◆ matched_publication_data()

◆ matched_publications() [1/2]

◆ matched_publications() [2/2]

◆ max_samples()

◆ move()

◆ next_instance()

◆ read()

◆ state()

◆ take()