RTI Connext DDS Micro C++ API  Version 3.0.3
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
DDSDomainParticipantListener Class Reference

<<interface>> <<cert>> Listener for participant status. More...

#include <dds_cpp_domain.hxx>

List of all members.

Public Member Functions

virtual void on_data_available (DDSDataReader *)
 <<cert>> Handle the DDS_DATA_AVAILABLE_STATUS communication status.
virtual void on_requested_deadline_missed (DDSDataReader *reader, const DDS_RequestedDeadlineMissedStatus &status)
 <<cert>> Handles the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.
virtual void on_liveliness_changed (DDSDataReader *reader, const DDS_LivelinessChangedStatus &status)
 <<cert>> Handles the DDS_LIVELINESS_CHANGED_STATUS communication status.
virtual void on_requested_incompatible_qos (DDSDataReader *reader, const DDS_RequestedIncompatibleQosStatus &status)
 <<cert>> Handles the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.
virtual void on_sample_rejected (DDSDataReader *reader, const DDS_SampleRejectedStatus &status)
 <<cert>> Handles the DDS_SAMPLE_REJECTED_STATUS communication status.
virtual void on_subscription_matched (DDSDataReader *reader, const DDS_SubscriptionMatchedStatus &status)
 <<cert>> Handles the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.
virtual void on_sample_lost (DDSDataReader *reader, const DDS_SampleLostStatus &status)
 <<cert>> Handles the DDS_SAMPLE_LOST_STATUS communication status.
virtual void on_instance_replaced (DDSDataReader *reader, const DDS_DataReaderInstanceReplacedStatus &status)
 <<cert>> Handles the DDS_INSTANCE_REPLACED_STATUS communication status.
virtual DDS_Boolean on_before_sample_deserialize (DDSDataReader *reader, NDDS_Type_Plugin *, CDR_Stream_t *stream, DDS_Boolean *)
 <<cert>> Callback to filter a received sample based on serialized data
virtual DDS_Boolean on_before_sample_commit (DDSDataReader *, const void *const, const struct DDS_SampleInfo *const, DDS_Boolean *)
 <<cert>> Callback to filter a received sample based on deserialized data
virtual void on_data_on_readers (DDSSubscriber *)
 Handles the DDS_DATA_ON_READERS_STATUS communication status.
virtual void on_offered_deadline_missed (DDSDataWriter *writer, const struct DDS_OfferedDeadlineMissedStatus &status)
 <<cert>> Handles the DDS_OFFERED_DEADLINE_MISSED_STATUS status.
virtual void on_liveliness_lost (DDSDataWriter *writer, const struct DDS_LivelinessLostStatus &status)
 <<cert>> Handles the DDS_LIVELINESS_LOST_STATUS status.
virtual void on_offered_incompatible_qos (DDSDataWriter *writer, const struct DDS_OfferedIncompatibleQosStatus &status)
 <<cert>> Handles the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS status.
virtual void on_publication_matched (DDSDataWriter *writer, const struct DDS_PublicationMatchedStatus &status)
 <<cert>> Handles the DDS_PUBLICATION_MATCHED_STATUS status.
virtual void on_reliable_reader_activity_changed (DDSDataWriter *writer, const struct DDS_ReliableReaderActivityChangedStatus &status)
 <<eXtension>> <<cert>> A matched reliable reader has become active or become inactive.
virtual void on_inconsistent_topic (DDSTopic *topic, const DDS_InconsistentTopicStatus &status)
 Handle the DDS_INCONSISTENT_TOPIC_STATUS status.

Detailed Description

<<interface>> <<cert>> Listener for participant status.

Entity:
DDSDomainParticipant
Status:
Status Kinds

This is the interface that can be implemented by an application-provided class and then registered with the DDSDomainParticipant such that the application can be notified by RTI Connext DDS Micro of relevant status changes.

The DDSDomainParticipantListener interface extends all other Listener interfaces and has no additional operation beyond the ones defined by the more general listeners.

The purpose of the DDSDomainParticipantListener is to be the listener of last resort that is notified of all status changes not captured by more specific listeners attached to the DDSDomainEntity objects. When a relevant status change occurs, RTI Connext DDS Micro will first attempt to notify the listener attached to the concerned DDSDomainEntity if one is installed. Otherwise, RTI Connext DDS Micro will notify the Listener attached to the DDSDomainParticipant.

Important: Because a DDSDomainParticipantListener may receive callbacks pertaining to many different entities, it is possible for the same listener to receive multiple callbacks simultaneously in different threads. (Such is not the case for listeners of other types.) It is therefore critical that users of this listener provide their own protection for any thread-unsafe activities undertaken in a DDSDomainParticipantListener callback.

See also:
DDSListener
DDSDomainParticipant::set_listener
RTI Connext DDS Micro C++ API avoids the use of multiple inheritance for certification
purposes. For this reason, DDSDomainParticipantListener is not
declared as a sub-class of DDSPublisherListener, DDSSubscriberListener,
and DDSTopicListener, but it explicitly declares all supported
call-backs.

Member Function Documentation

virtual void DDSDomainParticipantListener::on_data_available ( DDSDataReader )
inlinevirtual

<<cert>> Handle the DDS_DATA_AVAILABLE_STATUS communication status.

virtual void DDSDomainParticipantListener::on_requested_deadline_missed ( DDSDataReader reader,
const DDS_RequestedDeadlineMissedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_REQUESTED_DEADLINE_MISSED_STATUS communication status.

virtual void DDSDomainParticipantListener::on_liveliness_changed ( DDSDataReader reader,
const DDS_LivelinessChangedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_LIVELINESS_CHANGED_STATUS communication status.

virtual void DDSDomainParticipantListener::on_requested_incompatible_qos ( DDSDataReader reader,
const DDS_RequestedIncompatibleQosStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

virtual void DDSDomainParticipantListener::on_sample_rejected ( DDSDataReader reader,
const DDS_SampleRejectedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_SAMPLE_REJECTED_STATUS communication status.

virtual void DDSDomainParticipantListener::on_subscription_matched ( DDSDataReader reader,
const DDS_SubscriptionMatchedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_SUBSCRIPTION_MATCHED_STATUS communication status.

virtual void DDSDomainParticipantListener::on_sample_lost ( DDSDataReader reader,
const DDS_SampleLostStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_SAMPLE_LOST_STATUS communication status.

virtual void DDSDomainParticipantListener::on_instance_replaced ( DDSDataReader reader,
const DDS_DataReaderInstanceReplacedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_INSTANCE_REPLACED_STATUS communication status.

This listener may only be called when the instance replacement policy is set to DDS_REPLACE_OLDEST_INSTANCE_REPLACEMENT_QOS. When a new instance is detected and resources are exhausted the oldest instance will be removed even if samples with a not read state exists for the instance. Thus, this is a forceful removal of samples and the instance. The freed instance resources will be re-used for the newly detected instance. If there are outstanding loans for the replaced instance the samples can not be freed until returned. However, when the loan is returned the samples are automatically freed. Note that the instance will not be rejected.

virtual DDS_Boolean DDSDomainParticipantListener::on_before_sample_deserialize ( DDSDataReader reader,
NDDS_Type_Plugin *  ,
CDR_Stream_t *  stream,
DDS_Boolean  
)
inlinevirtual

<<cert>> Callback to filter a received sample based on serialized data

When a DataReader receives a (serialized) sample, it will deserialize it before storing it in its queue. On_before_sample_deserialize() is called before deserialization. It allows the application to determine whether or not to drop the sample, before it is read or taken.

The callback controls whether the sample is filter out of the DataReader's queue, with the sample_dropped parameter. If user code within the callback determines that the sample should be dropped, the user should set sample_dropped to true; consequently, when the callback returns, the DataReader will drop the sample before it is committed to the queue. Otherwise, returning the callback with sample_dropped as false will allow the sample to be read or taken.

Compared to on_before_sample_commit(), the sample would be dropped with less processing (without deserialization) by the subscribing application, but with the added complexity of filtering on serialized data.

The callback is not associated with a DDS Status. It is enabled when the callback in the listener is assigned, to a non-NULL callback.

virtual DDS_Boolean DDSDomainParticipantListener::on_before_sample_commit ( DDSDataReader ,
const void *  const,
const struct DDS_SampleInfo const,
DDS_Boolean  
)
inlinevirtual

<<cert>> Callback to filter a received sample based on deserialized data

When a DataReader receives a (serialized) sample, it will deserialize it before storing it in its queue. On_before_sample_commit() is called after deserialization, but before the sample is stored into the DataReader's queue. It allows the application to determine whether or not to drop the sample, before it is read or taken.

The callback controls whether the sample is filter out of the DataReader's queue, with the sample_dropped parameter. If user code within the callback determines that the sample should be dropped, the user should set sample_dropped to true; consequently, when the callback returns, the DataReader will drop the sample before it is committed to the queue. Otherwise, returning the callback with sample_dropped as false will allow the sample to be read or taken.

Compared to on_before_sample_deserialize(), the sample would be dropped with more processing (with deserialization) by the subscribing application, but with the lesser complexity of filtering on deserialized data.

The callback is not associated with a DDS Status. It is enabled when the callback in the listener is assigned, to a non-NULL callback.

The following fields are valid in the DDS_SampleInfo structure:

  • source_timestamp
  • instance_handle
  • publication_handle
  • valid_data
  • encapsulation_id
virtual void DDSDomainParticipantListener::on_data_on_readers ( DDSSubscriber )
inlinevirtual

Handles the DDS_DATA_ON_READERS_STATUS communication status.

virtual void DDSDomainParticipantListener::on_offered_deadline_missed ( DDSDataWriter writer,
const struct DDS_OfferedDeadlineMissedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_OFFERED_DEADLINE_MISSED_STATUS status.

This callback is called when the deadline that the DDSDataWriter has committed through its DEADLINE qos policy was not respected for a specific instance. This callback is called for each deadline period elapsed during which the DDSDataWriter failed to provide data for an instance.

Parameters:
writer<<out>> Locally created DDSDataWriter that triggers the listener callback
status<<out>> Current deadline missed status of locally created DDSDataWriter
virtual void DDSDomainParticipantListener::on_liveliness_lost ( DDSDataWriter writer,
const struct DDS_LivelinessLostStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_LIVELINESS_LOST_STATUS status.

This callback is called when the liveliness that the DDSDataWriter has committed through its LIVELINESS qos policy was not respected; this DDSDataReader entities will consider the DDSDataWriter as no longer "alive/active". This callback will not be called when an already not alive DDSDataWriter simply remains not alive for another liveliness period.

Parameters:
writer<<out>> Locally created DDSDataWriter that triggers the listener callback
status<<out>> Current liveliness lost status of locally created DDSDataWriter
virtual void DDSDomainParticipantListener::on_offered_incompatible_qos ( DDSDataWriter writer,
const struct DDS_OfferedIncompatibleQosStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS status.

This callback is called when the DDS_DataWriterQos of the DDSDataWriter was incompatible with what was requested by a DDSDataReader. This callback is called when a DDSDataWriter has discovered a DDSDataReader for the same DDSTopic and common partition, but with a requested QoS that is incompatible with that offered by the DDSDataWriter.

Parameters:
writer<<out>> Locally created DDSDataWriter that triggers the listener callback
status<<out>> Current incompatible qos status of locally created DDSDataWriter
virtual void DDSDomainParticipantListener::on_publication_matched ( DDSDataWriter writer,
const struct DDS_PublicationMatchedStatus status 
)
inlinevirtual

<<cert>> Handles the DDS_PUBLICATION_MATCHED_STATUS status.

This callback is called when the DDSDataWriter has found a DDSDataReader that matches the DDSTopic, has a common partition and compatible QoS, or has ceased to be matched with a DDSDataReader that was previously considered to be matched.

Parameters:
writer<<out>> Locally created DDSDataWriter that triggers the listener callback
status<<out>> Current publication match status of locally created DDSDataWriter
virtual void DDSDomainParticipantListener::on_reliable_reader_activity_changed ( DDSDataWriter writer,
const struct DDS_ReliableReaderActivityChangedStatus status 
)
inlinevirtual

<<eXtension>> <<cert>> A matched reliable reader has become active or become inactive.

A reliable writer considers a matched reliable reader to be active when it receives ACKNACK messages from the reader in response to its HEARTBEAT messages. The writer considers an active reader to have become inactive when it has sent a number of consecutive periodic HEARTBEATs equal to DDS_RtpsReliableWriterProtocol_t::max_heartbeat_retries without receiving an ACKNACK from the reader. An inactive reader becomes active once the writer receives an ACKNACK from it.

This callback is called when the transition from active to inactive, and vice versa, has occurred for a matched reliable reader.

Parameters:
writer<<out>> Locally created DDSDataWriter that triggers the listener callback
status<<out>> Current reliable reader activity changed status of locally created DDSDataWriter
virtual void DDSDomainParticipantListener::on_inconsistent_topic ( DDSTopic topic,
const DDS_InconsistentTopicStatus status 
)
inlinevirtual

Handle the DDS_INCONSISTENT_TOPIC_STATUS status.

This callback is called when a remote DDSTopic is discovered but is inconsistent with the locally created DDSTopic of the same topic name.

Parameters:
topic<<out>> Locally created DDSTopic that triggers the listener callback
status<<out>> Current inconsistent status of locally created DDSTopic

RTI Connext DDS Micro C++ API Version 3.0.3 Copyright © Wed Jun 24 2020 Real-Time Innovations, Inc