Detailed Description

<<interface>> Abstract base class for all Listener interfaces.

Entity:: DDSEntity

QoS:: QoS Policies

Status:: Status Kinds

All the supported kinds of concrete DDSListener interfaces (one per concrete DDSEntity type) derive from this root and add methods whose prototype depends on the concrete Listener.

Listeners provide a way for RTI Connext DDS Micro to asynchronously alert the application when there are relevant status changes.

Almost every application will have to implement listener interfaces.

Each dedicated listener presents a list of operations that correspond to the relevant communication status changes to which an application may respond.

The same DDSListener instance may be shared among multiple entities if you so desire. Consequently, the provided parameter contains a reference to the concerned DDSEntity.

Access to Plain Communication Status

The general mapping between the plain communication statuses (see Status Kinds) and the listeners' operations is as follows:

For each communication status, there is a corresponding operation whose name is on_<communication_status>(), which takes a parameter of type <communication_status> as listed in Status Kinds.

on_<communication_status> is available on the relevant DDSEntity as well as those that embed it, as expressed in the following figure:

"Hierarchical listener processing. The most specific relevant enabled listener is called."

When the application attaches a listener on an entity, it must set a mask. The mask indicates to RTI Connext DDS Micro which operations are enabled within the listener (cf. operation DDSEntity set_listener() ).

When a plain communication status changes, RTI Connext DDS Micro triggers the most specific relevant listener operation that is enabled. In case the most specific relevant listener operation corresponds to an application-installed 'nil' listener the operation will be considered handled by a NO-OP operation that does not reset the communication status.

This behavior allows the application to set a default behavior (e.g., in the listener associated with the DDSDomainParticipant) and to set dedicated behaviors only where needed.

Access to Read Communication Status

The two statuses related to data arrival are treated slightly differently. Since they constitute the core purpose of the Data Distribution Service, there is no need to provide a default mechanism (as is done for the plain communication statuses above).

The rule is as follows. Each time the read communication status changes:

First, RTI Connext DDS Micro tries to trigger the DDSSubscriberListener::on_data_on_readers with a parameter of the related DDSSubscriber;

If this does not succeed (there is no listener or the operation is not enabled), RTI Connext DDS Micro tries to trigger DDSDataReaderListener::on_data_available on all the related DDSDataReaderListener objects, with a parameter of the related DDSDataReader.

The rationale is that either the application is interested in relations among data arrivals and it must use the first option or it wants to treat each DDSDataReader independently and it may choose the second option (and then get the data by calling FooDataReader::read_next_sample or FooDataReader::take_next_sample on the related DDSDataReader).

Note that if DDSSubscriberListener::on_data_on_readers is called, RTI Connext DDS Micro will not try to call DDSDataReaderListener::on_data_available.

The operations that are allowed in DDSListener callbacks depend the DDSEntity to which the DDSListener is attached – or in the case of a DDSDataWriter of DDSDataReader listener, on the parent DDSPublisher or DDSSubscriber.

The following operations are not allowed:

Within any listener callback, deleting the entity to which the DDSListener is attached
Within a DDSTopic listener callback, any operations on any subscribers, readers, publishers or writers

An attempt to call a disallowed method from within a callback will result in DDS_RETCODE_ILLEGAL_OPERATION.

The following are not allowed:

Within any listener callback, creating any entity
Within any listener callback, deleting any entity
Within any listener callback, enabling any entity
Within any listener callback, setting the QoS of any entities
Within a DDSDataReader or DDSSubscriber listener callback, invoking any operation on any other DDSSubscriber or on any DDSDataReader belonging to another DDSSubscriber.
Within a DDSDataReader or DDSSubscriber listener callback, invoking any operation on any DDSPublisher (or on any DDSDataWriter belonging to such a DDSPublisher).
Within a DDSDataWriter of DDSPublisher listener callback, invoking any operation on another Publisher or on a DDSDataWriter belonging to another DDSPublisher.
Within a DDSDataWriter of DDSPublisher listener callback, invoking any operation on any DDSSubscriber or DDSDataReader.

An attempt to call a disallowed method from within a callback will result in DDS_RETCODE_ILLEGAL_OPERATION.

See also:: Status Kinds