RTI Connext Micro C API  2.4.14.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
DDS_SampleInfo Struct Reference

Information that accompanies each sample that is read or taken. More...

Data Fields

DDS_SampleStateKind sample_state
 The sample state of the sample.
DDS_ViewStateKind view_state
 The view state of the instance.
DDS_InstanceStateKind instance_state
 The instance state of the instance.
struct DDS_Time_t source_timestamp
 The timestamp when the sample was written by a DataWriter.
DDS_InstanceHandle_t instance_handle
 Identifies locally the corresponding instance.
DDS_InstanceHandle_t publication_handle
 Identifies locally the DataWriter that modified the instance.
DDS_Boolean valid_data
 Indicates whether the DataSample contains data or else it is only used to communicate a change in the instance_state of the instance.
struct DDS_Time_t reception_timestamp
 <<eXtension>> The timestamp when the sample was committed by a DataReader.
struct DDS_SequenceNumber_t publication_sequence_number
 <<eXtension>> The publication sequence number.

Detailed Description

Information that accompanies each sample that is read or taken.

Interpretation of the SampleInfo

The DDS_SampleInfo contains information pertaining to the associated Data instance sample including:

  • the sample_state of the Data value (i.e., if it has already been read or not)

  • the view_state of the related instance (i.e., if the instance is new or not)

  • the instance_state of the related instance (i.e., if the instance is alive or not)

  • the valid_data flag. This flag indicates whether there is data associated with the sample. Some samples do not contain data indicating only a change on the instance_state of the corresponding instance.

  • The source_timestamp of the sample. This is the timestamp provided by the DDS_DataWriter at the time the sample was produced.
See also:
DDS_SampleStateKind, DDS_InstanceStateKind, DDS_ViewStateKind, DDS_SampleInfo::valid_data
DDSInstanceViewStates.png
"Statechart of the instance_state and view_state of a single instance"

Field Documentation

DDS_SampleStateKind DDS_SampleInfo::sample_state

The sample state of the sample.

Indicates whether or not the corresponding data sample has already been read.

See also:
DDS_SampleStateKind
DDS_ViewStateKind DDS_SampleInfo::view_state

The view state of the instance.

Indicates whether the DDS_DataReader has already seen samples for the most-current generation of the related instance.

See also:
DDS_ViewStateKind
DDS_InstanceStateKind DDS_SampleInfo::instance_state

The instance state of the instance.

Indicates whether the instance is currently in existence or, if it has been disposed, the reason why it was disposed.

See also:
DDS_InstanceStateKind
struct DDS_Time_t DDS_SampleInfo::source_timestamp

The timestamp when the sample was written by a DataWriter.

DDS_InstanceHandle_t DDS_SampleInfo::instance_handle

Identifies locally the corresponding instance.

DDS_InstanceHandle_t DDS_SampleInfo::publication_handle

Identifies locally the DataWriter that modified the instance.

DDS_Boolean DDS_SampleInfo::valid_data

Indicates whether the DataSample contains data or else it is only used to communicate a change in the instance_state of the instance.

Normally each DataSample contains both a DDS_SampleInfo and some Data. However there are situations where a DataSample contains only the DDS_SampleInfo and does not have any associated data. This occurs when the RTI Connext Micro notifies the application of a change of state for an instance that was caused by some internal mechanism (such as a timeout) for which there is no associated data. An example of this situation is when the RTI Connext Micro detects that an instance has no writers and changes the corresponding instance_state to DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

The application can distinguish whether a particular DataSample has data by examining the value of the valid_data flag. If this flag is set to DDS_BOOLEAN_TRUE, then the DataSample contains valid Data. If the flag is set to DDS_BOOLEAN_FALSE, the DataSample contains no Data.

To ensure correctness and portability, the valid_data flag must be examined by the application prior to accessing the Data associated with the DataSample and if the flag is set to DDS_BOOLEAN_FALSE, the application should not access the Data associated with the DataSample, that is, the application should access only the DDS_SampleInfo.

struct DDS_Time_t DDS_SampleInfo::reception_timestamp

<<eXtension>> The timestamp when the sample was committed by a DataReader.

The reception_timestamp is platform dependent and depends on the port of RTI Connext Micro to the platform. Typically, it represents the current local time, but that may not always be the case. E.g, some platforms may not have a real-time clock and the system time is the time since the system was started.

A reception_timestamp equal to zero may mean any of the following:

  • RTI Connext Micro was unable to read the current time
  • The system time is not incrementing
  • Zero time has elapsed between the system was started and the first sample was comitted.
struct DDS_SequenceNumber_t DDS_SampleInfo::publication_sequence_number

<<eXtension>> The publication sequence number.


RTI Connext Micro C API 2.4.14.2 Copyright © Mon May 20 2024 Real-Time Innovations, Inc