#include "SubscriberListener.hpp"

Inherits dds::sub::AnyDataReaderListener.

Inherited by dds::domain::DomainParticipantListener [virtual], and dds::sub::NoOpSubscriberListener [virtual].

Public Member Functions
virtual void	on_data_available (AnyDataReader &reader)=0

virtual void	on_data_on_readers (Subscriber &sub)=0

virtual void	on_liveliness_changed (AnyDataReader &reader, const dds::core::status::LivelinessChangedStatus &status)=0

virtual void	on_requested_deadline_missed (AnyDataReader &reader, const dds::core::status::RequestedDeadlineMissedStatus &status)=0

virtual void	on_requested_incompatible_qos (AnyDataReader &reader, const dds::core::status::RequestedIncompatibleQosStatus &status)=0

virtual void	on_sample_lost (AnyDataReader &reader, const dds::core::status::SampleLostStatus &status)=0

virtual void	on_sample_rejected (AnyDataReader &reader, const dds::core::status::SampleRejectedStatus &status)=0

virtual void	on_subscription_matched (AnyDataReader &reader, const dds::core::status::SubscriptionMatchedStatus &status)=0

Detailed Description

Subscriber events Listener.

Since a Subscriber is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type SubscriberListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the SubscriberListener class.

All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.

The SubscriberListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The SubscriberListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::sub::SubscriberListener
{
public:
    virtual void on_requested_deadline_missed (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::RequestedDeadlineMissedStatus & status)
    {
        std::cout << "on_requested_deadline_missed" << std::endl;
    }
 
    virtual void on_requested_incompatible_qos (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::RequestedIncompatibleQosStatus & status)
    {
        std::cout << "on_requested_incompatible_qos" << std::endl;
    }
 
    virtual void on_sample_rejected (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SampleRejectedStatus & status)
    {
        std::cout << "on_sample_rejected" << std::endl;
    }
 
    virtual void on_liveliness_changed (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::LivelinessChangedStatus & status)
    {
        std::cout << "on_liveliness_changed" << std::endl;
    }
 
    virtual void on_data_available (
        dds::sub::AnyDataReader& reader)
    {
        std::cout << "on_data_available" << std::endl;
    }
 
    virtual void on_subscription_matched (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SubscriptionMatchedStatus & status)
    {
        std::cout << "on_subscription_matched" << std::endl;
    }
 
    virtual void on_sample_lost (
        dds::sub::AnyDataReader& reader,
        const dds::core::status::SampleLostStatus & status)
    {
        std::cout << "on_sample_lost" << std::endl;
    }
 
    virtual void on_data_on_readers (
        dds::sub::Subscriber& subs)
    {
        std::cout << "on_data_on_readers" << std::endl;
    }
};
 
// Create Subscriber with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
dds::sub::Subscriber subscriber(participant,
                                participant.default_subscriber_qos(),
                                new ExampleListener(),
                                dds::core::status::StatusMask::all());

See also: Subscriber; Listener information

Definition at line 124 of file SubscriberListener.hpp.

Member Function Documentation

◆ on_data_available()

virtual void dds::sub::AnyDataReaderListener::on_data_available ( AnyDataReader & reader )

pure virtualinherited

This operation is called by the Data Distribution Service when new data is available for this DataReader.

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataReaderListener is installed and enabled for the StatusMask::data_available().

The Data Distribution Service will provide a reference to the DataReader in the parameter reader for use by the application.

The statuses StatusMask::data_on_readers() and StatusMask::data_available() will occur together. In case these status changes occur, the Data Distribution Service will look for an attached and activated SubscriberListener or DomainParticipantListener (in that order) for the enabled StatusMask::data_on_readers(). In case the StatusMask::data_on_readers() can not be handled, the Data Distribution Service will look for an attached and activated DataReaderListener, SubscriberListener or DomainParticipantListener for the enabled StatusMask::data_available() (in that order).

Note that if on_data_on_readers is called, then the Data Distribution Service will not try to call on_data_available, however, the application can force a call to the DataReader objects that have data by means of the Subscriber::notify_datareaders() operation.

Parameters

reader contain a pointer to the DataReader for which data is available (this is an input to the application provided by the Data Distribution Service).

◆ on_data_on_readers()

virtual void dds::sub::SubscriberListener::on_data_on_readers ( Subscriber & sub )

pure virtual

This operation called by the Data Distribution Service when new data is available for this Subscriber.

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant SubscriberListener is installed and enabled with the StatusMask::data_on_readers().

The statuses on_data_on_readers() and on_data_available() will occur together. In case these status changes occur, the Data Distribution Service will look for an attached and activated SubscriberListener or DomainParticipantListener (in that order) for the enabled StatusMask::data_on_readers(). In case the StatusMask::data_on_readers() can not be handled, the Data Distribution Service will look for an attached and activated DataReaderListener, SubscriberListener or DomainParticipantListener for the enabled StatusMask::data_available() (in that order).

Note that if on_data_on_readers() is called, then the Data Distribution Service will not try to call on_data_available(), however, the application can force a call to the callback function on_data_available of DataReaderListener objects that have data by means of the Subscriber::notify_datareaders() operation.

Parameters

sub	contain a pointer to the Subscriber for which data is available (this is an input to the application provided by the Data Distribution Service).

◆ on_liveliness_changed()

virtual void dds::sub::AnyDataReaderListener::on_liveliness_changed	(	AnyDataReader &	reader,
		const dds::core::status::LivelinessChangedStatus &	status
	)

pure virtualinherited

This operation is called by the Data Distribution Service when the liveliness of one or more DataWriter objects that were writing instances read through this DataReader has changed.

In other words, some DataWriter have become “alive” or “not alive”. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataReaderListener is installed and enabled for the StatusMask::liveliness_changed().

Parameters

reader	contain a pointer to the DataReader for which the liveliness of one or more DataWriter objects has changed (this is an input to the application provided by the Data Distribution Service).
status	contain the LivelinessChangedStatus object (this is an input to the application provided by the Data Distribution Service).

◆ on_requested_deadline_missed()

virtual void dds::sub::AnyDataReaderListener::on_requested_deadline_missed	(	AnyDataReader &	reader,
		const dds::core::status::RequestedDeadlineMissedStatus &	status
	)

pure virtualinherited

This operation called by the Data Distribution Service when the deadline that the DataReader was expecting through its DeadlineQosPolicy was not respected for a specific instance.

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataReaderListener is installed and enabled for the StatusMask::requested_deadline_missed().

Parameters

reader	contain a pointer to the DataReader for which the deadline was missed (this is an input to the application provided by the Data Distribution Service).
status	contain the RequestedDeadlineMissedStatus object (this is an input to the application provided by the Data Distribution Service).

◆ on_requested_incompatible_qos()

virtual void dds::sub::AnyDataReaderListener::on_requested_incompatible_qos	(	AnyDataReader &	reader,
		const dds::core::status::RequestedIncompatibleQosStatus &	status
	)

pure virtualinherited

This operation is called by the Data Distribution Service when the RequestedIncompatibleQosStatus changes.

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataReaderListener is installed and enabled for the StatusMask::requested_incompatible_qos().

The Data Distribution Service will provide a reference to the DataReader in the parameter reader and the RequestedIncompatibleQosStatus object in the parameter status, for use by the application.

When the DataReaderListener on the DataReader is not enabled with the StatusMask::requested_incompatible_qos(), the RequestedIncompatibleQosStatus change will propagate to the SubscriberListener of the Subscriber (if enabled) or to the DomainParticipantListener of the DomainParticipant (if enabled).

Parameters

reader	the DataReader provided by the Data Distribution Service.
status	the RequestedIncompatibleQosStatus object provided by the Data Distribution Service.

◆ on_sample_lost()

virtual void dds::sub::AnyDataReaderListener::on_sample_lost	(	AnyDataReader &	reader,
		const dds::core::status::SampleLostStatus &	status
	)

pure virtualinherited

NOTE: This operation is not yet implemented. It is scheduled for a future release.

Parameters

reader the DataReader the Listener is applied to

status the SampleLostStatus status

◆ on_sample_rejected()

virtual void dds::sub::AnyDataReaderListener::on_sample_rejected	(	AnyDataReader &	reader,
		const dds::core::status::SampleRejectedStatus &	status
	)

pure virtualinherited

This operation called by the Data Distribution Service when a (received) sample has been rejected.

Samples may be rejected by the DataReader when it runs out of resource_limits to store incoming samples. Usually this means that old samples need to be ‘consumed’ (for example by ‘taking’ them instead of ‘reading’ them) to make room for newly incoming samples.

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataReaderListener is installed and enabled with the StatusMask::sample_lost().

Parameters

reader	contains a pointer to the DataReader for which a sample has been rejected (this is an input to the application provided by the Data Distribution Service).
status	contains the SampleRejectedStatus object (this is an input to the application provided by the Data Distribution Service).

◆ on_subscription_matched()

virtual void dds::sub::AnyDataReaderListener::on_subscription_matched	(	AnyDataReader &	reader,
		const dds::core::status::SubscriptionMatchedStatus &	status
	)

pure virtualinherited

This operation is called by the Data Distribution Service when a new match has been discovered for the current subscription, or when an existing match has ceased to exist.

Usually this means that a new DataWriter that matches the Topic and that has compatible Qos as the current DataReader has either been discovered, or that a previously discovered DataWriter has ceased to be matched to the current DataReader. A DataWriter may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DataReader or when either the DataReader or the DataWriter has chosen to put its matching counterpart on its ignore-list using the dds::sub::ignore or dds::pub::ignore operations.

The implementation of this Listener operation may be left empty when this functionality is not needed: it will only be called when the relevant DataReaderListener is installed and enabled for the StatusMask::subscription_matched().

Parameters

reader	contains a pointer to the DataReader for which a match has been discovered (this is an input to the application provided by the Data Distribution Service).
status	contains the SubscriptionMatchedStatus object (this is an input to the application provided by the Data Distribution Service).

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

dds/sub/SubscriberListener.hpp

reader	the DataReader the Listener is applied to
status	the SampleLostStatus status

Public Member Functions

Detailed Description

Member Function Documentation

◆ on_data_available()

◆ on_data_on_readers()

◆ on_liveliness_changed()

◆ on_requested_deadline_missed()

◆ on_requested_incompatible_qos()

◆ on_sample_lost()

◆ on_sample_rejected()

◆ on_subscription_matched()