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

3.4.7.1. sample_state

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

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

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

3.4.7.2. view_state

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: This is the first time a sample of this instance is retrieved.

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

3.4.7.3. instance_state

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: The instance is currently in existence.

  • NOT_ALIVE_DISPOSED: A remote DataWriter disposed the instance.

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

3.4.7.4. disposed_generation_count

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

3.4.7.5. no_writers_generation_count

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

3.4.7.6. sample_rank

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 sample_rank is not implemented, and its value is always set to 0. It will be implemented on a future release of Fast DDS.

3.4.7.7. generation_rank

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 generation_rank is not implemented, and its value is always set to 0. It will be implemented on a future release of Fast DDS.

3.4.7.8. absolute_generation_rank

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 absolute_generation_rank is not implemented, and its value is always set to 0. It will be implemented on a future release of Fast DDS.

3.4.7.9. source_timestamp

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

3.4.7.10. instance_handle

instance_handle handles of the local instance.

3.4.7.11. publication_handle

publication_handle handles of the DataWriter that published the data change.

3.4.7.12. valid_data

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.

3.4.7.13. sample_identity

sample_identity is an extension for requester-replier configuration. It contains the DataWriter and the sequence number of the current message, and it is used by the replier to fill the related_sample_identity when it sends the reply.