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.
Type |
Field Name |
Description |
DDS_SampleStateKind |
||
DDS_ViewStateKind |
||
DDS_InstanceStateKind |
See 40.8 Accessing and Managing Instances (Working with Keyed Data Types) |
|
DDS_Time_t |
Time stored by the DataWriter when the DDS sample was written. |
|
DDS_InstanceHandle_t |
Handle to the data-instance corresponding to the DDS sample. |
|
DDS_InstanceHandle_t |
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 |
||
DDS_Boolean |
Indicates whether the DDS data sample includes valid data. See 40.8.3 Valid Data Flag. |
|
DDS_Time_t |
Time stored when the DDS sample was committed by the DataReader. See 41.6.1 Reception Timestamp. |
|
DDS_SequenceNumber_t |
Publication sequence number assigned when the DDS sample was written by the DataWriter. |
|
DDS_SequenceNumber_t |
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. 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. 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 |
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 |
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:
|
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 have 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:
For more information, see 40.8 Accessing and Managing Instances (Working with Keyed Data Types).
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):
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.