RTI Connext Traditional C++ API Version 7.3.0
DDS_DataReaderProtocolQosPolicy Struct Reference

Along with DDS_WireProtocolQosPolicy and DDS_DataWriterProtocolQosPolicy, this QoS policy configures the DDS on-the-network protocol (RTPS). More...

Public Attributes

struct DDS_GUID_t virtual_guid
 The virtual GUID (Global Unique Identifier). More...
 
DDS_UnsignedLong rtps_object_id
 The RTPS Object ID. More...
 
DDS_Boolean expects_inline_qos
 Specifies whether this DataReader expects inline QoS with every sample. More...
 
DDS_Boolean disable_positive_acks
 Whether the reader sends positive acknowledgements to writers. More...
 
DDS_Boolean propagate_dispose_of_unregistered_instances
 Indicates whether or not an instance can move to the DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE state without being in the DDS_ALIVE_INSTANCE_STATE state. More...
 
DDS_Boolean propagate_unregister_of_disposed_instances
 Indicates whether or not an instance can move to the DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE state directly from the DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. More...
 
struct DDS_RtpsReliableReaderProtocol_t rtps_reliable_reader
 RTPS protocol-related configuration settings for the RTPS reliable reader associated with a DDSDataReader. This parameter only has effect if the reader is configured with DDS_RELIABLE_RELIABILITY_QOS DDS_ReliabilityQosPolicyKind. More...
 

Detailed Description

Along with DDS_WireProtocolQosPolicy and DDS_DataWriterProtocolQosPolicy, this QoS policy configures the DDS on-the-network protocol (RTPS).

DDS has a standard protocol for packet (user and meta data) exchange between applications using DDS for communications. This QoS policy and DDS_DataReaderProtocolQosPolicy give you control over configurable portions of the protocol, including the configuration of the reliable data delivery mechanism of the protocol on a per DataWriter or DataReader basis.

These configuration parameters control timing, timeouts, and give you the ability to tradeoff between speed of data loss detection and repair versus network and CPU bandwidth used to maintain reliability.

It is important to tune the reliability protocol (on a per DDSDataWriter and DDSDataReader basis) to meet the requirements of the end-user application so that data can be sent between DataWriters and DataReaders in an efficient and optimal manner in the presence of data loss.

You can also use this QoS policy to control how RTI Connext responds to "slow" reliable DataReaders or ones that disconnect or are otherwise lost. See DDS_ReliabilityQosPolicy for more information on the per-DataReader/DataWriter reliability configuration. DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy also play an important role in the DDS reliable protocol.

This QoS policy is an extension to the DDS standard.

Entity:
DDSDataReader
Properties:
RxO = N/A
Changeable = NO

Member Data Documentation

◆ virtual_guid

struct DDS_GUID_t DDS_DataReaderProtocolQosPolicy::virtual_guid

The virtual GUID (Global Unique Identifier).

The virtual GUID is used to uniquely identify different incarnations of the same DDSDataReader.

The association between a DDSDataReader and its persisted state is done using the virtual GUID.

[default] DDS_GUID_AUTO

◆ rtps_object_id

DDS_UnsignedLong DDS_DataReaderProtocolQosPolicy::rtps_object_id

The RTPS Object ID.

This value is used to determine the RTPS object ID of a data reader according to the DDS-RTPS Interoperability Wire Protocol.

Only the last 3 bytes are used; the most significant byte is ignored.

If the default value is specified, RTI Connext will automatically assign the object ID based on a counter value (per participant) starting at 0x00800000. That value is incremented for each new data reader.

A rtps_object_id value in the interval [0x00800000,0x00ffffff] may collide with the automatic values assigned by RTI Connext. In those cases, the recomendation is not to use automatic object ID assigment.

[default] DDS_RTPS_AUTO_ID

[range] [0,0x00ffffff]

◆ expects_inline_qos

DDS_Boolean DDS_DataReaderProtocolQosPolicy::expects_inline_qos

Specifies whether this DataReader expects inline QoS with every sample.

RTI Connext DataWriters do not match with DataReaders that set this field to DDS_BOOLEAN_TRUE (because RTI Connext DataWriters do not support sending inline QoS), but here is how the field is meant to be used:

In RTI Connext, a DDSDataReader nominally relies on Discovery to propagate QoS on a matched DDSDataWriter.

Alternatively, a DDSDataReader may get information on a matched DDSDataWriter through QoS sent inline with a sample.

Asserting DDS_DataReaderProtocolQosPolicy::expects_inline_qos indicates to a matching DDSDataWriter that this DDSDataReader expects to receive inline QoS with every sample. The complete set of inline QoS that a DDSDataWriter may send inline is specified by the Real-Time Publish-Subscribe (RTPS) Wire Interoperability Protocol.

Because RTI Connext DDSDataWriter and DDSDataReader cache Discovery information, inline QoS are largely redundant and thus unecessary. Only for other stateless implementations whose DDSDataReader does not cache Discovery information is inline QoS necessary.

Also note that inline QoS are additional wire-payload that consume additional bandwidth and serialization and deserialization time.

[default] DDS_BOOLEAN_FALSE

◆ disable_positive_acks

DDS_Boolean DDS_DataReaderProtocolQosPolicy::disable_positive_acks

Whether the reader sends positive acknowledgements to writers.

If set to DDS_BOOLEAN_TRUE, the reader does not send positive acknowledgments (ACKs) in response to Heartbeat messages. The reader will send negative acknowledgements (NACKs) when a Heartbeat advertises samples that it has not received.

Otherwise, if set to DDS_BOOLEAN_FALSE (the default), the reader will send ACKs to writers that expect ACKs (DDS_DataWriterProtocolQosPolicy::disable_positive_acks = DDS_BOOLEAN_FALSE) and it will not send ACKs to writers that disable ACKs (DDS_DataWriterProtocolQosPolicy::disable_positive_acks = DDS_BOOLEAN_TRUE)

[default] DDS_BOOLEAN_FALSE

◆ propagate_dispose_of_unregistered_instances

DDS_Boolean DDS_DataReaderProtocolQosPolicy::propagate_dispose_of_unregistered_instances

Indicates whether or not an instance can move to the DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE state without being in the DDS_ALIVE_INSTANCE_STATE state.

This field only applies to keyed readers.

When the field is set to DDS_BOOLEAN_TRUE, the DataReader will receive dispose notifications even if the instance is not alive.

To guarantee the key availability through the usage of the API FooDataReader::get_key_value, this option should be used in combination with setting DDS_DataWriterProtocolQosPolicy::serialize_key_with_dispose on the DataWriter to DDS_BOOLEAN_TRUE.

[default] DDS_BOOLEAN_FALSE

◆ propagate_unregister_of_disposed_instances

DDS_Boolean DDS_DataReaderProtocolQosPolicy::propagate_unregister_of_disposed_instances

Indicates whether or not an instance can move to the DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE state directly from the DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE.

This field only applies to keyed readers.

When the field is set to DDS_BOOLEAN_TRUE, the DataReader will receive unregister notifications even if the instance is not alive.

[default] DDS_BOOLEAN_FALSE

◆ rtps_reliable_reader

struct DDS_RtpsReliableReaderProtocol_t DDS_DataReaderProtocolQosPolicy::rtps_reliable_reader

RTPS protocol-related configuration settings for the RTPS reliable reader associated with a DDSDataReader. This parameter only has effect if the reader is configured with DDS_RELIABLE_RELIABILITY_QOS DDS_ReliabilityQosPolicyKind.

For details, refer to the DDS_RtpsReliableReaderProtocol_t

[default] See DDS_RtpsReliableReaderProtocol_t