dds::sub Namespace Reference

Namespaces
	cond
	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)
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)
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 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 BinIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const std::string &topic_name, BinIterator begin)
template<typename READER , typename FwdIterator >
uint32_t	find (const dds::sub::Subscriber &sub, const std::string &topic_name, FwdIterator begin, uint32_t max_size)
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)
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)
template<typename T , template< typename Q > class D>
LoanedSamples< T, D >	move (LoanedSamples< T, D > &a)

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

find() [1/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() [2/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

find() [3/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() [4/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() [5/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() [6/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

ignore() [1/2]

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

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

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

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.

See also DCPS_Builtin_Topics and DCPS_Builtin_Topics_PublicationData.

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.

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