SampleInfo

When a sample is retrieved from the DataReader, in addition to the sample data, a SampleInfo instance is returned. This object contains additional information that complements the returned data value and helps on it interpretation.

For example, if the valid_data value is false, the DataReader is not informing the application about a new value in the data instance, but a change on its status, and the returned data value must be discarded.

Please, refer to the section Accessing received data for more information regarding how received data can be accessed on the DataReader.

The following sections describe the data members of SampleInfo and the meaning of each one in relation to the returned sample data.

sample_state

SampleInfo::sample_state indicates whether or not the corresponding data sample has already been read previously. It can take one of these values:

  • READ_SAMPLE_STATE: This is the first time this data sample has been retrieved.

  • NOT_READ_SAMPLE_STATE: The data sample has already been read or taken previously.

view_state

SampleInfo::view_state indicates whether or not this is the very first sample of this data instance that the DataReader retrieves. It can take one of these values:

  • NEW_VIEW_STATE: This is the first time a sample of this instance is retrieved.

  • NOT_NEW_VIEW_STATE: Other samples of this instance have been retrieved previously.

instance_state

SampleInfo::instance_state indicates whether the instance is currently in existence or it has been disposed. In the latter case, it also provides information about the reason for the disposal. It can take one of these values:

  • ALIVE_INSTANCE_STATE: The instance is currently in existence.

  • NOT_ALIVE_DISPOSED_INSTANCE_STATE: A remote DataWriter disposed the instance.

  • NOT_ALIVE_NO_WRITERS_INSTANCE_STATE: The DataReader disposed the instance because no remote DataWriter that was publishing the instance is alive.

  • END_OF_LIFE_INSTANCE_STATE: There are no alive DataWriters and no samples lefts on the instance.

disposed_generation_count

SampleInfo::disposed_generation_count indicates the number of times the instance had become alive after it was disposed.

no_writers_generation_count

SampleInfo::no_writers_generation_count indicates the number of times the instance had become alive after it was disposed as NOT_ALIVE_NO_WRITERS_INSTANCE_STATE.

sample_rank

SampleInfo::sample_rank indicates the number of samples of the same instance that have been received after this one. For example, a value of 5 means that there are 5 newer samples available on the DataReader.

Note

Currently the SampleInfo::sample_rank is not implemented in Safe DDS, and its value is always set to 0.

generation_rank

SampleInfo::generation_rank indicates the number of times the instance was disposed and become alive again between the time the sample was received and the time the most recent sample of the same instance that is still held in the collection was received.

Note

Currently the SampleInfo::generation_rank is not implemented in Safe DDS, and its value is always set to 0.

absolute_generation_rank

SampleInfo::absolute_generation_rank indicates the number of times the instance was disposed and become alive again between the time the sample was received and the time the most recent sample of the same instance (which may not be in the collection) was received.

Note

Currently the SampleInfo::absolute_generation_rank is not implemented in Safe DDS, and its value is always set to 0.

source_timestamp

SampleInfo::source_timestamp holds the time stamp provided by the DataWriter when the sample was published.

instance_handle

SampleInfo::instance_handle handles of the local instance.

publication_handle

SampleInfo::publication_handle handles of the DataWriter that published the data change.

valid_data

SampleInfo::valid_data is a boolean that indicates whether the data sample contains a change in the value or not. Samples with this value set to false are used to communicate a change in the instance status, e.g., a change in the liveliness of the instance. In this case, the data sample should be dismissed as all the relevant information is in the data members of SampleInfo.