The SampleInfo Structure

41.6 The SampleInfo Structure

When you invoke the read/take operations, for every DDS data sample that is returned, a corresponding SampleInfo is also returned. SampleInfo structures provide you with additional information about the DDS data samples received by Connext.

Table 41.2 DDS_SampleInfo Structure shows the format of the SampleInfo structure.

Table 41.2 DDS_SampleInfo Structure
Type	Field Name	Description
DDS_SampleStateKind	sample_state	See 41.6.2 Sample States
DDS_ViewStateKind	view_state	See 41.6.3 View States
DDS_InstanceStateKind	instance_state	See 40.8.1 Instance States
DDS_Time_t	source_timestamp	Time stored by the DataWriter when the DDS sample was written.
DDS_InstanceHandle_t	instance_handle	Handle to the data-instance corresponding to the DDS sample.
DDS_InstanceHandle_t	publication_handle	Local handle to the DataWriter that modified the instance. This is the same instance handle returned by get_matched_publications(). You can use this handle when calling get_matched_publication_data().
DDS_Long	disposed_generation_count	See 40.8.2 Generation Counts and Ranks.
	no_writers_generation_count
	sample_rank
	generation_rank
	absolute_generation_rank
DDS_Boolean	valid_data	Indicates whether the DDS data sample includes valid data. See 40.8.3 Valid Data Flag.
DDS_Time_t	reception_timestamp	Time stored when the DDS sample was committed by the DataReader. See 41.6.1 Reception Timestamp.
DDS_SequenceNumber_t	publication_sequence_number	Publication sequence number assigned when the DDS sample was written by the DataWriter.
DDS_SequenceNumber_t	reception_sequence_number	Reception sequence number assigned when the DDS sample was committed by the DataReader. See 41.6.1 Reception Timestamp.
struct DDS_GUID_t	original_publication_ virtual_guid	Original publication virtual GUID. If the Publisher’s access_scope is GROUP, this field contains the Publisher virtual GUID that uniquely identifies the DataWriter group.
struct DDS_SequenceNumber_t	original_publication_ virtual_sequence_number	Original publication virtual sequence number. If the Publisher’s access_scope is GROUP, this field contains the Publisher virtual sequence number that uniquely identifies a DDS sample within the DataWriter group.
DDS_GUID_t	topic_query_guid	The GUID of the DDS_TopicQuery that is related to the sample. This GUID indicates whether a sample is part of the response to a DDS_TopicQuery or a regular ("live") sample: If the sample was written for the TopicQuery stream, this field contains the GUID of the target TopicQuery. If the sample was written for the live stream, this field will be set to DDS_GUID_UNKNOWN.
DDS_Long	flag	Flags associated with the DDS sample; set by using the flag field in DDS_WriteParams_t when writing a DDS sample with FooDataWriter_write_w_params() (see 31.8 Writing Data). RTI reserves least-significant bits [0-7] for middleware-specific usage. The application can use least significant bits [8-15]. The first bit, REDELIVERED_SAMPLE, is reserved to mark a DDS sample as redelivered when using RTI Queuing Service. The second bit, INTERMEDIATE_REPLY_SEQUENCE_SAMPLE, is used to indicate that a response DDS sample is not the last response DDS sample for a given request. This bit is usually set by Connext Repliers sending multiple responses for a request. The third bit, REPLICATE_SAMPLE, indicates if a sample must be broadcast by one Queuing Service replica to other replicas. The fourth bit, LAST_SHARED_READER_QUEUE_SAMPLE, indicates that a sample is the last sample in a SharedReaderQueue for a QueueConsumer DataReader. The fifth bit, INTERMEDIATE_TOPIC_QUERY_SAMPLE, indicates that a sample for a TopicQuery will be followed by more samples. This flag only applies to samples that have been published as a response to a TopicQuery. When this bit is not set and topic_query_guid is different from GUID_UNKNOWN, this sample is the last sample for that TopicQuery coming from the DataWriter identified by original_publication_virtual_guid. The sixth bit, WRITER_REMOVED_BATCH_SAMPLE, will be set if the sample was accepted into the DataReader queue even though it was marked by the DataWriter as removed. Examples of removed samples in a batch are samples that were replaced due to KEEP_LAST_HISTORY_QOS on the DataWriter (see 47.12 HISTORY QosPolicy) or samples that outlived the DataWriter's 47.14 LIFESPAN QoS Policy duration. If the DataReader sets the property dds.data_reader.accept_writer_removed_batch_samples to true (in the 47.19 PROPERTY QosPolicy (DDS Extension) ), the removed sample will be accepted into the DataReader queue and this flag will be set.
struct DDS_GUID_t	source_guid	The application logical data source associated with the sample.
struct DDS_GUID_t	related_source_guid	The application logical data source that is related to the sample.
struct DDS_GUID_t	related_subscription_guid	The related_reader_guid associated with the sample.
struct DDS_CoherentSetInfo_t	coherent_set_info	Information about the coherent set that this sample is a part of. This field is set for all samples that are part of a coherent set. This field contains the following members: group_guid identifies the DataWriter or the group of DataWriters publishing the coherent set, depending on the value of the Subscriber's access_scope in the 46.6 PRESENTATION QosPolicy. (If access_scope is TOPIC or INSTANCE, then group_guid identifies a single DataWriter; if access_scope is GROUP, then group_guid identifies all the DataWriters within a Publisher.) coherent_set_sequence_number identifies a sample as part of a DataWriter coherent set. When the Subscriber's access_scope in the 46.6 PRESENTATION QosPolicy is TOPIC or INSTANCE, the coherent set associated with a sample is identified by the pair (group_guid, coherent_set_sequence_number). group_coherent_set_sequence_number identifies a sample as part of a group coherent set. When the Subscriber's access_scope in the 46.6 PRESENTATION QosPolicy is GROUP, the coherent set associated with a sample is identified by the pair (group_guid, group_coherent_set_sequence_number). incomplete_coherent_set indicates if a sample is part of an incomplete coherent set. An incomplete coherent set is a coherent set for which not all samples have been received. Note that a coherent set is also considered incomplete if some of its samples are filtered by content or time on the DataWriter side. By default, received samples from an incomplete coherent set are not provided to the application and they are reported as LOST_BY_INCOMPLETE_COHERENT_SET (see 40.7.7 SAMPLE_LOST Status). You can change this behavior by setting drop_incomplete_ coherent_set to FALSE in the 46.6 PRESENTATION QosPolicy.

41.6.1 Reception Timestamp

In reliable communication, if DDS data samples are received out received of order, Connext will not deliver them until all the previous DDS data samples have been received. For example, if DDS sample 2 arrives before DDS sample 1, DDS sample 2 cannot be delivered until DDS sample 1 is received. The reception_timestamp is the time when all previous DDS samples has been received—the time at which the DDS sample is committed. If DDS samples are all received in order, the committed time will be same as reception time. However, if DDS samples are lost on the wire, then the committed time will be later than the initial reception time.

41.6.2 Sample States

For each DDS sample received, Connext keeps a sample_state relative to each DataReader. The sample_state can be either:

READ: The DataReader has already accessed that DDS sample by means of read().
NOT_READ: The DataReader has never accessed that DDS sample before.

The DDS samples retrieved by a read() or take() need not all have the same sample_state.

41.6.3 View States

For each instance (identified by a unique key value), Connext keeps a view_state relative to each DataReader. The view_state can be either:

NEW: Either this is the first time the DataReader has ever accessed DDS samples of the instance, or the DataReader has accessed previous DDS samples of the instance, but the instance has since been reborn (i.e., become not-alive and then alive again). These two cases are distinguished by examining the disposed_generation_count and the no_writers_generation_count (see 40.8.2 Generation Counts and Ranks).
NOT_NEW:The DataReader has already accessed DDS samples of the same instance and the instance has not been reborn since.

The view_state in the SampleInfo structure is really a per-instance concept (as opposed to the sample_state which is per DDS sample). Thus all DDS data samples related to the same instance that are returned by read() or take() will have the same value for view_state.

41.6.4 Instance States

Connext keeps an instance_state for each instance; it can be:

ALIVE
NOT_ALIVE_DISPOSED
NOT_ALIVE_NO_WRITERS

For more information, see 40.8.1 Instance States.

41.6.5 Generation Counts and Ranks

Each DataReader keeps two counters for each new instance it detects (recall that instances are distinguished by their key values):

disposed_generation_count
no_writers_generation_count

For more information, see 40.8.2 Generation Counts and Ranks.

41.6.6 Valid Data Flag

The SampleInfo structure’s valid_data flag indicates whether the DDS sample contains data or is only used to communicate a change in the instance_state of the instance.

For more information, see 40.8.3 Valid Data Flag.