A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions. More...

#include "Subscriber.hpp"

Public Types
typedef dds::sub::SubscriberListener	Listener

Public Member Functions
	Subscriber (const ::dds::domain::DomainParticipant &dp)

	Subscriber (const ::dds::domain::DomainParticipant &dp, const dds::sub::qos::SubscriberQos &qos, dds::sub::SubscriberListener *listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::none())

void	close ()

dds::sub::qos::DataReaderQos	default_datareader_qos () const

Subscriber &	default_datareader_qos (const dds::sub::qos::DataReaderQos &qos)

void	enable ()

const dds::core::InstanceHandle	instance_handle () const

bool	is_nil () const

Listener *	listener () const

void	listener (Listener *listener, const dds::core::status::StatusMask &event_mask)

void	notify_datareaders ()

bool	operator!= (const null_type nil) const

template<typename R >
bool	operator!= (const R &ref) const

DELEGATE *	operator-> ()

const DELEGATE *	operator-> () const

Subscriber &	operator<< (const dds::sub::qos::SubscriberQos &qos)

bool	operator== (const null_type) const

template<typename R >
bool	operator== (const R &ref) const

const Subscriber &	operator>> (dds::sub::qos::SubscriberQos &qos) const

const dds::domain::DomainParticipant &	participant () const

const dds::sub::qos::SubscriberQos &	qos () const

void	qos (const dds::sub::qos::SubscriberQos &sqos)

void	retain ()

const dds::core::status::StatusMask	status_changes ()

Detailed Description

A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions.

A Subscriber acts on the behalf of one or several DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned 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 DataReader objects through the operation get_datareaders and then access the data available through operations on the DataReader.

See also: Subscriber

Definition at line 53 of file Subscriber.hpp.

Member Typedef Documentation

◆ Listener

typedef dds::sub::SubscriberListener dds::sub::Subscriber::Listener

Local convenience typedef for dds::sub::SubscriberListener.

Definition at line 63 of file Subscriber.hpp.

Constructor & Destructor Documentation

◆ Subscriber() [1/2]

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

Create a new Subscriber.

The Subscriber will be created with the QoS values specified on the last successful call to dp.default_subscriber_qos(qos) or, if the call was never made, the default values.

Parameters

dp	the domain participant

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ Subscriber() [2/2]

dds::sub::Subscriber::Subscriber	(	const ::dds::domain::DomainParticipant &	dp,
		const dds::sub::qos::SubscriberQos &	qos,
		dds::sub::SubscriberListener *	listener = `NULL`,
		const dds::core::status::StatusMask &	mask = `dds::core::status::StatusMask::none()`
	)

Create a new Subscriber.

The Subscriber will be created with the given QosPolicy settings and if applicable, attaches the optionally specified SubscriberListener to it.

See listener for more information about listeners and possible status propagation to other entities.

Parameters

dp	the domain participant to create the Subscriber with.
qos	a collection of QosPolicy settings for the new Subscriber. In case these settings are not self consistent, no Subscriber is created.
listener	the subscriber listener
mask	the mask of events notified to the listener

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::InconsistentPolicyError	The parameter qos contains conflicting QosPolicy settings.

Member Function Documentation

◆ close()

void dds::core::Entity::close ( )

inherited

This function closes the entity and releases related resources.

Resource management for some reference types might involve relatively heavyweight operating- system resources — such as e.g., threads, mutexes, and network sockets — in addition to memory. These objects therefore provide a method close() that shall halt network communication (in the case of entities) and dispose of any appropriate operating-system resources.

Users of this PSM are recommended to call close on objects of all reference types once they are finished using them. In addition, implementations may automatically close objects that they deem to be no longer in use, subject to the following restrictions:

Any object to which the application has a direct reference is still in use.
Any object that has been explicitly retained is still in use
The creator of any object that is still in use is itself still in use.

Returns: void

◆ default_datareader_qos() [1/2]

dds::sub::qos::DataReaderQos dds::sub::Subscriber::default_datareader_qos ( ) const

Gets the default DataReaderQos of the Subscriber.

This operation gets an object with the default DataReader QosPolicy settings of the Subscriber (that is the DataReaderQos) which is used for newly created DataReader objects, in case no QoS was provided during the creation.

The values retrieved by this operation match the set of values specified on the last successful call to dds::sub::Subscriber::default_datareader_qos(const dds::sub::qos::DataReaderQos& qos), or, if the call was never made, the default values.

Returns: the default DataReaderQos

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ default_datareader_qos() [2/2]

Subscriber& dds::sub::Subscriber::default_datareader_qos ( const dds::sub::qos::DataReaderQos & qos )

Sets the default DataReaderQos of the Subscriber.

This operation sets the default SubscriberQos of the Subscriber which is used for newly created Subscriber objects, when no QoS is provided.

This operation checks if the DataReaderQos is self consistent. If it is not, the operation has no effect and throws dds::core::InconsistentPolicyError.

The values set by this operation are returned by dds::sub::Subscriber::default_datareader_qos().

Parameters

qos	the default DataReaderQos

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::UnsupportedError	One or more of the selected QosPolicy values are currently not supported by OpenSplice.
dds::core::InconsistentPolicyError	The parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ enable()

void dds::core::Entity::enable ( )

inherited

Enable entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the dds::core::policy::EntityFactory QoS policy on the corresponding factory for the Entity.

Enabled entities are immediately activated at creation time meaning all their immutable QoS settings can no longer be changed. Disabled Entities are not yet activated, so it is still possible to change there immutable QoS settings. However, once activated the immutable QoS settings can no longer be changed.

Creating disabled entities can make sense when the creator of the Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.

The default setting of dds::core::policy::EntityFactory is such that, by default, it is not necessary to explicitly call enable on newly- created entities.

The enable operation is idempotent. Calling enable on an already- enabled Entity does not raise exceptions and has no effect.

If an Entity has not yet been enabled, the only operations that can be invoked on it are: the ones to set, get or copy the QosPolicy settings, the ones that set (or get) the listener, the ones that get the StatusCondition, the get_status_changes operation (although the status of a disabled entity never changes), and the ‘factory’ operations that create, delete or lookup other Entities. Other operations will throw the exception dds::core::NotEnabledError.

Entities created from a factory that is disabled are created disabled regardless of the setting of the dds::core::policy::EntityFactory Qos policy. Calling enable on an Entity whose factory is not enabled will fail and throw an dds::core::PreconditionNotMetError exception.

If the dds::core::policy::EntityFactory QoS policy has autoenable_created_entities set to TRUE, the enable operation on the factory will automatically enable all entities created from the factory.

The Listeners associated with an entity are not called until the entity is enabled. Conditions associated with an entity that is not enabled are inactive; that is, they have a trigger_value==false (dds::core::cond::Condition and dds::core::cond::WaitSet).

eg.

dds::domain::qos::DomainParticipantQos dpq;
dpq << dds::core::policy::EntityFactory::ManuallyEnable();
...
dds::sub::DataReader<Foo::Bar> dr(dp, topic, drqos);
dr.enable();

Returns: void

Exceptions

dds::core::PreconditionNotMetError Entities' factory is not enabled.

◆ instance_handle()

const dds::core::InstanceHandle dds::core::Entity::instance_handle ( ) const

inherited

This operation returns the InstanceHandle_t that represents the Entity.

The relevant state of some Entity objects are distributed using built-in topics. Each built-in topic sample represents the state of a specific Entity and has a unique instance_handle. This operation returns the instance_handle of the built-in topic sample that represents the specified Entity.
Some Entities (dds::pub::Publisher and dds::sub::Subscriber) do not have a corresponding built-in topic sample, but they still have an instance_handle that uniquely identifies the Entity. The instance_handles obtained this way can also be used to check whether a specific Entity is located in a specific DomainParticipant (dds::domain::DomainParticipant::contains_entity()).

Returns: dds::core::InstanceHandle Result value is the instance_handle of the built-in topic sample that represents the state of this Entity.

◆ is_nil()

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::is_nil ( ) const

inherited

Check if the referenced object is nil.

In other words, check if the reference is pointing to a null object.

Returns: true if the referenced object is null.

◆ listener() [1/2]

Listener* dds::sub::Subscriber::listener ( ) const

Get the listener of this Subscriber.

◆ listener() [2/2]

void dds::sub::Subscriber::listener	(	Listener *	listener,
		const dds::core::status::StatusMask &	event_mask
	)

Register a listener with the Subscriber.

The notifications received by the listener depend on the status mask with which it was registered.

Listener un-registration is performed by setting the listener to NULL.

◆ notify_datareaders()

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

This operation invokes the on_data_available operation on DataReaderListener objects which are attached to the contained DataReader entities having new, available data.

The notify_datareaders operation ignores the bit mask value of individual DataReaderListener objects, even when the dds::core::status::StatusMask::data_available() has not been set on a DataReader that has new, available data. The on_data_available operation will still be invoked, when the dds::core::status::StatusMask::data_available() bit has not been set on a DataReader, but will not propagate to the DomainParticipantListener.

When the DataReader has attached a NULL listener, the event will be consumed and will not propagate to the DomainParticipantListener. (Remember that a NULL listener is regarded as a listener that handles all its events as a NOOP).

Look here for Status change information.
Look here for Listener information.

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ operator!=() [1/2]

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::operator!= ( const null_type nil ) const

inherited

Special operator!= used to check if this reference object does not equal the dds::core::null reference.

The non-null-check can be done like this:

if (r != dds::core::null) {
   // Use the dds reference object r
}

Returns: true if this reference is not null.

◆ operator!=() [2/2]

template<typename DELEGATE>

template<typename R >

bool dds::core::Reference< DELEGATE >::operator!= ( const R & ref ) const

inherited

Compares two Reference objects and returns true if they are not equal.

Inequality is based on the referential inequality of the object being pointed to.

Parameters

ref	the other Reference object

Returns: true when not equal

◆ operator->() [1/2]

template<typename DELEGATE>

DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( )

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();

my_dds_entity->vendor_specific_extension();

Returns: a reference to delegate.

◆ operator->() [2/2]

template<typename DELEGATE>

const DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( ) const

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();

my_dds_entity->vendor_specific_extension();

Returns: a reference to delegate.

◆ operator<<()

Subscriber& dds::sub::Subscriber::operator<< ( const dds::sub::qos::SubscriberQos & qos )

Sets the SubscriberQos setting for this instance.

Parameters

sqos the qos

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ operator==() [1/2]

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::operator== ( const null_type ) const

inherited

Special operator== used to check if this reference object equals the dds::core::null reference.

The null-check can be done like this:

if (r == dds::core::null) {
   // Do not use the dds reference object r in its current state
}

Returns: true if this reference is null.

◆ operator==() [2/2]

template<typename DELEGATE>

template<typename R >

bool dds::core::Reference< DELEGATE >::operator== ( const R & ref ) const

inherited

Compares two Reference objects and returns true if they are equal.

Equality is based on the referential equality of the object being pointed.

Parameters

ref	the other Reference object

Returns: true when equal

◆ operator>>()

const Subscriber& dds::sub::Subscriber::operator>> ( dds::sub::qos::SubscriberQos & qos ) const

Gets the SubscriberQos setting for this instance.

Returns: the qos

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ participant()

const dds::domain::DomainParticipant& dds::sub::Subscriber::participant ( ) const

Return the DomainParticipant that owns this Subscriber.

Returns: the DomainParticipant

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.

◆ qos() [1/2]

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

Gets the SubscriberQos setting for this instance.

Returns: the qos

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ qos() [2/2]

void dds::sub::Subscriber::qos ( const dds::sub::qos::SubscriberQos & sqos )

Sets the SubscriberQos setting for this instance.

Parameters

sqos the qos

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::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

◆ retain()

void dds::core::Entity::retain ( )

inherited

Retain the Entity, even when it goes out of scope.

This function indicates that references to this object may go out of scope but that the application expects to look it up again later. Therefore the Service must consider this object to be still in use and may not close it automatically.

Returns: void

◆ status_changes()

const dds::core::status::StatusMask dds::core::Entity::status_changes ( )

inherited

This operation returns a mask with the communication statuses in the Entity that are “triggered”.

This operation retrieves the list of communication statuses in the Entity that are triggered. That is the set of communication statuses whose value have changed since the last time the application called this operation. This operation shows whether a change has occurred even when the status seems unchanged because the status changed back to the original status.

When the Entity is first created or if the Entity is not enabled, all communication statuses are in the “un-triggered” state so the mask returned by the operation is empty.

The result value is a bit mask in which each bit shows which value has changed. The relevant bits represent one of the following statuses:

When the entity is first created, or if the entity is not enabled, all communication statuses are in the untriggered state so the list returned by the status_changes operation will be empty.

Each status bit is declared as a constant and can be used in an AND operation to check the status bit against the result of type StatusMask. Not all statuses are relevant to all Entity objects. See the respective Listener interfaces for each Entity for more information.

The list of statuses returned by the status_changes operation refers to the statuses that are triggered on the Entity itself, and does not include statuses that apply to contained entities.

Returns: dds::core::status::StatusMask a bit mask in which each bit shows which value has changed.

The documentation for this class was generated from the following file:

dds/sub/Subscriber.hpp

listener	the listener
event_mask	the mask defining the events for which the listener will be notified.

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Listener

Constructor & Destructor Documentation

◆ Subscriber() [1/2]

◆ Subscriber() [2/2]

Member Function Documentation

◆ close()

◆ default_datareader_qos() [1/2]

◆ default_datareader_qos() [2/2]

◆ enable()

◆ instance_handle()

◆ is_nil()

◆ listener() [1/2]

◆ listener() [2/2]

◆ notify_datareaders()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator<<()

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator>>()

◆ participant()

◆ qos() [1/2]

◆ qos() [2/2]

◆ retain()

◆ status_changes()