Specifies how the samples representing changes to data instances are presented to a subscribing application. More...

#include <dds_c_infrastructure.h>

Data Fields
DDS_PresentationQosPolicyAccessScopeKind	access_scope
	Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.
DDS_Boolean	coherent_access
	Specifies support for coherent access. Controls whether coherent access is supported within the scope `access_scope`.
DDS_Boolean	ordered_access
	Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope `access_scope`.

Detailed Description

Specifies how the samples representing changes to data instances are presented to a subscribing application.

NOTE: This QoS policy can only be set when using the static discovery API on the DDS_SubscriptionBuiltinTopicData.

However, a DDS_DataWriter always announces DDS_TOPIC_PRESENTATION_QOS via discovery, enabling a DDS_DataWriter to match with a DDS_DataReader that requests either DDS_INSTANCE_PRESENTATION_QOS or DDS_TOPIC_PRESENTATION_QOS, increasing interoperability.

A DataReader supports only DDS_INSTANCE_PRESENTATION_QOS.

This QoS policy controls the extent to which changes to data instances can be made dependent on each other and also the kind of dependencies that can be propagated and maintained by RTI Connext DDS Micro. Specifically, this policy affects the application's ability to:

specify and receive coherent changes to instances
specify the relative order in which changes are presented

Entity:: DDS_Publisher, DDS_Subscriber

Status:: DDS_OFFERED_INCOMPATIBLE_QOS_STATUS, DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS

A DDS_DataReader will usually receive data in the order that it was sent by a DDS_DataWriter, and the data is presented to the DDS_DataReader as soon as the application receives the next expected value. However, sometimes you may want a set of data for the same DDS_DataWriter to be presented to the DDS_DataReader only after all of the elements of the set have been received. Or you may want the data to be presented in a different order than that in which it was received. Specifically for keyed data, you may want the middleware to present the data in keyed – or instance – order, such that samples pertaining to the same instance are presented together.

The Presentation QoS policy allows you to specify different scopes of presentation: within a DDS_DataWriter, across instances of a single DDS_DataWriter, and even across multiple DataWriters used by different writers of a publisher. It also controls whether or not a set of changes within the scope is delivered at the same time or can be delivered as soon as each element is received.

coherent_access controls whether RTI Connext DDS Micro will preserve the groupings of changes made by a publishing application by means of the operations begin_coherent_changes() and end_coherent_changes(). These operations are not supported.

ordered_access controls whether RTI Connext DDS Micro will preserve the order of changes.

access_scope controls the granularity of the other settings. See below:

If coherent_access is set, then the access_scope controls the maximum extent of coherent changes. The behavior is as follows:

If access_scope is set to DDS_INSTANCE_PRESENTATION_QOS (the default), the use of begin_coherent_changes() and end_coherent_changes() has no effect on how the subscriber can access the data, because with the scope limited to each instance, changes to separate instances are considered independent and thus cannot be grouped into a coherent set.

If access_scope is set to DDS_TOPIC_PRESENTATION_QOS, then coherent changes (indicated by their enclosure within calls to begin_coherent_changes() and end_coherent_changes() will be made available as such to each remote DDS_DataReader independently. That is, changes made to instances within each individual DDS_DataWriter will be available as coherent with respect to other changes to instances in that same DDS_DataWriter, but will not be grouped with changes made to instances belonging to a different DDS_DataWriter.

If access_scope is set to DDS_GROUP_PRESENTATION_QOS, then coherent changes made to instances through a DDS_DataWriter attached to a common DDS_Publisher are made available as a unit to remote subscribers.

If ordered_access is set, then the access_scope controls the maximum extent for which order will be preserved by RTI Connext DDS Micro.

If access_scope is set to DDS_INSTANCE_PRESENTATION_QOS (the lowest level), then changes to each instance are considered unordered relative to changes to any other instance. That means that changes (creations, deletions, modifications) made to two instances are not necessarily seen in the order they occur. This is the case even if it is the same application thread making the changes using the same DDS_DataWriter.

If access_scope is set to DDS_TOPIC_PRESENTATION_QOS, changes (creations, deletions, modifications) made by a single DDS_DataWriter are made available to subscribers in the same order they occur. Changes made to instances though different DDS_DataWriter entities are not necessarily seen in the order they occur. This is the case, even if the changes are made by a single application thread using DDS_DataWriter objects attached to the same DDS_Publisher.

Finally, if access_scope is set to DDS_GROUP_PRESENTATION_QOS, changes made to instances via DDS_DataWriter entities attached to the same DDS_Publisher object are made available to subscribers on the same order they occur.

Note that this QoS policy controls the scope at which related changes are made available to the subscriber. This means the subscriber can access the changes in a coherent manner and in the proper order; however, it does not necessarily imply that the DDS_Subscriber will indeed access the changes in the correct order. For that to occur, the application at the subscriber end must use the proper logic in reading the DDS_DataReader objects.

Compatibility

The value offered is considered compatible with the value requested if and only if the following conditions are met:

the inequality offered access_scope >= requested access_scope evaluates to 'TRUE'. For the purposes of this inequality, the values of access_scope are considered ordered such that DDS_INSTANCE_PRESENTATION_QOS < DDS_TOPIC_PRESENTATION_QOS < DDS_GROUP_PRESENTATION_QOS.
requested coherent_access is DDS_BOOLEAN_FALSE, or else both offered and requested coherent_access are DDS_BOOLEAN_TRUE.
requested ordered_access is DDS_BOOLEAN_FALSE, or else both offered and requested ordered_access are DDS_BOOLEAN_TRUE.

Field Documentation

DDS_PresentationQosPolicyAccessScopeKind DDS_PresentationQosPolicy::access_scope

Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.

NOTE: This QoS setting can only be set when using the static discovery API on the DDS_SubscriptionBuiltinTopicData.

DDS_Boolean DDS_PresentationQosPolicy::coherent_access

Specifies support for coherent access. Controls whether coherent access is supported within the scope access_scope.

That is, the ability to group a set of changes as a unit on the publishing end such that they are received as a unit at the subscribing end.

To use this feature, the DataWriter must be configured for RELIABLE communication (see DDS_RELIABLE_RELIABILITY_QOS).

NOTE: This QoS setting can only be set when using the static discovery API on the DDS_SubscriptionBuiltinTopicData.

[default] DDS_BOOLEAN_FALSE

DDS_Boolean DDS_PresentationQosPolicy::ordered_access

Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope access_scope.

That is, the ability of the subscriber to see changes in the same order as they occurred on the publishing end.

NOTE: This QoS setting can only be set when using the static discovery API on the DDS_SubscriptionBuiltinTopicData.

[default] DDS_BOOLEAN_TRUE for DataWriters, DDS_BOOLEAN_FALSE for DataReaders

Data Fields

Detailed Description

Compatibility

Field Documentation