RTI Connext Modern C++ API  Version 7.0.0
dds::sub Namespace Reference

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 subscription. 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)

◆ 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
nThe 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
queryThe 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"))
>> samples;

is equivalent to:

reader >> read
>> condition(Query(system.reader, "foo = 7"), DataState()::new_data())
>> samples;
Parameters
conditionThe 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
sThe 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
hThe 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
hThe 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 subscription.

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.

There is no way to reverse this operation.

Exceptions
Oneof 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
participantThe DomainParticipant for which the remote entity will be ignored
handleThe 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
participantThe DomainParticipant for which the remote entity will be ignored
beginA forward iterator to the initial position in a dds::core::InstanceHandleSeq holding the handles to the remote DataReaders to be ignored.
endA 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
Oneof 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
TThe topic-type that the DataReader subscribes to
Parameters
readerThe 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
Oneof 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
TThe topic-type that the DataReader subscribes to
FwdIteratorA forward iterator whose value type is dds::core::InstanceHandle
Parameters
readerThe reader whose publications are being retrieved
beginA forward iterator to the beginning position in the destination container of matching InstanceHandles
endA 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
Oneof the Standard Exceptions or dds::core::NotEnabledError
Template Parameters
TThe topic-type that the DataReader subscribes to
Parameters
readerThe reader associated with the publication whose data is being retrieved
handleThe 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
dpThe 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:

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
ReaderThe 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)
FwdIteratorThe type of forward iterator passed to this function
Parameters
subscriberThe dds::sub::Subscriber the DataReader belongs to
topic_nameName of the dds::topic::Topic associated with the DataReader that is to be looked up.
beginA forward iterator to the position in the destination container where the DataReaders will be copied into
max_sizeOnly 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:

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
ReaderThe 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)
BinIteratorThe type of back-inserting iterator passed to this function
Parameters
subscriberThe dds::sub::Subscriber the DataReader belongs to
topic_nameName of the dds::topic::Topic associated with the DataReader that is to be looked up.
beginA 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
AnyDataReaderFwdIteratorA forward iterator whose value_type is dds::sub::AnyDataReader
Parameters
subscriberThe dds::sub::Subscriber the DataReaders belong to
data_stateThe DataState describing what kinds of samples the returned DataReaders must contain
beginA 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_sizeThe 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
AnyDataReaderBackInsertIteratorA back-inserting iterator whose value_type is dds::sub::AnyDataReader
Parameters
subscriberThe dds::sub::Subscriber the DataReaders belong to
data_stateThe DataState describing what kinds of samples the returned DataReaders must contain
beginA 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
lsThe LoanedSamples object that transfers its ownership of the contained samples into the returned object. After this call, ls is empty.
Returns
A new LoanedSamples object, the new loan owner, with the same contents as ls had.
See also
LoanedSamples

References move().

Referenced by move().

◆ begin() [1/2]

◆ begin() [2/2]

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

◆ end() [1/2]

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

◆ end() [2/2]

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

◆ swap()

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