RTI Connext C API  Version 6.0.0
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Status Kinds

Kinds of communication status. More...

Macros

#define DDS_STATUS_MASK_NONE
 No bits are set.
 
#define DDS_STATUS_MASK_ALL
 All bits are set.
 

Typedefs

typedef DDS_UnsignedLong DDS_StatusMask
 A bit-mask (list) of concrete status types, i.e. DDS_StatusKind[].
 

Enumerations

enum  DDS_StatusKind {
  DDS_INCONSISTENT_TOPIC_STATUS,
  DDS_OFFERED_DEADLINE_MISSED_STATUS,
  DDS_REQUESTED_DEADLINE_MISSED_STATUS,
  DDS_OFFERED_INCOMPATIBLE_QOS_STATUS,
  DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS,
  DDS_SAMPLE_LOST_STATUS,
  DDS_SAMPLE_REJECTED_STATUS,
  DDS_DATA_ON_READERS_STATUS,
  DDS_DATA_AVAILABLE_STATUS,
  DDS_LIVELINESS_LOST_STATUS,
  DDS_LIVELINESS_CHANGED_STATUS,
  DDS_PUBLICATION_MATCHED_STATUS,
  DDS_SUBSCRIPTION_MATCHED_STATUS,
  DDS_SERVICE_REQUEST_ACCEPTED_STATUS,
  DDS_DATA_WRITER_APPLICATION_ACKNOWLEDGMENT_STATUS,
  DDS_DATA_WRITER_INSTANCE_REPLACED_STATUS,
  DDS_RELIABLE_WRITER_CACHE_CHANGED_STATUS,
  DDS_RELIABLE_READER_ACTIVITY_CHANGED_STATUS,
  DDS_DATA_WRITER_CACHE_STATUS,
  DDS_DATA_WRITER_PROTOCOL_STATUS,
  DDS_DATA_READER_CACHE_STATUS,
  DDS_DATA_READER_PROTOCOL_STATUS ,
  DDS_DATA_WRITER_SAMPLE_REMOVED_STATUS
}
 Type for status kinds. More...
 

Detailed Description

Kinds of communication status.

Entity:
DDS_Entity
QoS:
QoS Policies
Listener:
DDS_Listener

Each concrete DDS_Entity is associated with a set of Status objects whose value represents the communication status of that entity. Each status value can be accessed with a corresponding function on the DDS_Entity.

When these status values change, the corresponding DDS_StatusCondition objects are activated and the proper DDS_Listener objects are invoked to asynchronously inform the application.

An application is notified of communication status by means of the DDS_Listener or the DDS_WaitSet / DDS_Condition mechanism. The two mechanisms may be combined in the application (e.g., using DDS_WaitSet (s) / DDS_Condition (s) to access the data and DDS_Listener (s) to be warned asynchronously of erroneous communication statuses).

It is likely that the application will choose one or the other mechanism for each particular communication status (not both). However, if both mechanisms are enabled, then the DDS_Listener mechanism is used first and then the DDS_WaitSet objects are signalled.

The statuses may be classified into:

Read communication statuses are treated slightly differently than the others because they don't change independently. In other words, at least two changes will appear at the same time (DDS_DATA_ON_READERS_STATUS and DDS_DATA_AVAILABLE_STATUS) and even several of the last kind may be part of the set. This 'grouping' has to be communicated to the application.

For each plain communication status, there is a corresponding structure to hold the status value. These values contain the information related to the change of status, as well as information related to the statuses themselves (e.g., contains cumulative counts).

DDSStatuses.png
Status Values

Changes in Status

Associated with each one of an DDS_Entity's communication status is a logical StatusChangedFlag. This flag indicates whether that particular communication status has changed since the last time the status was read by the application. The way the status changes is slightly different for the Plain Communication Status and the Read Communication status.

DDSStatusChangedFlag.png
StatusChangedFlag indicates if status has changed

Changes in plain communication status

For the plain communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever the plain communication status changes and it is reset to DDS_BOOLEAN_FALSE each time the application accesses the plain communication status via the proper get_<plain communication status>() operation on the DDS_Entity.

The communication status is also reset to FALSE whenever the associated listener operation is called as the listener implicitly accesses the status which is passed as a parameter to the operation. The fact that the status is reset prior to calling the listener means that if the application calls the get_<plain communication status> from inside the listener it will see the status already reset.

An exception to this rule is when the associated listener is the 'nil' listener. The 'nil' listener is treated as a NOOP and the act of calling the 'nil' listener does not reset the communication status.

For example, the value of the StatusChangedFlag associated with the DDS_REQUESTED_DEADLINE_MISSED_STATUS will become TRUE each time new deadline occurs (which increases DDS_RequestedDeadlineMissedStatus::total_count). The value changes to FALSE when the application accesses the status via the corresponding DDS_DataReader_get_requested_deadline_missed_status method on the proper Entity

DDSPlainCommunicationStatus.png
Changes in StatusChangedFlag for plain communication status

Changes in read communication status

For the read communication status, the StatusChangedFlag flag is initially set to FALSE. The StatusChangedFlag becomes TRUE when either a data-sample arrives or else the DDS_ViewStateKind, DDS_SampleStateKind, or DDS_InstanceStateKind of any existing sample changes for any reason other than a call to FooDataReader_read, FooDataReader_take or their variants. Specifically any of the following events will cause the StatusChangedFlag to become TRUE:

Depending on the kind of StatusChangedFlag, the flag transitions to FALSE again as follows:

DDSDataAvailableStatus.png
DDSDataOnReadersStatus.png
Changes in StatusChangedFlag for read communication status
See Also
DDS_Listener
DDS_WaitSet, DDS_Condition

Macro Definition Documentation

#define DDS_STATUS_MASK_NONE

No bits are set.

Examples:
HelloWorld_publisher.c, and HelloWorld_subscriber.c.
#define DDS_STATUS_MASK_ALL

All bits are set.

Examples:
HelloWorld_subscriber.c.

Typedef Documentation

A bit-mask (list) of concrete status types, i.e. DDS_StatusKind[].

The bit-mask is an efficient and compact representation of a fixed-length list of DDS_StatusKind values.

Bits in the mask correspond to different statuses. You can choose which changes in status will trigger a callback by setting the corresponding status bits in this bit-mask and installing callbacks for each of those statuses.

The bits that are true indicate that the listener will be called back for changes in the corresponding status.

For example:

datareader->set_listener(listener, mask);

or

datareader = subscriber->create_datareader(topic,
listener, mask);

Enumeration Type Documentation

Type for status kinds.

Each concrete DDS_Entity is associated with a set of *Status objects whose values represent the communication status of that DDS_Entity.

The communication statuses whose changes can be communicated to the application depend on the DDS_Entity.

Each status value can be accessed with a corresponding function on the DDS_Entity. The changes on these status values cause activation of the corresponding DDS_StatusCondition objects and trigger invocation of the proper DDS_Listener objects to asynchronously inform the application. Note that not all statuses will activate the DDS_StatusCondition or have a corresponding listener callback. Refer to the documentation of the individual statuses for that information.

See Also
DDS_Entity, DDS_StatusCondition, DDS_Listener
Enumerator:
DDS_INCONSISTENT_TOPIC_STATUS 

Another topic exists with the same name but different characteristics.

Entity:
DDS_Topic
Status:
DDS_InconsistentTopicStatus
Listener:
DDS_TopicListener
DDS_OFFERED_DEADLINE_MISSED_STATUS 

The deadline that the DDS_DataWriter has committed through its DDS_DeadlineQosPolicy was not respected for a specific instance.

Entity:
DDS_DataWriter
QoS:
DEADLINE
Status:
DDS_OfferedDeadlineMissedStatus
Listener:
DDS_DataWriterListener
DDS_REQUESTED_DEADLINE_MISSED_STATUS 

The deadline that the DDS_DataReader was expecting through its DDS_DeadlineQosPolicy was not respected for a specific instance.

Entity:
DDS_DataReader
QoS:
DEADLINE
Status:
DDS_RequestedDeadlineMissedStatus
Listener:
DDS_DataReaderListener
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS 

A QosPolicy value was incompatible with what was requested.

Entity:
DDS_DataWriter
Status:
DDS_OfferedIncompatibleQosStatus
Listener:
DDS_DataWriterListener
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS 

A QosPolicy value was incompatible with what is offered.

Entity:
DDS_DataReader
Status:
DDS_RequestedIncompatibleQosStatus
Listener:
DDS_DataReaderListener
DDS_SAMPLE_LOST_STATUS 

A sample has been lost (i.e. was never received).

Entity:
DDS_DataReader
Status:
DDS_SampleLostStatus
Listener:
DDS_DataReaderListener
DDS_SAMPLE_REJECTED_STATUS 

A (received) sample has been rejected.

Entity:
DDS_DataReader
QoS:
RESOURCE_LIMITS
Status:
DDS_SampleRejectedStatus
Listener:
DDS_DataReaderListener
DDS_DATA_ON_READERS_STATUS 

New data is available.

Entity:
DDS_Subscriber
Listener:
DDS_SubscriberListener
DDS_DATA_AVAILABLE_STATUS 

One or more new data samples have been received.

Entity:
DDS_DataReader
Listener:
DDS_DataReaderListener
DDS_LIVELINESS_LOST_STATUS 

The liveliness that the DDS_DataWriter has committed to through its DDS_LivelinessQosPolicy was not respected, thus DDS_DataReader entities will consider the DDS_DataWriter as no longer alive.

Entity:
DDS_DataWriter
QoS:
LIVELINESS
Status:
DDS_LivelinessLostStatus
Listener:
DDS_DataWriterListener
DDS_LIVELINESS_CHANGED_STATUS 

The liveliness of one or more DDS_DataWriter that were writing instances read through the DDS_DataReader has changed. Some DDS_DataWriter have become alive or not_alive.

Entity:
DDS_DataReader
QoS:
LIVELINESS
Status:
DDS_LivelinessChangedStatus
Listener:
DDS_DataReaderListener
DDS_PUBLICATION_MATCHED_STATUS 

The DDS_DataWriter has found DDS_DataReader that matches the DDS_Topic and has compatible QoS.

Entity:
DDS_DataWriter
Status:
DDS_PublicationMatchedStatus
Listener:
DDS_DataWriterListener
DDS_SUBSCRIPTION_MATCHED_STATUS 

The DDS_DataReader has found DDS_DataWriter that matches the DDS_Topic and has compatible QoS.

Entity:
DDS_DataReader
Status:
DDS_SubscriptionMatchedStatus
Listener:
DDS_DataReaderListener
DDS_SERVICE_REQUEST_ACCEPTED_STATUS 

<<extension>> A DDS_DataWriter has been issued a DDS_ServiceRequest

Enables a DDS_DataWriter callback that is called when a DDS_ServiceRequest has been accepted and dispatched to the DataWriter.

Entity:
DDS_DataWriter
Listener:
DDS_DataWriterListener
DDS_DATA_WRITER_APPLICATION_ACKNOWLEDGMENT_STATUS 

<<extension>> A DDS_DataWriter has received an application-level acknowledgment for a sample

Enables a DDS_DataWriter callback that is called when an application-level acknowledgment from a DDS_DataReader is received. The callback is called for each sample that is application-level acknowledged. Changes to this status do not trigger a DDS_StatusCondition.

Entity:
DDS_DataWriter
Listener:
DDS_DataWriterListener
DDS_DATA_WRITER_INSTANCE_REPLACED_STATUS 

<<extension>> A DDS_DataWriter instance has been replaced

Enables a DDS_DataWriter callback that is called when an instance in the writer queue is replaced.

Entity:
DDS_DataWriter
Listener:
DDS_DataWriterListener
DDS_RELIABLE_WRITER_CACHE_CHANGED_STATUS 

<<extension>> The number of unacknowledged samples in a reliable writer's cache has changed such that it has reached a pre-defined trigger point.

This status is considered changed at the following times: the cache is empty (i.e. contains no unacknowledge samples), full (i.e. the sample count has reached the value specified in DDS_ResourceLimitsQosPolicy::max_samples), or the number of samples has reached a high (see DDS_RtpsReliableWriterProtocol_t::high_watermark) or low (see DDS_RtpsReliableWriterProtocol_t::low_watermark) watermark.

Entity:
DDS_DataWriter
Status:
DDS_ReliableWriterCacheChangedStatus
Listener:
DDS_DataWriterListener
DDS_RELIABLE_READER_ACTIVITY_CHANGED_STATUS 

<<extension>> One or more reliable readers has become active or inactive.

A reliable reader is considered active by a reliable writer with which it is matched if that reader acknowledges the samples it has been sent in a timely fashion. For the definition of "timely" in this case, see DDS_RtpsReliableWriterProtocol_t and DDS_ReliableReaderActivityChangedStatus.

See Also
DDS_RtpsReliableWriterProtocol_t
DDS_ReliableReaderActivityChangedStatus
DDS_DATA_WRITER_CACHE_STATUS 

<<extension>> The status of the writer's cache.

Changes to this status do not trigger a DDS_StatusCondition.

DDS_DATA_WRITER_PROTOCOL_STATUS 

<<extension>> The status of a writer's internal protocol related metrics

The status of a writer's internal protocol-related metrics, such as the number of samples pushed, pulled, and filtered and the status of wire protocol traffic. Changes to this status information do not trigger a DDS_StatusCondition.

DDS_DATA_READER_CACHE_STATUS 

<<extension>> The status of the reader's cache.

Changes to this status do not trigger a DDS_StatusCondition.

DDS_DATA_READER_PROTOCOL_STATUS 

<<extension>> The status of a reader's internal protocol related metrics

The status of a reader's internal protocol related metrics, like the number of samples received, filtered, rejected; and status of wire protocol traffic. Changes to this status do not trigger a DDS_StatusCondition.

DDS_DATA_WRITER_SAMPLE_REMOVED_STATUS 

<<extension>> A DDS_DataWriter has removed a sample from its queue.

Enables a DDS_DataWriter callback that is called when a sample is removed from its queue.

Entity:
DDS_DataWriter
Listener:
DDS_DataWriterListener

RTI Connext C API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc