<<extension>> Extensions to dds::sub More...

Classes
class	AckResponseData
	<<extension>> Data payload associated to an application-level acknowledgment More...

class	LoanedSample
	The element type of a dds::sub::LoanedSamples collection. More...

struct	IsValidData
	<<extension>> A functor that returns true when a sample has valid data. More...

class	SampleIterator
	A random-access iterator of LoanedSample. More...

class	ValidSampleIterator
	A forward iterator adapter that skips invalid samples. More...

class	ManipulatorSelector

class	SharedSamples
	Provides access to a collection of middleware-loaned samples. More...

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

template<typename SubscriberForwardIterator >
uint32_t	find_subscribers (const dds::domain::DomainParticipant participant, SubscriberForwardIterator begin, uint32_t max_size)
	<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

template<typename SubscriberBackInsertIterator >
uint32_t	find_subscribers (const dds::domain::DomainParticipant participant, SubscriberBackInsertIterator begin)
	<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

dds::sub::Subscriber	find_subscriber (const dds::domain::DomainParticipant participant, const std::string &subscriber_name)
	<<extension>> Finds a Subscriber by name

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

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.

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

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

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

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

dds::sub::Subscriber	implicit_subscriber (const dds::domain::DomainParticipant &dp)
	<<extension>> Retrieves the implicit dds::sub::Subscriber for the given dds::domain::DomainParticipant.

template<typename T >
dds::sub::Sample< T >	copy_to_sample (const rti::sub::LoanedSample< T > &ls)
	Copies the contents of a rti::sub::LoanedSample into a dds::sub::Sample.

template<typename T >
std::ostream &	operator<< (std::ostream &out, const LoanedSample< T > &sample)
	Calls the operator on the data or prints [invalid data].

bool	operator== (const SampleInfoImpl &other) const
	Compare two dds::sub::SampleInfo objects for equality.

template<typename T >
ValidSampleIterator< T >	valid_samples (const SampleIterator< T > &sample_iterator)
	<<extension>> Returns an iterator that skips invalid samples

Detailed Description

<<extension>> Extensions to dds::sub

Function Documentation

template<typename T >

dds::topic::ParticipantBuiltinTopicData rti::sub::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.

Matched Participants are those with a matching dds::topic::Topic, compatible QoS and common partition that the application has not indicated should be "ignored" by means of the dds::pub::ignore operation.

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.

Note: This operation does not retrieve the dds::topic::ParticipantBuiltinTopicData::property.

The above information is available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the PublicationBuiltinTopicDataDataReader).

.

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 associated with a DataWriter. 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

template<typename SubscriberForwardIterator >

uint32_t rti::sub::find_subscribers	(	const dds::domain::DomainParticipant	participant,
		SubscriberForwardIterator	begin,
		uint32_t	max_size
	)

<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

Template Parameters

SubscriberForwardIterator Type of the forward iterator passed into this function

Parameters

participant	The dds::domain::DomainParticipant the Publishers belong to
begin	A forward iterator to the position in the destination container to insert the found Subscribers into
max_size	The maximum size of Subscribers to add

Returns: The number of found Subscribers

template<typename SubscriberBackInsertIterator >

uint32_t rti::sub::find_subscribers	(	const dds::domain::DomainParticipant	participant,
		SubscriberBackInsertIterator	begin
	)

<<extension>> Retrieve all of the dds::sub::Subscriber created from this dds::domain::DomainParticipant

Template Parameters

SubscriberBackInsertIterator Type of the back-inserting iterator passed into this function

Parameters

participant	The dds::domain::DomainParticipant the Subscribers belong to
begin	A back-inserting iterator to the position in the destination container to insert the found Subscribers into

Returns: The number of found Subscribers

dds::sub::Subscriber rti::sub::find_subscriber	(	const dds::domain::DomainParticipant	participant,
		const std::string &	subscriber_name
	)

<<extension>> Finds a Subscriber by name

Parameters

participant	The dds::domain::DomainParticipant the Subscribers belong to
subscriber_name	The name of the Subscriber

Returns: A valid reference if the a subscriber with that name exists or a reference equals to dds::core::null otherwise.

template<typename AnyDataReaderBackInsertIterator >

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

<<extension>> Retrieve all the dds::sub::DataReader created from this dds::sub::Subscriber

Template Parameters

AnyDataReaderBackInsertIterator Type of the back-inserting iterator passed into this function

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

template<typename AnyDataReaderForwardIterator >

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

<<extension>> Retrieve all the readers created from a subscriber.

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 to insert the found readers in.
max_size	The maximum number of readers to return

Returns: The number of found readers

template<typename READER >

READER rti::sub::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

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 lookup_datareader().
Call enable() on the DomainParticipant.

Parameters

topic_name <<in>> Name of the TopicDescription that the retrieved dds::sub::DataReader is attached to. Cannot be NULL.

Returns: A dds::sub::DataReader that belongs to the dds::sub::Subscriber attached to the TopicDescription with topic_name. If no such dds::sub::DataReader exists, this operation returns NULL.

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.

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

template<typename READER >

READER rti::sub::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

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

template<typename READER , typename T >

READER rti::sub::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

Template Parameters

READER	The type of Reader that is being looked up
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

template<typename READER >

READER rti::sub::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

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

dds::sub::Subscriber rti::sub::implicit_subscriber ( const dds::domain::DomainParticipant & dp )

<<extension>> Retrieves the implicit dds::sub::Subscriber for the given dds::domain::DomainParticipant.

If an implicit Subscriber does not already exist, this creates one.

The implicit Subscriber is created with default dds::sub::qos::SubscriberQos and no listener. When a DomainParticipant is deleted, if there are no attached dds::sub::DataReader that belong to the implicit Subscriber, the implicit Subscriber will be implicitly deleted.

                \par MT Safety:

UNSAFE. it is not safe to create the implicit subscriber while another thread may be simultaneously calling dds::domain::DomainParticipant::default_subscriber_qos(const dds::sub::qos::SubscriberQos & qos ).

Parameters

dp	The DomainParticipant that the implicit subscriber belongs to.

Returns: The implicit Subscriber

template<typename T >

dds::sub::Sample< T > copy_to_sample ( const rti::sub::LoanedSample< T > & ls )

Copies the contents of a rti::sub::LoanedSample into a dds::sub::Sample.

Example:

dds::sub::LoanedSamples<Foo> samples = reader.take();
std::vector<Sample<Foo> > sample_vector;
std::transform(
    rti::sub::valid_samples(samples.begin()),
    rti::sub::valid_samples(samples.end()),
    std::back_inserter(sample_vector),
    rti::sub::copy_to_sample<Foo>);

template<typename T >

std::ostream & operator<<	(	std::ostream &	out,
		const LoanedSample< T > &	sample
	)

Calls the operator on the data or prints [invalid data].

bool rti::sub::operator== ( const SampleInfoImpl & other ) const

Compare two dds::sub::SampleInfo objects for equality.

template<typename T >

ValidSampleIterator< T > rti::sub::valid_samples ( const SampleIterator< T > & sample_iterator )

<<extension>> Returns an iterator that skips invalid samples

Given a regular sample iterator, this functions creates another iterator it that behaves exactly the same except that it++ moves to the next valid sample (or to the end of the collection). That is, if it doesn't point to the end of the collection, it->info.valid() is always true.

This is useful when your application doesn't need to deal with samples containing meta-information only.

For example, the following code copies all the data in a LoanedSamples collection skipping any invalid samples (otherwise, attempting to copy the data from an invalid sample would throw an exception, see rti::sub::LoanedSample::operator const DataType& ()).

dds::sub::LoanedSamples<KeyedType> samples = reader.take();
std::vector<KeyedType> data_vector;
std::copy(
     rti::sub::valid_samples(samples.begin()),
     rti::sub::valid_samples(samples.end()),
     std::back_inserter(data_vector));

Note that valid_samples(samples.begin()) won't point to the first element if that element is not a valid sample.

A similar utility is the functor rti::sub::IsValidData.

See Also: dds::sub::LoanedSamples; rti::sub::IsValidData; dds::sub::SampleInfo::valid(); Reading data samples

Classes

Functions

Detailed Description

Function Documentation