RTI Connext DDS Micro C API
Version 3.0.1
|
<<interface>> Abstract base class for all Listener interfaces. More...
#include <dds_c_infrastructure.h>
Data Fields | |
void * | listener_data |
A place for listener implementors to keep a pointer to data that may be needed by their listener. |
<<interface>> Abstract base class for all Listener interfaces.
All the supported kinds of concrete DDS_Listener interfaces (one per concrete DDS_Entity type) derive from this root and add functions 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 DDS_Listener instance may be shared among multiple entities if you so desire. Consequently, the provided parameter contains a reference to the concerned DDS_Entity.
The general mapping between the plain communication statuses (see Status Kinds) and the listeners' operations is as follows:
on_<communication_status>
(), which takes a parameter of type <communication_status>
as listed in Status Kinds. on_<communication_status>
is available on the relevant DDS_Entity as well as those that embed it, as expressed in the following figure: This behavior allows the application to set a default behavior (e.g., in the listener associated with the DDS_DomainParticipant) and to set dedicated behaviors only where needed.
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:
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 DDS_DataReader 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 DDS_DataReader).
Note that if DDS_SubscriberListener::on_data_on_readers is called, RTI Connext DDS Micro will not try to call DDS_DataReaderListener::on_data_available.
The operations that are allowed in DDS_Listener callbacks depend the DDS_Entity to which the DDS_Listener is attached – or in the case of a DDS_DataWriter of DDS_DataReader listener, on the parent DDS_Publisher or DDS_Subscriber.
The following operations are not allowed:
An attempt to call a disallowed function from within a callback will result in DDS_RETCODE_ILLEGAL_OPERATION.
The following are not allowed:
An attempt to call a disallowed function from within a callback will result in DDS_RETCODE_ILLEGAL_OPERATION.
void* DDS_Listener::listener_data |
A place for listener implementors to keep a pointer to data that may be needed by their listener.