3.1.3. Status

Each Entity is associated with a set of Status objects whose values represent the communication status of that Entity. Changes on the status values occur due to communication events related to each of the entities, e.g., when new data arrives, a new participant is discovered, or a remote endpoint is lost. The status is decomposed into several status objects, each concerning a different aspect of the communication, so that each of these status objects can vary independently of the others.

Changes on a status object trigger the corresponding Listener callbacks that allow the Entity to inform the application about the event. For a given status object with name fooStatus, the entity listener interface defines a callback function on_foo() that will be called when the status changes. Beware that some statuses have data members that are reset every time the corresponding listener is called. The only exception to this rule is when the entity has no listener attached, so the callback cannot be called. See the documentation of each status for details.

The entities expose functions to access the value of its statuses. For a given status with name fooStatus, the entity exposes a member function get_foo() to access the data in its fooStatus. The only exceptions are DataOnReaders and DataAvailable. These getter functions return a read-only struct where all data members are public and accessible to the application. Beware that some statuses have data members that are reset every time the getter function is called by the application. See the documentation of each status for details.

The following subsections describe each of the status objects, their data members, and to which Entity type they concern. The next table can be used as a quick reference too.

Status Name

Entity

Listener callback

Accessor

InconsistentTopicStatus

Topic

on_inconsistent_topic()

get_inconsistent_topic_status()

DataOnReaders

Subscriber

on_data_on_readers()

N/A

DataAvailable

DataReader

on_data_available()

N/A

LivelinessChangedStatus

DataReader

on_liveliness_changed()

get_liveliness_changed_status()

RequestedDeadlineMissedStatus

DataReader

on_requested_deadline_missed()

get_requested_deadline_missed_status()

RequestedIncompatibleQosStatus

DataReader

on_requested_incompatible_qos()

get_requested_incompatible_qos_status()

SampleLostStatus

DataReader

on_sample_lost()

get_sample_lost_status()

SampleRejectedStatus

DataReader

on_sample_rejected()

get_sample_rejected_status()

SubscriptionMatchedStatus

DataReader

on_subscription_matched()

get_subscription_matched_status()

LivelinessLostStatus

DataWriter

on_liveliness_lost()

get_liveliness_lost_status()

OfferedDeadlineMissedStatus

DataWriter

on_offered_deadline_missed()

get_offered_deadline_missed_status()

OfferedIncompatibleQosStatus

DataWriter

on_offered_incompatible_qos()

get_offered_incompatible_qos_status()

PublicationMatchedStatus

DataWriter

on_publication_matched()

get_publication_matched_status()

3.1.3.1. InconsistentTopicStatus

This status changes every time an inconsistent remote Topic is discovered, that is, one with the same name but different characteristics than the current Topic. See InconsistentTopicStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.2. DataOnReaders

This status becomes active every time there is new data available for the application on any DataReader belonging to the current Subscriber. There is no getter function to access this status, as it does not keep track of any information related to the data itself. Its only purpose is to trigger the on_data_on_readers() callback on the listener attached to the DataReader.

3.1.3.3. DataAvailable

This status becomes active every time there is new data available for the application on the DataReader. There is no getter function to access this status, as it does not keep track of any information related to the data itself. Its only purpose is to trigger the on_data_available() callback on the listener attached to the DataReader.

3.1.3.4. LivelinessChangedStatus

This status changes every time the liveliness status of a matched DataWriter has changed. Either because a DataWriter that was inactive has become active or the other way around. See LivelinessChangedStatus.

List of status data members:

Data Member Name

Type

alive_count

int32_t

not_alive_count

int32_t

alive_count_change

int32_t

not_alive_count_change

int32_t

last_publication_handle

InstanceHandle_t

  • alive_count: Total number of currently active DataWriters. This count increases every time a newly matched DataWriter asserts its liveliness or a DataWriter that was considered not alive reasserts its liveliness. It decreases every time an active DataWriter becomes not alive, either because it failed to asserts its liveliness or because it was deleted for any reason.

  • not_alive_count: Total number of matched DataWriters that are currently considered not alive. This count increases every time an active DataWriter becomes not alive because it fails to assert its liveliness. It decreases every time a DataWriter that was considered not alive reasserts its liveliness. Normal matching and unmatching of DataWriters does not affect this count.

  • alive_count_change: The change in alive_count since the last time on_liveliness_changed() was called or the status was read. It can have positive or negative values.

  • not_alive_count_change: The change in not_alive_count since the last time on_liveliness_changed() was called or the status was read. It can have positive or negative values.

  • last_publication_handle: Handle to the last DataWriter whose liveliness status was changed. If no liveliness has ever changed, it will have value c_InstanceHandle_Unknown.

3.1.3.5. RequestedDeadlineMissedStatus

This status changes every time the DataReader does not receive data within the deadline period configured on its DataReaderQos. See RequestedDeadlineMissedStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

last_instance_handle

InstanceHandle_t

  • total_count: Total cumulative count of missed deadlines for any instance read by the current DataReader. As the deadline period applies to each instance of the Topic independently, the count will will be incremented by one for each instance for which data was not received in the deadline period.

  • total_count_change: The change in total_count since the last time on_requested_deadline_missed() was called or the status was read. It can only have zero or positive values.

  • last_instance_handle: Handle to the last instance that missed the deadline. If no deadline was ever missed, it will have value c_InstanceHandle_Unknown.

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.6. RequestedIncompatibleQosStatus

This status changes every time the DataReader finds a DataWriter that matches the Topic and has a common partition, but with a QoS configuration incompatible with the one defined on the DataReader. See RequestedIncompatibleQosStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

last_policy_id

QosPolicyId_t

policies

QosPolicyCountSeq

  • total_count: Total cumulative count of DataWriters found matching the Topic and with a common partition, but with a QoS configuration that is incompatible with the one defined on the DataReader.

  • total_count_change: The change in total_count since the last time on_requested_incompatible_qos() was called or the status was read. It can only have zero or positive values.

  • last_policy_id: The policy ID of one of the policies that was found to be incompatible with the current DataReader. If more than one policy happens to be incompatible, only one of them will be reported in this member.

  • policies: A collection that holds, for each policy, the total number of times that the policy was found to be incompatible with the one offered by a remote DataWriter that matched the Topic and with a common partition. See QosPolicyCountSeq and QosPolicyCount for more information the information that is stored for each policy.

3.1.3.6.1. QosPolicyCountSeq

Holds a QosPolicyCount for each Policy, indexed by its QosPolicyId_t. Therefore, the Qos Policy with ID N will be at position N in the sequence. See QosPolicyCountSeq.

DataReader* data_reader =
        subscriber->create_datareader(topic, DATAREADER_QOS_DEFAULT);

// Get how many times ReliabilityQosPolicy was not compatible with a remote writer
RequestedIncompatibleQosStatus status;
data_reader->get_requested_incompatible_qos_status(status);
uint32_t incompatible_reliability_count = status.policies[RELIABILITY_QOS_POLICY_ID].count;

3.1.3.6.2. QosPolicyCount

This structure holds a counter for a policy. See QosPolicyCount.

List of data members:

Data Member Name

Type

policy_id

QosPolicyId_t

count

int32_t

  • policy_id: The ID of the policy.

  • count: The counter value for the policy.

3.1.3.7. SampleLostStatus

This status changes every time a new data sample is lost and will never be received. See SampleLostStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.8. SampleRejectedStatus

This status changes every time an incoming data sample is rejected by the DataReader. The reason for the rejection is stored as a SampleRejectedStatusKind. See SampleRejectedStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

last_reason

SampleRejectedStatusKind

last_instance_handle

InstanceHandle_t

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.8.1. SampleRejectedStatusKind

There are four possible values (see SampleRejectedStatusKind):

3.1.3.9. SubscriptionMatchedStatus

This status changes every time the DataReader finds a DataWriter that matches the Topic and has a common partition and a compatible QoS, or has ceased to be matched with a DataWriter that was previously considered to be matched. See SubscriptionMatchedStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

current_count

int32_t

current_count_change

int32_t

last_publication_handle

InstanceHandle_t

3.1.3.10. LivelinessLostStatus

This status changes every time the DataWriter failed to assert its liveliness during the period configured on its DataWriterQos. This means that matched DataReader entities will consider the DataWriter as no longer alive. See LivelinessLostStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

  • total_count: Total cumulative count of times that the DataWriter failed to assert its liveliness during the period configured on its DataWriterQos, becoming considered not alive. This count does not change when the DataWriter is already considered not alive and simply remains not alive for another liveliness period.

  • total_count_change: The change in total_count since the last time on_liveliness_lost() was called or the status was read. It can only have zero or positive values.

3.1.3.11. OfferedDeadlineMissedStatus

This status changes every time the DataWriter fails to provide data within the deadline period configured on its DataWriterQos. See OfferedDeadlineMissedStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

last_instance_handle

InstanceHandle_t

  • total_count: Total cumulative count of missed deadlines for any instance written by the current DataWriter. As the deadline period applies to each instance of the Topic independently, the count will will be incremented by one for each instance for which data was not sent in the deadline period.

  • total_count_change: The change in total_count since the last time on_offered_deadline_missed() was called or the status was read. It can only have zero or positive values.

  • last_instance_handle: Handle to the last instance that missed the deadline. If no deadline was ever missed, it will have value c_InstanceHandle_Unknown.

Warning

Currently this status is not supported and will be implemented in future releases. As a result, trying to access this status will return NOT_SUPPORTED and the corresponding listener will never be called.

3.1.3.12. OfferedIncompatibleQosStatus

This status changes every time the DataWriter finds a DataReader that matches the Topic and has a common partition, but with a QoS configuration that is incompatible with the one defined on the DataWriter. See OfferedIncompatibleQosStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

last_policy_id

QosPolicyId_t

policies

QosPolicyCountSeq

  • total_count: Total cumulative count of DataReaders found matching the Topic and with a common partition, but with a QoS configuration that is incompatible with the one defined on the DataWriter.

  • total_count_change: The change in total_count since the last time on_offered_incompatible_qos() was called or the status was read. It can only have zero or positive values.

  • last_policy_id: The policy ID of one of the policies that was found to be incompatible with the current DataWriter. If more than one policy happens to be incompatible, only one of them will be reported in this member.

  • policies: A collection that holds, for each policy, the total number of times that the policy was found to be incompatible with the one requested by a remote DataReader that matched the Topic and with a common partition. See QosPolicyCountSeq and QosPolicyCount for more information the information that is stored for each policy.

3.1.3.13. PublicationMatchedStatus

This status changes every time the DataWriter finds a DataReader that matches the Topic and has a common partition and a compatible QoS, or has ceased to be matched with a DataReader that was previously considered to be matched. See PublicationMatchedStatus.

List of status data members:

Data Member Name

Type

total_count

int32_t

total_count_change

int32_t

current_count

int32_t

current_count_change

int32_t

last_subscription_handle

InstanceHandle_t