RTI Connext Modern C++ API  Version 5.3.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::sub::Subscriber Class Reference

<<reference-type>> A subscriber is the object responsible for actually receiving data from a subscription. More...

#include "dds/sub/Subscriber.hpp"

Inheritance diagram for dds::sub::Subscriber:
dds::core::Entity

Public Member Functions

 Subscriber (const ::dds::domain::DomainParticipant &the_participant)
 Create a Subscriber attached to the given DomainParticipant.
 
 Subscriber (const ::dds::domain::DomainParticipant &dp, const dds::sub::qos::SubscriberQos &the_qos, dds::sub::SubscriberListener *the_listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all())
 Create a Subscriber attached to the given DomainParticipant.
 
void notify_datareaders ()
 This operation invokes the operation on_data_available on the DataReaderListener objects attached to contained DataReader entities with a DATA_AVAILABLE status that is considered changed as described in Changes in read communication status.
 
void listener (Listener *the_listener, const dds::core::status::StatusMask &event_mask)
 Attach a listener to this Subscriber.
 
Listenerlistener () const
 Get the Subscriber listener.
 
dds::sub::qos::SubscriberQos qos () const
 Get the Subscriber QoS.
 
void qos (const dds::sub::qos::SubscriberQos &the_qos)
 Set the Subscriber QoS.
 
dds::sub::qos::DataReaderQos default_datareader_qos () const
 Get the default DataReader QoS.
 
Subscriberdefault_datareader_qos (const dds::sub::qos::DataReaderQos &the_qos)
 Set the default DataReaderQoS.
 
const
dds::domain::DomainParticipant
participant () const
 Return the DomainParticipant that owns this Subscriber.
 
- Public Member Functions inherited from dds::core::Entity
void enable ()
 Enables this entity (if it was created disabled)
 
const dds::core::status::StatusMask status_changes ()
 Retrieves the list of communication statuses that are triggered.
 
const dds::core::InstanceHandle instance_handle () const
 Get the instance handle that represents this entity.
 
void close ()
 Forces the destruction of this entity.
 
void retain ()
 Disables the automatic destruction of this entity.
 

Related Functions

(Note that these are not member functions.)

dds::sub::Subscriber builtin_subscriber (const dds::domain::DomainParticipant &dp)
 Access the built-in Subscriber.
 
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
 
dds::sub::Subscriber implicit_subscriber (const dds::domain::DomainParticipant &dp)
 <<extension>> Retrieves the implicit dds::sub::Subscriber for the given dds::domain::DomainParticipant.
 

Detailed Description

<<reference-type>> A subscriber is the object responsible for actually receiving data from a subscription.

QoS:
dds::sub::qos::SubscriberQos
Status:
dds::core::status::StatusMask::data_on_readers()
Listener:
dds::sub::SubscriberListener

A subscriber acts on the behalf of one or several dds::sub::DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned dds::sub::DataReader objects and then indicates to the application that data is available through its listener or by enabling related conditions.

The application can access the list of concerned dds::sub::DataReader objects through the operation dds::sub::find and then access the data available through operations on the dds::sub::DataReader.

The following operations may be called even if the dds::sub::Subscriber is not enabled. Other operations will the value dds::core::NotEnabledError if called on a disabled dds::sub::Subscriber:

All operations except for dds::sub::Subscriber::qos(const dds::sub::qos::SubscriberQos&), dds::sub::Subscriber::qos() const, dds::sub::Subscriber::listener(Listener* the_listener,const dds::core::status::StatusMask& event_mask), dds::sub::Subscriber::listener(), dds::core::Entity::enable and dds::sub::DataReader::DataReader() may fail with dds::core::NotEnabledError.

See Also
Operations Allowed in Listener Callbacks
dds::sub::find() and related functions
Entity Use Cases
Examples:
Foo_subscriber.cxx.

Constructor & Destructor Documentation

dds::sub::Subscriber::Subscriber ( const ::dds::domain::DomainParticipant the_participant)
inlineexplicit

Create a Subscriber attached to the given DomainParticipant.

The subscriber QoS will be set to participant.default_subscriber_qos()

Parameters
the_participantthe DomainParticipant that will own this subscriber.
dds::sub::Subscriber::Subscriber ( const ::dds::domain::DomainParticipant dp,
const dds::sub::qos::SubscriberQos the_qos,
dds::sub::SubscriberListener the_listener = NULL,
const dds::core::status::StatusMask mask = dds::core::status::StatusMask::all() 
)
inline

Create a Subscriber attached to the given DomainParticipant.

Parameters
dpThe DomainParticipant that will own this subscriber.
the_qosThe qos::SubscriberQos
the_listenerThe subscriber listener.
maskThe listener event mask.

Member Function Documentation

void dds::sub::Subscriber::notify_datareaders ( )
inline

This operation invokes the operation on_data_available on the DataReaderListener objects attached to contained DataReader entities with a DATA_AVAILABLE status that is considered changed as described in Changes in read communication status.

This operation is typically invoked from the dds::sub::SubscriberListener::on_data_on_readers operation in the dds::sub::SubscriberListener. That way the dds::sub::SubscriberListener can delegate to the dds::sub::DataReaderListener objects the handling of the data.

The operation will notify the data readers that have a sample_state of dds::sub::status::SampleState::not_read(), view_state of any() and instance_state of any().

Exceptions
Oneof the Standard Exceptions, or dds::core::NotEnabledError.
void dds::sub::Subscriber::listener ( Listener the_listener,
const dds::core::status::StatusMask event_mask 
)
inline

Attach a listener to this Subscriber.

Parameters
the_listenerThe listener
event_maskThe event mask for the listener.
Listener* dds::sub::Subscriber::listener ( ) const
inline

Get the Subscriber listener.

dds::sub::qos::SubscriberQos dds::sub::Subscriber::qos ( ) const
inline

Get the Subscriber QoS.

void dds::sub::Subscriber::qos ( const dds::sub::qos::SubscriberQos the_qos)
inline

Set the Subscriber QoS.

Parameters
the_qosthe new QoS.
dds::sub::qos::DataReaderQos dds::sub::Subscriber::default_datareader_qos ( ) const
inline

Get the default DataReader QoS.

Returns
dds::sub::qos::DataReaderQos
Subscriber& dds::sub::Subscriber::default_datareader_qos ( const dds::sub::qos::DataReaderQos the_qos)
inline

Set the default DataReaderQoS.

Parameters
the_qosThe default DataReaderQoS.
const dds::domain::DomainParticipant& dds::sub::Subscriber::participant ( ) const
inline

Return the DomainParticipant that owns this Subscriber.

Returns
const dds::domain::DomainParticipant& The DomainParticipant that owns this subscriber

Friends And Related Function Documentation

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

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.
template<typename SubscriberForwardIterator >
uint32_t find_subscribers ( const dds::domain::DomainParticipant  participant,
SubscriberForwardIterator  begin,
uint32_t  max_size 
)
related

<<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 find_subscribers ( const dds::domain::DomainParticipant  participant,
SubscriberBackInsertIterator  begin 
)
related

<<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 find_subscriber ( const dds::domain::DomainParticipant  participant,
const std::string &  subscriber_name 
)
related

<<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.
dds::sub::Subscriber implicit_subscriber ( const dds::domain::DomainParticipant dp)
related

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

RTI Connext Modern C++ API Version 5.3.1 Copyright © Mon Feb 19 2018 Real-Time Innovations, Inc