RTI Connext Micro  Version 2.4.1.0
 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...

#include <dds_c_subscription.h>

Data Fields

DDS_SampleStateKind sample_state
 The sample state of the sample.Indicates whether or not the corresponding data sample has already been read.
DDS_ViewStateKind 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.
DDS_InstanceStateKind 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.
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.The publication_handle is the same DDS_InstanceHandle_t that is returned by the operation ::DDS_DataReader_get_matched_publications and can also be used as a parameter to the operation ::DDS_DataReader_get_matched_publication_data.
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 instanceNormally 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.
struct DDS_Time_t reception_timestamp
 <<eXtension>> The timestamp when the sample was committed by a DataReader.

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.The publication_handle is the same DDS_InstanceHandle_t that is returned by the operation ::DDS_DataReader_get_matched_publications and can also be used as a parameter to the operation ::DDS_DataReader_get_matched_publication_data.

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 instanceNormally 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.


RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc