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

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