Entity Status

group entity_status

All entities have a set of “status conditions” (following the DCPS spec), read peeks, take reads & resets (analogously to read & take operations on reader). The “mask” allows operating only on a subset of the statuses. Enabled status analogously to DCPS spec.

Defines

DDS_STATUS_ID_MAX (DDS_SUBSCRIPTION_MATCHED_STATUS_ID)

Helper value to indicate the highest bit that can be set in a status mask.

DDS_INCONSISTENT_TOPIC_STATUS (1u << DDS_INCONSISTENT_TOPIC_STATUS_ID)

Another topic exists with the same name but with different characteristics.

DDS_OFFERED_DEADLINE_MISSED_STATUS (1u << DDS_OFFERED_DEADLINE_MISSED_STATUS_ID)

The deadline that the writer has committed through its deadline QoS policy was not respected for a specific instance.

DDS_REQUESTED_DEADLINE_MISSED_STATUS (1u << DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID)

The deadline that the reader was expecting through its deadline QoS policy was not respected for a specific instance.

DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (1u << DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID)

A QoS policy setting was incompatible with what was requested.

DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (1u << DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID)

A QoS policy setting was incompatible with what is offered.

DDS_SAMPLE_LOST_STATUS (1u << DDS_SAMPLE_LOST_STATUS_ID)

A sample has been lost (never received).

DDS_SAMPLE_REJECTED_STATUS (1u << DDS_SAMPLE_REJECTED_STATUS_ID)

A (received) sample has been rejected.

DDS_DATA_ON_READERS_STATUS (1u << DDS_DATA_ON_READERS_STATUS_ID)

New information is available in some of the data readers of a subscriber.

DDS_DATA_AVAILABLE_STATUS (1u << DDS_DATA_AVAILABLE_STATUS_ID)

New information is available in a data reader.

DDS_LIVELINESS_LOST_STATUS (1u << DDS_LIVELINESS_LOST_STATUS_ID)

The liveliness that the DDS_DataWriter has committed through its liveliness QoS policy was not respected; thus readers will consider the writer as no longer “alive”.

DDS_LIVELINESS_CHANGED_STATUS (1u << DDS_LIVELINESS_CHANGED_STATUS_ID)

The liveliness of one or more writers, that were writing instances read through the readers has changed. Some writers have become “alive” or “not alive”.

DDS_PUBLICATION_MATCHED_STATUS (1u << DDS_PUBLICATION_MATCHED_STATUS_ID)

The writer has found a reader that matches the topic and has a compatible QoS.

DDS_SUBSCRIPTION_MATCHED_STATUS (1u << DDS_SUBSCRIPTION_MATCHED_STATUS_ID)

The reader has found a writer that matches the topic and has a compatible QoS.

Typedefs

typedef enum dds_status_id dds_status_id_t

These identifiers are used to generate the bitshifted identifiers. By using bitflags instead of these IDs the process of building status masks is simplified to using simple binary OR operations. DOC_TODO fix the refs.

Enums

enum dds_status_id

These identifiers are used to generate the bitshifted identifiers. By using bitflags instead of these IDs the process of building status masks is simplified to using simple binary OR operations. DOC_TODO fix the refs.

Values:

enumerator DDS_INCONSISTENT_TOPIC_STATUS_ID

See DDS_INCONSISTENT_TOPIC_STATUS

enumerator DDS_OFFERED_DEADLINE_MISSED_STATUS_ID

See DDS_OFFERED_DEADLINE_MISSED_STATUS

enumerator DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID

See DDS_REQUESTED_DEADLINE_MISSED_STATUS

enumerator DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID

See DDS_OFFERED_INCOMPATIBLE_QOS_STATUS

enumerator DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID

See DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS

enumerator DDS_SAMPLE_LOST_STATUS_ID

See DDS_SAMPLE_LOST_STATUS

enumerator DDS_SAMPLE_REJECTED_STATUS_ID

See DDS_SAMPLE_REJECTED_STATUS

enumerator DDS_DATA_ON_READERS_STATUS_ID

See DDS_DATA_ON_READERS_STATUS

enumerator DDS_DATA_AVAILABLE_STATUS_ID

See DDS_DATA_AVAILABLE_STATUS

enumerator DDS_LIVELINESS_LOST_STATUS_ID

See DDS_LIVELINESS_LOST_STATUS

enumerator DDS_LIVELINESS_CHANGED_STATUS_ID

See DDS_LIVELINESS_CHANGED_STATUS

enumerator DDS_PUBLICATION_MATCHED_STATUS_ID

See DDS_PUBLICATION_MATCHED_STATUS

enumerator DDS_SUBSCRIPTION_MATCHED_STATUS_ID

See DDS_SUBSCRIPTION_MATCHED_STATUS

Functions

dds_return_t dds_read_status(dds_entity_t entity, uint32_t *status, uint32_t mask)

Read the status set for the entity

This operation reads the status(es) set for the entity based on the enabled status and mask set. It does not clear the read status(es).

Parameters

  • entity – [in] Entity on which the status has to be read.

  • status – [out] Returns the status set on the entity, based on the enabled status.

  • mask – [in] Filter the status condition to be read, 0 means all statuses

Return values

  • DDS_RETCODE_OK – Success.

  • DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter, status is a null pointer or mask has bits set outside the status range.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object or mask has status bits set that are undefined for the type of entity.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_take_status(dds_entity_t entity, uint32_t *status, uint32_t mask)

Read the status set for the entity

This operation reads the status(es) set for the entity based on the enabled status and mask set. It clears the status set after reading.

Parameters

  • entity – [in] Entity on which the status has to be read.

  • status – [out] Returns the status set on the entity, based on the enabled status.

  • mask – [in] Filter the status condition to be read, 0 means all statuses

Return values

  • DDS_RETCODE_OK – Success.

  • DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter, status is a null pointer or mask has bits set outside the status range.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object or mask has status bits set that are undefined for the type of entity.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_get_status_changes(dds_entity_t entity, uint32_t *status)

Get changed status(es)

This operation returns the status changes since they were last read.

Parameters

  • entity – [in] Entity on which the statuses are read.

  • status – [out] Returns the current set of triggered statuses.

Return values

  • DDS_RETCODE_OK – Success.

  • DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_get_status_mask(dds_entity_t entity, uint32_t *mask)

Get enabled status on entity

This operation returns the status enabled on the entity.

Parameters

  • entity – [in] Entity to get the status.

  • mask – [out] Mask of enabled statuses set on the entity.

Return values

  • DDS_RETCODE_OK – Success.

  • DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_set_status_mask(dds_entity_t entity, uint32_t mask)

Set status enabled on entity

This operation enables the status(es) based on the mask set.

Parameters

  • entity – [in] Entity to enable the status.

  • mask – [in] Status value that indicates the status to be enabled.

Return values

  • DDS_RETCODE_OK – Success.

  • DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.