dds::domain::DomainParticipantListener Class Reference

DomainParticipant events Listener. More...

#include "DomainParticipantListener.hpp"

Inherits dds::pub::PublisherListener, dds::sub::SubscriberListener, and dds::topic::AnyTopicListener.

Inherited by dds::domain::NoOpDomainParticipantListener [virtual].

Public Member Functions
virtual void	on_data_available (AnyDataReader &reader)=0
virtual void	on_data_on_readers (Subscriber &sub)=0
virtual void	on_inconsistent_topic (AnyTopic &topic, const dds::core::status::InconsistentTopicStatus &status)=0
virtual void	on_liveliness_changed (AnyDataReader &reader, const dds::core::status::LivelinessChangedStatus &status)=0
virtual void	on_liveliness_lost (dds::pub::AnyDataWriter &writer, const ::dds::core::status::LivelinessLostStatus &status)=0
virtual void	on_offered_deadline_missed (dds::pub::AnyDataWriter &writer, const ::dds::core::status::OfferedDeadlineMissedStatus &status)=0
virtual void	on_offered_incompatible_qos (dds::pub::AnyDataWriter &writer, const ::dds::core::status::OfferedIncompatibleQosStatus &status)=0
virtual void	on_publication_matched (dds::pub::AnyDataWriter &writer, const ::dds::core::status::PublicationMatchedStatus &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

DomainParticipant events Listener.

Since a DomainParticipant is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DomainParticipantListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DomainParticipantListener 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 DomainParticipantListener 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 DomainParticipantListener is related to changes in communication status StatusConditions.

// Application example listener
class ExampleListener :
               public virtual dds::domain::DomainParticipantListener
{
public:
    virtual void on_inconsistent_topic (
        dds::topic::AnyTopic& topic,
        const dds::core::status::InconsistentTopicStatus& status)
    {
        std::cout << "on_inconsistent_topic" << std::endl;
    }
 
    virtual void on_offered_deadline_missed (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::OfferedDeadlineMissedStatus& status)
    {
        std::cout << "on_offered_deadline_missed" << std::endl;
    }
 
    virtual void on_offered_incompatible_qos (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::OfferedIncompatibleQosStatus& status)
    {
        std::cout << "on_offered_incompatible_qos" << std::endl;
    }
 
    virtual void on_liveliness_lost (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::LivelinessLostStatus& status)
    {
        std::cout << "on_liveliness_lost" << std::endl;
    }
 
    virtual void on_publication_matched (
        dds::pub::AnyDataWriter& writer,
        const dds::core::status::PublicationMatchedStatus& status)
    {
        std::cout << "on_publication_matched" << std::endl;
    }
 
    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 DomainParticipant with the listener
dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id(),
                                           dds::domain::DomainParticipant::default_participant_qos(),
                                           new ExampleListener(),
                                           dds::core::status::StatusMask::all());

See also

Domain Participant

Listener information

Definition at line 160 of file DomainParticipantListener.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 virtualinherited

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_inconsistent_topic()

virtual void dds::topic::AnyTopicListener::on_inconsistent_topic ( AnyTopic &  topic, const dds::core::status::InconsistentTopicStatus &  status  )

pure virtualinherited

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

The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant TopicListener is installed and enabled with the StatusMask::inconsistent_topic(). The InconsistentTopicStatus will change when another Topic exists with the same topic_name but different characteristics.

Parameters

topic	contain a pointer to the Topic on which the conflict occurred (this is an input to the application).
status	contain the InconsistentTopicStatus object (this is an input to the application).

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_liveliness_lost()

virtual void dds::pub::AnyDataWriterListener::on_liveliness_lost ( dds::pub::AnyDataWriter &  writer, const ::dds::core::status::LivelinessLostStatus &  status  )

pure virtualinherited

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

This operation will only be called when the relevant DataWriterListener is installed and enabled for the liveliness lost status (StatusMask::liveliness_lost()). The liveliness lost status will change when the liveliness that the DataWriter has committed through its LivelinessQosPolicy was not respected. In other words, the DataWriter failed to actively signal its liveliness within the offered liveliness period. As a result, the DataReader objects will consider the DataWriter as no longer “alive”.

Parameters

writer	contains a pointer to the DataWriter on which the LivelinessLostStatus has changed (this is an input to the application).
status	contains the LivelinessLostStatus object (this is an input to the application).

on_offered_deadline_missed()

virtual void dds::pub::AnyDataWriterListener::on_offered_deadline_missed ( dds::pub::AnyDataWriter &  writer, const ::dds::core::status::OfferedDeadlineMissedStatus &  status  )

pure virtualinherited

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

This operation will only be called when the relevant DataWriterListener is installed and enabled for the offered deadline missed status (StatusMask::offered_deadline_missed()). The offered deadline missed status will change when the deadline that the DataWriter has committed through its DeadlineQosPolicy was not respected for a specific instance.

Parameters

writer	contain a pointer to the DataWriter on which the OfferedDeadlineMissedStatus has changed (this is an input to the application)
status	contain the OfferedDeadlineMissedStatus object (this is an input to the application).

on_offered_incompatible_qos()

virtual void dds::pub::AnyDataWriterListener::on_offered_incompatible_qos ( dds::pub::AnyDataWriter &  writer, const ::dds::core::status::OfferedIncompatibleQosStatus &  status  )

pure virtualinherited

This operation called by the Data Distribution Service when the OfferedIncompatibleQosStatus changes.

This operation will only be called when the relevant DataWriterListener is installed and enabled for the StatusMask::offered_incompatible_qos(). The incompatible Qos status will change when a DataReader object has been discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter.

Parameters

writer	contain a pointer to the DataWriter on which the OfferedIncompatibleQosStatus has changed (this is an input to the application).
status	contain the OfferedIncompatibleQosStatus object (this is an input to the application).

on_publication_matched()

virtual void dds::pub::AnyDataWriterListener::on_publication_matched ( dds::pub::AnyDataWriter &  writer, const ::dds::core::status::PublicationMatchedStatus &  status  )

pure virtualinherited

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

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

it will only be called when the relevant DataWriterListener is installed and enabled for the StatusMask::publication_matched().

Parameters

writer	contains a pointer to the DataWriter for which a match has been discovered (this is an input to the application provided by the Data Distribution Service).
status	contains the PublicationMatchedStatus 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/domain/DomainParticipantListener.hpp