RTI Connext Modern C++ API  Version 5.2.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::sub Namespace Reference

<<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
Oneof the Standard Exceptions or dds::core::NotEnabledError
Template Parameters
TThe topic-type that the DataReader subscribes to
Parameters
readerThe reader to lookup the matched participant data of
handleThe 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
SubscriberForwardIteratorType of the forward iterator passed into this function
Parameters
participantThe dds::domain::DomainParticipant the Publishers belong to
beginA forward iterator to the position in the destination container to insert the found Subscribers into
max_sizeThe 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
SubscriberBackInsertIteratorType of the back-inserting iterator passed into this function
Parameters
participantThe dds::domain::DomainParticipant the Subscribers belong to
beginA 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
participantThe dds::domain::DomainParticipant the Subscribers belong to
subscriber_nameThe 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
AnyDataReaderBackInsertIteratorType of the back-inserting iterator passed into this function
Parameters
subscriberThe dds::sub::Subscriber the DataReaders belong to
beginA 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
AnyDataReaderForwardIteratorA forward iterator whose value_type is dds::sub::AnyDataReader
Parameters
subscriberThe dds::sub::Subscriber the readers belong to
beginA forward iterator to the position in the destination container to insert the found readers in.
max_sizeThe 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:

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
subscriberThe dds::sub::Subscriber that created the DataReader to find
topic_nameTopic 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
subscriberThe dds::sub::Subscriber that created the DataReader to find
datareader_nameEntity 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
READERThe type of Reader that is being looked up
TThe topic-type
Parameters
subscriberThe Subscriber to which the DataReader belongs
topic_descriptionThe 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
participantThe dds::domain::DomainParticipant within which the dds::sub::DataReader exists
datareader_nameEntityName 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
dpThe 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:

std::vector<Sample<Foo> > sample_vector;
std::transform(
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& ()).

std::vector<KeyedType> data_vector;
std::copy(
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

RTI Connext Modern C++ API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc