| DDS_ReturnCode_t | Return Code Description |
| DDS_RETCODE_OK | Successful return |
| DDS_RETCODE_ERROR | Generic, unspecified error |
| DDS_RETCODE_BAD_PARAMETER | Illegal parameter value |
| DDS_RETCODE_UNSUPPORTED | Unsupported operation or DDS_QosPolicy setting. Can only be returned by operations that are optional or operations that uses an optional DDS_QoS as a parameter |
| DDS_RETCODE_ALREADY_DELETED | The object target of this operation has already been deleted |
| DDS_RETCODE_OUT_OF_RESOURCES | Service ran out of the resources needed to complete the operation |
| DDS_RETCODE_NOT_ENABLED | Operation invoked on an DDS_Entity that is not yet enabled |
| DDS_RETCODE_IMMUTABLE_POLICY | Application attempted to modify an immutable DDS_QosPolicy |
| DDS_RETCODE_INCONSISTENT_POLICY | Application specified a set of policies that are not consistent with each other |
| DDS_RETCODE_PRECONDITION_NOT_MET | A pre-condition for the operation was not met |
Table 1: Return Codes
| QosPolicy | Attribute | Value |
| user_data | value.length | 0 |
| topic_data | value.length | 0 |
| group_data | value.length | 0 |
| transport_priority | value | 0 |
| lifespan | duration | DDS_DURATION_INFINITE |
| durability | kind | DDS_VOLATILE_DURABILITY_QOS |
| presentation | access_scope | DDS_INSTANCE_PRESENTATION_QOS |
| coherent_access | FALSE |
| ordered_access | FALSE |
| deadline | period | DDS_DURATION_INFINITE |
| latency_budget | duration | 0 |
| ownership_strength | value | 0 |
| ownership | kind | DDS_SHARED_OWNERSHIP_QOS |
| liveliness | kind | DDS_AUTOMATIC_LIVELINESS_QOS |
| lease_duration | DDS_DURATION_INFINITE |
| time_based_filter | minimum_separation | 0 |
| partition | name.length | 0 |
| reliability | kind | DDS_BEST_EFFORT_RELIABILITY_QOS |
| max_blocking_time | 100 ms |
| synchronous | FALSE |
| destination_order | kind | DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS |
| history | kind | DDS_KEEP_LAST_HISTORY_QOS |
| depth | 1 |
| resource_limits | max_samples | DDS_LENGTH_UNLIMITED |
| max_instances | DDS_LENGTH_UNLIMITED |
| max_samples_per_instance | DDS_LENGTH_UNLIMITED |
| entity_factory | autoenable_created_entities | TRUE |
| writer_data_lifecycle | autodispose_unregistered_instances | TRUE |
| reader_data_lifecycle | autopurge_nowriter_samples_delay | DDS_DURATION_INFINITE |
| autopurge_disposed_samples_delay | DDS_DURATION_INFINITE |
| autopurge_dispose_all | FALSE |
| enable_invalid_samples | TRUE |
| invalid_sample_visibilityy.kind | DDS_MINIMUM_INVALID_SAMPLES |
| durability_service | history_kind | KEEP_LAST |
| history_depth | 1 |
| max_samples | LENGTH_UNLIMITED |
| max_instances | LENGTH_UNLIMITED |
| max_samples_per_instance | LENGTH_UNLIMITED |
| service_cleanup_delay | 0 |
| watchdog_scheduling, listener_scheduling | scheduling_class.kind | DDS_SCHEDULE_DEFAULT |
| scheduling_priority_kind.kind | DDS_PRIORITY_RELATIVE |
| scheduling_priority | 0 |
| subscription_keys | use_key_list | FALSE |
| key_list.length | 0 |
| reader_lifespan | use_lifespan | FALSE |
| duration | DDS_DURATION_INFINITE |
| share | name | "" |
| enable | FALSE |
| view_keys | use_key_list | FALSE |
| key_list.length | 0 |
# RxO
The QosPolicy settings that need to be set in a compatible manner between the publisher and subscriber ends are indicated by the setting of the “RxO” (Requested/Offered) property. The “RxO” property of each QosPolicy is listed in Table 6: on page 67
• A $\mathrm { { ^ { \circ } R x O ^ { \circ } } }$ setting of “Yes” indicates that the QosPolicy can be set at both ends (publishing and subscribing) and the attributes must be set in a compatible manner. In this case the compatible attributes are explicitly defined
• A “RxO” setting of “No” indicates that the QosPolicy can be set at both ends (publishing and subscribing) but the two settings are independent. That is, all combinations of attributes are compatible
• A “RxO” setting of “Not applicable” indicates that the QosPolicy can only be specified at either the publishing or the subscribing end, but not at both ends. So compatibility does not apply.
# Changeable
The “changeable” property determines whether the QosPolicy can be changed after the DDS\_Entity is enabled. In other words, a QosPolicy with “changeable” setting of “No” is considered “immutable” and can only be specified either at DDS\_Entity creation time or prior to calling the DDS\_Entity\_enable operation on the DDS\_Entity.
When the application tries to change a QosPolicy with “changeable” setting of “ N o ” , t h e D a t a D i s t r i b u t i o n S e r v i c e w i l l n o t i f y t h i s b y r e t u r n i n g a DDS\_RETCODE\_IMMUTABLE\_POLICY.
The basic way to modify or set the <DDS\_Entity>Qos is by using a DDS\_<Entity>\_get\_qos and DDS\_<Entity>\_set\_qos operation to get all QosPolicy settings from this DDS\_Entity (that is the <DDS\_Entity>Qos), modify several specific QosPolicy settings and put them back using an user operation to set all QosPolicy settings on this DDS\_Entity (that is the <DDS\_Entity>Qos). An example of these operations for the DDS\_DataWriter are DDS\_DataWriter\_get\_qos and DDS\_DataWriter\_set\_qos, which take the DataWriterQos as a parameter.
The “RxO” setting and the “changeable” setting of each QosPolicy are listed in Table 6: below:
Table 6: QosPolicy Basics
| QosPolicy | Concerns DDS_Entity | RxO | Changeable After Enabling |
| user_data | DDS_DomainParticipantDDS_DataReaderDDS_DataWriter | No | Yes |
| topic_data | DDS_Topic | No | Yes |
| group_data | DDS_PublisherDDS_Subscriber | No | Yes |
| transport_priority | DDS_TopicDDS_DataWriter | Not applicable | Yes |
| lifespan | DDS_TopicDDS_DataWriter | Not applicable | Yes |
| durability | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | No |
| presentation | DDS_PublisherDDS_Subscriber | Yes | No |
| deadline | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | Yes |
| latency_budget | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | Yes |
| ownership | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | No |
| ownership_strength | DDS_DataWriter | Not applicable | Yes |
| liveliness | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | No |
| time_based_filter | DDS_DataReader | Not applicable | Yes |
| partition | DDS_PublisherDDS_Subscriber | No | Yes |
| reliability | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | No |
| destination_order | DDS_TopicDDS_DataReaderDDS_DataWriter | Yes | No |
| history | DDS_TopicDDS_DataReaderDDS_DataWriter | No | No |
| resource_limits | DDS_TopicDDS_DataReaderDDS_DataWriter | No | No |
| entity_factory | DDS_DomainParticipantFactoryDDS_DomainParticipantDDS_PublisherDDS_Subscriber | No | Yes |
| writer_data_lifecycle | DDS_DataWriter | Not applicable | Yes |
| reader_data_lifecycle | DDS_DataReader | Not applicable | Yes |
| durability_service | DDS_Topic | No | No |
| scheduling | DDS_DomainParticipant | Not applicable | No |
| subscription_keys | DDS_DataReader | Not applicable | No |
| reader_lifespan | DDS_DataReader | Not applicable | Yes |
| share | DDS_DataReaderDDS_Subscriber | Not applicable | NoNo |
| view_keys | DDS_DataReaderView | Not applicable | No |
The next paragraphs describe the usage of each QosPolicy struct.
# 3.1.3.1 DDS\_DeadlineQosPolicy
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DeadlineQosPolicy
{ DDS_Duration_t period; };
```
# Description
This QosPolicy defines the period within which a new sample is expected by the DataReader or to be written by the DataWriter.
# Attributes
DDS\_Duration\_t period - specifies the period within which a new sample is expected or to be written.
# Detailed Description
This QosPolicy will set the period within which a DDS\_DataReader expects a new sample or, in case of a DDS\_DataWriter, the period in which it expects applications to write the sample. The default value of the period is DDS\_DURATION\_INFINITE, indicating that there is no deadline. The QosPolicy may be used to monitor the real-time behaviour, a DDS\_Listener or a DDS\_StatusCondition may be used to catch the event that is generated when a deadline is missed.
DDS\_DeadlineQosPolicy is instance oriented (i.e. the period is monitored for each individual instance).
The exact consequences of a missed deadline depend on the DDS\_Entity in which it occured, and the DDS\_OwnershipQosPolicy value of that DDS\_Entity:
• In case a DDS\_DataWriter misses an instance deadline (regardless of its DDS\_OwnershipQosPolicy setting), an offered\_deadline\_missed\_status is raised, which can be detected by either a DDS\_Listener or a DDS\_StatusCondition. There are no further consequences.
• In case a DDS\_DataReader misses an instance deadline, a requested\_deadline\_missed\_status is raised, which can be detected by either a DDS\_Listener or a DDS\_StatusCondition. In case the DDS\_OwnershipQosPolicy is set to SHARED, there are no further consequences. In case the DDS\_OwnershipQosPolicy is set to EXCLUSIVE, the ownership of that instance on that particular DDS\_DataReader is transferred to the next available highest strength DDS\_DataWriter, but this will have no impact on the instance\_state whatsoever. So even when a deadline is missed for an instance that has no other (lower-strength) DDS\_DataWriters to transfer ownership to, the instance\_state remains unchanged. See also Section 3.1.3.11, DDS\_OwnershipQosPolicy.
This QosPolicy is applicable to a DDS\_DataReader, a DDS\_DataWriter and a DDS\_Topic. After enabling of the concerning DDS\_Entity, this QosPolicy may be changed by using the DDS\_<DDS\_Entity>\_set\_qos operation.
# Requested/Offered
In case the Requested/Offered QosPolicy are incompatible, the notification DDS\_OFFERED\_INCOMPATIBLE\_QOS status on the offering side and DDS\_REQUESTED\_INCOMPATIBLE\_QOS status on the requesting side is raised.
Table 7: DDS\_DeadlineQosPolicy
| DDS_Entity | Status Name | Meaning |
| DDS_Topic | DDS_INCONSISTENT_TOPIC_STATUS | Another DDS_Topic exists with the same name but with different characteristics. |
| DDS_ALL_DATA_DISPOSED_TOPIC_STATUS | All instances of the Topic have been disposed by the dispose_all_data operation on that topic. |
| DDS_Subscriber | DDS_DATA_ON_READERS_STATUS | New information is available. |
| DDS_DataReader | DDS_SAMPLE_REJECTED_STATUS | A (received) sample has been rejected. |
| DDS_LIVELINESS_CHANGED_STATUS | The liveliness of one or more DDS_DataWriter objects that were writing instances read through the DDS_DataReader has changed. Some DDS_DataWriter have become “alive” or “not alive”. |
| DDS_REQUESTED_DEADLINE_MISSED_STATUS | The deadline that the DDS_DataReader was expecting through its DDS_DeadlineQosPolicy was not respected for a specific instance. |
| DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what is offered. |
| DDS_DATA_AVAILABLE_STATUS | New information is available. |
| DDS_SAMPLE_LOST_STATUS | A sample has been lost (never received). |
| DDS_SUBSCRIPTION_MATCHED_STATUS | The DDS_DataReader has found a DDS_DataWriter that matches the DDS_Topic and has compatible QoS. |
| DDS_DataWriter | DDS_LIVELINESS_LOST_STATUS | The liveliness that the DDS_DataWriter has committed through itsDDS_LivelinessQosPolicy was not respected; thus DDS_DataReader objects will consider the DDS_DataWriter as no longer “alive”. |
| DDS_OFFERED_DEADLINE_MISSED_STATUS | The deadline that the DDS_DataWriter has committed through itsDDS_DeadlineQosPolicy was not respected for a specific instance. |
| DDS_OFFERED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what was requested. |
| DDS_PUBLICATION_MATCHED_STATUS | The DDS_DataWriter has found a DDS_DataReader that matches the DDS_Topic and has compatible QoS. |
A D D S \_ S t a t u s a t t r i b u t e c a n b e r e t r i e v e d w i t h t h e o p e r a t i o n get\_<status\_name>\_status. For example, to get the DDS\_InconsistentTopicStatus value, the application must call the operation DDS\_Topic\_get\_inconsistent\_topic\_status.
Conceptually associated with each DDS\_Entity communication status is a logical StatusChangedFlag. This flag indicates whether that particular communication status has changed. The StatusChangedFlag is only conceptual, therefore, it is not important whether this flag actually exists.
For the plain communication DDS\_Status, the StatusChangedFlag is initially set to FALSE. It becomes TRUE whenever the plain communication DDS\_Status changes and it is reset to FALSE each time the application accesses the plain communication DDS\_Status via the proper get\_<status\_name>\_status operation on the DDS\_Entity.
A flag set means that a change has occurred since the last time the application has read its value.
Figure 12: DCPS DDS\_Status Values
Each DDS\_Status attribute is implemented as a struct and therefore does not provide any operations. The interface description of these structs is as follows:
```c
/*
* struct DDS_<name>Status
*/
struct DDS_InconsistentTopicStatus
{ DDS_long total_count;
DDS_long total_count_change; };
struct DDS_AllDataDisposedTopicStatus
{ DDS_long total_count;
DDS_long total_count_change; }
struct DDS_SampleLostStatus
{ DDS_long total_count;
DDS_long total_count_change; };
enum DDS_SampleRejectedStatusKind
{ DDS_NOT_REJECTED,
DDS_REJECTED_BY_INSTANCES_LIMIT,
DDS_REJECTED_BY_SAMPLES_LIMIT,
DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT };
struct DDS_SampleRejectedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_SampleRejectedStatusKind last_reason;
```
```c
DDS_InstanceHandle_t last_instance_handle; };
struct DDS_LivelinessLostStatus
{ DDS_long total_count;
DDS_long total_count_change; };
struct DDS_LivelinessChangedStatus
{ DDS_long alive_count;
DDS_long not_alive_count;
DDS_long alive_count_change;
DDS_long not_alive_count_change;
DDS_InstanceHandle_t last_publication_handle; };
struct DDS_OfferedDeadlineMissedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_InstanceHandle_t last_instance_handle; };
struct DDS_RequestedDeadlineMissedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_InstanceHandle_t last_instance_handle; };
struct DDS_OfferedIncompatibleQosStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_QosPolicyId_t last_policy_id;
DDS_QosPolicyCountSeq policies; };
struct DDS_RequestedIncompatibleQosStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_QosPolicyId_t last_policy_id;
DDS_QosPolicyCountSeq policies; };
struct DDS_PublicationMatchedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_long current_count;
DDS_long current_count_change;
DDS_InstanceHandle_t last Subscription_handle; };
struct DDS_SubscriptionMatchedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_long current_count;
DDS_long current_count_change;
DDS_InstanceHandle_t last Publication_handle; };
/*
* implemented API operations
* <no operations>
*/
```
The sections describe the usage of each DDS\_<name>Status struct.
# 3.1.5.1 DDS\_InconsistentTopicStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_InconsistentTopicStatus
{ DDS_long total_count;
DDS_long total_count_change; };
```
# Description
This struct contains the statistics about attempts to create other DDS\_Topics with the same name but with different characteristics.
# Attributes
DDS\_long total\_count - the total detected cumulative count of DDS\_Topic creations, whose name matches the DDS\_Topic to which this DDS\_Status is attached and whose characteristics are inconsistent.
DDS\_long total\_count\_change - the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
# Detailed Description
This struct contains the statistics about attempts to create other DDS\_Topics with the same name but with different characteristics.
The attribute total\_count holds the total cumulative count of DDS\_Topic creations, whose name matches the DDS\_Topic to which this DDS\_Status is attached and whose characteristics are inconsistent.
The attribute total\_count\_change holds the incremental number of inconsistent DDS\_Topics, since the last time the Listener was called or the DDS\_Status was read.
# 3.1.5.2 DDS\_LivelinessChangedStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_LivelinessChangedStatus
{ DDS_long alive_count;
DDS_long not_alive_count;
DDS_long alive_count_change;
DDS_long not_alive_count_change;
DDS_InstanceHandle_t last_publication_handle; };
```
# Description
This struct contains the statistics about whether the liveliness of one or more connected DDS\_DataWriter objects has changed.
# Attributes
DDS\_long alive\_count - the total count of currently alive DDS\_DataWriter objects that write the topic read by the DDS\_DataReader to which this DDS\_Status is attached.
DDS\_long not\_alive\_count - the total count of currently not alive DDS\_DataWriter objects that wrote the topic read by the DDS\_DataReader to which this DDS\_Status is attached.
DDS\_long alive\_count\_change - the change in alive\_count since the last time the Listener was called or the DDS\_Status was read.
DDS\_long not\_alive\_count\_change - the change in not\_alive\_count since the last time the Listener was called or the DDS\_Status was read.
DDS\_InstanceHandle\_t last\_publication\_handle - handle to the last DDS\_DataWriter whose change in liveliness caused this status to change.
# Detailed Description
This struct contains the statistics about whether the liveliness of one or more connected DDS\_DataWriter objects that were writing instances read through the DDS\_DataReader has changed. In other words, some DDS\_DataWriters have become “alive” or “not alive”.
The attribute alive\_count holds the total number of currently alive DDS\_DataWriter objects that write the topic read by the DDS\_DataReader to which this DDS\_Status is attached. This count increases when a newly matched D D S \_ D a t a W r i t e r a ss e r t s i t s l i v e l i n e s s f o r t h e f i r st t i m e o r w h e n a DDS\_DataWriter previously considered to be not alive reasserts its liveliness. The count decreases when a DDS\_DataWriter considered alive fails to assert its liveliness and becomes not alive, whether because it was deleted normally or for some other reason.
The attribute not\_alive\_count holds the total count of currently not alive DDS\_DataWriters that wrote the topic read by the DDS\_DataReader to which this DDS\_Status is attached, and that are no longer asserting their liveliness. This count increases when a DDS\_DataWriter considered alive fails to assert its liveliness and becomes not alive for some reason other than the normal deletion of that DDS\_DataWriter. It decreases when a previously not alive DDS\_DataWriter either reasserts its liveliness or is deleted normally.
The attribute alive\_count\_change holds the change in alive\_count since the last time the Listener was called or the DDS\_Status was read.
T h e a t t r i b u t e n o t \_ al i v e \_ c o un t \_ c h a ng e h o l d s t h e c h a n g e i n not\_alive\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_publication\_handle contains the instance handle to the DDS\_PublicationBuiltinTopicData instance that represents the last datawriter whose change in liveliness caused this status to change. Be aware that t h i s h a n d l e b e l o n g s t o a n o t h e r d a t a r e a d e r, t h e DDS\_PublicationBuiltinTopicDataDataReader in the builtin-subscriber, and has no meaning in the context of the datareader from which the DDS\_LivelinessChangedStatus was obtained. If the builtin-subscriber has not e x p l i c i t l y b e e n o b t a i n e d u s i n g DDS\_DomainParticipant\_get\_builtin\_subscriber, then there is no DDS\_PublicationBuiltinTopicDataDataReader as well, in which case the last\_publication\_handle will be set to DDS\_HANDLE\_NIL.
# 3.1.5.3 DDS\_LivelinessLostStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_LivelinessLostStatus
{ DDS_long total_count;
DDS_long total_count_change; };
```
# Description
This struct contains the statistics about whether the liveliness of the DDS\_DataWriter to which this DDS\_Status is attached has been committed through its DDS\_LivelinessQosPolicy.
# Attributes
DDS\_long total\_count - the total cumulative count of times the DDS\_DataWriter to which this DDS\_Status is attached failed to actively signal its liveliness within the offered liveliness period.
DDS\_long total\_count\_change - the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
# Detailed Description
This struct contains the statistics about whether the liveliness of the DDS\_DataWriter to which this DDS\_Status is attached has been committed through its DDS\_LivelinessQosPolicy. In other words, whether the DDS\_DataWriter failed to actively signal its liveliness within the offered liveliness period. In such a case, the connected DDS\_DataReader objects will consider the DDS\_DataWriter as no longer “alive”.
The attribute total\_count holds the total cumulative number of times that the previously-alive DDS\_DataWriter became not alive due to a failure to actively signal its liveliness within its offered liveliness period. This count does not change when an already not alive DDS\_DataWriter simply remains not alive for another liveliness period.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
# 3.1.5.4 DDS\_OfferedDeadlineMissedStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_OfferedDeadlineMissedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_InstanceHandle_t last_instance_handle; };
```
# Description
This struct contains the statistics about whether the deadline that the DDS\_DataWriter to which this DDS\_Status is attached has committed through its DDS\_DeadlineQosPolicy, was not respected for a specific instance.
# Attributes
DDS\_long total\_count - the total cumulative count of times the DDS\_DataWriter to which this DDS\_Status is attached failed to write within its offered deadline.
DDS\_long total\_count\_change - the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
DDS\_InstanceHandle\_t last\_instance\_handle - the handle to the last instance in the DDS\_DataWriter to which this DDS\_Status is attached, for which an offered deadline was missed.
# Detailed Description
This struct contains the statistics about whether the deadline that the DDS\_DataWriter to which this DDS\_Status is attached has committed through its DDS\_DeadlineQosPolicy, was not respected for a specific instance.
The attribute total\_count holds the total cumulative number of offered deadline periods elapsed during which the DDS\_DataWriter to which this DDS\_Status is attached failed to provide data. Missed deadlines accumulate; that is, each deadline period the total\_count will be incremented by one.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_instance\_handle holds the handle to the last instance in the DDS\_DataWriter to which this DDS\_Status is attached, for which an offered deadline was missed.
# 3.1.5.5 DDS\_OfferedIncompatibleQosStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_OfferedIncompatibleQosStatus
{ DDS_long total_count;
DDS_long total_count_change;
QosPolicyId_t last_policy_id;
QosPolicyCountSeq policies; };
```
# Description
This struct contains the statistics about whether an offered QosPolicy setting was incompatible with the requested QosPolicy setting.
# Attributes
DDS\_long total\_count - the total cumulative count of DDS\_DataReader objects discovered by the DDS\_DataWriter with the same DDS\_Topic and Partition and with a requested DDS\_DataReaderQos that was incompatible with the one offered by the DDS\_DataWriter.
DDS\_long total\_count\_change - the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
QosPolicyId\_t last\_policy\_id - the id of one of the QosPolicy settings that was found to be incompatible with what was offered, the last time an incompatibility was detected.
QosPolicyCountSeq policies - a list containing for each QosPolicy the total number of times that the concerned DDS\_DataWriter discovered a D D S\_ D a t a R e ad e r for the sa me D D S \_ T o pi c a nd a requeste d DDS\_DataReaderQos that is incompatible with the one offered by the DDS\_DataWriter.
# Detailed Description
This struct contains the statistics about whether an offered QosPolicy setting was incompatible with the requested QosPolicy setting.
The Request/Offering mechanism is applicable between:
• the DDS\_DataWriter and the DDS\_DataReader. If the QosPolicy settings between DDS\_DataWriter and DDS\_DataReader are incompatible, no communication between them is established. In addition the DDS\_DataWriter will be informed via a DDS\_REQUESTED\_INCOMPATIBLE\_QOS status change and the DDS\_DataReader will be informed via an DDS\_OFFERED\_INCOMPATIBLE\_QOS status change.
• the DDS\_DataWriter and the Durability Service (as a built-in DDS\_DataReader). If the QosPolicy settings between DDS\_DataWriter and the Durability Service are inconsistent, no communication between them is established. In that case data published by the DDS\_DataWriter will not be maintained by the service and as a consequence will not be available for late joining DDS\_DataReaders. The QosPolicy of the Durability Service in the role of DDS\_DataReader is specified by the DDS\_DurabilityServiceQosPolicy in the DDS\_Topic.
• the Durability Service (as a built-in DDS\_DataWriter) and the DDS\_DataReader. If the QosPolicy settings between the Durability Service and the DDS\_DataReader are inconsistent, no communication between them is established. In that case the Durability Service will not publish historical data to late joining DDS\_DataReaders. The QosPolicy of the Durability Service in the role of DDS\_DataWriter is specified by the DDS\_DurabilityServiceQosPolicy in the DDS\_Topic.
The attribute total\_count holds the total cumulative count of DDS\_DataReader objects discovered by the DDS\_DataWriter with the same DDS\_Topic and a requested DDS\_DataReaderQos that was incompatible with the one offered by the DDS\_DataWriter.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_policy\_id holds the id of one of the QosPolicy settings that was found to be incompatible with what was offered, the last time an incompatibility was detected.
The attribute policies holds a list containing for each QosPolicy the total number of times that the concerned DDS\_DataWriter discovered an incompatible DDS\_DataReader for the same DDS\_Topic. Each element in the list represents a counter for a different QosPolicy, identified by a corresponding unique index number. A named list of all index numbers is expressed as a set of constants in the API. See Table 16: below for an overview of all these constants.
Table 16: Overview of All Named QosPolicy Indexes
| Index Name | Index Value |
| DDS_INVALID_QOS_POLICY_ID | 0 |
| DDS_USERDATA_QOS_POLICY_ID | 1 |
| DDS_DURABILITY_QOS_POLICY_ID | 2 |
| DDS_PRESENTATION_QOS_POLICY_ID | 3 |
| DDS_DEADLINE_QOS_POLICY_ID | 4 |
| DDS_LATENCYBUDGET_QOS_POLICY_ID | 5 |
| DDS_OWNERSHIP_QOS_POLICY_ID | 6 |
| DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID | 7 |
| DDS_LIVELINESS_QOS_POLICY_ID | 8 |
| DDS_TIMEBASEDFILTER_QOS_POLICY_ID | 9 |
| DDS_PARTITION_QOS_POLICY_ID | 10 |
| DDS_RELIABILITY_QOS_POLICY_ID | 11 |
| DDS_DESTINATIONORDER_QOS_POLICY_ID | 12 |
| DDS_HISTORY_QOS_POLICY_ID | 13 |
| DDS_RESOURCELIMITS_QOS_POLICY_ID | 14 |
| DDS_ENTITYFACTORY_QOS_POLICY_ID | 15 |
| DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID | 16 |
| DDS_READERDATALIFECYCLE_QOS_POLICY_ID | 17 |
| DDS_TOPICDATA_QOS_POLICY_ID | 18 |
| DDS_GROUPDATA_QOS_POLICY_ID | 19 |
| DDS_TRANSPORTPRIORITY_QOS_POLICY_ID | 20 |
| DDS_LIFESPAN_QOS_POLICY_ID | 21 |
| DDS_DURABILITIESERVICE_QOS_POLICY_ID | 22 |
# 3.1.5.6 DDS\_PublicationMatchedStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_PublicationMatchedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_long current_count;
DDS_long current_count_change;
```
DDS\_InstanceHandle\_t last\_subscription\_handle; };
# Description
This struct contains the statistics about the discovered number of matching DataReaders currently connected to the owner of this status, and of the cumulative number of DataReaders that has connected to the owner of this status over time.
# Attributes
DDS\_long total\_count - Total cumulative count of DataReaders compatible with the concerned DataWriter.
DDS\_long total\_count\_change - The change in total\_count since the last time the Status was read.
DDS\_long current\_count - Total count of DataReaders that are currently available and compatible with the DataWriter.
DDS\_long current\_count\_change - The change in current\_count since the last time the Status was read.
DDS\_InstanceHandle\_t last\_subscription\_handle - Handle to the last DataReader that matched the DataWriter causing the status to change.
# Detailed Description
This struct contains the statistics about the discovered number of DataReaders that are compatible with the DataWriter to which the Status is attached. DataReader and DataWriter are compatible if they use the same Topic and if the QoS requested by the DataReader is compatible with that offered by the DataWriter. A DataReader will automatically connect to a matching DataWriter, but will disconnect when that DataReader is deleted, when either changes its QoS into an incompatible value, or when either puts its matching counterpart on its ignore-list using the ignore\_subscription or ignore\_publication operations on the DomainParticipant.
The total\_count includes DataReaders that have already been disconnected, while in the current\_count only the currently connected DataReaders are considered.
# 3.1.5.7 DDS\_RequestedDeadlineMissedStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_RequestedDeadlineMissedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_InstanceHandle_t last_instance_handle; };
```
# Description
This struct contains the statistics about whether the deadline that the DDS\_DataReader to which this DDS\_Status is attached was expecting through its DDS\_DeadlineQosPolicy, was not respected for a specific instance.
# Attributes
DDS\_long total\_count - the total cumulative count of the missed deadlines detected for any instance read by the DDS\_DataReader to which this DDS\_Status is attached.
DDS\_long total\_count\_change - the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
DDS\_InstanceHandle\_t last\_instance\_handle - the handle to the last instance in the DDS\_DataReader to which this DDS\_Status is attached for which a missed deadline was detected.
# Detailed Description
This struct contains the statistics about whether the deadline that the DDS\_DataReader to which this DDS\_Status is attached was expecting through its DDS\_DeadlineQosPolicy, was not respected for a specific instance. Missed deadlines accumulate, that is, each deadline period the total\_count will be incremented by one for each instance for which data was not received.
The attribute total\_count holds the total cumulative count of the missed deadlines detected for any instance read by the DDS\_DataReader.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_instance\_handle holds the handle to the last instance in the DDS\_DataReader for which a missed deadline was detected.
# 3.1.5.8 DDS\_RequestedIncompatibleQosStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_RequestedIncompatibleQosStatus
{ DDS_long total_count;
DDS_long total_count_change;
QosPolicyId_t last_policy_id;
QosPolicyCountSeq policies; };
```
# Description
This struct contains the statistics about whether a requested QosPolicy setting was incompatible with the offered QosPolicy setting.
# Attributes
DDS\_long total\_count - holds the total cumulative count of DDS\_DataWriter objects, discovered by the DDS\_DataReader to which this DDS\_Status is attached, with the same DDS\_Topic and an offered DDS\_DataWriterQos that was incompatible with the one requested by the DDS\_DataReader.
DDS\_long total\_count\_change - holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
QosPolicyId\_t last\_policy\_id - holds the DDS\_<name>\_QOS\_POLICY\_ID of one of the QosPolicies that was found to be incompatible with what was requested, the last time an incompatibility was detected.
QosPolicyCountSeq policies - a list containing (for each QosPolicy) the total number of times that the concerned DDS\_DataReader discovered a D D S\_ D a t a W r it e r w i t h t h e s a m e D D S\_ T o p i c a n d a n o ff e r e d DDS\_DataWriterQos that is incompatible with the one requested by the DDS\_DataReader.
# Detailed Description
This struct contains the statistics about whether a requested QosPolicy setting was incompatible with the offered QosPolicy setting.
The Request/Offering mechanism is applicable between:
• the DDS\_DataWriter and the DDS\_DataReader. If the QosPolicy settings between DDS\_DataWriter and DDS\_DataReader are incompatible, no communication between them is established. In addition the DDS\_DataWriter will be informed via a DDS\_REQUESTED\_INCOMPATIBLE\_QOS status change and the DDS\_DataReader will be informed via an DDS\_OFFERED\_INCOMPATIBLE\_QOS status change.
• the DDS\_DataWriter and the Durability Service (as a built-in DDS\_DataReader). If the QosPolicy settings between DDS\_DataWriter and the Durability Service are inconsistent, no communication between them is established. In that case data published by the DDS\_DataWriter will not be maintained by the service and as a consequence will not be available for late joining DDS\_DataReaders. The QosPolicy of the Durability Service in the role of DDS\_DataReader is specified by the DDS\_DurabilityServiceQosPolicy in the DDS\_Topic.
• the Durability Service (as a built-in DDS\_DataWriter) and the DDS\_DataReader. If the QosPolicy settings between the Durability Service and the DDS\_DataReader are inconsistent, no communication between them is established. In that case the Durability Service will not publish historical data to late joining DDS\_DataReaders. The QosPolicy of the Durability Service in the role of DDS\_DataWriter is specified by the DDS\_DurabilityServiceQosPolicy in the DDS\_Topic.
The attribute total\_count holds the total cumulative count of DDS\_DataWriter objects discovered by the DDS\_DataReader with the same DDS\_Topic and an offered DDS\_DataWriterQos that was incompatible with the one requested by the DDS\_DataReader.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_policy\_id holds the DDS\_<name>\_QOS\_POLICY\_ID of one of the QosPolicies that was found to be incompatible with what was requested, the last time an incompatibility was detected.
The attribute policies holds a list containing for each QosPolicy: the total number of times that the concerned DDS\_DataReader discovered an incompatible DDS\_DataWriter for the same DDS\_Topic. Each element in the list represents a counter for a different QosPolicy, identified by a corresponding unique index number. A named list of all index numbers is expressed as a set of constants in the API. See Table 16, Overview of All Named QosPolicy Indexes, on page 128 for an overview of all these constants.
# 3.1.5.9 DDS\_SampleLostStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_SampleLostStatus
{ DDS_long total_count;
DDS_long total_count_change; };
```
# Description
This struct contains the statistics about whether a sample has been lost (never received).
# Attributes
DDS\_long total\_count - holds the total cumulative count of all samples lost across all instances of data published under the DDS\_Topic.
DDS\_long total\_count\_change - holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
# Detailed Description
This struct contains the statistics about whether a sample has been lost (never received). The status is independent of the differences in instances, in other words, it includes all samples lost across all instances of data published under the DDS\_Topic.
total\_count holds the total cumulative count of all samples lost across all instances of data published under the DDS\_Topic.
total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
# 3.1.5.10 DDS\_SampleRejectedStatus
# Synopsis
```c
#include <dds_dcps.h>
enum DDS_SampleRejectedStatusKind
{ DDS_NOT_REJECTED,
DDS_REJECTED_BY_INSTANCES_LIMIT,
DDS_REJECTED_BY_SAMPLES_LIMIT,
DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT };
struct DDS_SampleRejectedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_SampleRejectedStatusKind last_reason;
DDS_InstanceHandle_t last_instance_handle; };
```
# Description
This struct contains the statistics about samples that have been rejected.
# Attributes
DDS\_long total\_count - holds the total cumulative count of samples rejected by the DDS\_DataReader to which this DDS\_Status is attached.
DDS\_long total\_count\_change - holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
DDS\_SampleRejectedStatusKind last\_reason - holds the reason for rejecting the last sample.
DDS\_InstanceHandle\_t last\_instance\_handle - holds the handle to the instance which would have updated by the last sample that was rejected.
# Detailed Description
This struct contains the statistics about whether a received sample has been rejected.
The attribute total\_count holds the total cumulative count of samples rejected by the DDS\_DataReader to which this DDS\_Status is attached.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the DDS\_Status was read.
The attribute last\_reason holds the reason for rejecting the last sample. The attribute can have the following values:
• DDS\_NOT\_REJECTED - no sample has been rejected yet.
• DDS\_REJECTED\_BY\_INSTANCES\_LIMIT - the sample was rejected because it would exceed the maximum number of instances set by the DDS\_ResourceLimitsQosPolicy.
• DDS\_REJECTED\_BY\_SAMPLES\_LIMIT - the sample was rejected because it would exceed the maximum number of samples set by the DDS\_ResourceLimitsQosPolicy.
• DDS\_REJECTED\_BY\_SAMPLES\_PER\_INSTANCE\_LIMIT - the sample was rejected because it would exceed the maximum number of samples per instance set by the DDS\_ResourceLimitsQosPolicy.
The attribute last\_instance\_handle holds the handle to the instance which would have updated by the last sample that was rejected.
# 3.1.5.11 DDS\_SubscriptionMatchedStatus
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_SubscriptionMatchedStatus
{ DDS_long total_count;
DDS_long total_count_change;
DDS_long current_count;
DDS_long current_count_change;
DDS_InstanceHandle_t last_publication_handle; };
```
# Description
This struct contains the statistics about the discovered number of matching DataWriters currently connected to the owner of this status, and of the cumulative number of DataWriters that has connected to the owner of this status over time.
# Attributes
DDS\_long total\_count - Total cumulative count of DataWriters compatible with the concerned DataReader.
DDS\_long total\_count\_change - The change in total\_count since the last time the Status was read.
DDS\_long current\_count - Total count of DataWriters that are currently available and compatible with the DataWriter.
DDS\_long current\_count\_change - The change in current\_count since the last time the Status was read.
DDS\_InstanceHandle\_t last\_publication\_handle - Handle to the last DataWriter that matched the DataReader causing the status to change.
# Detailed Description
This struct contains the statistics about the discovered number of DataWriters that are compatible with the DataReader to which the Status is attached. DataWriter and DataReader are compatible if they use the same Topic and if the QoS requested by the DataReader is compatible with that offered by the DataWriter. A DataWriter will automatically connect to a matching DataReader, but will disconnect when that DataWriter is deleted, when either changes its QoS into an incompatible value, or when either puts its matching counterpart on its ignore-list using the ignore\_subscription or ignore\_publication operations on the DomainParticipant.
The total\_count includes DataWriters that have already been disconnected, while in the current\_count only the currently connected DataWriters are considered.
# 3.1.5.12 DDS\_AllDataDisposedTopicStatus
# Synopsis
```txt
#include <dds_dcps.h>
struct DDS_AllDataDisposedTopicStatus
{ DDS_long total_count
DDS_long total_count_change }
```
# Description
T h i s s t r u c t c o n t a i n s t h e s t a t i s t i c s a b o u t t h e o c c u r e n c e o f t h e DDS\_ALL\_DATA\_DISPOSED\_TOPIC\_STATUS event on the Topic to which this Status is attached.
# Attributes
DDS\_long total\_count - the total detected cumulative count of ALL\_DATA\_DISPOSED\_TOPIC\_STATUS events.
DDS\_long total\_count\_change - the change in total\_count since the last time the Status was read.
# Detailed Description
T h i s s t r u c t c o n t a i n s t h e s t a t i s t i c s a b o u t t h e o c c u r e n c e o f t h e DDS\_ALL\_DATA\_DISPOSED\_TOPIC\_STATUS event on the Topic to which this Status is attached. The Status is directly related to the invocation of the DDS\_Topic\_dispose\_all\_data() operation. Statistics are only kept when all instances are disposed using this operation, not when instances are disposed seperately by individual dispose calls.
# 3.1.6 Class DDS\_WaitSet
A DDS\_WaitSet object allows an application to wait until one or more of the attached DDS\_Condition objects evaluates to TRUE or until the timeout expires.
The DDS\_WaitSet has no factory and must be created by the application. It is directly created as an object by using DDS\_WaitSet constructors.
Figure 13: DCPS DDS\_WaitSets
The interface description of this class is as follows:
```c
/*
* interface DDS_WaitSet
*/
/*
* implemented API operations
*/
DDS_WaitSet
DDS_WaitSet__alloc
(void);
DDS_ReturnCode_t
DDS_WaitSet_wait
(DDS_WaitSet _this,
DDS_ConditionSeq *active_conditions,
const DDS_Duration_t *timeout);
DDS_ReturnCode_t
DDS_WaitSet_attach_condition
(DDS_WaitSet _this,
const DDS_Condition cond);
DDS_ReturnCode_t
DDS_WaitSet_detach_condition
(DDS_WaitSet _this,
const DDS_Condition cond);
DDS_ReturnCode_t
```
```c
DDS_WaitSet_get_conditions
(DDS_WaitSet _this,
DDS_ConditionSeq *attached_conditions);
```
The following sections describe the usage of all DDS\_WaitSet operations.
# 3.1.6.1 DDS\_WaitSet\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
DDS_WaitSet
DDS_WaitSet__alloc
(void);
```
# Description
This operation creates a new DDS\_WaitSet.
# Parameters
```txt
<none>
```
# Return Value
DDS\_WaitSet - handle to the newly-created DDS\_WaitSet. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_WaitSet. The DDS\_WaitSet must be created using this operation. In other words, the application is not allowed to declare an object of type DDS\_WaitSet. When the application wants to release the DDS\_WaitSet it must be released using DDS\_free.
In case there are insufficient resources available to allocate the DDS\_WaitSet, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.1.6.2 DDS\_WaitSet\_attach\_condition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_WaitSet_attach_condition
(DDS_WaitSet _this,
const DDS_Condition cond);
```
# Description
This operation attaches a DDS\_Condition to the DDS\_WaitSet.
# Parameters
in DDS\_WaitSet \_this - the DDS\_WaitSet object on which the operation is operated.
in const DDS\_Condition cond - a pointer to a DDS\_Condition.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER or DDS\_RETCODE\_OUT\_OF\_ RESOURCES.
# Detailed Description
This operation attaches a DDS\_Condition to the DDS\_WaitSet. The parameter cond must be either a DDS\_ReadCondition, DDS\_QueryCondition, DDS\_StatusCondition or DDS\_GuardCondition. To get this parameter see:
• DDS\_ReadCondition created by DDS\_DataReader\_create\_readcondition
• DDS\_QueryCondition created by DDS\_DataReader\_create\_querycondition
• DDS\_StatusCondition retrieved by DDS\_<Entity>\_get\_statuscondition on an DDS\_<Entity>
• DDS\_GuardCondition created by the C operation DDS\_GuardCondition\_\_alloc.
When a DDS\_GuardCondition is initially created, the trigger\_value is FALSE.
When a DDS\_Condition, whose trigger\_value evaluates to TRUE, is attached t o a D D S \_ W a i t S e t t h a t i s c u r r e n t l y b e i n g w a i t e d o n ( u s i n g t h e DDS\_WaitSet\_wait operation), the DDS\_WaitSet will unblock immediately.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_Condition is attached to the DDS\_WaitSet.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter cond is not a valid DDS\_Condition.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.1.6.3 DDS\_WaitSet\_detach\_condition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_WaitSet_detach_condition
(DDS_WaitSet _this,
const DDS_Condition cond)
```
# Description
This operation detaches a DDS\_Condition from the DDS\_WaitSet.
# Parameters
in DDS\_WaitSet \_this - the DDS\_WaitSet object on which the operation is operated.
in const DDS\_Condition cond - a pointer to a DDS\_Condition in the DDS\_WaitSet.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation detaches a DDS\_Condition from the DDS\_WaitSet. If the DDS\_Condition was not attached to this DDS\_WaitSet, the operation returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_Condition is detached from the DDS\_WaitSet.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter cond is not a valid DDS\_Condition.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DDS\_Condition was not attached to this DDS\_WaitSet.
# 3.1.6.4 DDS\_WaitSet\_get\_conditions
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_WaitSet_get_conditions
(DDS_WaitSet _this,
DDS_ConditionSeq *attached_conditions);
```
# Description
This operation retrieves the list of attached conditions.
# Parameters
in DDS\_WaitSet \_this - the DDS\_WaitSet object on which the operation is operated.
inout DDS\_ConditionSeq \*attached\_conditions - the inout parameter attached\_conditions is a sequence, which is used to pass the list of attached conditions.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation retrieves the list of attached conditions in the DDS\_WaitSet. The parameter attached\_conditions is a pointer to a sequence which afterwards will point to the sequence of attached conditions. The attached\_conditions sequence and its buffer may be pre-allocated by the application and therefore must e i t h e r b e r e - u s e d i n a s u b s e q u e n t i n v o c a t i o n o f t h e DDS\_WaitSet\_get\_conditions operation or be released by calling DDS\_free on the returned attached\_conditions. If the pre-allocated sequence is not big enough to hold the number of attached DDS\_Conditions, the sequence will automatically be (re-)allocated to fit the required size. The resulting sequence will either be an empty sequence, meaning there were no conditions attached, or will contain a list of DDS\_ReadCondition, DDS\_QueryCondition, DDS\_StatusCondition and DDS\_GuardCondition. These conditions previously have been attached by DDS\_WaitSet\_attach\_condition and were created by there respective create operation:
• DDS\_ReadCondition created by DDS\_DataReader\_create\_readcondition
• DDS\_QueryCondition created by DDS\_DataReader\_create\_querycondition
• DDS\_StatusCondition retrieved by DDS\_<Entity>\_get\_statuscondition on an DDS\_<Entity>
• DDS\_GuardCondition created by the C operation DDS\_GuardCondition\_\_alloc.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the list of attached conditions is returned
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.1.6.5 DDS\_WaitSet\_wait
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_WaitSet_wait
(DDS_WaitSet _this,
DDS_ConditionSeq *active_conditions,
const DDS_Duration_t *timeout)
```
# Description
This operation allows an application thread to wait for the occurrence of at least one of the conditions that is attached to the DDS\_WaitSet.
# Parameters
in DDS\_WaitSet \_this - the DDS\_WaitSet object on which the operation is operated.
inout DDS\_ConditionSeq \*active\_conditions - a sequence which is used to pass the list of all the attached conditions that have a trigger\_value of TRUE.
in const DDS\_Duration\_t \*timeout - the maximum duration to block for the DDS\_WaitSet\_wait, after which the application thread is unblocked. The special constant DDS\_DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_TIMEOUT or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation allows an application thread to wait for the occurrence of at least one of the conditions to evaluate to TRUE that is attached to the DDS\_WaitSet. If all of the conditions attached to the DDS\_WaitSet have a trigger\_value of FALSE, the DDS\_WaitSet\_wait operation will block the calling thread. The result of the operation is the continuation of the application thread after which the result is left in active\_conditions. This is a sequence, which will contain the list of all the a t t a c h e d c o n d i t i o n s t h a t h a v e a t r i g g e r \_ v a l u e o f T R U E . T h e active\_conditions sequence and its buffer may be pre-allocated by the application and therefore must either be re-used in a subsequent invocation of the DDS\_WaitSet\_wait operation or be released by calling DDS\_free on the returned active\_conditions. If the pre-allocated sequence is not big enough to hold the number of triggered DDS\_Conditions, the sequence will automatically be (re-)allocated to fit the required size. The parameter timeout specifies the maximum duration for the DDS\_WaitSet\_wait to block the calling application thread (when none of the attached conditions has a trigger\_value of TRUE). In t h a t c a s e t h e r e t u r n v a l u e i s D D S \_ R E T C O D E \_ T I M E O U T a n d t h e active\_conditions sequence is left empty. Since it is not allowed for more than one application thread to be waiting on the same DDS\_WaitSet, the operation returns immediately with the value DDS\_RETCODE\_PRECONDITION\_NOT\_MET when the DDS\_WaitSet\_wait operation is invoked on a DDS\_WaitSet which already has an application thread blocking on it.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - at least one of the attached conditions has a trigger\_value of TRUE.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_TIMEOUT - the timeout has elapsed without any of the attached conditions becoming TRUE.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DDS\_WaitSet already has an application thread blocking on it.
# 3.1.7 Class DDS\_Condition
This class is the base class for all the conditions that may be attached to a DDS\_WaitSet. This base class is specialized in three classes by the Data Distribution Service: DDS\_GuardCondition, DDS\_StatusCondition and DDS\_ReadCondition (also there is a DDS\_QueryCondition which is a specialized DDS\_ReadCondition).
Each DDS\_Condition has a trigger\_value that can be TRUE or FALSE and is set by the Data Distribution Service (except a DDS\_GuardCondition) depending on the evaluation of the DDS\_Condition.
Figure 14: DCPS DDS\_Conditions
The interface description of this class is as follows:
```c
/*
* interface DDS_Condition
*/
/*
* implemented API operations
*/
DDS_boolean
DDS_Condition_get_trigger_value
(DDS_Condition _this);
```
The next paragraph describes the usage of the DDS\_Condition operation.
# 3.1.7.1 DDS\_Condition\_get\_trigger\_value
# Synopsis
```c
#include <dds_dcps.h>
```
```c
DDS_boolean
DDS_Condition_get_trigger_value
(DDS_Condition _this);
```
# Description
This operation returns the trigger\_value of the DDS\_Condition.
# Parameters
in DDS\_Condition \_this - the DDS\_Condition object on which the operation is operated.
# Return Value
DDS\_boolean - the trigger\_value.
# Detailed Description
A DDS\_Condition has a trigger\_value that can be TRUE or FALSE and is set by the Data Distribution Service (except a DDS\_GuardCondition). This operation returns the trigger\_value of the DDS\_Condition.
# 3.1.8 Class DDS\_GuardCondition
A DDS\_GuardCondition object is a specific DDS\_Condition whose trigger\_value is completely under the control of the application. The DDS\_GuardCondition has no factory and must be created by the application. The DDS\_GuardCondition is directly created as an object by using the DDS\_GuardCondition constructor. When a DDS\_GuardCondition is initially c r e a t e d , t h e t r i g g e r \_ v a l u e i s F A L S E . T h e p u r p o s e o f t h e DDS\_GuardCondition is to provide the means for an application to manually w a k e u p a D D S \_ W a i t S e t . T h i s i s a c c o m p l i s h e d b y a t t a c h i n g t h e DDS\_GuardCondition to the Waitset and setting the trigger\_value by means of the DDS\_GuardCondition\_set\_trigger\_value operation.
The interface description of this class is as follows:
```c
/*
* interface DDS_GuardCondition
*/
/*
* inherited from DDS_Condition
*/
/* DDS_boolean
* DDS_GuardCondition_get_trigger_value
* (DDS_GuardCondition _this);
*/
/*
* implemented API operations
```
```c
*/
DDS_GuardCondition
DDS_GuardCondition__alloc
(void);
DDS_ReturnCode_t
DDS_GuardCondition_set_trigger_value
(DDS_GuardCondition _this,
const DDS_boolean value);
```
The following sections describe the usage of all DDS\_GuardCondition operations.
The inherited operation is listed but not fully described since it is not implemented in this class. The full description of this operation is given in the class from which it is inherited. This is described in their respective paragraph.
# 3.1.8.1 DDS\_GuardCondition\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
DDS_GuardCondition
DDS_GuardCondition_alloc
(void);
```
# Description
This operation creates a new DDS\_GuardCondition.
# Parameters
```txt
<none>
```
# Return Value
DDS\_GuardCondition - Return value is the handle to the newly-created DDS\_GuardCondition. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_GuardCondition. The DDS\_GuardCondition must be created using this operation. In other words, the application is not allowed to declare an object of type DDS\_GuardCondition. When the application wants to release the DDS\_GuardCondition it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_GuardCondition, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.1.8.2 DDS\_GuardCondition\_get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Condition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_boolean
DDS_GuardCondition_get_trigger_value
(DDS_GuardCondition _this);
```
# 3.1.8.3 DDS\_GuardCondition\_set\_trigger\_value
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_GuardCondition_set_trigger_value
(DDS_GuardCondition _this,
const DDS_boolean value);
```
# Description
This operation sets the trigger\_value of the DDS\_GuardCondition.
# Parameters
in DDS\_GuardCondition \_this - the DDS\_GuardCondition object on which the operation is operated.
in const DDS\_boolean value - the boolean value to which the DDS\_GuardCondition is set.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e :DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR or DDS\_RETCODE\_ILLEGAL\_OPERATION.
# Detailed Description
A DDS\_GuardCondition object is a specific DDS\_Condition which trigger\_value is completely under the control of the application. This operation must be used by the application to manually wake-up a DDS\_WaitSet. This operation sets the trigger\_value of the DDS\_GuardCondition to the parameter v a lu e . T h e D D S \_ G u ar d C o n d it i o n i s d i r e c t l y c r e a te d u s i n g t h e DDS\_GuardCondition constructor. When a DDS\_GuardCondition is initially created, the trigger\_value is FALSE.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the specified trigger\_value has successfully been applied
• DDS\_RETCODE\_ERROR - an internal error has occurred
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object
# 3.1.9 Class DDS\_StatusCondition
D D S \_ E n t i t y o b j e c t s t h a t h a v e s t a t u s a t t r i b u t e s a l s o h a v e a DDS\_StatusCondition, access is provided to the application by the DDS\_<Entity>\_get\_statuscondition operation.
The communication statuses whose changes can be communicated to the application depend on the DDS\_Entity. The following table shows the relevant statuses for each DDS\_Entity.
Table 17: Status Per DDS\_Entity
| DDS_Entity | Status Name |
| DDS_Topic | DDS_INCONSISTENT_TOPIC_STATUSDDS_ALL_DATA_DISPOSED_TOPIC_STATUS |
| DDS_Subscriber | DDS_DATA_ON_READERS_STATUS |
| DDS_DataReader | DDS_SAMPLE_REJECTED_STATUS |
| DDS_LIVELINESS_CHANGED_STATUS |
| DDS_REQUESTED_DEADLINE_MISSED_STATUS |
| DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS |
| DDS_DATA_AVAILABLE_STATUS |
| DDS_SAMPLE_LOST_STATUS |
| DDS_SUBSCRIPTION_MATCHED_STATUS |
| DDS_DataWriter | DDS_LIVELINESS_LOST_STATUS |
| DDS_OFFERED_DEADLINE_MISSED_STATUS |
| DDS_OFFERED_INCOMPATIBLE_QOS_STATUS |
| DDS_PUBLICATION_MATCHED_STATUS |
The trigger\_value of the DDS\_StatusCondition depends on the communication statuses of that DDS\_Entity (e.g., missed deadline) and also depends on the value of the DDS\_StatusCondition attribute mask (enabled\_statuses mask). A DDS\_StatusCondition can be attached to a DDS\_WaitSet in order to allow an application to suspend until the trigger\_value has become TRUE.
The trigger\_value of a DDS\_StatusCondition will be TRUE if one of the enabled StatusChangedFlags is set. That is, trigger\_value==FALSE only if all the values of the StatusChangedFlags are FALSE.
The sensitivity of the DDS\_StatusCondition to a particular communication status is controlled by the list of enabled\_statuses set on the condition by means of the DDS\_StatusCondition\_set\_enabled\_statuses operation.
W h e n t h e en a b l e d \_s t a t u s e s a r e n o t c h a ng e d b y t h e DDS\_StatusCondition\_set\_enabled\_statuses operation, all statuses are enabled by default.
The interface description of this class is as follows:
```c
/*
* interface DDS_StatusCondition
*/
/*
* inherited from DDS_Condition
*/
/* DDS_boolean
* DDS_StatusCondition_get_trigger_value
* (DDS_StatusCondition _this);
*/
/*
* implemented API operations
*/
DDS_StatusMask
DDS_StatusCondition_get_enabled statuses
(DDS_StatusCondition _this);
DDS_ReturnCode_t
DDS_StatusCondition_set_enabled statuses
(DDS_StatusCondition _this,
const DDS_StatusMask mask);
DDS_Entity
DDS_StatusCondition_get_entity
(DDS_StatusCondition _this);
```
The next paragraphs describe the usage of all DDS\_StatusCondition operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.1.9.1 DDS\_StatusCondition\_get\_enabled\_statuses
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_StatusCondition_get_enabled statuses
(DDS_StatusCondition _this);
```
# Description
This operation returns the list of enabled communication statuses of the DDS\_StatusCondition.
# Parameters
in DDS\_StatusCondition \_this - the DDS\_StatusCondition object on which the operation is operated.
# Return Value
DDS\_StatusMask - Result is a bit-mask in which each bit shows which status is taken into account for the DDS\_StatusCondition.
# Detailed Description
The trigger\_value of the DDS\_StatusCondition depends on the communication status of that DDS\_Entity (e.g., missed deadline, loss of information, etc.), ‘filtered’ by the set of enabled\_statuses on the DDS\_StatusCondition.
This operation returns the list of communication statuses that are taken into account to determine the trigger\_value of the DDS\_StatusCondition. This operation r e t u r n s t h e s t a t u s e s t h a t w e r e e x p l i c i t l y s e t o n t h e l a s t c a l l t o DDS\_StatusCondition\_set\_enabled\_statuses o r , i f DDS\_StatusCondition\_set\_enabled\_statuses was never called, the default list.
The result value is a bit-mask in which each bit shows which status is taken into account for the DDS\_StatusCondition. The relevant bits represents one of the following statuses:
```pickle
DDS_INCONSISTENT_TOPIC_STATUS
DDS_ALL_DATA_DISPOSED_TOPIC_STATUS
DDS_OFFERED_DEADLINE_MISSED_STATUS
DDS_REQUESTED_DEADLINE_MISSED_STATUS
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
DDS_SAMPLE_LOST_STATUS
DDS_SAMPLE_REJECTED_STATUS
DDS_DATA_ON_READERS_STATUS
DDS_DATA_AVAILABLE_STATUS
DDS_LIVELINESS_LOST_STATUS
DDS_LIVELINESS_CHANGED_STATUS
DDS_PUBLICATION_MATCHED_STATUS
DDS_SUBSCRIPTION_MATCHED_STATUS.
```
Each status bit is declared as a constant and can be used in an AND operation to check the status bit against the result of type DDS\_StatusMask. Not all statuses are relevant to all DDS\_Entity objects. See the respective Listener objects for each DDS\_Entity for more information.
# 3.1.9.2 DDS\_StatusCondition\_get\_entity
# Synopsis
```c
#include <dds_dcps.h>
DDS_Entity
DDS_StatusCondition_get_entity
(DDS_StatusCondition _this);
```
# Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ E n t i t y a s s o c i a t e d w i t h t h e DDS\_StatusCondition or the DDS\_OBJECT\_NIL pointer.
# Parameters
in DDS\_StatusCondition \_this - the DDS\_StatusCondition object on which the operation is operated.
# Return Value
D D S \_ E n t i t y - a p o i n t e r t o t h e D D S \_ E n t i t y a s s o c i a t e d w i t h t h e DDS\_StatusCondition or the DDS\_OBJECT\_NIL pointer.
# Detailed Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ E n t i t y a s s o c i a t e d w i t h t h e DDS\_StatusCondition. Note that there is exactly one DDS\_Entity associated with each DDS\_StatusCondition. When the DDS\_Entity was already deleted (there is no associated DDS\_Entity any more), the DDS\_OBJECT\_NIL pointer is returned.
# 3.1.9.3 DDS\_StatusCondition\_get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Condition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_boolean
DDS_StatusCondition_get_trigger_value
(DDS_StatusCondition _this);
```
# 3.1.9.4 DDS\_StatusCondition\_set\_enabled\_statuses
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_StatusCondition_set_enabled statuses
(DDS_StatusCondition _this,
const DDS_StatusMask mask);
```
# Description
This operation sets the list of communication statuses that are taken into account to determine the trigger\_value of the DDS\_StatusCondition.
# Parameters
in DDS\_StatusCondition \_this - the DDS\_StatusCondition object on which the operation is operated.
in const DDS\_StatusMask mask - a bit-mask in which each bit sets the status which is taken into account for the DDS\_StatusCondition.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e :DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_OPERATION or DDS\_RETCODE\_ALREADY\_DELETED.
# Detailed Description
The trigger\_value of the DDS\_StatusCondition depends on the communication status of that DDS\_Entity (e.g., missed deadline, loss of information, etc.), ‘filtered’ by the set of enabled\_statuses on the DDS\_StatusCondition.
This operation sets the list of communication statuses that are taken into account to determine the trigger\_value of the DDS\_StatusCondition. This operation may change the trigger\_value of the DDS\_StatusCondition.
DDS\_WaitSet objects behaviour depend on the changes of the trigger\_value of their attached DDS\_Conditions. Therefore, any DDS\_WaitSet to which the DDS\_StatusCondition is attached is potentially affected by this operation.
If this function is not invoked, the default list of enabled\_statuses includes all the statuses.
The parameter mask is a bit-mask in which each bit shows which status is taken into account for the DDS\_StatusCondition. The relevant bits represents one of the following statuses:
```txt
DDS_INCONSISTENT_TOPIC_STATUS
DDS_ALL_DATA_DISPOSED_TOPIC_STATUS
DDS_OFFERED_DEADLINE_MISSED_STATUS
DDS_REQUESTED_DEADLINE_MISSED_STATUS
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
DDS_SAMPLE_LOST_STATUS
DDS_SAMPLE_REJECTED_STATUS
DDS_DATA_ON_READERS_STATUS
DDS_DATA_AVAILABLE_STATUS
DDS_LIVELINESS_LOST_STATUS
DDS_LIVELINESS_CHANGED_STATUS
DDS_PUBLICATION_MATCHED_STATUS
DDS_SUBSCRIPTION_MATCHED_STATUS
```
Each status bit is declared as a constant and can be used in an OR operation to set the status bit in the parameter mask of type DDS\_StatusMask. Not all statuses are relevant to all DDS\_Entity objects. See the respective Listener objects for each DDS\_Entity for more information.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the list of communication statuses is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_StatusCondition has already been deleted.
# 3.1.10 Class DDS\_ErrorInfo
The DDS\_ErrorInfo mechanism is an OpenSplice-specific extension to the OMG-DDS standard, that can help DDS users to get a more finegrained overview of the context of an error. The DDS specification only mandates that functions return a DDS\_ReturnCode\_t value as a broad categorization of potential types of problems (there are 12 possible DDS\_ReturnCode\_t values, of which 11 indicate some kind of error), but factory operations do not even have this mechanism at their disposal since they return the object they were requested to create.
The DDS\_ErrorInfo was added to OpenSplice for the following reasons:
• It can provide context for errors that occur in factory operations (e.g. when create\_topic returns NULL).
• It can provide a DDS\_ErrorCode\_t value, that represents a much more fine-grained error categorization than the DDS\_ReturnCode\_t (21 categories vs. the 11 categories provided by DDS\_ReturnCode\_t).
• It can provide an error description that can give a much more dedicated explanation of the exact circumstances of the error.
• It can provide the name of the function call/component that caused the error.
• It can provide source code location where the error occured (file name + line number).
• It can provide a stacktrace of the thread that ran into the error.
The DDS\_ErrorInfo obtains its information from the API-level log messages recorded by the internal mechanisms of the data distribution service. These are messages that are, by default, also written to the ospl-info.log file. The application can access this information through an DDS\_ErrorInfo object, and take appropriate action based on the contents of this information. The DDS\_ErrorInfo has no factory and an instance of the class can be created by the application by calling its constructor.
The interface of this class is as follows:
```c
DDS_ErrorInfo
DDS_ErrorInfo_alloc
(void);
DDS_ReturnCode_t
DDS_ErrorInfo_update
(DDS_ErrorInfo _this);
DDS_ReturnCode_t
DDS_ErrorInfo_get_code
(DDS_ErrorInfo _this,
DDS_ErrorCode_t *code);
DDS_ReturnCode_t
DDS_ErrorInfo_get_message
(DDS_ErrorInfo _this,
DDS_string *message);
DDS_ReturnCode_t
DDS_ErrorInfo_get_location
(DDS_ErrorInfo _this,
DDS_string *location);
DDS_ReturnCode_t
DDS_ErrorInfo_get_source_line
(DDS_ErrorInfo _this,
DDS_string* source_line);
```
```txt
DDS_ReturnCode_t
DDS_ErrorInfo_get_stack_trace
(DDS_ErrorInfo _this,
DDS_string* stack_trace);
```
The following sections describe the usage of all DDS\_ErrorInfo operations.
# 3.1.10.1 DDS\_ErrorInfo\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
DDS_ErrorInfo
DDS_ErrorInfo_alloc
(void);
```
# Description
This operation creates a new DDS\_ErrorInfo.
# Parameters
```txt
<none>
```
# Return Value
DDS\_ErrorInfo - handle to the newly-created DDS\_ErrorInfo. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_ErrorInfo. The DDS\_ErrorInfo must be created using this operation. In other words, the application is not allowed to declare an object of type DDS\_ErrorInfo. When the application wants to release the DDS\_ErrorInfo it must be released using DDS\_free.
If there are insufficient resources available to allocate the DDS\_ErrorInfo, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.1.10.2 DDS\_ErrorInfo\_update
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ErrorInfo_update
(DDS_ErrorInfo _this);
```
# Description
This operation updates the DDS\_ErrorInfo object with the latest available information.
# Parameters
in DDS\_ErrorInfo \_this - the DDS\_ErrorInfo object on which the operation is operated.
# Return Value
D D S \_ R e t ur n C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation requests the latest error information from the data distribution service and stores it in the DDS\_ErrorInfo object. The error information remains available in the DDS\_ErrorInfo object until a new error occurs and the update operation is explicitly invoked on the DDS\_ErrorInfo object. If the information is successfully updated, DDS\_RETCODE\_OK is returned. If no information is available because no error has occurred yet, DDS\_RETCODE\_NO\_DATA is returned.
# 3.1.10.3 DDS\_ErrorInfo\_get\_code
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ErrorInfo_get_code
(DDS_ErrorInfo _this,
DDS_ErrorCode_t* code);
```
NOTE: This operation is not yet consistently implemented everywhere: various kinds of errors are still categorized as ‘UNDEFINED’.
# Description
This operation retrieves the error code of the last error message.
# Parameters
in DDS\_ErrorInfo \_this - the DDS\_ErrorInfo object on which the operation is operated.
inout ErrorCode\_t\* code - The DDS\_ErrorCode\_t struct in which the error code will be stored.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation stores the error code of the latest error in the provided DDS\_ErrorCode\_t struct. The DDS\_ErrorCode\_t type is an OpenSplice-specific equivalent to the DDS\_ReturnCode\_t type that is mandated by the OMG-DDS standard, but the DDS\_ErrorCode\_t type has a more fine-grained error categorization which uses 21 categories instead of the 11 provided by the DDS\_ReturnCode\_t type.
Table 18: below contains a list of all supported DDS\_ErrorInfo values and their meaning.
Table 18: All DDS\_ErrorInfo values
| Label | Value | Meaning. |
| DDS_ERRORCODE_UNDEFINED | 0 | Error has not (yet) been categorized. |
| DDS_ERRORCODE_ERROR | 1 | Unexpected error. |
| DDS_ERRORCODE_OUT_OF_RESOURCES | 2 | Not enough resources to complete the operation. |
| DDS_ERRORCODE_CREATION_KERNEL_ENTITY_FAILED | 3 | The kernel was not able to create the entity. Probably there is not enough shared memory available. |
| DDS_ERRORCODE_INVALID_VALUE | 4 | A value is passed that is outside its valid bounds. |
| DDS_ERRORCODE_INVALID_DURATION | 5 | A Duration is passed that is outside its valid bounds or that has not been normalized properly. |
| DDS_DDS_ERRORCODE_INVALID_TIME | 6 | A Time is passed that is outside its valid bounds or that has not been normalized properly. |
| DDS_ERRORCODE_ENTITY_INUSE | 7 | Attempted to delete an entity that is still in use. |
| DDS_ERRORCODE_CONTAINS_ENTITIES | 8 | Attempted to delete a factory that still contains entities. |
| DDS_ERRORCODE_ENTITY_UNKNOWN | 9 | A pointer to an unknown entity has been passed. |
| DDS_ERRORCODE_HANDLE_NOT_REGISTERED | 10 | A handle has been passed that is no longer in use. |
| DDS_ERRORCODE_HANDLE_NOT_MATCH | 11 | A handle has been passed to an entity to which it does not belong. |
| DDS_ERRORCODE_HANDLE_INVALID | 12 | An unknown handle has been passed. |
| DDS_ERRORCODE_INVALID_SEQUENCE | 13 | A sequence has been passed that has inconsistent variables (e.g. length > maximum, buffer equals NULL while maximum > 0, etc.) |
| DDS_ERRORCODE_UNSUPPORTED_VALUE | 14 | A value has been passed that is not (yet) supported. |
| DDS_ERRORCODE_INCONSISTENT_VALUE | 15 | A value has been passed that is inconsistent |
| DDS_ERRORCODE_IMMUTABLE_QOS_POLICY | 16 | Attempted to modify a QosPolicy that is immutable. |
| DDS_ERRORCODE_INCONSISTENT_QOS | 17 | Attempted to set QosPolicy values that are mutually inconsistent. |
| DDS_ERRORCODE_UNSUPPORTED_QOS_POLICY | 18 | Attempted to pass a QosPolicy setting that is not (yet) supported. |
| DDS_ERRORCODE_CONTAINS_CONDITIONS | 19 | Attempted to delete a WaitSet that still has Conditions attached to it. |
| DDS_ERRORCODE_CONTAINS_LOANS | 20 | Attempted to delete a DataReader/DataView that has unreturned loans. |
| DDS_ERRORCODE_INCONSISTENT_TOPIC | 21 | Attempted to create a topic that is inconsistent with existing topic definitions. |
# 3.1.10.4 DDS\_ErrorInfo\_get\_message
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ErrorInfo_get_message
(DDS_ErrorInfo _this,
DDS_string* message);
```
# Description
This operation retrieves the description of the latest error.
# Parameters
in DDS\_ErrorInfo \_this - the DDS\_ErrorInfo object on which the operation is operated.
inout DDS\_string\* message - Reference to a string holding the latest description.
# Return Value
D D S \_ R e t u rn C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation stores the description of the latest error in a newly-allocated string. If the pointer supplied by the application through the message parameter already contains a string, it is freed. If no error has occurred, DDS\_RETCODE\_NO\_DATA is returned and NULL is assigned to the message parameter.
# 3.1.10.5 DDS\_ErrorInfo\_get\_location
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ErrorInfo_get_location
(DDS_ErrorInfo _this,
DDS_string* location);
```
# Description
This operation retrieves the location or context of the latest error.
# Parameters
in DDS\_ErrorInfo \_this - the DDS\_ErrorInfo object on which the operation is operated.
inout DDS\_string\* message - Pointer to a string holding the location of the latest error.
# Return Value
D D S \_ R e t u rn C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation stores the context or location of the latest error in a newly-allocated string. The string may contain the name of an operation or component of the data distribution service in which the error occurred, or other descriptive information on the location of the error. If the pointer supplied by the application through the location parameter already contains a string, it is freed. If no error has occurred, DDS\_RETCODE\_NO\_DATA is returned and NULL is assigned to the location parameter.
# 3.1.10.6 DDS\_ErrorInfo\_get\_source\_line
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ErrorInfo_get_source_line
(DDS_ErrorInfo _this,
DDS_string* source_line);
```
# Description
This operation retrieves the location within the sourcecode of the latest error.
# Parameters
in DDS\_ErrorInfo \_this - the DDS\_ErrorInfo object on which the operation is operated.
inout DDS\_string\* source\_line - Pointer to a string holding the sourcecode information of the latest error.
# Return Value
D D S \_ R e t ur n C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation stores the name and line number of the source file in which the latest error occurred, seperated by a colon, in a newly-allocated string. If the pointer supplied by the application through the source\_line parameter already contains a string, it is freed. If no error has occurred, DDS\_RETCODE\_NO\_DATA is returned and NULL is assigned to the source\_line parameter.
# 3.1.10.7 DDS\_ErrorInfo\_get\_stack\_trace
# Synopsis
```c
#include <dds_dcps.h>
```
```c
DDS_ReturnCode_t
DDS_ErrorInfoget_stack_trace
(DDS_ErrorInfo _this,
DDS_string* stack_trace);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.2 Domain Module
Figure 15: DCPS Domain Module’s Class Model
This module contains the following classes:
```txt
DDS_DomainParticipant
DDS_DomainParticipantFactory
DDS_DomainParticipantListener (interface)
DDS_Domain (not depicted)
```
# 3.2.1 Class DDS\_DomainParticipant
All the DCPS DDS\_Entity objects are attached to a DDS\_DomainParticipant. A DDS\_DomainParticipant represents the local membership of the application in a Domain.
A Domain is a distributed concept that links all the applications that must be able to communicate with each other. It represents a communication plane: only the DDS\_Publishers and the DDS\_Subscribers attached to the same Domain can interact.
This class implements several functions:
• It acts as a container for all other DDS\_Entity objects
• It acts as a factory for the DDS\_Publisher, DDS\_Subscriber, DDS\_Topic, DDS\_ContentFilteredTopic and DDS\_MultiTopic objects
• It provides access to the built-in DDS\_Topic objects
• It provides information about DDS\_Topic objects
• It isolates applications within the same Domain (sharing the same domainId) from other applications in a different Domain on the same set of computers. In this way, several independent distributed applications can coexist in the same physical network without interfering, or even being aware of each other
• It provides administration services in the Domain, offering operations, which allow the application to ignore locally any information about a given Participant, Publication, Subscription or Topic.
The interface description of this class is as follows:
```c
/*
* interface DDS_DomainParticipant
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_DomainParticipant_get_statuscondition
* (DDS_DomainParticipant _this);
*/
/* DDS_StatusMask
* DDS_DomainParticipant_get_status_changes
* (DDS_DomainParticipant _this);
*/
/* DDS_ReturnCode_t
* DDS_DomainParticipant_enable
* (DDS_DomainParticipant _this);
*/
/*
* implemented API operations
*/
DDS_Publisher
DDS_DomainParticipant_create_publisher
(DDS_DomainParticipant _this,
const DDS_PublisherQos *qos,
```
```c
const struct DDS_PublisherListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_publisher
(DDS_DomainParticipant _this,
const DDS_Publisher p);
DDS_Subscriber
DDS_DomainParticipant_create_subscriber
(DDS_DomainParticipant _this,
const DDS_SubscriberQos *qos,
const struct DDS_SubscriberListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_subscriber
(DDS_DomainParticipant _this,
const DDS_Subscriber s);
DDS_Subscriber
DDS_DomainParticipant_get_builtin_subscriber
(DDS_DomainParticipant _this);
DDS_Topic
DDS_DomainParticipant_create_topic
(DDS_DomainParticipant _this,
const DDS_char *topic_name,
const DDS_char *type_name,
const DDS_TopicQos *qos,
const struct DDS_TopicListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_topic
(DDS_DomainParticipant _this,
const DDS_Topic a_topic);
DDS_Topic
DDS_DomainParticipant_find_topic
(DDS_DomainParticipant _this,
const DDS_char *topic_name,
const DDS_Duration_t *timeout);
DDS_TopicDescription
DDS_DomainParticipant_lookup_topicdescription
(DDS_DomainParticipant _this,
const DDS_char *name);
DDS_ContentFilteredTopic
DDS_DomainParticipant_create_contentfilteredtopic
(DDS_DomainParticipant _this,
const DDS_char *name,
const DDS_Topic related_topic,
const DDS_char *filter_expression,
const DDS_StringSeq *expression_parameters);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_contentfilteredtopic
(DDS_DomainParticipant _this,
```
```c
const DDS_ContentFilteredTopic
a_contentfilteredtopic);
DDS_MultiTopic
DDS_DomainParticipant_create_multitopic
(DDS_DomainParticipant _this,
const DDS_char *name,
const DDS_char *type_name,
const DDS_char *subscription_expression,
const DDS_StringSeq *expression_parameters);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_multitopic
(DDS_DomainParticipant _this,
const DDS_MultiTopic a_multitopic);
DDS_ReturnCode_t
DDS_DomainParticipant_delete_contained_entities
(DDS_DomainParticipant _this);
DDS_ReturnCode_t
DDS_DomainParticipant_set_qos
(DDS_DomainParticipant _this,
const DDS_DomainParticipantQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_get_qos
(DDS_DomainParticipant _this,
DDS_DomainParticipantQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_set_listener
(DDS_DomainParticipant _this,
const struct DDS_DomainParticipantListener *a_listener,
const DDS_StatusMask mask);
struct DDS_DomainParticipantListener
DDS_DomainParticipant_get_listener
(DDS_DomainParticipant _this);
DDS_ReturnCode_t
DDS_DomainParticipant_ignore_participant
(DDS_DomainParticipant _this,
const DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
DDS_DomainParticipant_ignore_topic
(DDS_DomainParticipant _this,
const DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
DDS_DomainParticipant_ignore_publication
(DDS_DomainParticipant _this,
const DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
DDS_DomainParticipant_ignore Subscription
(DDS_DomainParticipant _this,
const DDS_InstanceHandle_t handle);
DomainId_t
DDS_DomainParticipant_get_domain_id
```
```c
(DDS_DomainParticipant _this);
DDS_ReturnCode_t
DDS_DomainParticipant_get_discovered_participants
(DDS_DomainParticipant _this,
DDS_InstanceHandleSeq *participant_handles);
DDS_ReturnCode_t
DDS_DomainParticipant_get_discovered_participant_data
(DDS_DomainParticipant _this,
DDS_ParticipantBuiltinTopicData *participant_data,
DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
DDS_DomainParticipant_get_discovered_topics
(DDS_DomainParticipant _this,
DDS_InstanceHandleSeq *topic_handles);
DDS_ReturnCode_t
DDS_DomainParticipant_get_discovered_topic_data
(DDS_DomainParticipant _this,
DDS_TopicBuiltinTopicData *topic_data,
DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
DDS_DomainParticipant_assert_liveliness
(DDS_DomainParticipant _this);
DDS_ReturnCode_t
DDS_DomainParticipant_set_default_publisher_qos
(DDS_DomainParticipant _this,
const DDS_PublisherQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_get_default_publisher_qos
(DDS_DomainParticipant _this,
DDS_PublisherQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_set_default_subscriber_qos
(DDS_DomainParticipant _this,
const DDS_SubscriberQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_get_default_subscriber_qos
(DDS_DomainParticipant _this,
DDS_SubscriberQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_set_default_topic_qos
(DDS_DomainParticipant _this,
const DDS_TopicQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipant_get_default_topic_qos
(DDS_DomainParticipant _this,
DDS_TopicQos *qos);
DDS_boolean
contains_entity
(DDS_InstanceHandle_t a_handle);
DDS_ReturnCode_t
```
```txt
get_current_time
(DDS_Time_t *current_time);
```
The following sections describe the usage of all DDS\_DomainParticipant operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.2.1.1 DDS\_DomainParticipant\_assert\_liveliness
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipant_assert_liveliness
(DDS_DomainParticipant _this);
```
# Description
This operation asserts the liveliness for the DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.
```
# Detailed Description
T h i s o p e r a t i o n w i l l m a n u a l l y a s s e r t t h e l i v e l i n e s s f o r t h e DDS\_DomainParticipant. This way, the Data Distribution Service is informed that the DDS\_DomainParticipant is still alive. This operation only needs to be used when the DDS\_DomainParticipant contains DDS\_DataWriters with the DDS\_LivelinessQosPolicy s e t t o DDS\_MANUAL\_BY\_PARTICIPANT\_LIVELINESS\_QOS, and it will only affect the liveliness of those DDS\_DataWriters.
Writing data via the DDS\_DataWriter\_write operation of a DDS\_DataWriter w i l l a s s e r t t h e l i v e l i n e s s o n t h e D D S \_ D a t a W r i t e r i t s e l f a n d i t s DDS\_DomainParticipant. DDS\_DomainParticipant\_assert\_liveliness subsequently is only needed when data is not written regularly.
The liveliness should be asserted by the application, depending on the DDS\_LivelinessQosPolicy.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the liveliness of this DDS\_DomainParticipant has successfully been asserted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DomainParticipant has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DomainParticipant is not enabled.
# 3.2.1.2 DDS\_DomainParticipant\_contains\_entity
# Synopsis
```c
#include <dds_dcps.h>
DDS_boolean
contains_entity
(DDS_DomainParticipant _this,
DDS_InstanceHandle_t a_handle);
```
# Description
This operation checks whether or not the given Entity represented by a\_handle is created by the DDS\_DomainParticipant or any of its contained entities.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in DDS\_InstanceHandle\_t a\_handle - represents a DDS\_Entity in the Data Distribution System.
# Return Value
DDS\_boolean - Return value is TRUE if a\_handle represents a DDS\_Entity that is created by the DDS\_DomainParticipant or any of its contained DDS\_Entites. Otherwise the return value is FALSE.
# Detailed Description
This operation checks whether or not the given Entity represented by a\_handle is created by the DDS\_DomainParticipant itself (DDS\_TopicDescription, DDS\_Publisher or DDS\_Subscriber) or created by any of its contained entities (DDS\_DataReader, DDS\_ReadCondition, DDS\_QueryCondition, DDS\_DataWriter, etc.).
Return value is TRUE if a\_handle represents a DDS\_Entity that is created by the DDS\_DomainParticipant or any of its contained DDS\_Entites. Otherwise the return value is FALSE.
# 3.2.1.3 DDS\_DomainParticipant\_create\_contentfilteredtopic
# Synopsis
```c
#include <dds_dcps.h>
DDS_ContentFilteredTopic
DDS_DomainParticipant_create_contentfilteredtopic
(DDS_DomainParticipant _this,
const DDS_char *name,
const DDS_Topic related_topic,
const DDS_char *filter_expression,
const DDS_StringSeq *expression_parameters);
```
# Description
T h i s o p e r a t i o n c r e a t e s a D D S\_ C o n t e nt F i l t e r ed T o p i c fo r a DDS\_DomainParticipant in order to allow DDS\_DataReaders to subscribe to a subset of the topic content.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_char \*name c o n t a i n s t h e n a m e o f t h e DDS\_ContentFilteredTopic.
in const DDS\_Topic related\_topic - the handle to the base DDS\_Topic on which the filtering will be applied. Therefore, a filtered topic is based on an existing DDS\_Topic.
in const DDS\_char \*filter\_expression - holds the SQL expression (subset of SQL), which defines the filtering.
in const DDS\_StringSeq \*expression\_parameters - the handle to a sequence of strings with the parameter value used in the SQL expression (i.e., the number of %n tokens in the expression). The number of values in expression\_parameters must be equal or greater than the highest referenced %n token in the filter\_expression (e.g. if %1 and %8 are used as parameter in the filter\_expression, the expression\_parameters should at least contain n+1 = 9 values).
# Return Value
DDS\_ContentFilteredTopic - Return value is the handle to the newly-created DDS\_ContentFilteredTopic. In case of an error, a nil pointer is returned.
# Detailed Description
T h i s o p e r a t i o n c r e a t e s a D D S\_ C o n t e nt F i l t e r ed T o p i c fo r a DDS\_DomainParticipant in order to allow DDS\_DataReaders to subscribe to a subset of the topic content. The base topic, which is being filtered is defined by the parameter related\_topic. The resulting DDS\_ContentFilteredTopic only relates to the samples published under the related\_topic, which have been filtered according to their content. The resulting DDS\_ContentFilteredTopic only exists at the DDS\_DataReader side and will never be published. The samples of the related\_topic are filtered according to the SQL expression, which is a subset of SQL as defined in the parameter filter\_expression (see Appendix H, DCPS Queries and Filters).
The filter\_expression may also contain parameters, which appear as %n tokens in the expression which must be set by the sequence of strings defined by the pa ra meter e x pr e s s i o n\_ p a r a m e te r s . T h e n u m b e r o f v a l u e s i n expression\_parameters must be equal or greater than the highest referenced %n token in the filter\_expression (e.g. if %1 and %8 are used as parameter in the filter\_expression, the expression\_parameters should at least contain n+1 = 9 values).
The filter\_expression is a string that specifies the criteria to select the data samples of interest. In other words, it identifies the selection of data from the associated DDS\_Topics. It is an SQL expression where the WHERE clause gives the content filter.
# 3.2.1.4 DDS\_DomainParticipant\_create\_multitopic
# Synopsis
```c
#include <dds_dcps.h>
DDS_MultiTopic
DDS_DomainParticipant_create_multitopic
(DDS_DomainParticipant _this,
const DDS_char *name,
const DDS_char *type_name,
const DDS_char *subscription_expression,
const DDS_StringSeq *expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation creates a DDS\_MultiTopic for a DDS\_DomainParticipant in order to allow DDS\_DataReaders to subscribe to a filtered/re-arranged combination and/or subset of the content of several topics.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_char \*name - contains the name of the DDS\_MultiTopic.
in const DDS\_char \*type\_name - contains the name of the type of the DDS\_MultiTopic. This type\_name must have been registered using DDS\_TypeSupport\_register\_type prior to calling this operation.
in const DDS\_char \*subscription\_expression - the SQL expression (subset of SQL), which defines the selection, filtering, combining and re-arranging of the sample data.
in const DDS\_StringSeq \*expression\_parameters - the handle to a sequence of strings with the parameter value used in the SQL expression (i.e., the number of %n tokens in the expression). The number of values in expression\_parameters must be equal or greater than the highest referenced %n token in the subscription\_expression (e.g. if %1 and %8 are used as parameter in the subscription\_expression, the expression\_parameters should at least contain n+1 = 9 values).
# Return Value
DDS\_MultiTopic - Return value is the handle to the newly-created DDS\_MultiTopic. In case of an error, a nil pointer is returned.
# Detailed Description
This operation creates a DDS\_MultiTopic for a DDS\_DomainParticipant in order to allow DDS\_DataReaders to subscribe to a filtered/re-arranged combination and/or subset of the content of several topics. Before the DDS\_MultiTopic can be created, the type\_name of the DDS\_MultiTopic must have been registered prior to calling this operation. Registering is done, using the DDS\_TypeSupport\_register\_type operation from DDS\_TypeSupport. The list of topics and the logic, which defines the selection, filtering, combining and re-arranging of the sample data, is defined by the SQL expression, a subset of SQL defined in subsciption\_expression. The subscription\_expression may also contain parameters, which appear as %n tokens in the expression. These parameters are defined in expression\_parameters. The number of values in expression\_parameters must be equal or greater than the highest referenced %n token in the subscription\_expression (e.g. if %1 and %8 are used as parameter in the subscription\_expression, the expression\_parameters should at least contain n+1 = 9 values).
The subscription\_expression is a string that specifies the criteria to select the data samples of interest. In other words, it identifies the selection and rearrangement of data from the associated DDS\_Topics. It is an SQL expression where the SELECT clause provides the fields to be kept, the FROM part provides the names of the DDS\_Topics that are searched for those fields, and the WHERE clause gives the content filter. The DDS\_Topics combined may have different types but they are restricted in that the type of the fields used for the NATURAL JOIN operation must be the same.
The DDS\_DataReader, which is associated with a DDS\_MultiTopic only accesses information which exist locally in the DDS\_DataReader, based on the DDS\_Topics used in the subscription\_expression. The actual DDS\_MultiTopic will never be produced, only the individual DDS\_Topics.
# 3.2.1.5 DDS\_DomainParticipant\_create\_publisher
# Synopsis
```c
#include <dds_dcps.h>
DDS_Publisher
DDS_DomainParticipant_create_publisher
(DDS_DomainParticipant_this,
const DDS_PublisherQos *qos,
const struct DDS_PublisherListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation creates a DDS\_Publisher with the desired QosPolicy settings and if applicable, attaches the optionally specified DDS\_PublisherListener to it.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_PublisherQos \*qos - a collection of QosPolicy settings for the new DDS\_Publisher. In case these settings are not self consistent, no DDS\_Publisher is created.
in const struct DDS\_PublisherListener \*a\_listener - a pointer to the DDS\_PublisherListener instance which will be attached to the new DDS\_Publisher. It is permitted to use DDS\_OBJECT\_NIL as the value of the listener: this behaves as a DDS\_PublisherListener whose operations perform no action.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_PublisherListener for a certain status.
# Return Value
DDS\_Publisher - Return value is a pointer to the newly-created DDS\_Publisher. In case of an error, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a DDS\_Publisher with the desired QosPolicy settings and if applicable, attaches the optionally specified DDS\_PublisherListener to it. When the DDS\_PublisherListener is not applicable, the DDS\_OBJECT\_NIL pointer must be supplied instead. To delete the DDS\_Publisher the operation DDS\_DomainParticipant\_delete\_publisher o r DDS\_ DomainParticipant\_delete\_contained\_entities must be used.
In case the specified QosPolicy settings are not consistent, no DDS\_Publisher is created and the DDS\_OBJECT\_NIL pointer is returned. DDS\_OBJECT\_NIL can also be returned when insufficient access rights exist for the partition(s) listed in the provided QoS structure.
# Default QoS
The constant DDS\_PUBLISHER\_QOS\_DEFAULT can be used as parameter qos to create a DDS\_Publisher with the default DDS\_PublisherQos as set in the DDS\_DomainParticipant. The effect of using DDS\_PUBLISHER\_QOS\_DEFAULT i s t h e s a m e a s c a l l i n g t h e o p e r a t i o n DDS\_DomainParticipant\_get\_default\_publisher\_qos and using the resulting DDS\_PublisherQos to create the DDS\_Publisher.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_PublisherListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior to calling the listener means that if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset.
The following statuses are applicable to the DDS\_PublisherListener:
• DDS\_OFFERED\_DEADLINE\_MISSED\_STATUS (propagated)
• DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• DDS\_LIVELINESS\_LOST\_STATUS (propagated)
• DDS\_PUBLICATION\_MATCHED\_STATUS (propagated).
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_OBJECT\_NIL.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant DDS\_STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener. In other words, in case a communication status is also activated on the DDS\_DataWriterListener of a contained DDS\_DataWriter, the DDS\_DataWriterListener on that contained DDS\_DataWriter is invoked instead of the DDS\_PublisherListener. This means that a status change on a contained DDS\_DataWriter only invokes the DDS\_PublisherListener if the contained DDS\_DataWriter itself does not handle the trigger event generated by the status change.
In case a communication status is not activated in the m a sk of the DDS\_PublisherListener, the DDS\_DomainParticipantListener of the containing DDS\_DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant and a DDS\_Publisher specific behaviour when needed. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# 3.2.1.6 DDS\_DomainParticipant\_create\_subscriber
# Synopsis
```c
#include <dds_dcps.h>
DDS_Subscriber
DDS_DomainParticipant_create_subscriber
(DDS_DomainParticipant_this,
const DDS_SubscriberQos *qos,
const struct DDS_SubscriberListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation creates a DDS\_Subscriber with the desired QosPolicy settings and if applicable, attaches the optionally specified DDS\_SubscriberListener to it.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_SubscriberQos \*qos - a collection of QosPolicy settings for the new DDS\_Subscriber. In case these settings are not self consistent, no DDS\_Subscriber is created.
in const struct DDS\_SubscriberListener \*a\_listener - a pointer to the DDS\_SubscriberListener instance which will be attached to the new DDS\_Subscriber. It is permitted to use DDS\_OBJECT\_NIL as the value of the listener: this behaves as a DDS\_SubscriberListener whose operations perform no action.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_SubscriberListener for a certain status.
# Return Value
DDS\_Subscriber - Return value is a pointer to the newly-created DDS\_Subscriber. In case of an error, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a DDS\_Subscriber with the desired QosPolicy settings and if applicable, attaches the optionally specified DDS\_SubscriberListener to it. When the DDS\_SubscriberListener is not applicable, the DDS\_OBJECT\_NIL pointer must be supplied instead. To delete the DDS\_Subscriber the operation DDS\_DomainParticipant\_delete\_subscriber o r DDS\_ DomainParticipant\_delete\_contained\_entities must be used.
In case the specified QosPolicy settings are not consistent, no DDS\_Subscriber is created and the DDS\_OBJECT\_NIL pointer is returned. DDS\_OBJECT\_NIL can also be returned when insufficient access rights exist for the partition(s) listed in the provided QoS structure.
# Default QoS
The constant DDS\_SUBSCRIBER\_QOS\_DEFAULT can be used as parameter qos to create a DDS\_Subscriber with the default DDS\_SubscriberQos as set in the Domainparticipant. The effect of using DDS\_SUBSCRIBER\_QOS\_DEFAULT is t h e s a m e a s c a l l i n g t h e o p e r a t i o n DDS\_DomainParticipant\_get\_default\_subscriber\_qos and using the resulting DDS\_SubscriberQos to create the DDS\_Subscriber.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_SubscriberListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior to calling the listener means that if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset.
The following statuses are applicable to the DDS\_SubscriberListener:
| DDS_INCONSISTENT_TOPIC_STATUS | (propagated) |
| DDS_OFFERED_DEADLINE_MISSED_STATUS | (propagated) |
| DDS_REQUESTED_DEADLINE_MISSED_STATUS | (propagated) |
| DDS_OFFERED_INCOMPATIBLE_QOS_STATUS | (propagated) |
| DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS | (propagated) |
| DDS_SAMPLE_LOST_STATUS | (propagated) |
| DDS_SAMPLE_REJECTED_STATUS | (propagated) |
| DDS_DATA_ON_READERS_STATUS | (propagated) |
| DDS_DATA_AVAILABLE_STATUS | (propagated) |
| DDS_LIVELINESS_LOST_STATUS | (propagated) |
| DDS_LIVELINESS_CHANGED_STATUS | (propagated) |
| DDS_PUBLICATION_MATCHED_STATUS | (propagated) |
| DDS_SUBSCRIPTION_MATCHED_STATUS | (propagated). |
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS and DDS\_SUBSCRIPTION\_MATCHED\_STATUS are not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener. In other words, in case a communication status is also activated on the Listener of a contained entity, the Listener on that contained entity is invoked instead of the DDS\_DomainParticipantListener. This means that a status change on a contained entity only invokes the DDS\_DomainParticipantListener if the contained entity itself does not handle the trigger event generated by the status change.
The statuses DDS\_DATA\_ON\_READERS\_STATUS and DDS\_DATA AVAILABLE\_STATUS are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a get\_<status\_name>\_status operation and they are mutually exclusive. When new information becomes available to a DataReader, the Data Distribution Service will first look in an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D DS \_ D A T A \_ ON \_ R E A D ER S \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DomainParticipantListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DomainParticipant has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.39 DDS\_DomainParticipant\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipant_set_qos
(DDS_DomainParticipant_this,
const DDS_DomainParticipantQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipant \_this - is the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_DomainParticipantQos \*qos - must contain the new set of QosPolicy settings for the DDS\_DomainParticipant.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DomainParticipant. The parameter qos must contain the struct with the QosPolicy settings which is checked for self-consistency.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_DomainParticipantQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_DomainParticipantQos. It contains a QosPolicy setting with a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DomainParticipant has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.40 DDS\_DomainParticipant\_delete\_historical\_data
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipant_delete_historical_data
(DDS_DomainParticipant _this,
const DDS_string partition_expression,
const DDS_string topic_expression);
```
# Description
This operation deletes all historical TRANSIENT and PERSISTENT data that is stored by the durability service that is configured to support this DomainParticipant.
# Parameters
in DDS\_DomainParticipant \_this - is the DDS\_DomainParticipant object on which the operation is operated.
in const DDS\_string partition\_expression - An expression to define a filter on partitions.
in const DDS\_string topic\_expression - An expression to define a filter on topic names.
# Return Value
D D S \_ R e t ur n C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR.
# Detailed Description
This operation deletes all historical TRANSIENT and PERSISTENT data that is stored by the durability service that is configured to support this DomainParticipant. It only deletes the samples stored in the transient and persistent store, samples stored in individual application DataReaders is spared and remains available to these readers. However, late-joiners will no longer be able to obtain the deleted samples.
The partition\_expression and topic\_expression strings can be used to specify selection criteria for the topic and/or partition in which the data will be deleted. Wildcards are supported. Note that these parameters are mandatory and cannot be empty. The "\*" expression can be used to match all partitions and/or topics.
Only data that exists prior to this method invocationis deleted. Data that is still being inserted during this method invocationwill not be removed.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - all data matching the topic and partition expressions has been deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
# 3.2.1.41 DDS\_DomainParticipant\_get\_property
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipant_get_property
(DDS_DomainParticipant this,
DDS_DomainParticipantProperty *a_property);
```
# Description
This function queries the value of a property set on a DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in DDS\_DomainParticipantProperty \*a\_property - on entry, a\_property.name determines which property to query the value of; on successful return, a\_property.value is set to the current value of that property in the DDS\_DomainParticipant.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_UNSUPPORTED.
# Detailed Description
This operation looks up the property specified by a\_property.name in the DDS\_DomainParticipant, setting a\_property.value to the current value of the property. If the property has not been set using set\_property, the default value is returned.
NOTE: The user application is responsible for freeing the memory that is allocated by the middleware for a\_property.value.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a\_property.value has been set to the current value of the property.
• DDS\_RETCODE\_BAD\_PARAMETER - an invalid value has been specified.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DomainParticipant has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_UNSUPPORTED - a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.2.1.42 DDS\_DomainParticipant\_set\_property
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipant_set_property
(DDS_DomainParticipant this,
const DDS_DomainParticipantProperty *a_property);
```
# Description
This function sets a property on a DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipant \_this - the DDS\_DomainParticipant object on which the operation is operated.
in DDS\_DomainParticipantProperty a\_property - on specifies the property (in a\_property.name) and its new value (in a\_property.value).
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_UNSUPPORTED.
# Detailed Description
This operation sets the property specified by a\_property.name to the value given by a\_property.value.
Currently, the following properties are defined:
# isolateNode
The isolateNode property allows applications to isolate the federation from the rest of the Domain; i.e. at network level to disconnect the node from the rest of the system.
Applications also need to be able to issue a request to re-connect their federation to the domain again, after which the durability merge-policy that is configured needs to be applied.
To isolate a federation, the application needs to set the isolateNode property value to ‘true’, and to (de)isolate the federation the same property needs to be set to ‘false’. The default value of the isolateNode property is ‘false’.
All data that is published after isolateNode is set to true will not be sent to the network, and any data received from the network will be ignored.
Be aware that data being processed by the network service at the time of isolating a node may still be sent to the network, due to the asynchronous nature of network service internals.
The value is interpreted as a boolean (i.e., it must be either ‘true’ or ‘false’).
• false (default): The federation is connected to the domain.
• true: The federation is disconnected from the domain meaning that data is not published on the network and data from the network is ignored.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the property has been set.
• DDS\_RETCODE\_BAD\_PARAMETER - an invalid value has been specified.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DomainParticipant has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_UNSUPPORTED - a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.2.2 Class DDS\_DomainParticipantFactory
The purpose of this cl ass is to allow the creation and destruction of DDS\_DomainParticipant objects. DDS\_DomainParticipantFactory itself has no factory. It is a pre-existing singleton object that can be accessed by means of the DDS\_DomainParticipantFactory\_get\_instance operation on the DDS\_DomainParticipantFactory class.
The pre-defined value DDS\_TheParticipantFactory can also be used as an a l i a s f o r t h e s i n g l e t o n f a c t o r y r e t u r n e d b y t h e o p e r a t i o n DDS\_DomainParticipantFactory\_get\_instance.
The interface description of this class is as follows:
```c
/*
* interface DDS_DomainParticipantFactory
*/
/*
* implemented API operations
*/
DDS_DomainParticipantFactory
DDS_DomainParticipantFactory_get_instance
(void);
DDS_DomainParticipant
DDS_DomainParticipantFactory_create_participant
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId,
const DDS_DomainParticipantQos *qos,
const struct DDS_DomainParticipantListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_participant
(DDS_DomainParticipantFactory _this,
const DDS_DomainParticipant a_participant);
DDS_DomainParticipant
DDS_DomainParticipantFactory_lookup_participant
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_set_default_participant_qos
(DDS_DomainParticipantFactory _this,
const DDS_DomainParticipantQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_get_default_participant_qos
```
```c
(DDS_DomainParticipantFactory _this,
DDS_DomainParticipantQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_set_qos
(DDS_DomainParticipantFactory _this,
const DDS_DomainParticipantFactoryQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_get_qos
(DDS_DomainParticipantFactory _this,
DDS_DomainParticipantFactoryQos *qos);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_domain
(DDS_DomainParticipantFactory _this,
DDS_Domain a_domain);
DDS_Domain
DDS_DomainParticipantFactory_lookup_domain
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_contained_entities
(DDS_DomainParticipantFactory _this);
DDS_ReturnCode_t
DDS_DomainParticipantFactory_detach_all_domains
(DDS_DomainParticipantFactory _this,
DDS_boolean block_operations,
DDS_boolean delete_entities);
```
T h e f o l l o w i n g p a r a g r a p h s d e s c r i b e t h e u s a g e o f a l l DDS\_DomainParticipantFactory operations.
# 3.2.2.1 DDS\_DomainParticipantFactory\_create\_participant
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_DomainParticipantFactory_create_participant
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId,
const DDS_DomainParticipantQos *qos,
const struct DDS_DomainParticipantListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation creates a new DDS\_DomainParticipant which will join the domain identified by domainId, with the desired DDS\_DomainParticipantQos and attaches the optionally specified DDS\_DomainParticipantListener to it.
# Parameters
i n DDS\_DomainParticipantFactory this t h e DDS\_DomainParticipantFactory object on which the operation is operated.
in const DomainId\_t domainId - the ID of the Domain to which the DDS\_DomainParticipant is joined. This should be the ID as specified in the configuration file. This will also be applicable for the lookup\_participant, lookup\_domain and get\_domain\_id operations.
in const DDS\_DomainParticipantQos \*qos - a DDS\_DomainParticipantQos for the new DDS\_DomainParticipant. W h e n t h i s s e t o f Q o s P o l i c y s e t t i n g s i s i n c o n s i s t e n t , n o DDS\_DomainParticipant is created.
in const struct DDS\_DomainParticipantListener \*a\_listener - a pointer to the DDS\_DomainParticipantListener instance which will be attached to the new DDS\_DomainParticipant. It is permitted to use DDS\_OBJECT\_NIL as the value of the listener: this behaves as a DDS\_DomainParticipantListener whose operations perform no action.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_DomainParticipantListener for a certain status.
# Return Value
DDS\_DomainParticipant -Return value is a pointer to the newly-created DDS\_DomainParticipant. In case of an error, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_DomainParticipant, with the desired DDS\_DomainParticipantQos and attaches the optionally specified DDS\_DomainParticipantListener to it. The DDS\_DomainParticipant signifies that the calling application intends to join the Domain identified by the domainId argument.
If the specified QosPolicy settings are not consistent, the operation will fail; no DDS\_DomainParticipant is created and the operation returns the DDS\_OBJECT\_NIL pointer. To delete the DDS\_DomainParticipant the operation DDS\_DomainParticipantFactory\_delete\_participant must be used.
# Identifying the Domain
The DDS\_DomainParticipant will attach to the Domain that is specified by the domainId parameter. This parameter corresponds to the integer specified in the Id tag in the configuration file. Note that to make multiple connections to a Domain (create multiple Participants for the same Domain) within a single process, all of the Participants must use the same identification (i.e. all use the same domain Id).
The constant DDS\_DOMAIN\_ID\_DEFAULT can be used for this parameter. If this is done the value of Id tag from the configuration file specified by the environment variable called OSPL\_URI will be used.
It is recommended to use this domain Id in conjunction with the OSPL\_URI environment variable instead of hard-coding a domain Id into your application, since this gives you much more flexibility in the deployment phase of your product. See also Section 1.3.2.1, The OSPL\_URI environment variable, in the Deployment Guide.
# Default QoS
The constant DDS\_PARTICIPANT\_QOS\_DEFAULT can be used as parameter qos to create a DDS\_DomainParticipant w i t h t h e d e f a u l t DDS\_DomainParticipantQos a s s e t i n t h e DDS\_DomainParticipantfactory. The effect of using DDS\_PARTICIPANT\_QOS\_DEFAULT is the same as calling the operation DDS\_DomainParticipantFactory\_get\_default\_participant\_qos and u s i n g th e r e s u l t i n g D D S\_ D o m a i n Pa r t i c i pa n t Q o s t o c r e a t e t h e DDS\_DomainParticipant.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_DomainParticipantListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior t o c a l l i n g t h e l i s t e n e r m e a n s t h a t i f t h e a p p l i c a t i o n c a l l s t h e get\_<status\_name>\_status from inside the listener it will see the status already reset.
The following statuses are applicable to the DDS\_DomainParticipantListener:
• DDS\_INCONSISTENT\_TOPIC\_STATUS
(propagated)
• DDS\_OFFERED\_DEADLINE\_MISSED\_STATUS
(propagated)
• DDS\_REQUESTED\_DEADLINE\_MISSED\_STATUS
(propagated)
```txt
- DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)
- DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)
- DDS_SAMPLE_LOST_STATUS (propagated)
- DDS_SAMPLE_REJECTED_STATUS (propagated)
- DDS_DATA_ON_READERS_STATUS (propagated)
- DDS_DATA_AVAILABLE_STATUS (propagated)
- DDS_LIVELINESS_LOST_STATUS (propagated)
- DDS_LIVELINESS_CHANGED_STATUS (propagated)
- DDS_PUBLICATION_MATCHED_STATUS (propagated)
- DDS_SUBSCRIPTION_MATCHED_STATUS (propagated).
```
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS and DDS\_SUBSCRIPTION\_MATCHED\_STATUS are not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_OBJECT\_NIL.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener. In other words, in case a communication status is also activated on the Listener of a contained entity, the Listener on that contained entity is invoked instead of the DDS\_DomainParticipantListener. This means that a status change on a contained entity only invokes the DDS\_DomainParticipantListener if the contained entity itself does not handle the trigger event generated by the status change.
The statuses DDS\_DATA\_ON\_READERS\_STATUS and DDS\_DATA AVAILABLE\_STATUS are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a get\_<status\_name>\_status operation and they are mutually exclusive. When new information becomes available to a DataReader, the Data Distribution Service will first look in an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D D S\_ D A T A \_ ON \_ R E A D E RS \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
# 3.2.2.2 DDS\_DomainParticipantFactory\_delete\_participant
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_participant
(DDS_DomainParticipantFactory _this,
const DDS_DomainParticipant a_participant);
```
# Description
This operation deletes a DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipantFactory this t h e DDS\_DomainParticipantFactory object on which the operation is operated.
in const DDS\_DomainParticipant a\_participant - a pointer to the DDS\_DomainParticipant, which is to be deleted.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_ PRECONDITION\_NOT\_MET.
# Detailed Description
T h i s o p e r a ti o n d e l e t e s a D D S\_ D o m a i nP a r t i c i pa n t . A DDS\_DomainParticipant cannot be deleted when it has any attached D D S \_ E n t i t y o b j e c t s . W h e n t h e o p e r a t i o n i s c a l l e d o n a DDS\_DomainParticipant with existing DDS\_Entity objects, the operation returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DomainParticipant is deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter a\_participant is not a valid DDS\_DomainParticipant.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DDS\_DomainParticipant contains one or more DDS\_Entity objects.
# 3.2.2.3 DDS\_DomainParticipantFactory\_get\_default\_participant\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_get_default_participant_qos
(DDS_DomainParticipantFactory _this,
DDS_DomainParticipantQos *qos);
```
# Description
This operation gets the default DDS\_DomainParticipantQos of the DDS\_DomainParticipant.
# Parameters
```txt
in DDS_DomainParticipantFactory _ this - the DDS_DomainParticipantFactory object on which the operation is operated.
```
```txt
inout DDS_DomainParticipantQos *qos - a pointer to the DDS_DomainParticipantQos struct (provided by the application) in which the default DDS_DomainParticipantQos for the DDS_DomainParticipant is written.
```
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation gets the default DDS\_DomainParticipantQos of the DDS\_DomainParticipant (that is the struct with the QosPolicy settings) which is used for newly-created DDS\_DomainParticipant objects, in case the constant DDS\_PARTICIPANT\_QOS\_DEFAULT i s u s e d . T h e d e f a u l t DDS\_DomainParticipantQos is only used when the constant is supplied as parameter qos to specify the DDS\_DomainParticipantQos in the DDS\_DomainParticipantFactory\_create\_participant operation. The application must provide the DDS\_DomainParticipantQos struct in which the QosPolicy settings can be stored and provide a pointer to the struct. The operation writes the default QosPolicy settings to the struct pointed to by qos. Any settings in the struct are overwritten.
The values retrieved by this operation match the set of values specified on the last successful call to DDS\_DomainParticipantFactory\_set\_default participant\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 5: on page 65.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the default DDS\_DomainParticipant QosPolicy settings of this DDS\_DomainParticipantFactory have successfully been copied into the specified DDS\_DomainParticipantQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.4 DDS\_DomainParticipantFactory\_get\_instance
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipantFactory
DDS_DomainParticipantFactory_get_instance
(void);
```
# Description
This operation returns the DDS\_DomainParticipantFactory singleton.
# Parameters
```txt
<none>
```
# Return Value
DDS\_DomainParticipantFactory - return value is a pointer to the DDS\_DomainParticipantFactory.
# Detailed Description
This operation returns the DDS\_DomainParticipantFactory singleton. The operation can be called multiple times without side-effects and it returns the same DDS\_DomainParticipantFactory instance.
The pre-defined value DDS\_TheParticipantFactory can also be used as an a l i a s f o r t h e s i n g l e t o n f a c t o r y r e t u r n e d b y t h e o p e r a t i o n DDS\_DomainParticipantFactory\_get\_instance.
# 3.2.2.5 DDS\_DomainParticipantFactory\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_get_qos
(DDS_DomainParticipantFactory_this,
DDS_DomainParticipantFactoryQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DDS\_DomainParticipantFactory.
# Parameters
in DDS\_DomainParticipantFactory this - t h e DDS\_DomainParticipantFactory object on which the operation is operated.
inout DDS\_DomainParticipantFactoryQos \*qos - a pointer to the destination DDS\_DomainparticipantFactoryQos struct in which the QosPolicy settings will be copied.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DDS\_DomainParticipantFactory on which this operation is used. This DDS\_DomainparticipantFactoryQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_DomainParticipantFactory has successfully been copied into the specified DDS\_DomainParticipantFactoryQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.6 DDS\_DomainParticipantFactory\_lookup\_participant
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_DomainParticipantFactory_lookup_participant
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId);
```
# Description
This operation retrieves a previously created DDS\_DomainParticipant belonging to the specified domainId.
# Parameters
in DDS\_DomainParticipantFactory this - t h e DDS\_DomainParticipantFactory object on which the operation is operated.
in const DomainId\_t domainId - the ID of the Domain for which a joining DDS\_DomainParticipant should be retrieved. This should be the ID as specified in the configuration file.
# Return Value
D D S\_ D o m a i nP a r t i c i pa n t - R e tu r n v a l u e i s a p o in t e r t o t h e D D S\_ D o m a i n Pa r t i c i pa n t re tr i e v e d . W he n n o s uc h DDS\_DomainParticipant is found, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation retrieves a previously created DDS\_DomainParticipant belonging to the specified domainId. If no such DDS\_DomainParticipant exists, the operation will return DDS\_OBJECT\_NIL.
The domainId used to search for a specific DDS\_DomainParticipant must be i d e n t i c a l t o t h e d o m a i n I d t h a t w a s u s e d t o c r e a t e t h a t s p e c i f i c DDS\_DomainParticipant.
If multiple DDS\_DomainParticipant entities belonging to the specified domainId exist, then the operation will return one of them. It is not specified which one. See also DDS\_DomainParticipantFactory\_create\_participant (section 3.2.2.1 on page 221).
# 3.2.2.7 DDS\_DomainParticipantFactory\_set\_default\_participant\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_set_default_participant_qos
(DDS_DomainParticipantFactory _this,
const DDS_DomainParticipantQos *qos);
```
# Description
This operation sets the default DDS\_DomainParticipantQos of the DDS\_DomainParticipant.
# Parameters
in DDS\_DomainParticipantFactory t h i s - t h e DDS\_DomainParticipantFactory object on which the operation is operated.
in const DDS\_DomainParticipantQos \*qos - t h e DDS\_DomainParticipantQos struct, which contains the new default DDS\_DomainParticipantQos f o r t h e n e w l y - c r e a t e d DDS\_DomainParticipants.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation sets the default DDS\_DomainParticipantQos of the DDS\_DomainParticipant (that is the struct with the QosPolicy settings) which is used for newly-created DDS\_DomainParticipant objects, in case the constant DDS\_PARTICIPANT\_QOS\_DEFAULT i s u s e d . T h e d e f a u l t DDS\_DomainParticipantQos is only used when the constant is supplied as parameter qos to specify the DDS\_DomainParticipantQos in the DDS\_DomainParticipantFactory\_create\_participant operation. The DDS\_DomainParticipantQos is always self consistent, because its policies do not depend on each other. This means this operation never returns the DDS\_RETCODE\_INCONSISTENT\_POLICY.
T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b y DDS\_DomainParticipantFactory\_get\_default\_participant\_qos.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new default DDS\_DomainParticipantQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_DomainParticipantQos. It contains a QosPolicy setting with a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.8 DDS\_DomainParticipantFactory\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_set_qos
(DDS_DomainParticipantFactory_this,
const DDS_DomainParticipantFactoryQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DomainParticipantFactory.
# Parameters
in DDS\_DomainParticipantFactory t h i s - i s t h e DDS\_DomainParticipantFactory object on which the operation is operated.
in const DDS\_DomainParticipantFactoryQos \*qos - must contain the new set of QosPolicy settings for the DDS\_DomainParticipantFactory.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DomainParticipantFactory. The parameter qos must contain the struct with the QosPolicy settings.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_DomainParticipantFactoryQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.9 DDS\_DomainParticipantFactory\_delete\_domain
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_domain
(DDS_DomainParticipantFactory _this,
```
DDS\_Domain a\_domain);
# Description
This operation deletes a DDS\_Domain.
# Parameters
in DDS\_DomainParticipantFactory \_this - the DDS\_DomainParticipantFactory object on which the operation is operated.
in DDS\_Domain a\_domain - a pointer to the DDS\_Domain, which is to be deleted.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation deletes a DDS\_Domain.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_Domain is deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter a\_domain is not a valid DDS\_Domain.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.10 DDS\_DomainParticipantFactory\_lookup\_domain
# Synopsis
```c
#include <dds_dcps.h>
DDS_Domain
DDS_DomainParticipantFactory_lookup_domain
(DDS_DomainParticipantFactory _this,
const DomainId_t domainId);
```
# Description
This operation retrieves a previously created DDS\_Domain proxy belonging to the specified domainId or creates a new DDS\_Domain if no DDS\_Domain yet exists but the Domain itself is available.
# Parameters
in DDS\_DomainParticipantFactory \_this - the DDS\_DomainParticipantFactory object on which the operation is operated. in const DomainId\_t domainId - the ID of the Domain for which a DDS\_Domain proxy should be retrieved. This should be the ID as specified in the configuration file.
# Return Value
DDS\_Domain - Return value is a pointer to the DDS\_Domain proxy retrieved. When n o s u c h D D S \_ D o m a i n p r o x y i s f o u n d o r c o u l d b e c r e a t e d , t h e DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation retrieves a previously created DDS\_Domain proxy belonging to the specified domainId or creates a new DDS\_Domain proxy if no DDS\_Domain proxy was found, but the DomainId does refer to a valid Domain. If no such DDS\_Domain exists or could be created, the operation will return DDS\_OBJECT\_NIL. See also DDS\_DomainParticipantFactory\_create\_participant (section 3.2.2.1 on page 221).
# 3.2.2.11 DDS\_DomainParticipantFactory\_delete\_contained\_entities
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DomainParticipantFactory_delete_contained_entities
(DDS_DomainParticipantFactory _this);
```
# Description
This operation deletes all of the DDS\_Entity objects that were created on the DDS\_DomainParticipantFactory.
# Parameters
in DDS\_DomainParticipantFactory \_this - the DDS\_DomainParticipantFactory object on which the operation is performed.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are:
DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ PRECONDITION\_NOT\_MET or DDS\_RETCODE\_BAD\_PARAMETER.
# Detailed Description
This operation deletes all of the DDS\_Entity objects that were created on the DDS\_DomainParticipantFactory (it deletes all contained DDS\_DomainParticipant objects). Prior to deleting each contained DDS\_Entity, t h i s o p e r a t i o n r e g r e s s i v e l y c a l l s t h e DDS\_DomainParticipant\_delete\_contained\_entities operation on each DDS\_Participant. In other words, this operation cleans up all DDS\_Entity objects in the process.
NOTE: The operation will return DDS\_PRECONDITION\_NOT\_MET if the any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDS\_DataReader cannot be deleted because the application has called a read or take operation and has not called the corresponding return\_loan operation to return the loaned samples. In such cases, the operation does not roll back any entity deletions performed prior to the detection of the problem.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - all contained DDS\_Entity objects are deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter \_this is not a valid DDS\_DomainParticipantFactory.
# 3.2.2.12 DDS\_DomainParticipantFactory\_detach\_all\_domains
# Synopsis
#include <dds\_dcps.h>
```txt
DDS_ReturnCode_t
DDS_DomainParticipantFactory_detach_all_domains
(DDS_DomainParticipantFactory _this,
DDS_boolean block_operations,
DDS_boolean delete_entities);
```
# Description
This operation will safely detach the application from all domains it is currently participating in.
# Parameters
```txt
in DDS_DomainParticipantFactory _this-
The DDS_DomainParticipantFactory object on which the operation is performed.
in DDS_boolean block_operations -
Indicates whether the application wants any operations that are called while detaching to be blocked or not.
in DDS_boolean delete_entities -
Indicates whether the application DDS entities in the 'connected' domains must be deleted synchronously during detaching.
```
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are:
DDS_RETCODE_OK
```
# Detailed Description
This operation safely detaches the application from all domains it is currently participating in. When this operation has been performed successfully, the application is no longer connected to any Domain.
• For Federated domains, finishing this operation successfully means that all shared memory segments have been safely un-mapped from the application process.
• For SingleProcess mode domains, this means all services for all domains have been stopped. This allows graceful termination of the OSPL services that run as threads within the application. Graceful termination of services in this mode would for instance allow durability flushing of persistent data and networking termination announcement over the network.
When this call returns, further access to all domains will be denied and it will not be possible for the application to open or re-open any DDS domain.
The behavior of the detach\_all\_domains operation is determined by the block\_operations and delete\_entities parameters
block\_operations – This parameter specifies whether the application wants any DDS operation to be blocked or not while detaching. When TRUE, any DDS operation called during this operation will be blocked and remain blocked forever (so also after the detach operation has completed and returns to the caller). When FALSE, any DDS operation called during this operation may return DDS\_RETCODE\_ALREADY\_DELETED.
Please note that a listener callback is not considered an operation in progress. Of course, if a DDS operation is called from within the listener callback, that operation will be blocked during the detaching if this attribute is set to TRUE.
delete\_entities – This parameter specifies whether the application wants the DDS entities created by the application to be deleted (synchronously) while detaching from the domain or not. If TRUE, all application entities are guaranteed to be deleted when the call returns. If FALSE, application entities will not explicitly be deleted by this operation.
In federated mode, the splice-daemon will delete them asynchronously after this operation has returned successfully. In SingleProcess mode this attribute is ignored and clean up will always be performed, as this cannot be delegated to a different process.
NOTE: In federated mode when the detach\_all\_domain operation is called with block\_operations set to FALSE and delete\_entities also FALSE then the DDS operations which are in progress and which are waiting for some condition to become true (or waiting for an event to occur) while the detach operation is performed may be blocked.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK – the application is detached from all domains.
# 3.2.3 Class DDS\_Domain
The purpose of this class is to represent the Domain and allow certain Domain-wide operations to be performed. In essence it is a proxy to the Domain.
A Domain is a distributed concept that links all the applications that must be able to communicate with each other. It represents a communication plane: only the DDS\_Publishers and the DDS\_Subscribers attached to the same Domain can interact.
This class currently implements one function:
• It allows for a snapshot to be taken of all persistent data available within this Domain on local node level.
The interface description of this class is as follows:
/\*
```c
* interface DDS_Domain
*/
DDS_ReturnCode_t
DDS_Domain_create_persistent_snapshot(
DDS_Domain _this,
const DDS_char* partition_expression,
const DDS_char* topic_expression,
const DDS_char* URI);
```
The following sections describe the usage of all DDS\_Domain operations.
# 3.2.3.1 DDS\_Domain\_create\_persistent\_snapshot
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Domain_create_persistent_snapshot(
DDS_Domain _this,
const DDS_char* partition_expression,
const DDS_char* topic_expression,
const DDS_char* URI);
```
# Description
This operation will create a snapshot of all persistent data matching the provided partition and topic expressions and store the snapshot at the location indicated by the URI. Only persistent data available on the local node is considered.
# Parameters
in DDS\_Domain \_this - the DDS\_Domain object on which the operation is operated.
in DDS\_char\* partition\_expression - the expression of all partitions involved in the snapshot; this may contain wildcards.
in DDS\_char\* topic\_expression - the expression of all topics involved in the snapshot; this may contain wildcards.
in DDS\_char\* uri - the location where to store the snapshot. Currently only directories are supported.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation will create a snapshot of all persistent data matching the provided partition and topic expressions and store the snapshot at the location indicated by the URI. Only persistent data available on the local node is considered. This operation will fire an event to trigger the snapshot creation by the durability service and then return while the durability service fulfills the snapshot request; if no durability service is available then there is no persistent data available and the operation will return OK as a snapshot of an empty store is an empty store.
The created snapshot can then be used as the persistent store for the durability service next time it starts up by configuring the location of the snapshot as the persistent store in the configuration file. The durability service will then use the snapshot as the regular store (and can thus also alter its contents).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK – The persistent snapshot is (being) created.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter partition\_expression, topic\_expression or uri is NIL.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Domain proxy has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.4 DDS\_DomainParticipantListener interface
Since a DDS\_DomainParticipant is a DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_DomainParticipantListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DDS\_DomainParticipantListener class. All DDS\_DomainParticipantListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The DDS\_DomainParticipantListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed d e a d l i n e , v i o l a t i o n o f a Q o s P o l i c y s e t t i n g , e t c . T h e DDS\_DomainParticipantListener is related to changes in communication status DDS\_StatusConditions.
The interface description of this class is as follows:
```c
/*
* interface DDS_DomainParticipantListener
*/
/*
* inherited from DDS_TopicListener
*/
/* void
* DDS_DomainParticipantListener_on_inconsistent_topic
* (void *listener_data,
* DDS_Topic the_topic,
* const DDS_InconsistentTopicStatus *status);
*/
/*
* inherited from DDS_PublisherListener
*/
/* void
* DDS_DomainParticipantListener_on_offered_deadline_missed
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedDeadlineMissedStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_offered_incompatible_qos
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedIncompatibleQosStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_liveliness_lost
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_LivelinessLostStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_publication_matched
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_PublicationMatchedStatus *status);
```
```c
*/
/*
* inherited from DDS_SubscriberListener
*/
/* void
* DDS_DomainParticipantListener_on_data_on_readers
* (void *listener_data,
* DDS_Subscriber subs);
*/
/* void
* DDS_DomainParticipantListener_on_requested_deadline_missed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedDeadlineMissedStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_requested_incompatible_qos
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedIncompatibleQosStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_sample_rejected
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleRejectedStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_liveliness_changed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_LivelinessChangedStatus *status);
*/
/* void
* DDS_DomainParticipantListener_on_data_available
* (void *listener_data,
* DDS_DataReader reader);
*/
/* void
* DDS_DomainParticipantListener_on_subscription_matched
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SubscriptionMatchedStatus *status);
*/
```
```c
/* void
* DDS_DomainParticipantListener_on_sample_lost
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleLostStatus *status);
*/
/*
* implemented API operations
*/
struct DDS_DomainParticipantListener *
DDS_DomainParticipantListener_alloc
(void);
```
The next paragraphs list all DDS\_DomainParticipantListener operations. Since these operations are all inherited, they are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.2.4.1 DDS\_DomainParticipantListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DomainParticipantListener *
DDS_DomainParticipantListener__alloc
(void);
```
# Description
This operation creates a new DDS\_DomainParticipantListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_DomainParticipantListener \* - Return value is the handle to the newly-created DDS\_DomainParticipantListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_DomainParticipantListener. The DDS\_DomainParticipantListener must be created using this operation. In other words, the application is not allowed to declare an object of type DDS\_DomainParticipantListener. When the application wants to release the DDS\_DomainParticipantListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_DomainParticipantListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.2.4.2 DDS\_DomainParticipantListener\_on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_data_available
(void *listener_data,
DDS_DataReader reader);
```
# 3.2.4.3 DDS\_DomainParticipantListener\_on\_data\_on\_readers (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_SubscriberListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_data_on_readers
(void *listener_data,
DDS_Subscriber_subs);
```
# 3.2.4.4 DDS\_DomainParticipantListener\_on\_inconsistent\_topic (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_TopicListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_inconsistent_topic
(void *listener_data,
DDS_Topic the_topic,
const DDS_InconsistentTopicStatus *status);
```
# 3.2.4.5 DDS\_DomainParticipantListener\_on\_liveliness\_changed (inherited,
# abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_liveliness_changed
(void *listener_data,
DDS_DataReader reader,
const DDS_LivelinessChangedStatus *status);
```
# 3.2.4.6 DDS\_DomainParticipantListener\_on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_liveliness_lost
(void *listener_data,
DDS_DataWriter writer,
const DDS_LivelinessLostStatus *status);
```
# 3.2.4.7 DDS\_DomainParticipantListener\_on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
```c
Synopsis
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_offered_deadline_missed
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedDeadlineMissedStatus *status);
```
# 3.2.4.8 DDS\_DomainParticipantListener\_on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
```
```txt
void
DDS_DomainParticipantListener_on_offered_incompatible_qos
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedIncompatibleQosStatus *status);
```
# 3.2.4.9 DDS\_DomainParticipantListener\_on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_publication_matched
(void *listener_data,
DDS_DataWriter writer,
const DDS_PublicationMatchedStatus *status);
```
# 3.2.4.10 DDS\_DomainParticipantListener\_on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_requested_deadline_missed
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedDeadlineMissedStatus *status);
```
# 3.2.4.11 DDS\_DomainParticipantListener\_on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_requested_incompatible_qos
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedIncompatibleQosStatus *status);
```
# 3.2.4.12 DDS\_DomainParticipantListener\_on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_sample_lost
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleLostStatus *status);
```
# 3.2.4.13 DDS\_DomainParticipantListener\_on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_sample_rejected
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleRejectedStatus *status);
```
# 3.2.4.14 DDS\_DomainParticipantListener\_on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DomainParticipantListener_on_subscription_matched
(void *listener_data,
DDS_DataReader reader,
const DDS_SubscriptionMatchedStatus *status);
```
# 3.2.5 DDS\_ExtDomainParticipantListener interface
The ExtDomainParticipantListener interface is a subtype of both DomainParticipantListener and ExtTopicListener and thereby provides an additional OpenSplice-specific callback, on\_all\_disposed\_data, usable from the DomainParticipant.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The interface description of this class is as follows:
```c
/*
* interface DDS_ExtDomainParticipantListener
*/
/*
* inherited from DDS_TopicListener
*/
/* void
* DDS_ExtDomainParticipantListener_on_inconsistent_topic
* (void *listener_data,
* DDS_Topic the_topic,
* const DDS_InconsistentTopicStatus *status);
*/
/*
* inherited from DDS_ExtTopicListener
*/
/* void
* DDS_ExtDomainParticipantListener_on_all_data_disposed
* (void *listener_data,
* DDS_Topic the_topic);
*/
/*
* inherited from DDS_PublisherListener
*/
/* void
* DDS_ExtDomainParticipantListener_on_offered_deadline_missed
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedDeadlineMissedStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_offered_incompatible_qos
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedIncompatibleQosStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_liveliness_lost
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_LivelinessLostStatus *status);
*/
```
```c
/* void
* DDS_ExtDomainParticipantListener_on_publication_matched
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_PublicationMatchedStatus *status);
*/
/*
* inherited from DDS_SubscriberListener
*/
/* void
* DDS_ExtDomainParticipantListener_on_data_on_readers
* (void *listener_data,
* DDS_Subscriber subs);
*/
/* void
* DDS_ExtDomainParticipantListener_on_requested_deadline_missed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedDeadlineMissedStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_requested_incompatible_qos
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedIncompatibleQosStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_sample_rejected
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleRejectedStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_liveliness_changed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_LivelinessChangedStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_data_available
* (void *listener_data,
* DDS_DataReader reader);
*/
/* void
* DDS_ExtDomainParticipantListener_on_subscription_matched
```
```c
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SubscriptionMatchedStatus *status);
*/
/* void
* DDS_ExtDomainParticipantListener_on_sample_lost
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleLostStatus *status);
*/
/*
* implemented API operations
*/
struct DDS_ExtDomainParticipantListener *
DDS_ExtDomainParticipantListener__alloc
(void);
```
The following paragraphs list all ExtDomainParticipantListener operations. Since these operations are all inherited, they are listed but not fully described because they are not implemented in this class. The full descriptions of these operations are given in the classes from which they are inherited.
# 3.2.5.1 DDS\_ExtDomainParticipantListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_ExtDomainParticipantListener *
DDS_ExtDomainParticipantListener__alloc
(void);
```
# Description
This operation creates a new DDS\_ExtDomainParticipantListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_ExtDomainParticipantListener \* - Return value is the handle to the newly-created DDS\_ExtDomainParticipantListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_ExtDomainParticipantListener. The DDS\_ExtDomainParticipantListener must be created using this operation. In other words, the application is not allowed to declare an object of type
DDS\_ExtDomainParticipantListener. When the application wants to release the DDS\_ExtDomainParticipantListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_ExtDomainParticipantListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.2.5.2 DDS\_ExtDomainParticipantListener\_on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_data_available
(void *listener_data,
DDS_DataReader reader);
```
# 3.2.5.3 DDS\_ExtDomainParticipantListener\_on\_data\_on\_readers (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_SubscriberListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_data_on_readers
(void *listener_data,
DDS_Subscriber subs);
```
# 3.2.5.4 DDS\_ExtDomainParticipantListener\_on\_inconsistent\_topic (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_TopicListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_inconsistent_topic
(void *listener_data,
DDS_Topic the_topic,
const DDS_InconsistentTopicStatus *status);
```
# 3.2.5.5 DDS\_ExtDomainParticipantListener\_on\_liveliness\_changed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_liveliness_changed
(void *listener_data,
DDS_DataReader reader,
const DDS_LivelinessChangedStatus *status);
```
# 3.2.5.6 DDS\_ExtDomainParticipantListener\_on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_liveliness_lost
(void *listener_data,
DDS_DataWriter writer,
const DDS_LivelinessLostStatus *status);
```
# 3.2.5.7 DDS\_ExtDomainParticipantListener\_on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
```c
Synopsis
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_offered_deadline_missed
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedDeadlineMissedStatus *status);
```
# 3.2.5.8 DDS\_ExtDomainParticipantListener\_on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_offered_incompatible_qos
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedIncompatibleQosStatus *status);
```
# 3.2.5.9 DDS\_ExtDomainParticipantListener\_on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_publication_matched
(void *listener_data,
DDS_DataWriter writer,
const DDS_PublicationMatchedStatus *status);
```
# 3.2.5.10 DDS\_ExtDomainParticipantListener\_on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_requested_deadline_missed
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedDeadlineMissedStatus *status);
```
# 3.2.5.11 DDS\_ExtDomainParticipantListener\_on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_requested_incompatible_qos
(void *listener_data,
DDS_DataReader reader,
```
```javascript
const DDS_RequestedIncompatibleQosStatus *status);
```
# 3.2.5.12 DDS\_ExtDomainParticipantListener\_on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_sample_lost
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleLostStatus *status);
```
# 3.2.5.13 DDS\_ExtDomainParticipantListener\_on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_sample_rejected
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleRejectedStatus *status);
```
# 3.2.5.14 DDS\_ExtDomainParticipantListener\_on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_subscription_matched
(void *listener_data,
DDS_DataReader reader,
const DDS_SubscriptionMatchedStatus *status);
```
# 3.2.5.15 DDS\_ExtDomainParticipantListener\_on\_all\_data\_disposed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_ExtTopicListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtDomainParticipantListener_on_all_data_disposed
(DDS_Topic the_topic);
```
# 3.3 Topic-Definition Module
Figure 16: DCPS Topic-Definition Module Class Model
This module contains the following classes:
• DDS\_TopicDescription (abstract)
• DDS\_Topic
• DDS\_ContentFilteredTopic
• DDS\_MultiTopic
• DDS\_TopicListener (interface)
• Topic-Definition type specific classes.
“Topic-Definition type specific classes” contains the generic class and the generated data type specific classes. For each data type, a data type specific class <NameSpace>\_<type>TypeSupport is generated (based on IDL) by calling the pre-processor.
Figure 17: Pre-processor Generation of the Typed Classes for Data Type “Foo”
For instance, for the user-defined data type Foo (this also applies to other types), defined in the module SPACE; “Topic-Definition type specific classes” contains the following classes:
• DDS\_TypeSupport (abstract)
• SPACE\_FooTypeSupport.
DDS\_Topic objects conceptually fit between publications and subscriptions. Publications must be known in such a way that subscriptions can refer to them unambiguously. A DDS\_Topic is meant to fulfil that purpose: it associates a name (unique in the Domain), a data type, and DDS\_TopicQos related to the data itself.
# 3.3.1 Class DDS\_TopicDescription (abstract)
T h i s c l a s s i s a n a b s t r a c t c l a s s . I t i s t h e b a s e c l a s s f o r D D S \_ T o p i c , DDS\_ContentFilteredTopic and DDS\_MultiTopic.
The DDS\_TopicDescription attribute type\_name defines an unique data type that is made available to the Data Distribution Service via the DDS\_TypeSupport. DDS\_TopicDescription has also a name that allows it to be retrieved locally.
The interface description of this class is as follows:
```c
/*
* interface DDS_TopicDescription
*/
/*
* implemented API operations
*/
DDS_string
DDS_TopicDescription_get_type_name
(DDS_TopicDescription _this);
DDS_string
DDS_TopicDescription_get_name
(DDS_TopicDescription _this);
DDS_DomainParticipant
DDS_TopicDescription_get_participant
(DDS_TopicDescription _this);
```
The next paragraphs describe the usage of all DDS\_TopicDescription operations.
# 3.3.1.1 DDS\_TopicDescription\_get\_name
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_TopicDescription_get_name
(DDS_TopicDescription _this);
```
# Description
This operation returns the name used to create the DDS\_TopicDescription.
# Parameters
in DDS\_TopicDescription \_this - the DDS\_TopicDescription object on which the operation is operated.
# Return Value
DDS\_string - the name of the DDS\_TopicDescription.
# Detailed Description
This operation returns the name used to create the DDS\_TopicDescription.
# 3.3.1.2 DDS\_TopicDescription\_get\_participant
# Synopsis
```c
#include <dds_dcps.h>
```
```txt
DDS_DomainParticipant
DDS_TopicDescription_get_participant
(DDS_TopicDescription _this);
```
# Description
This operation returns the DDS\_DomainParticipant associated with the DDS\_TopicDescription or the DDS\_OBJECT\_NIL pointer.
# Parameters
in DDS\_TopicDescription \_this - the DDS\_TopicDescription object on which the operation is operated.
# Return Value
DDS\_DomainParticipant - a pointer to the DDS\_DomainParticipant associated with the DDS\_TopicDescription or the DDS\_OBJECT\_NIL pointer.
# Detailed Description
This operation returns the DDS\_DomainParticipant associated with the D D S\_ T o p i c D es c r i p t io n . N o t e t h a t t h e r e i s e x a c t l y o n e DDS\_DomainParticipant associated with each DDS\_TopicDescription. When the DDS\_TopicDescription was already deleted (there is no associated DDS\_DomainParticipant any more), the DDS\_OBJECT\_NIL pointer is returned.
# 3.3.1.3 DDS\_TopicDescription\_get\_type\_name
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_TopicDescription_get_type_name
(DDS_TopicDescription _this);
```
# Description
This operation returns the registered name of the data type associated with the DDS\_TopicDescription.
# Parameters
in DDS\_TopicDescription \_this - the DDS\_TopicDescription object on which the operation is operated.
# Return Value
D D S \_ s t r i n g - r e t u r n v a l u e i s t h e n a m e o f t h e d a t a t y p e o f t h e DDS\_TopicDescription.
# Detailed Description
This operation returns the registered name of the data type associated with the DDS\_TopicDescription.
# 3.3.2 Class DDS\_Topic
DDS\_Topic is the most basic description of the data to be published and subscribed.
A DDS\_Topic is identified by its name, which must be unique in the whole Domain. In addition (by virtue of extending DDS\_TopicDescription) it fully identifies the type of data that can be communicated when publishing or subscribing to the DDS\_Topic.
DDS\_Topic is the only DDS\_TopicDescription that can be used for publications and therefore a specialized DDS\_DataWriter is associated to the DDS\_Topic.
The interface description of this class is as follows:
```c
/*
* interface DDS_Topic
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_Topic_get_statuscondition
* (DDS_Topic _this);
*/
/* DDS_StatusMask
* DDS_Topic_get_status_changes
* (DDS_Topic _this);
*/
/* DDS_ReturnCode_t
* DDS_Topic_enable
* (DDS_Topic _this);
*/
/*
* inherited from class DDS_TopicDescription
*/
/* DDS_string
* DDS_Topic_get_type_name
* (DDS_Topic _this);
*/
/* DDS_string
* DDS_Topic_get_name
* (DDS_Topic _this);
*/
/* DDS_DomainParticipant
```
```c
* DDS_Topic_get_participant
* (DDS_Topic _this);
*/
/*
* implemented API operations
*/
DDS_ReturnCode_t
DDS_Topic_set_qos
(DDS_Topic _this,
const DDS_TopicQos *qos);
DDS_ReturnCode_t
DDS_Topic_get_qos
(DDS_Topic _this,
DDS_TopicQos *qos);
DDS_ReturnCode_t
DDS_Topic_set_listener
(DDS_Topic _this,
const struct DDS_TopicListener *a_listener,
const DDS_StatusMask mask);
struct DDS_TopicListener
DDS_Topic_get_listener
(DDS_Topic _this);
DDS_ReturnCode_t
DDS_Topic_get_inconsistent_topic_status
(DDS_Topic _this,
DDS_InconsistentTopicStatus *a_status);
DDS_ReturnCode_t dispose_all_data();
```
The next paragraphs describe the usage of all DDS\_Topic operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.3.2.1 DDS\_Topic\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Topic_enable
(DDS_Topic _this);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.2.2 DDS\_Topic\_get\_inconsistent\_topic\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Topic_get_inconsistent_topic_status
(DDS_Topic _this,
DDS_InconsistentTopicStatus *a_status);
```
# Description
This operation obtains the DDS\_InconsistentTopicStatus of the DDS\_Topic.
# Parameters
in DDS\_Topic \_this - the DDS\_Topic object on which the operation is operated.
inout DDS\_InconsistentTopicStatus \*a\_status - the contents of the DDS\_InconsistentTopicStatus struct of the DDS\_Topic will be copied into the location specified by a\_status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_InconsistentTopicStatus of the DDS\_Topic. The DDS\_InconsistentTopicStatus can also be monitored using a DDS\_TopicListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_InconsistentTopicStatus of this DDS\_Topic has successfully been copied into the specified a\_status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Topic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.3 DDS\_Topic\_get\_listener
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_TopicListener
DDS_Topic_get_listener
(DDS_Topic _this);
```
# Description
This operation allows access to a DDS\_TopicListener.
# Parameters
in DDS\_Topic \_this - the DDS\_Topic object on which the operation is operated.
# Return Value
struct DDS\_TopicListener - to the DDS\_TopicListener attached to the DDS\_Topic.
# Detailed Description
This operation allows access to a DDS\_TopicListener attached to the DDS\_Topic. When no DDS\_TopicListener was attached to the DDS\_Topic, the DDS\_OBJECT\_NIL pointer is returned.
# 3.3.2.4 DDS\_Topic\_get\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_Topic_get_name
(DDS_Topic _this);
```
# 3.3.2.5 DDS\_Topic\_get\_participant (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_Topic_get_participant
(DDS_Topic_this);
```
# 3.3.2.6 DDS\_Topic\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Topic_get_qos
(DDS_Topic_this,
DDS_TopicQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DDS\_Topic.
# Parameters
in DDS\_Topic \_this - the DDS\_Topic object on which the operation is operated.
inout DDS\_TopicQos \*qos - a pointer to the destination DDS\_TopicQos struct in which the QosPolicy settings will be copied.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DDS\_Topic on which this operation is used. This DDS\_TopicQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_Topic has successfully been copied into the specified DDS\_TopicQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Topic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.7 DDS\_Topic\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_Topic_get_status_changes
(DDS_Topic _this);
```
# 3.3.2.8 DDS\_Topic\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_Topic_get_statuscondition
(DDS_Topic_this);
```
# 3.3.2.9 DDS\_Topic\_get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_Topic_get_type_name
(DDS_Topic _this);
```
# 3.3.2.10 DDS\_Topic\_set\_listener
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Topic_set_listener
(DDS_Topic _this,
const struct DDS_TopicListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation attaches a DDS\_TopicListener to the DDS\_Topic.
# Parameters
in DDS\_Topic \_this - the DDS\_Topic object on which the operation is operated.
in const struct DDS\_TopicListener \*a\_listener - a pointer to the DDS\_TopicListener instance, which will be attached to the DDS\_Topic.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_TopicListener for a certain status.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a DDS\_TopicListener to the DDS\_Topic. Only one D D S\_ T o p i c Li s t e n e r c an b e a t t a c h e d t o e a c h DD S \_ T o p i c. I f a DDS\_TopicListener was already attached, the operation will replace it with the new one. When a\_listener is the DDS\_OBJECT\_NIL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bitmask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that plain communication status changes. For each plain communication status activated in the mask, the associated DDS\_TopicListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get\_<status\_name> from inside the listener it will see the status already reset. An exception to this rule is the DDS\_OBJECT\_NIL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DDS\_TopicListener:
• DDS\_INCONSISTENT\_TOPIC\_STATUS.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
In case a communication status is not activated in the m a sk of the DDS\_TopicListener, the DDS\_DomainParticipantListener of the containing DDS\_DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant and a DDS\_Topic specific behaviour when needed. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_TopicListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Topic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.11 DDS\_Topic\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Topic_set_qos
(DDS_Topic _this,
const DDS_TopicQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_Topic.
# Parameters
in DDS\_Topic \_this - the DDS\_Topic object on which the operation is operated.
in const DDS\_TopicQos \*qos - new set of QosPolicy settings for the DDS\_Topic.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES, DDS\_RETCODE\_IMMUTABLE\_POLICY or DDS\_RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This replaces the existing set of QosPolicy settings for a DDS\_Topic. The parameter qos must contain the struct with the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_Topic, which can only be set before the D D S \_ T o p i c i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the currently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a DDS\_RETCODE\_INCONSISTENT\_POLICY is returned.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_TopicQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_TopicQos. It contains a QosPolicy setting with an invalid DDS\_Duration\_t value, an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Topic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DDS\_Topic.
• DDS\_RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.3.2.12 DDS\_Topic\_dispose\_all\_data
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t dispose_all_data();
```
# Description
This operation allows the application to dispose of all of the instances for a particular topic without the network overhead of using a separate dispose call for each instance.
# Parameters
```txt
<none>
```
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are:
DDS_RETCODE_OK, DDS_RETCODE_ERROR,
DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_ALREADY_DELETED,
DDS_RETCODE_NOT_ENABLED.
```
# DetailedDescription
This operation allows the application to dispose of all of the instances for a particular topic without the network overhead of using a separate dispose call for each instance. Its effect is equivalent to invoking a separate dispose operation for each individual instance on the DataWriter that owns it. (See the description of FooDataWriter.dispose in Section 3.4.2.33, SPACE\_FooDataWriter\_dispose, on page 349.)
(The dispose\_all\_data is an asynchronous C&M operation that is not part of a coherent update; it operates on the DataReaders history cache and not on the incomplete transactions. The dispose\_all\_data is effectuated as soon as a transaction becomes complete and is inserted into the DataReaders history cache; at that point messages will be inserted according to the destination\_order qos p o l ic y. F or B Y \_ S OU R C E \_ T IM E S T A M P all messa ges olde r than the dispose\_all\_data will be disposed and all newer will be alive; for BY\_RECEPTION\_TIMESTAMP all messages will be alive if the transaction is completed after receiving the dispose\_all\_data command.)
This operation only sets the instance state of the instances concerned to NOT\_ALIVE\_DISPOSED. It does not unregister the instances, and so does not automatically clean up the memory that is claimed by the instances in both the DataReaders and DataWriters.
# Blocking
The blocking (or nonblocking) behaviour of this call is undefined.
# Concurrency
If there are subsequent calls to this function before the action has been completed (completion of the disposes on all nodes, not simply return from the function), then the behaviour is undefined.
# Other notes
The effect of this call on disposed\_generation\_count, generation\_rank and absolute\_generation\_rank is undefined.
# Return Code
• DDS\_RETCODE\_OK - a request to dispose the topic has been sucessfully queued.
• DDS\_RETCODE\_ERROR - and internal error has occured.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_ALREADY\_DELETED - the topic has already been deleted.
• DDS\_RETCODE\_NOT\_ENABLED - the topic is not enabled.
# 3.3.3 Class DDS\_ContentFilteredTopic
DDS\_ContentFilteredTopic is a specialization of DDS\_TopicDescription that allows for content based subscriptions.
DDS\_ContentFilteredTopic describes a more sophisticated subscription that indicates the DDS\_Subscriber does not necessarily want to see all values of each instance published under the DDS\_Topic. Rather, it only wants to see the values whose contents satisfy certain criteria. Therefore this class must be used to request content-based subscriptions.
The selection of the content is done using the SQL based filter with parameters to adapt the filter clause.
Appendix H, DCPS Queries and Filters describes the syntax of the SQL based filter and the parameters.
The interface description of this class is as follows:
```c
/*
* interface DDS_ContentFilteredTopic
*/
/*
* inherited from class DDS_TopicDescription
*/
/* DDS_string
* DDS_ContentFilteredTopic_get_type_name
* (DDS_ContentFilteredTopic _this);
*/
/* DDS_string
* DDS_ContentFilteredTopic_get_name
* (DDS_ContentFilteredTopic _this);
*/
/* DDS_DomainParticipant
* DDS_ContentFilteredTopic_get_participant
* (DDS_ContentFilteredTopic _this);
*/
/*
* implemented API operations
*/
DDS_string
DDS_ContentFilteredTopic_get_filter_expression
(DDS_ContentFilteredTopic _this);
DDS_ReturnCode_t
DDS_ContentFilteredTopic_get_expression_parameters
(DDS_ContentFilteredTopic _this,
DDS_StringSeq *expression_parameters);
DDS_ReturnCode_t
DDS_ContentFilteredTopic_set_expression_parameters
(DDS_ContentFilteredTopic _this,
const DDS_StringSeq *expression_parameters);
DDS_Topic
DDS_ContentFilteredTopic_get_related_topic
(DDS_ContentFilteredTopic _this);
*/
```
The next paragraphs describe the usage of all DDS\_ContentFilteredTopic operations.
# 3.3.3.1 DDS\_ContentFilteredTopic\_get\_expression\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ContentFilteredTopic_get_expression_parameters
(DDS_ContentFilteredTopic _this,
DDS_StringSeq *expression_parameters);
```
# Description
This operation obtains the expression parameters associated with the DDS\_ContentFilteredTopic.
# Parameters
```txt
in DDS_ContentFilteredTopic _this - the DDS_ContentFilteredTopic object on which the operation is operated.
```
inout DDS\_StringSeq \*expression\_parameters - a handle to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation obtains the expression parameters associated with the DDS\_ContentFilteredTopic. That is, the parameters specified on the last successful call to DDS\_ContentFilteredTopic\_set\_expression\_ parameters, or if DDS\_ContentFilteredTopic\_set\_expression\_ p a r a m e t e r s w a s n e v e r c a l l e d , t h e p a r a m e t e r s s p e c i f i e d w h e n t h e DDS\_ContentFilteredTopic was created.
The resulting handle contains a sequence of strings with the parameters used in the SQL expression (i.e., the %n tokens in the expression). The number of parameters in the result sequence will exactly match the number of %n tokens in the filter expression associated with the DDS\_ContentFilteredTopic.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of expression parameters applied to this DDS\_ContentFilteredTopic has successfully been copied into the specified expression\_parameters parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_ContentFilteredTopic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.3.2 DDS\_ContentFilteredTopic\_get\_filter\_expression
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_ContentFilteredTopic_get_filter_expression
(DDS_ContentFilteredTopic_this);
```
# Description
This operation returns the filter\_expression associated with the DDS\_ContentFilteredTopic.
# Parameters
in DDS\_ContentFilteredTopic \_this - the DDS\_ContentFilteredTopic object on which the operation is operated.
# Return Value
DDS\_string - result is a handle to a string which holds the SQL filter expression.
# Detailed Description
This operation returns the filter\_expression associated with the DDS\_ContentFilteredTopic. That is, the expression specified when the DDS\_ContentFilteredTopic was created.
The filter expression result is a string that specifies the criteria to select the data samples of interest. It is similar to the WHERE clause of an SQL expression.
# 3.3.3.3 DDS\_ContentFilteredTopic\_get\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_ContentFilteredTopic_get_name
(DDS_ContentFilteredTopic _this);
```
# 3.3.3.4 DDS\_ContentFilteredTopic\_get\_participant (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_ContentFilteredTopic_get_participant
(DDS_ContentFilteredTopic _this);
```
# 3.3.3.5 DDS\_ContentFilteredTopic\_get\_related\_topic
# Synopsis
```c
#include <dds_dcps.h>
DDS_Topic
DDS_ContentFilteredTopic_get_related_topic
(DDS_ContentFilteredTopic _this);
```
# Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ T o p i c a s s o c i a t e d w i t h t h e DDS\_ContentFilteredTopic.
# Parameters
in DDS\_ContentFilteredTopic \_this - the DDS\_ContentFilteredTopic object on which the operation is operated.
# Return Value
DDS\_Topic - result is a handle to the base topic on which the filtering will be applied.
# Detailed Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ T o p i c a s s o c i a t e d w i t h t h e DDS\_ContentFilteredTopic. That is, the DDS\_Topic specified when the DDS\_ContentFilteredTopic was created. This DDS\_Topic is the base topic on which the filtering will be applied.
# 3.3.3.6 DDS\_ContentFilteredTopic\_get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_ContentFilteredTopic_get_type_name
(DDS_ContentFilteredTopic _this);
```
# 3.3.3.7 DDS\_ContentFilteredTopic\_set\_expression\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_ContentFilteredTopic_set_expression_parameters
(DDS_ContentFilteredTopic _this,
const DDS_StringSeq *expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4 Class DDS\_MultiTopic
DDS\_MultiTopic is a specialization of DDS\_TopicDescription that allows subscriptions to combine, filter and/or rearrange data coming from several DDS\_Topics.
DDS\_MultiTopic allows a more sophisticated subscription that can select and combine data received from multiple DDS\_Topics into a single data type (specified by the inherited type\_name). The data will then be filtered (selection) and possibly re-arranged (aggregation and/or projection) according to an SQL expression with parameters to adapt the filter clause.
The interface description of this class is as follows:
```c
/*
* interface DDS_MultiTopic
*/
/*
* inherited from class DDS_TopicDescription
*/
/* DDS_string
* DDS_MultiTopic_get_type_name
* (DDS_MultiTopic _this);
*/
/* DDS_string
* DDS_MultiTopic_get_name
* (DDS_MultiTopic _this);
*/
```
```c
/* DDS_DomainParticipant
* DDS_MultiTopic_get_participant
* (DDS_MultiTopic _this);
*/
/*
* implemented API operations
*/
DDS_string
DDS_MultiTopic_get Subscription_expression
(DDS_MultiTopic _this);
DDS_ReturnCode_t
DDS_MultiTopic_get_expression_parameters
(DDS_MultiTopic _this,
DDS_StringSeq *expression_parameters);
DDS_ReturnCode_t
DDS_MultiTopic_set_expression_parameters
(DDS_MultiTopic _this,
const DDS_StringSeq *expression_parameters);
```
The next paragraphs describe the usage of all DDS\_MultiTopic operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
NOTE: DDS\_MultiTopic operations have not been yet been implemented. Multitopic functionality is scheduled for a future release.
# 3.3.4.1 DDS\_MultiTopic\_get\_expression\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_MultiTopic_get_expression_parameters
(DDS_MultiTopic _this,
DDS_StringSeq *expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation returns the expression parameters associated with the DDS\_MultiTopic.
# Parameters
in DDS\_MultiTopic \_this - the DDS\_MultiTopic object on which the operation is operated.
inout DDS\_StringSeq \*expression\_parameters - a handle to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the expression parameters associated with the DDS\_MultiTopic. That is, the parameters specified on the last successful call to DDS\_MultiTopic\_set\_expression\_parameters, o r i f DDS\_MultiTopic\_set\_expression\_parameters was never called, the parameters specified when the DDS\_MultiTopic was created.
The resulting handle contains a sequence of strings with the values of the parameters used in the SQL expression (i.e., the %n tokens in the expression). The number of parameters in the result sequence will exactly match the number of %n tokens in the filter expression associated with the DDS\_MultiTopic.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of expression parameters applied to this DDS\_MultiTopic has successfully been copied into the specified expression\_parameters parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_MultiTopic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.4.2 DDS\_MultiTopic\_get\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
#include <dds\_dcps.h> DDS\_string
```txt
DDS_MultiTopic_get_name
(DDS_MultiTopic_this);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.3 DDS\_MultiTopic\_get\_participant (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_MultiTopic_get_participant
(DDS_MultiTopic_this);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.4 DDS\_MultiTopic\_get\_subscription\_expression
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_MultiTopic_get Subscription_expression
(DDS_MultiTopic _this);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation returns the subscription expression associated with the DDS\_MultiTopic.
# Parameters
in DDS\_MultiTopic \_this - is the DDS\_MultiTopic object on which the operation is operated.
# Return Value
DDS\_string - a handle to a string which holds the SQL subscription expression.
# Detailed Description
This operation returns the subscription expression associated with the DDS\_MultiTopic. That is, the expression specified when the DDS\_MultiTopic was created.
The subscription expression result is a string that specifies the criteria to select the data samples of interest. In other words, it identifies the selection and rearrangement of data from the associated DDS\_Topics. It is an SQL expression where the
SELECT clause provides the fields to be kept, the FROM part provides the names of the DDS\_Topics that are searched for those fields, and the WHERE clause gives the content filter. The DDS\_Topics combined may have different types but they are restricted in that the type of the fields used for the NATURAL JOIN operation must be the same.
# 3.3.4.5 DDS\_MultiTopic\_get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class DDS\_TopicDescription for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_MultiTopic_get_type_name
(DDS_MultiTopic _this);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.6 DDS\_MultiTopic\_set\_expression\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_MultiTopic_set_expression_parameters
(DDS_MultiTopic _this,
const DDS_StringSeq *expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation changes the expression parameters associated with the DDS\_MultiTopic.
# Parameters
in DDS\_MultiTopic \_this - the DDS\_MultiTopic object on which the operation is operated.
in const DDS\_StringSeq \*expression\_parameters - the handle to a sequence of strings with the parameters used in the SQL expression.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation changes the expression parameters associated with the DDS\_MultiTopic. The parameter expression\_parameters is a handle to a sequence of strings with the parameters used in the SQL expression. The number of parameters in expression\_parameters must exactly match the number of %n tokens in the subscription expression associated with the DDS\_MultiTopic. This is the subscription expression specified when the DDS\_MultiTopic was created.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new expression parameters are set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the number of parameters in expression\_parameters does not match the number of “%n” tokens in the expression for this DDS\_MultiTopic or one of the parameters is an illegal parameter.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_MultiTopic has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.5 DDS\_TopicListener Interface
Since a DDS\_Topic is a DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_TopicListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DDS\_TopicListener class. All DDS\_TopicListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
NOTE: All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The DDS\_TopicListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as an inconsistent DDS\_Topic. The DDS\_TopicListener is related to changes in communication status.
The interface description of this class is as follows:
```c
/*
* interface DDS_TopicListener
*/
/*
* abstract external operations
*/
/* void
* DDS_TopicListener_on_inconsistent_topic
* (void *listener_data,
* DDS_Topic the_topic,
* const DDS_InconsistentTopicStatus *status);
*/
/*
* implemented API operations
*/
struct DDS_TopicListener *
DDS_TopicListener__alloc
(void);
```
The next paragraph describes the usage of the DDS\_TopicListener operation. This abstract operation is fully described since it must be implemented by the application.
# 3.3.5.1 DDS\_TopicListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_TopicListener *
DDS_TopicListener__alloc
(void);
```
# Description
This operation creates a new DDS\_TopicListener.
# Parameters
```txt
<none>
```
# Return Value
DDS\_TopicListener - the handle to the newly-created DDS\_TopicListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_TopicListener. The DDS\_TopicListener must be created using this operation. In other words, the application is not allowed to declare an object of type DDS\_TopicListener. When the application wants to release the DDS\_TopicListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_TopicListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.3.5.2 DDS\_TopicListener\_on\_inconsistent\_topic (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_TopicListener_on_inconsistent_topic
(void *listener_data,
DDS_Topic the_topic,
const DDS_InconsistentTopicStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the DDS\_InconsistentTopicStatus changes.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_Topic the\_topic - a pointer to the DDS\_Topic on which the conflict occurred (this is an input to the application).
in const DDS\_InconsistentTopicStatus \*status - the DDS\_InconsistentTopicStatus struct (this is an input to the application).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the DDS\_InconsistentTopicStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when th e relevant D DS \_ To p ic Li s te n er is installed and enabled for the
DDS\_InconsistentTopicStatus. The DDS\_InconsistentTopicStatus will change when another DDS\_Topic exists with the same topic\_name but different characteristics.
The Data Distribution Service will call the DDS\_TopicListener operation with a parameter the\_topic, which will contain a pointer to the DDS\_Topic on which the conflict occurred and a parameter status, which will contain the DDS\_InconsistentTopicStatus struct.
# 3.3.6 DDS\_ExtTopicListener interface
The DDS\_ExtTopicListener interface is a subtype of DDS\_TopicListener and provides an OpenSplice-specific callback on\_all\_disposed\_data.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The interface description of this class is as follows:
```c
/*
* interface DDS_ExtTopicListener
*/
/*
* inherited from DDS_TopicListener
*/
/* void
* DDS_ExtTopicListener_on_inconsistent_topic
* (void *listener_data,
* DDS_Topic the_topic,
* const DDS_InconsistentTopicStatus);
*/
/*
* abstract external operations
*/
/* void
* DDS_ExtTopicListener_on_all_data_disposed
* (void *listener_data,
* DDS_Topic the_topic);
*/
/*
* implemented API operations
*/
struct DDS_ExtTopicListener *
DDS_ExtTopicListener_alloc
(void);
```
# 3.3.6.1 DDS\_ExtTopicListener\_on\_all\_data\_disposed (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_ExtTopicListener_on_all_data_disposed(void *listener_data, DDS_Topic_the_topic);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the node has completed disposal of data as a result of a call to DDS\_Topic\_dispose\_all\_data().
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_Topic the\_topic - contains a pointer to the Topic which has been disposed.
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the node has c o m p l e t e d d i s p o s a l o f d a t a a s a r e s u l t o f a c a l l t o DDS\_Topic\_dispose\_all\_data().
The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant ExtTopicListener is installed.
# Concurrency
The threading behaviour of calls to this method are undefined, so:
• Subsequent disposal via DDS\_Topic\_dispose\_all\_data(), and the associated callbacks may be blocked until this method returns.
• This method may be called concurrently by OpenSplice if other DDS\_Topic\_dispose\_all\_data() operations complete before this method returns.
# 3.3.7 Topic-Definition Type Specific Classes
This paragraph describes the generic DDS\_TypeSupport class and the derived application type specific <NameSpace>\_<type>TypeSupport classes which together implement the application DDS\_Topic interface. For each application type, u s e d a s D D S \_ T o p i c d a t a t y p e , t h e p r e - p r o c e s s o r g e n e r a t e s a <NameSpace>\_<type>DataReader class from an IDL type description. The SPACE\_FooTypeSupport class that would be generated by the pre-processor for a f i c t i o n a l t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e s c r i b e s t h e <NameSpace>\_<type>TypeSupport classes.
# 3.3.7.1 Class DDS\_TypeSupport (abstract)
The DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic is bound to a data type described by the type name argument. Prior to creating a DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic, the data type must have been registered with the Data Distribution Service. This is done using the data type specific DDS\_TypeSupport\_register\_type operation on a derived class of the DDS\_TypeSupport interface. A derived class is generated for each data type used by the application, by calling the pre-processor.
The interface description of this class is as follows:
```c
/*
* interface DDS_TypeSupport
*/
/*
* abstract operations
*/
/* DDS_TypeSupport
* DDS_TypeSupport_alloc
* (void);
*/
/* DDS_ReturnCode_t
* DDS_TypeSupport_register_type
* (DDS_TypeSupport _this,
* Domainparticipant domain,
* DDS_string type_name);
*
* DDS_string
* DDS_TypeSupport_get_type_name
* (DDS_TypeSupport _this);
*/
/*
* implemented API operations
* <no operations>
*/
```
The next paragraph list the DDS\_TypeSupport operation. This abstract operation is listed but not fully described since it is not implemented in this class. The full description of this operation is given in the SPACE\_FooTypeSupport class (for the data type example Foo), which contains the data type specific implementation of this operation.
# 3.3.7.2 DDS\_TypeSupport\_\_alloc (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>TypeSupport class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooTypeSupport class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_TypeSupport
DDS_TypeSupport_alloc
(void);
```
# 3.3.7.3 DDS\_TypeSupport\_get\_type\_name (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>TypeSupport class. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooTypeSupport class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_TypeSupport_get_type_name
(DDS_TypeSupport _this);
```
# 3.3.7.4 DDS\_TypeSupport\_register\_type (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>TypeSupport class. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooTypeSupport class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_TypeSupport_register_type
(DDS_TypeSupport _this,
Domainparticipant domain,
DDS_string type_name);
```
# 3.3.7.5 Class SPACE\_FooTypeSupport
The pre-processor generates from IDL type descriptions the application <NameSpace>\_<type>TypeSupport classes. For each application data type that i s u s e d a s D D S \_ T o p i c d a t a t y p e , a t y p e d c l a s s <NameSpace>\_<type>TypeSupport is derived from the DDS\_TypeSupport class. In this paragraph, the class SPACE\_FooTypeSupport describes the operations of these derived <NameSpace>\_<type>TypeSupport classes as an example for the fictional application type Foo (defined in the module SPACE).
For instance, for an application, the definitions are located in the Space.idl file. The pre-processor will generate a Space.h include file.
The DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic is bound to a data type described by the type type\_name argument. Prior to creating a DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic, the data type must have been registered with the Data Distribution Service. This is done using the data type specific SPACE\_FooTypeSupport\_register\_type operation on the <NameSpace>\_<type>TypeSupport class for each data type. A derived class is generated for each data type used by the application, by calling the pre-processor.
The interface description of this class is as follows:
```c
/*
* interface SPACE_FooTypeSupport
*/
/*
* implemented API operations
*/
SPACE_FooTypeSupport
SPACE_FooTypeSupport_alloc
(void);
DDS_ReturnCode_t
SPACE_FooTypeSupport_register_type
(SPACE_FooTypeSupport _this,
DDS_DomainParticipant domain,
DDS_string type_name);
DDS_string
SPACE_FooTypeSupport_get_type_name
(SPACE_FooTypeSupport _this);
```
The next paragraph describes the usage of the SPACE\_FooTypeSupport operations.
# 3.3.7.6 SPACE\_FooTypeSupport\_\_alloc
# Synopsis
```txt
#include <Space.h>
SPACE_FooTypeSupport
```
```txt
SPACE_FooTypeSupport_alloc (void);
```
# Description
This operation creates a new SPACE\_FooTypeSupport.
# Parameters
```txt
<none>
```
# Return Value
S P AC E \_ F o o Ty p e S u p p or t - t h e h a n d l e t o t h e n e w l y - c r e a t e d SPACE\_FooTypeSupport. In case of an error, a nil pointer is returned.
# Detailed Description
T h i s o p e r a t i o n c r e at e s a n e w S P AC E \_ F o o T yp e S u p p or t . T h e SPACE\_FooTypeSupport must be created using this operation. In other words, the application is not allowed to declare an object of type SPACE\_FooTypeSupport. When the application wants to release the SPACE\_FooTypeSupport it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e SPACE\_FooTypeSupport, a nil pointer is returned instead.
# 3.3.7.7 SPACE\_FooTypeSupport\_get\_type\_name
# Synopsis
```c
#include <Space.h>
DDS_string
SPACE_FooTypeSupport_get_type_name
(SPACE_FooTypeSupport _this);
```
# Description
This operation returns the default name of the data type associated with the SPACE\_FooTypeSupport.
# Parameters
in SPACE\_FooTypeSupport \_this - the SPACE\_FooTypeSupport object on which the operation is operated.
# Return Value
DDS\_string - the name of the data type of the SPACE\_FooTypeSupport.
# Detailed Description
This operation returns the default name of the data type associated with the SPACE\_FooTypeSupport. The default name is derived from the type name as specified in the IDL definition. It is composed of the scope names and the type name, each separated by “::”, in order of lower scope level to deeper scope level followed by the type name.
# 3.3.7.8 SPACE\_FooTypeSupport\_register\_type
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooTypeSupport_register_type
(SPACE_FooTypeSupport _this,
DDS_DomainParticipant domain,
DDS_string type_name);
```
# Description
This operation registers a new data type name to a DDS\_DomainParticipant.
# Parameters
in SPACE\_FooTypeSupport \_this - the SPACE\_FooTypeSupport object on which the operation is operated.
in DDS\_DomainParticipant domain - a pointer to a DDS\_DomainParticipant object to which the new data type is registered.
in DDS\_string type\_name - a local alias of the new data type to be registered.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation registers a new data type name to a DDS\_DomainParticipant. This operation informs the Data Distribution Service, in order to allow it to manage the new registered data type. This operation also informs the Data Distribution Service about the key definition, which allows the Data Distribution Service to distinguish different instances of the same data type.
# Precondition
A t y p e \_ n a m e c a n n o t b e r e g i s t e r e d w i t h t w o d i ff e r e n t <NameSpace>\_<type>TypeSupport classes (this means of a different data type) with the same DDS\_DomainParticipant. When the operation is called on the same DDS\_DomainParticipant with the same type\_name for a different <NameSpace>\_<type>TypeSupport class, the operation returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET. However, it is possible to register the same <NameSpace>\_<type>TypeSupport classes with the same DDS\_DomainParticipant and the same or different type\_name multiple times. All registrations return DDS\_RETCODE\_OK, but any subsequent registrations with the same type\_name are ignored.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the SPACE\_FooTypeSupport class is registered with the new data type name to the DDS\_DomainParticipant or the SPACE\_FooTypeSupport class was already registered.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - one or both of the parameters is invalid, the domain parameter is the DDS\_OBJECT\_NIL pointer, or the parameter type\_name has zero length.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - this type\_name is already registered with this DDS\_DomainParticipant for a different <NameSpace>\_<type>TypeSupport class.
# 3.4 Publication Module
Figure 18: The DCPS Publication Module’s Class Model
This module contains the following classes:
• DDS\_Publisher
• Publication type specific classes
• DDS\_PublisherListener (interface)
• DDS\_DataWriterListener (interface).
The paragraph “Publication type specific classes” contains the generic class and the generated data type specific classes. For each data type, a data type specific class <NameSpace>\_<type>DataWriter is generated (based on IDL) by calling the pre-processor.
For instance, for the fictional data type Foo (this also applies to other types), defined in the module SPACE; “Publication type specific classes” contains the following classes:
• DDS\_DataWriter (abstract)
• SPACE\_FooDataWriter.
A DDS\_Publisher is an object responsible for data distribution. It may publish data of different data types. A DDS\_DataWriter acts as a typed accessor to a DDS\_Publisher. The DDS\_DataWriter is the object the application must use to communicate the existence and value of data-objects of a given data type to a DDS\_Publisher. When data-object values have been communicated to the DDS\_Publisher through the appropriate DDS\_DataWriter, it is the DD S \_P u bl i sh er ’ s responsibility to perform th e distribu tion. The DDS\_Publisher will do this according to its own DDS\_PublisherQos, and the DDS\_DataWriterQos attached to the corresponding DDS\_DataWriter. A publication is defined by the association of a DDS\_DataWriter to a DDS\_Publisher. This association expresses the intent of the application to publish the data described by the DDS\_DataWriter in the context provided by the DDS\_Publisher.
# 3.4.1 Class DDS\_Publisher
The DDS\_Publisher acts on behalf of one or more DDS\_DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DDS\_DataWriter objects, it decides when it is appropriate to actually process the s a m p l e - u p d a t e m e s s a g e . I n m a k i n g t h i s d e c i s i o n , i t c o n s i d e r s t h e DDS\_PublisherQos and the DDS\_DataWriterQos.
The interface description of this class is as follows:
```c
/*
* interface DDS_Publisher
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_Publisher_get_statuscondition
* (DDS_Publisher _this);
*/
/* DDS_StatusMask
* DDS_Publisher_get_status_changes
* (DDS_Publisher _this);
*/
/* DDS_ReturnCode_t
* DDS_Publisher_enable
* (DDS_Publisher _this);
*/
/*
* implemented API operations
*/
DDS_DataWriter
DDS_Publisher_create_datawriter
```
```c
(DDS_Publisher _this,
const DDS_Topic a_topic,
const DDS_DataWriterQos *qos,
const struct DDS_DataWriterListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_Publisher_delete_datawriter
(DDS_Publisher _this,
const DDS_DataWriter a_datawriter);
DDS_DataWriter
DDS_Publisher_lookup_datawriter
(DDS_Publisher _this,
const DDS_char *topic_name);
DDS_ReturnCode_t
DDS_Publisher_delete_contained_entities
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_set_qos
(DDS_Publisher _this,
const DDS_PublisherQos *qos);
DDS_ReturnCode_t
DDS_Publisher_get_qos
(DDS_Publisher _this,
DDS_PublisherQos *qos);
DDS_ReturnCode_t
DDS_Publisher_set_listener
(DDS_Publisher _this,
const struct DDS_PublisherListener *a_listener,
const DDS_StatusMask mask);
struct DDS_PublisherListener
DDS_Publisher_get_listener
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_suspend_publications
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_resume_publications
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_begin_coherent_changes
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_end_coherent_changes
(DDS_Publisher _this);
```
```c
DDS_ReturnCode_t
DDS_Publisher_wait_for_acknowledgments
(DDS_Publisher _this,
const DDS_Duration_t *max_wait);
DDS_DomainParticipant
DDS_Publisher_get_participant
(DDS_Publisher _this);
DDS_ReturnCode_t
DDS_Publisher_set_default_datawriter_qos
(DDS_Publisher _this,
const DDS_DataWriterQos *qos);
DDS_ReturnCode_t
DDS_Publisher_get_default_datawriter_qos
(DDS_Publisher _this,
DDS_DataWriterQos *qos);
DDS_ReturnCode_t
DDS_Publisher_copy_from_topic_qos
(DDS_Publisher _this,
DDS_DataWriterQos *a_datawriter_qos,
const DDS_TopicQos *a_topic_qos);
```
The following paragraphs describe the usage of all DDS\_Publisher operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.4.1.1 DDS\_Publisher\_begin\_coherent\_changes
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_begin_coherent_changes
(DDS_Publisher _this);
```
# Description
This operation requests that the application will begin a ‘coherent set’ of modifications using DDS\_DataWriter objects attached to this DDS\_Publisher. The ‘coherent set’ will be completed by a matching call to DDS\_Publisher\_ end\_coherent\_changes.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation requests that the application will begin a ‘coherent set’ of modifications using DDS\_DataWriter objects attached to this DDS\_Publisher. The ‘coherent set’ will be completed by a matching call to DDS\_Publisher\_ end\_coherent\_changes.
A ‘coherent set’ is a set of modifications that must be propagated in such a way that they are interpreted at the receivers’ side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.
A precondition for making coherent changes is that the PresentationQos of the DDS\_Publisher has its coherent\_access attribute set to TRUE. If this is not the case, the Publisher will not accept any coherent start requests and return DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the DDS\_Publisher or one of its connected DDS\_Subscribers may change, a late-joining DDS\_DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.
These calls can be nested. In that case, the coherent set terminates only with the last call to DDS\_Publisher\_end\_coherent\_changes.
The support for ‘coherent changes’ enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen ‘atomically’ by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the ‘altitude’ and ‘velocity vector’ of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a new coherent change has successfully been started.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter passed to the operation is NULL, or is not pointing to any valid object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DDS\_Publisher is not able to handle coherent changes because its PresentationQos has not set coherent\_access to TRUE.
# 3.4.1.2 DDS\_Publisher\_copy\_from\_topic\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_copy_from_topic_qos
(DDS_Publisher _this,
DDS_DataWriterQos *a_datawriter_qos,
const DDS_TopicQos *a_topic_qos);
```
# Description
This operation will copy policies in a\_topic\_qos to the corresponding policies in a\_datawriter\_qos.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
inout DDS\_DataWriterQos \*a\_datawriter\_qos - the destination DDS\_DataWriterQos struct to which the QosPolicy settings should be copied.
in const DDS\_TopicQos \*a\_topic\_qos - the source DDS\_TopicQos struct, which should be copied.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation will copy the QosPolicy settings in a\_topic\_qos to the corresponding QosPolicy settings in a\_datawriter\_qos (replacing the values in a\_datawriter\_qos, if present). This will only apply to the common QosPolicy settings in each <DDS\_Entity>Qos.
This is a “convenience” operation, useful in combination with the operations DDS\_Publisher\_get\_default\_datawriter\_qos and DDS\_Topic\_get\_qos. The operation DDS\_Publisher\_copy\_from\_topic\_qos can be used to merge the DDS\_DataWriter default QosPolicy settings with the corresponding ones on the DDS\_TopicQos. The resulting DDS\_DataWriterQos can then be used to create a new DDS\_DataWriter, or set its DDS\_DataWriterQos.
This operation does not check the resulting a\_datawriter\_qos for consistency. This is because the “merged” a\_datawriter\_qos may not be the final one, as the application can still modify some QosPolicy settings prior to applying the DDS\_DataWriterQos to the DDS\_DataWriter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the QosPolicy settings have successfully been copied from the DDS\_TopicQos to the DDS\_DataWriterQos.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.3 DDS\_Publisher\_create\_datawriter
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataWriter
DDS_Publisher_create_datawriter
```
```c
(DDS_Publisher _this,
const DDS_Topic a_topic,
const DDS_DataWriterQos *qos,
const struct DDS_DataWriterListener *a_listener,
const DDS_StatusMask mask);
```
# Description
T h i s o p e r a t i o n c r e a t e s a D D S \_ D a t a W r i t e r w i t h t h e d e s i r e d DDS\_DataWriterQos, for the desired DDS\_Topic and attaches the optionally specified DDS\_DataWriterListener to it.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const DDS\_Topic a\_topic - a pointer to the topic for which the DDS\_DataWriter is created.
in const DDS\_DataWriterQos \*qos - the DDS\_DataWriterQos for the new DDS\_DataWriter. In case these settings are not self consistent, no DDS\_DataWriter is created.
in const struct DDS\_DataWriterListener \*a\_listener - a pointer to the DDS\_DataWriterListener instance which will be attached to the new DDS\_DataWriter. It is permitted to use DDS\_OBJECT\_NIL as the value of the listener: this behaves as a DDS\_DataWriterListener whose operations perform no action.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_DataWriterListener for a certain status.
# Return Value
DD S \_D at aW ri t er - Return value is a pointer to the newly-created DDS\_DataWriter. In case of an error, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
T h i s o p e r a t i o n c r e a t e s a D D S \_ D a t a W r i t e r w i t h t h e d e s i r e d DDS\_DataWriterQos, for the desired DDS\_Topic and attaches the optionally specified DDS\_DataWriterListener to it. The returned DDS\_DataWriter is attached (and belongs) to the DDS\_Publisher on which this operation is being called. To delete the DDS\_DataWriter the operation DDS\_Publisher\_ delete\_datawriter or DDS\_Publisher\_delete\_contained\_entities must be used. If no write rights are defined for the specific topic then the creation of the DataWriter will fail.
# Application Data Type
The DDS\_DataWriter returned by this operation is an object of a derived class, specific to the data type associated with the DD S\_ To pi c . For each a p p l i c a t i o n - d e f i n e d d a t a t y p e < t y p e > t h e r e i s a c l a s s <NameSpace>\_<type>DataWriter generated by calling the pre-processor. This data type specific class extends DDS\_DataWriter and contains the operations to write data of data type <type>.
# QosPolicy
The possible application pattern to construct the DDS\_DataWriterQos for the DDS\_DataWriter is to:
• Retrieve the QosPolicy settings on the associated DDS\_Topic by means of the get\_qos operation on the DDS\_Topic.
• Retrieve the default DDS\_DataWriterQos by means of the DDS\_Publisher\_get\_default\_datawriter\_qos operation on the DDS\_Publisher
• Combine those two lists of QosPolicy settings and selectively modify QosPolicy settings as desired
• Use the resulting DDS\_DataWriterQos to construct the DDS\_DataWriter.
• In case the specified QosPolicy settings are not consistent, no DDS\_DataWriter is created and the DDS\_OBJECT\_NIL pointer is returned.
# Default QoS
The constant DDS\_DATAWRITER\_QOS\_DEFAULT can be used as parameter qos to create a DDS\_DataWriter with the default DDS\_DataWriterQos as set in the DDS\_Publisher. The effect of using DDS\_DATAWRITER\_QOS\_DEFAULT is the same as calling the operation DDS\_Publisher\_get\_default\_datawriter\_qos and using the resulting DDS\_DataWriterQos to create the DDS\_DataWriter.
The special DDS\_DATAWRITER\_QOS\_USE\_TOPIC\_QOS can be used to create a DDS\_DataWriter with a combination of the default DDS\_DataWriterQos and t h e DDS\_TopicQos. T h e e f f e c t o f u s i n g DDS\_DATAWRITER\_QOS\_USE\_TOPIC\_QOS is the same as calling the operation DDS\_Publisher\_get\_default\_datawriter\_qos and retrieving the DDS\_TopicQos (by means of the operation DDS\_Topic\_get\_qos) and then c o m b i n i n g t h e s e t w o Q o s P o l i c y s e t t i n g s u s i n g t h e o p e r a t i o n DDS\_Publisher\_copy\_from\_topic\_qos, whereby any common policy that is set on the DDS\_TopicQos “overrides” the corresponding policy on the default DDS\_DataWriterQos. The resulting DDS\_DataWriterQos is then applied to create the DDS\_DataWriter.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_DataWriterListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior to calling the listener means that if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset.
The following statuses are applicable to the DDS\_DataWriterListener:
```pickle
DDS_OFFERED_DEADLINE_MISSED_STATUS
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS
DDS_LIVELINESS_LOST_STATUS
DDS_PUBLICATION_MATCHED_STATUS.
```
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_OBJECT\_NIL.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
In case a communication status is not activated in the m as k of th e DDS\_DataWriterListener, the DDS\_PublisherListener of the containing DDS\_Publisher is invoked (if attached and activated for the status that occurred). T h i s a l l o w s t h e a p p l i c a t i o n t o s e t a d e f a u l t b e h a v i o u r i n t h e DDS\_PublisherListener of the containing DDS\_Publisher and a DDS\_DataWriter specific behaviour when needed. In case the communication status is not activated in the mask of the DDS\_PublisherListener as well, the c o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h e DDS\_DomainParticipantListener o f t h e c o n t a i n i n g
DDS\_DomainParticipant. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# 3.4.1.4 DDS\_Publisher\_delete\_contained\_entities
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_delete_contained_entities
(DDS_Publisher _this);
```
# Description
This operation deletes all the DDS\_DataWriter objects that were created by means of one of the DDS\_Publisher\_create\_datawriter operations on the DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes all the DDS\_DataWriter objects that were created by means of one of the DDS\_Publisher\_create\_datawriter operations on the DDS\_Publisher. In other words, it deletes all contained DDS\_DataWriter objects.
NOTE: The operation will return DDS\_PRECONDITION\_NOT\_MET if the any of the contained entities is in a state where it cannot be deleted. In such cases, the operation does not roll back any entity deletions performed prior to the detection of the problem.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the contained DDS\_Entity objects are deleted and the application may delete the DDS\_Publisher.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.4.1.5 DDS\_Publisher\_delete\_datawriter
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_delete_datawriter
(DDS_Publisher _this,
const DDS_DataWriter a_datawriter);
```
# Description
This operation deletes a DDS\_DataWriter that belongs to the DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation -is operated.
i n const DDS\_DataWriter a\_datawriter - a pointer to the DDS\_DataWriter, which is to be deleted.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a DDS\_DataWriter that belongs to the DDS\_Publisher. When the operation is called on a different DDS\_Publisher, as used when the DDS\_DataWriter was created, the operation has no effect and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET. The deletion of the DDS\_DataWriter will automatically unregister all instances. Depending on the settings of DDS\_WriterDataLifecycleQosPolicy, the deletion of the DDS\_DataWriter may also dispose of all instances.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DataWriter is deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter a\_datawriter is not a valid DDS\_DataWriter.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DDS\_Publisher, as used when the DDS\_DataWriter was created.
# 3.4.1.6 DDS\_Publisher\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_enable
(DDS_Publisher _this);
```
# 3.4.1.7 DDS\_Publisher\_end\_coherent\_changes
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_end_coherent_changes
(DDS_Publisher_this);
```
# Description
This operation terminates the ‘coherent set’ initiated by the matching call to DDS\_Publisher\_begin\_coherent\_changes.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation terminates the ‘coherent set’ initiated by the matching call to DDS\_Publisher\_begin\_coherent\_changes. If there is no matching call to DDS\_Publisher\_begin\_coherent\_changes, the operation will return the error DDS\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the coherent change has successfully been closed.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter passed to the operation is NULL, or is not pointing to any valid object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - there is no matching DDS\_Publisher\_begin\_coherent\_changes call that can be closed.
# 3.4.1.8 DDS\_Publisher\_get\_default\_datawriter\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_get_default_datawriter_qos
(DDS_Publisher _this,
DDS_DataWriterQos *qos);
```
# Description
This operation gets the default DDS\_DataWriterQos of the DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
inout DDS\_DataWriterQos \*qos - a pointer to the DDS\_DataWriterQos struct (provided by the application) in which the default DDS\_DataWriterQos for the DDS\_DataWriter is written.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation gets the default DDS\_DataWriterQos of the DDS\_Publisher (that is the struct with the QosPolicy settings) which is used for newly-created DDS\_DataWriter objects, in case the constant DDS\_DATAWRITER\_QOS\_DEFAULT is used. The default DDS\_DataWriterQos is only used when the constant is supplied as parameter qos to specify the DDS\_DataWriterQos in the DDS\_Publisher\_create\_datawriter operation. The application must provide the DDS\_DataWriterQos struct in which the QosPolicy settings can be stored and pass the qos pointer to the operation. The operation writes the default DDS\_DataWriterQos to the struct pointed to by qos. Any settings in the struct are overwritten.
The values retrieved by this operation match the set of values specified on the last successful call to DDS\_Publisher\_set\_default\_datawriter\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 5: on page 65.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the default DDS\_DataWriter QosPolicy settings of this DDS\_Publisher have successfully been copied into the specified DDS\_DataWriterQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.9 DDS\_Publisher\_get\_listener
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_PublisherListener
DDS_Publisher_get_listener
(DDS_Publisher_this);
```
# Description
This operation allows access to a DDS\_PublisherListener.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
struct DDS\_PublisherListener - a pointer to the DDS\_PublisherListener attached to the DDS\_Publisher.
# Detailed Description
This operation allows access to a DDS\_PublisherListener attached to the DDS\_Publisher. When no DDS\_PublisherListener was attached to the DDS\_Publisher, the DDS\_OBJECT\_NIL pointer is returned.
# 3.4.1.10 DDS\_Publisher\_get\_participant
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_Publisher_get_participant
(DDS_Publisher _this);
```
# Description
This operation returns the DDS\_DomainParticipant associated with the DDS\_Publisher or the DDS\_OBJECT\_NIL pointer.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
DDS\_DomainParticipant - a pointer to the DDS\_DomainParticipant associated with the DDS\_Publisher or the DDS\_OBJECT\_NIL pointer.
# Detailed Description
This operation returns the DDS\_DomainParticipant associated with the DDS\_Publisher. Note that there is exactly one DDS\_DomainParticipant associated with each DDS\_Publisher. When the DDS\_Publisher was already deleted (there is no associated DDS\_DomainParticipant any more), the DDS\_OBJECT\_NIL pointer is returned.
# 3.4.1.11 DDS\_Publisher\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_get_qos
(DDS_Publisher _this,
DDS_PublisherQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
i no u t D D S\_ P u bl i s he r Qo s \*q o s - a pointer to the destination DDS\_PublisherQos struct in which the QosPolicy settings will be copied.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DDS\_Publisher on which this operation is used. This DDS\_PublisherQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_Publisher has successfully been copied into the specified DDS\_PublisherQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.12 DDS\_Publisher\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_Publisher_get_status_changes
(DDS_Publisher_this);
```
# 3.4.1.13 DDS\_Publisher\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_Publisher_get_statuscondition
(DDS_Publisher_this);
```
# 3.4.1.14 DDS\_Publisher\_lookup\_datawriter
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataWriter
DDS_Publisher_lookup_datawriter
(DDS_Publisher _this,
const DDS_char *topic_name);
```
# Description
This operation returns a previously created DDS\_DataWriter belonging to the DDS\_Publisher which is attached to a DDS\_Topic with the matching topic\_name.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const DDS\_char \*topic\_name - the name of the DDS\_Topic, which is attached to the DDS\_DataWriter to look for.
# Return Value
DDS\_DataWriter - Return value is a pointer to the DDS\_DataWriter found. When no such DDS\_DataWriter is found, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation returns a previously created DDS\_DataWriter belonging to the DDS\_Publisher which is attached to a DDS\_Topic with the matching topic\_name. When multiple DDS\_DataWriter objects (which satisfy the same condition) exist, this operation will return one of them. It is not specified which one.
# 3.4.1.15 DDS\_Publisher\_resume\_publications
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_resume_publications
(DDS_Publisher _this);
```
# Description
This operation resumes a previously suspended publication.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
If the DDS\_Publisher is suspended, this operation will resume the publication of all DDS\_DataWriter objects contained by this DDS\_Publisher. All data held in the history buffer of the DDS\_DataWriter's is actively published to the consumers. When the operation returns, all DDS\_DataWriter's have resumed the publication of suspended updates.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_Publisher object has been resumed.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_Publisher is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DDS\_Publisher is not suspended.
# 3.4.1.16 DDS\_Publisher\_set\_default\_datawriter\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_set_default_datawriter_qos
(DDS_Publisher_this,
const DDS_DataWriterQos *qos);
```
# Description
This operation sets the default DDS\_DataWriterQos of the DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const DDS\_DataWriterQos \*qos - the DDS\_DataWriterQos struct, which contains the new default DDS\_DataWriterQos for the newly-created DDS\_DataWriters.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation sets the default DDS\_DataWriterQos of the DDS\_Publisher (that is the struct with the QosPolicy settings) which is used for newly-created DDS\_DataWriter objects, in case the constant DDS\_DATAWRITER\_QOS\_DEFAULT is used. The default DDS\_DataWriterQos is only used when the constant is supplied as parameter qos to specify the DDS\_DataWriterQos in the DDS\_Publisher\_create\_datawriter operation.
The DDS\_Publisher\_set\_default\_datawriter\_qos operation checks if the DDS\_DataWriterQos is self consistent. If it is not, the operation has no effect and returns DDS\_RETCODE\_INCONSISTENT\_POLICY.
T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b y DDS\_Publisher\_get\_default\_datawriter\_qos.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new default DDS\_DataWriterQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_DataWriterQos. It contains a QosPolicy setting with an invalid DDS\_Duration\_t value, an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.4.1.17 DDS\_Publisher\_set\_listener
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_set_listener
(DDS_Publisher _this,
const struct DDS_PublisherListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation attaches a DDS\_PublisherListener to the DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const struct DDS\_PublisherListener \*a\_listener - a pointer to the DDS\_PublisherListener instance, which will be attached to the DDS\_Publisher.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_PublisherListener for a certain status.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation attaches a DDS\_PublisherListener to the DDS\_Publisher. Only one DDS\_PublisherListener can be attached to each DDS\_Publisher. If a DDS\_PublisherListener was already attached, the operation will replace it with the new one. When a\_listener is the DDS\_OBJECT\_NIL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bitmask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_PublisherListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset. An exception to this rule is the DDS\_OBJECT\_NIL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DDS\_PublisherListener:
• DDS\_OFFERED\_DEADLINE\_MISSED\_STATUS (propagated)
• DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• DDS\_LIVELINESS\_LOST\_STATUS (propagated)
• DDS\_PUBLICATION\_MATCHED\_STATUS (propagated).
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener. In other words, in case a communication status is also activated on the DDS\_DataWriterListener of a contained DDS\_DataWriter, the
DDS\_DataWriterListener on that contained DDS\_DataWriter is invoked instead of the DDS\_PublisherListener. This means that a status change on a contained DDS\_DataWriter only invokes the DDS\_PublisherListener if the contained DDS\_DataWriter itself does not handle the trigger event generated by the status change.
In case a status is not activated in the mask of the DDS\_PublisherListener, the DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant and a DDS\_Publisher specific behaviour when needed. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_PublisherListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.18 DDS\_Publisher\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_set_qos
(DDS_Publisher_this,
const DDS_PublisherQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_Publisher.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const DDS\_PublisherQos \*qos - contains the new set of QosPolicy settings for the DDS\_Publisher.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES, DDS\_RETCODE\_IMMUTABLE\_POLICY or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_Publisher. The parameter qos contains the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_Publisher, which can only be set before t h e D D S \_ P u b l i s h e r i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the currently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a DDS\_RETCODE\_INCONSISTENT\_POLICY is returned.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK). If one or more of the partitions in the QoS structure have insufficient access rights configured then the set\_qos function will fail with a DDS\_RETCODE\_PRECONDITION\_NOT\_MET error code.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_PublisherQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_PublisherQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DDS\_Publisher.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - returned when insufficient access rights exist for the partition(s) listed in the QoS structure.
# 3.4.1.19 DDS\_Publisher\_suspend\_publications
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_suspend_publications
(DDS_Publisher _this);
```
# Description
This operation will suspend the dissemination of the publications by all contained DataWriter objects.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.
```
# Detailed Description
This operation suspends the publication of all DDS\_DataWriter objects contained by this DDS\_Publisher. The data written, disposed or unregistered by a DDS\_DataWriter is stored in the history buffer of the DDS\_DataWriter and therefore, depending on its QoS settings, the following operations may block (see the operation descriptions for more information):
• DDS\_DataWriter\_dispose
• DDS\_DataWriter\_dispose\_w\_timestamp
• DDS\_DataWriter\_write
• DDS\_DataWriter\_write\_w\_timestamp
• DDS\_DataWriter\_writedispose
• DDS\_DataWriter\_writedispose\_w\_timestamp
• DDS\_DataWriter\_unregister\_instance
• DDS\_DataWriter\_unregister\_instance\_w\_timestamp
Subsequent calls to the DDS\_Publisher\_suspend\_publications operation h a v e n o e ff e c t . W h e n t h e D D S \_ P u b l i s h e r i s d e l e t e d b e f o r e DDS\_Publisher\_resume\_publications is called, all suspended updates are discarded.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_Publisher has been suspended.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_Publisher is not enabled.
# 3.4.1.20 DDS\_Publisher\_wait\_for\_acknowledgments
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Publisher_wait_for_acknowledgments
(DDS_Publisher _this,
const DDS_Duration_t *max_wait);
```
# Description
This operation blocks the calling thread until either all data written by all contained DataWriters is acknowledged by the local infrastructure, or until the duration specified by max\_wait parameter elapses, whichever happens first.
# Parameters
in DDS\_Publisher \_this - the DDS\_Publisher object on which the operation is operated.
in const DDS\_Duration\_t \*max\_wait - the maximum duration to block for the DDS\_Publisher\_wait\_for\_acknowledgments, after which the a p p l i c a t i o n t h r e a d i s u n b l o c k e d . T h e s p e c i a l c o n s t a n t DDS\_DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation blocks the calling thread until either all data written by all contained DataWriters is acknowledged by the local infrastructure, or until the duration specified by max\_wait parameter elapses, whichever happens first.
Data is acknowledged by the local infrastructure when it does not need to be stored in its DataWriter’s local history. When a locally-connected subscription (including the networking service) has no more resources to store incoming samples it will start to reject these samples, resulting in their source DataWriters to store them temporarily in their own local history to be retransmitted at a later moment in time. In such scenarios, the DDS\_Publisher\_wait\_for\_acknowledgments operation will block until all contained DataWriters have retransmitted their entire history, which is therefore effectively empty, or until the max\_wait timeout expires, w h i c h e v e r h a p p e n s f i r s t . I n t h e f i r s t c a s e t h e o p e r a t i o n w i l l r e t u r n DDS\_RETCODE\_OK, in the latter it will return DDS\_RETCODE\_TIMEOUT.
Be aware that in case the operation returns DDS\_RETCODE\_OK, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered ‘on-route’ and will therefore eventually arrive (unless the networking service itself crashes). In contrast, if a DataWriter would still have data in its local history buffer when it terminates, this data is considered ‘lost’.
This operation is intended to be used only if one or more of the contained DataWriters has its DDS\_ReliabilityQosPolicyKind set to DDS\_RELIABLE\_RELIABILITY\_QOS. Otherwise the operation will return immediately with DDS\_RETCODE\_OK, since best-effort DataWriters will never store rejected samples in their local history: they will just drop them and continue business as usual.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the data of all contained DataWriters has been acknowledged by the local infrastructure.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Publisher has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_Publisher is not enabled.
• DDS\_RETCODE\_TIMEOUT - not all data is acknowledged before max\_wait elapsed.
# 3.4.2 Publication Type Specific Classes
This paragraph describes the generic DDS\_DataWriter class and the derived application type specific <NameSpace>\_<type>DataWriter classes which together implement the application publication interface. For each application type, u s e d a s D D S \_ T o p i c d a t a t y p e , t h e p r e - p r o c e s s o r g e n e r a t e s a <NameSpace>\_<type>DataWriter class from an IDL type description. The SPACE\_FooDataWriter class that would be generated by the pre-processor for a f i c t i o n a l t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e s c r i b e s t h e <NameSpace>\_<type>DataWriter classes.
# 3.4.2.1 Class DDS\_DataWriter (abstract)
DDS\_DataWriter allows the application to set the value of the sample to be published under a given DDS\_Topic.
A DDS\_DataWriter is attached to exactly one DDS\_Publisher which acts as a factory for it.
A DDS\_DataWriter is bound to exactly one DDS\_Topic and therefore to exactly one data type. The DDS\_Topic must exist prior to the DDS\_DataWriter's creation.
DDS\_DataWriter is an abstract class. It must be specialized for each particular application data type. For a fictional application data type Foo (defined in the module SPACE) the specialized class would be SPACE\_FooDataWriter.
The interface description of this class is as follows:
```c
/*
* interface DDS_DataWriter
*/
*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_DataWriter_get_statuscondition
* (DDS_DataWriter _this);
*/
/* DDS_StatusMask
* DDS_DataWriter_get_status_changes
* (DDS_DataWriter _this);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_enable
* (DDS_DataWriter _this);
*/
/*
* abstract operations
* (implemented in the data type specific DDS_DataWriter)
*/
/* DDS_InstanceHandle_t
* DDS_DataWriter_register_instance
* (DDS_DataWriter _this);
* const <data> *instance_data);
*/
/* DDS_InstanceHandle_t
* DDS_DataWriter_register_instance_w_timestamp
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_Time_t *source_timestamp);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_unregister_instance
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t handle);
*/
/* DDS_ReturnCode_t
```
```c
* DDS_DataWriter_unregister_instance_w_timestamp
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t handle,
* const DDS_Time_t *source_timestamp);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_write
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t handle);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_write_w_timestamp
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t handle,
* const DDS_Time_t *source_timestamp);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_dispose
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t instance_handle);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_dispose_w_timestamp
* (DDS_DataWriter _this);
* const <data> *instance_data,
* const DDS_InstanceHandle_t instance_handle,
* const DDS_Time_t *source_timestamp);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_writedispose
* (DDS_DataWriter _this,
* const <data> *instance_data,
* const DDS_InstanceHandle_t instance_handle);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_writedispose_w_timestamp
* (DDS_DataWriter _this,
* const <data> *instance_data,
* const DDS_InstanceHandle_t instance_handle,
* const DDS_Time_t *source_timestamp);
*/
/* DDS_ReturnCode_t
* DDS_DataWriter_get_key_value
* (DDS_DataWriter _this);
* <data> *key_holder,
```
```c
* const DDS_InstanceHandle_t handle);
*/
/* DDS_InstanceHandle_t
* DDS_DataWriter_lookup_instance
*/ (DDS_DataWriter _this,
* <data> *instance_data);
/*
/*
* implemented API operations
*/
DDS_ReturnCode_t
DDS_DataWriter_set_qos
(DDS_DataWriter this,
const DDS_DataWriterQos *qos);
DDS_ReturnCode_t
DDS_DataWriter_get_qos
(DDS_DataWriter this,
DDS_DataWriterQos *qos);
DDS_ReturnCode_t
DDS_DataWriter_set_listener
(DDS_DataWriter this,
const struct DDS_DataWriterListener *a_listener,
const DDS_StatusMask mask);
struct DDS_DataWriterListener
struct DDS_DataWriter_get_listener
(DDS_DataWriter this);
DDS_Topic
DDS_DataWriter_get_topic
(DDS_DataWriter this);
DDS_Publisher
DDS_DataWriter_get_publisher
(DDS_DataWriter this);
DDS_ReturnCode_t
DDS_DataWriter_wait_for_acknowledgments
(DDS_DataWriter _this,
const DDS_Duration_t *max_wait);
DDS_ReturnCode_t
DDS_DataWriter_get_liveliness_lost_status
(DDS_DataWriter this,
DDS_LivelinessLostStatus *status);
DDS_ReturnCode_t
DDS_DataWriter_get_offered_deadline_missed_status
```
```c
(DDS_DataWriter this,
DDS_OfferedDeadlineMissedStatus *status);
DDS_ReturnCode_t
DDS_DataWriter_get_offered_incompatible_qos_status
(DDS_DataWriter this,
DDS_OfferedIncompatibleQosStatus *status);
DDS_ReturnCode_t
DDS_DataWriter_get_publication_matched_status
(DDS_DataWriter this,
DDS_PublicationMatchedStatus *status);
DDS_ReturnCode_t
DDS_DataWriter_assert_liveliness
(DDS_DataWriter this);
DDS_ReturnCode_t
DDS_DataWriter_get_matched_subscriptions
(DDS_DataWriter this,
DDS_InstanceHandleSeq *subscription_handles);
DDS_ReturnCode_t
DDS_DataWriter_get_matched_subscription_data
(DDS_DataWriter this,
DDS_SubscriptionBuiltinTopicData
*subscription_data,
const DDS_InstanceHandle_t subscription_handle
);
```
The following paragraphs describe the usage of all DDS\_DataWriter operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited. The abstract operations are listed but not fully described because they are not implemented in this specific class. The full description of these operations is located in the subclasses, which contain the data type specific implementation of these operations.
# 3.4.2.2 DDS\_DataWriter\_assert\_liveliness
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_assert_liveliness
(DDS_DataWriter _this);
```
# Description
This operation asserts the liveliness for the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - is the DDS\_DataWriter object on which the operation is operated.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation will manually assert the liveliness for the DDS\_DataWriter. This way, the Data Distribution Service is informed that the corresponding DDS\_DataWriter is still alive. This operation is used in combination with the DDS\_LivelinessQosPolicy set to DDS\_MANUAL\_BY\_PARTICIPANT LIVELINESS\_QOS or DDS\_MANUAL\_BY\_TOPIC\_LIVELINESS\_QOS. See Section 3.1.3.10, DDS\_LivelinessQosPolicy, on page 85, for more information on LivelinessQosPolicy.
Writing data via the DDS\_DataWriter\_write operation of a DDS\_DataWriter will assert the liveliness on the DDS\_DataWriter itself and its containing DDS\_DomainParticipant. Therefore, DDS\_DataWriter\_assert\_ liveliness is only needed when data is not written regularly.
The liveliness should be asserted by the application, depending on the DDS\_LivelinessQosPolicy. Asserting the liveliness for this DDS\_DataWriter can also be achieved by asserting the liveliness to the DDS\_DomainParticipant.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the liveliness of this DDS\_DataWriter has successfully been asserted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataWriter is not enabled.
# 3.4.2.3 DDS\_DataWriter\_dispose (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_dispose
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t instance_handle);
```
# 3.4.2.4 DDS\_DataWriter\_dispose\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_dispose_w_timestamp
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t *source_timestamp);
```
# 3.4.2.5 DDS\_DataWriter\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_enable
(DDS_DataWriter _this);
```
# 3.4.2.6 DDS\_DataWriter\_get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_key_value
(DDS_DataWriter _this,
<data> *key_holder,
const DDS_InstanceHandle_t handle);
```
# 3.4.2.7 DDS\_DataWriter\_get\_listener
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DataWriterListener
DDS_DataWriter_get_listener
(DDS_DataWriter _this);
```
# Description
This operation allows access to a DDS\_DataWriterListener.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
# Return Value
struct DDS\_DataWriterListener - a pointer to the DDS\_DataWriterListener attached to the DDS\_DataWriter.
# Detailed Description
This operation allows access to a DDS\_DataWriterListener attached to the DDS\_DataWriter. When no DDS\_DataWriterListener was attached to the DDS\_DataWriter, the DDS\_OBJECT\_NIL pointer is returned.
# 3.4.2.8 DDS\_DataWriter\_get\_liveliness\_lost\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
```
```c
DDS_DataWriter_get_liveliness_lost_status
(DDS_DataWriter _this,
DDS_LivelinessLostStatus *status);
```
# Description
This operation obtains the DDS\_LivelinessLostStatus struct of the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_LivelinessLostStatus \*status - the contents of the DDS\_LivelinessLostStatus struct of the DDS\_DataWriter will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_LivelinessLostStatus struct of the DDS\_DataWriter. This struct contains the information whether the liveliness (that the DDS\_DataWriter has committed through its DDS\_LivelinessQosPolicy) was respected.
This means that the status represents whether the DDS\_DataWriter failed to actively signal its liveliness within the offered liveliness period. If the liveliness is lost, the DDS\_DataReader objects will consider the DDS\_DataWriter as no longer “alive”.
The DDS\_LivelinessLostStatus can also be monitored using a DDS\_DataWriterListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_LivelinessLostStatus of this DDS\_DataWriter has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.9 DDS\_DataWriter\_get\_matched\_subscription\_data
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_matched_subscription_data
(DDS_DataWriter _this,
DDS_SubscriptionBuiltinTopicData *subscription_data,
const DDS_InstanceHandle_t subscription_handle);
```
# Description
This operation retrieves information on the specified subscription that is currently “associated” with the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_SubscriptionBuiltinTopicData \*subscription\_data - a pointer to the sample in which the information about the specified subscription is to be stored.
in const DDS\_InstanceHandle\_t subscription\_handle - a handle to the subscription whose information needs to be retrieved.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves information on the specified subscription that is currently “associated” with the DDS\_DataWriter. That is, a subscription with a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the DDS\_DomainParticipant\_ignore\_subscription operation.
The subscription\_handle must correspond to a subscription currently associated with the DDS\_DataWriter, otherwise the operation will fail and return DDS\_RETCODE\_BAD\_PARAMETER. The operation DDS\_DataWriter\_ get\_matched\_subscriptions can be used to find the subscriptions that are currently matched with the DDS\_DataWriter.
The operation may also fail if the infrastructure does not hold the information necessary to fill in the subscription\_data. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the information on the specified subscription has been successfully retrieved.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataWriter is not enabled.
# 3.4.2.10 DDS\_DataWriter\_get\_matched\_subscriptions
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_matched_subscriptions
(DDS_DataWriter _this,
DDS_InstanceHandleSeq *subscription_handles);
```
# Description
This operation retrieves the list of subscriptions currently "associated" with the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_InstanceHandleSeq \*subscription\_handles - a sequence which is used to pass the list of all associated subscribtions.
# Return Value
D D S \_ R e t ur n C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves the list of subscriptions currently "associated" with the DDS\_DataWriter. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the DDS\_DomainParticipant\_ignore\_subscription operation.
The subscription\_handles sequence and its buffer may be pre-allocated by the application and therefore must either be re-used in a subsequent invocation of the DDS\_DataWriter\_get\_matched\_subscriptions operation or be released by calling DDS\_free on the returned subscription\_handles. If the pre-allocated sequence is not big enough to hold the number of associated subscriptions, the sequence will automatically be (re-)allocated to fit the required size.
The handles returned in the subscription\_handles sequence are the ones that are used by the DDS implementation to locally identify the corresponding matched DataReader entities. You can access more detailed information about a particular subscription by passing its subscription\_handle to either the DDS\_DataWriter\_get\_matched\_subscription\_data operation or to the DDS\_SubscriptionBuiltinTopicDataDataReader\_read\_instance operation on the built-in reader for the “DCPSSubscription” topic.
Be aware that since DDS\_InstanceHandle\_t is an opaque datatype, it does not necessarily mean that the handles obtained from the DDS\_DataWriter get\_matched\_subscriptions operation have the same value as the ones that appear in the instance\_handle field of the DDS\_SampleInfo when retrieving the subscription info through corresponding "DCPSSubscriptions" built-in reader. You can’t just compare two handles to determine whether they represent the same subscription. If you want to know whether two handles actually do represent the same subscription, use both handles to retrieve their corresponding DDS\_SubscriptionBuiltinTopicData samples and then compare the key field of both samples.
The operation may fail if the infrastructure does not locally maintain the connectivity information. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the list of associated subscriptions has successfully been obtained.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataWriter is not enabled.
# 3.4.2.11 DDS\_DataWriter\_get\_offered\_deadline\_missed\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_offered_deadline_missed_status
(DDS_DataWriter_this,
DDS_OfferedDeadlineMissedStatus *status);
```
# Description
This operation obtains the DDS\_OfferedDeadlineMissedStatus struct of the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_OfferedDeadlineMissedStatus \*status - the contents of the DDS\_OfferedDeadlineMissedStatus struct of the DDS\_DataWriter will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_OfferedDeadlineMissedStatus struct of the DDS\_DataWriter. This struct contains the information whether the deadline (that the DDS\_DataWriter has committed through its DDS\_DeadlineQosPolicy) was respected for each instance.
The DDS\_OfferedDeadlineMissedStatus can also be monitored using a DDS\_DataWriterListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_LivelinessLostStatus of this DDS\_DataWriter has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.12 DDS\_DataWriter\_get\_offered\_incompatible\_qos\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_offered_incompatible_qos_status
(DDS_DataWriter_this,
DDS_OfferedIncompatibleQosStatus *status);
```
# Description
This operation obtains the DDS\_OfferedIncompatibleQosStatus struct of the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_OfferedIncompatibleQosStatus \*status - the contents of the DDS\_OfferedIncompatibleQosStatus struct of the DDS\_DataWriter will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_OfferedIncompatibleQosStatus struct of the DDS\_DataWriter. This struct contains the information whether a QosPolicy setting was incompatible with the requested QosPolicy setting.
This means that the status represents whether a DDS\_DataReader object has been discovered by the DDS\_DataWriter with the same DDS\_Topic and a requested DDS\_DataReaderQos that was incompatible with the one offered by the DDS\_DataWriter.
The DDS\_OfferedIncompatibleQosStatus can also be monitored using a DDS\_DataWriterListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_OfferedIncompatibleQosStatus of this DDS\_DataWriter has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.13 DDS\_DataWriter\_get\_publication\_matched\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_publication_matched_status
(DDS_DataWriter _this,
DDS_PublicationMatchedStatus *status);
```
# Description
This operation obtains the DDS\_PublicationMatchedStatus struct of the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_PublicationMatchedStatus \*status - the contents of the DDS\_PublicationMatchedStatus struct of the DDS\_DataWriter will be copied into the location specified by status.
# Return Value
D D S \_ R e t ur n C o d e \_ t - Possible re turn codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_PublicationMatchedStatus struct of the DDS\_DataWriter. This struct contains information about whether a new match has been discovered for the current publication, or whether an existing match has ceased to exist.
This means that the status represents that either a DataReader object has been discovered by the DDS\_DataWriter with the same Topic and a compatible Qos, or that a previously-discovered DataReader has ceased to be matched to the current DDS\_DataWriter. A DataReader may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DDS\_DataWriter or when either the DDS\_DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the DDS\_DomainParticipant\_ ignore\_subcription or DDS\_DomainParticipant\_ignore\_publication operations.
The operation may fail if the infrastructure does not hold the information necessary to fill in the DDS\_PublicationMatchedStatus. This is the case when OpenSplice is configured not to maintain discovery information in the Networking S e r v i c e . ( S e e t h e d e s c r i p t i o n f o r t h e N e t w o r k i n g S e r v i c e / Discovery/enabled property in the Deployment Manual for more information a b o u t t h i s s u b j e c t . ) I n t h i s c a s e t h e o p e r a t i o n w i l l r e t u r n DDS\_RETCODE\_UNSUPPORTED.
The DDS\_PublicationMatchedStatus can also be monitored using a DDS\_DataWriterListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_PublicationMatchedStatus of this DDS\_DataWriter has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.14 DDS\_DataWriter\_get\_publisher
# Synopsis
```c
#include <dds_dcps.h>
DDS_Publisher
DDS_DataWriter_get_publisher
(DDS_DataWriter _this);
```
# Description
This operation returns the DDS\_Publisher to which the DDS\_DataWriter belongs.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
# Return Value
DDS\_Publisher - a pointer to the DDS\_Publisher to which the DDS\_DataWriter belongs.
# Detailed Description
This operation returns the DDS\_Publisher to which the DDS\_DataWriter belongs, thus the DDS\_Publisher that has created the DDS\_DataWriter. If the DDS\_DataWriter is already deleted, the DDS\_OBJECT\_NIL pointer is returned.
# 3.4.2.15 DDS\_DataWriter\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_get_qos
(DDS_DataWriter_this,
DDS_DataWriterQos *qos);
```
# Description
This operation allows access to the existing list of QosPolicy settings for a DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
inout DDS\_DataWriterQos \*qos - a pointer to the destination DDS\_DataWriterQos struct in which the QosPolicy settings will be copied.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing list of QosPolicy settings of a DDS\_DataWriter on which this operation is used. This DDS\_DataWriterQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_DataWriter has successfully been copied into the specified DDS\_DataWriterQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.16 DDS\_DataWriter\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_DataWriter_get_status_changes
(DDS_DataWriter _this);
```
# 3.4.2.17 DDS\_DataWriter\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_DataWriter_get_statuscondition
(DDS_DataWriter_this);
```
# 3.4.2.18 DDS\_DataWriter\_get\_topic
# Synopsis
```c
#include <dds_dcps.h>
DDS_Topic
DDS_DataWriter_get_topic
(DDS_DataWriter _this);
```
# Description
This operation returns the DDS\_Topic which is associated with the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
# Return Value
DDS\_Topic - Return value is a pointer to the DDS\_Topic which is associated with the DDS\_DataWriter.
# Detailed Description
This operation returns the DDS\_Topic which is associated with the DDS\_DataWriter, thus the DDS\_Topic with which the DDS\_DataWriter is created. If the DDS\_DataWriter is already deleted, the DDS\_OBJECT\_NIL pointer is returned.
# 3.4.2.19 DDS\_DataWriter\_lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_InstanceHandle_t
DDS_DataWriter_lookup_instance
(DDS_DataWriter _this,
<data> *instance_data);
```
# 3.4.2.20 DDS\_DataWriter\_register\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
const DDS_InstanceHandle_t
```
```txt
DDS_DataWriter_register_instance
(DDS_DataWriter _this,
const <data> *instance_data);
```
# 3.4.2.21 DDS\_DataWriter\_register\_instance\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
const DDS_InstanceHandle_t
DDS_DataWriter_register_instance_w_timestamp
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_Time_t *source_timestamp);
```
# 3.4.2.22 DDS\_DataWriter\_set\_listener
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_set_listener
(DDS_DataWriter _this,
const struct DDS_DataWriterListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation attaches a DDS\_DataWriterListener to the DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
in const struct DDS\_DataWriterListener \*a\_listener - a pointer to the DDS\_DataWriterListener instance, which will be attached to the DDS\_DataWriter.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_DataWriterListener for a certain status.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ ALREADY\_DELETED or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a DDS\_DataWriterListener to the DDS\_DataWriter. Only one DDS\_DataWriterListener can be attached to each DDS\_DataWriter. If a DDS\_DataWriterListener was already attached, the operation will replace it with the new one. When a\_listener is the DDS\_OBJECT\_NIL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bitmask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_DataWriterListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset. An exception to this rule is the DDS\_OBJECT\_NIL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DDS\_DataWriterListener:
• DDS\_OFFERED\_DEADLINE\_MISSED\_STATUS
• DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS
• DDS\_LIVELINESS\_LOST\_STATUS
• DDS\_PUBLICATION\_MATCHED\_STATUS.
Be aware that the DDS\_PUBLICATION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
In case a communication status is not activated in the m a sk of the DDS\_DataWriterListener, the DDS\_PublisherListener of the containing DDS\_Publisher is invoked (if attached and activated for the status that occurred). T h i s a l l o w s t h e a p p l i c a t i o n t o s e t a d e f a u l t b e h a v i o u r i n t h e DDS\_PublisherListener of the containing DDS\_Publisher and a DDS\_DataWriter specific behaviour when needed. In case the communication status is not activated in the mask of the DDS\_PublisherListener as well, the c o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h e DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DataWriterListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.23 DDS\_DataWriter\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
```
```c
DDS_DataWriter_set_qos
(DDS_DataWriter_this,
const DDS_DataWriterQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DataWriter.
# Parameters
in DDS\_DataWriter \_this - the DDS\_DataWriter object on which the operation is operated.
in const DDS\_DataWriterQos \*qos - contain the new set of QosPolicy settings for the DDS\_DataWriter.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALLREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_IMMUTABLE_POLICY or DDS_RETCODE_INCONSISTENT_POLICY.
```
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DataWriter. The parameter qos contains the struct with the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_DataWriter, which can only be set before the DDS\_DataWriter is enabled, the operation will fail and a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a DDS\_RETCODE\_INCONSISTENT\_POLICY is returned.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new default DDS\_DataWriterQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid. DDS\_DataWriterQos. It contains a QosPolicy setting with an invalid DDS\_Duration\_t value, an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DDS\_DataWriter.
• DDS\_RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.4.2.24 DDS\_DataWriter\_unregister\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_unregister_instance
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t handle);
```
# 3.4.2.25 DDS\_DataWriter\_unregister\_instance\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_unregister_instance_w_timestamp
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
```
# 3.4.2.26 DDS\_DataWriter\_wait\_for\_acknowledgments
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_wait_for_acknowledgments
(DDS_DataWriter _this,
const DDS_Duration_t *max_wait);
```
# Description
This operation blocks the calling thread until either all data written by the DDS\_DataWriter is acknowledged by the local infrastructure, or until the duration specified by max\_wait parameter elapses, whichever happens first.
Parameters
```txt
in DDS_DataWriter _this - the DDS_DataWriter object on which the operation is operated.
in const DDS_Duration_t *max_wait - the maximum duration to block for the DDS_DataWriter_wait_for_acknowledgments, after which the application thread is unblocked. The special constant DDS_DURATION_INFINITE can be used when the maximum waiting time does not need to be bounded.
```
Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation blocks the calling thread until either all data written by the DDS\_DataWriter is acknowledged by the local infrastructure, or until the duration specified by max\_wait parameter elapses, whichever happens first.
Data is acknowledged by the local infrastructure when it does not need to be stored in its DataWriter’s local history. When a locally-connected subscription (including the networking service) has no more resources to store incoming samples it will start to reject these samples, resulting in its source DataWriter to store them temporarily in its own local history to be retransmitted at a later moment in time. In such scenarios, the DDS\_DataWriter\_wait\_for\_acknowledgments operation will block until the DDS\_DataWriter has retransmitted its entire history, which is therefore effectively empty, or until the max\_wait timeout expires, whichever happens first. In the first case the operation will return DDS\_RETCODE\_OK, in the latter it will return DDS\_RETCODE\_TIMEOUT.
Be aware that in case the operation returns DDS\_RETCODE\_OK, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered ‘on-route’ and will therefore eventually arrive (unless the networking service itself crashes). In contrast, if the DDS\_DataWriter would still have data in it’s local history buffer when it terminates, this data is considered ‘lost’.
This operation is intended to be used only if the DDS\_DataWriter has its DDS\_ReliabilityQosPolicyKind set to DDS\_RELIABLE\_RELIABILITY\_QOS. Otherwise the operation will return immediately with DDS\_RETCODE\_OK, since best-effort DataWriters will never store rejected samples in their local history: they will just drop them and continue business as usual.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the data of the DDS\_DataWriter has been acknowledged by the local infrastructure.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataWriter is not enabled.
• DDS\_RETCODE\_TIMEOUT - not all data is acknowledged before max\_wait elapsed.
# 3.4.2.27 DDS\_DataWriter\_write (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_write
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t handle);
```
# 3.4.2.28 DDS\_DataWriter\_write\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_write_w_timestamp
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
```
# 3.4.2.29 DDS\_DataWriter\_writedispose (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_writedispose
(DDS_DataWriter _this,
const <data> *instance_data,
```
const DDS\_InstanceHandle\_t instance\_handle);
# 3.4.2.30 DDS\_DataWriter\_writedispose\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataWriter class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataWriter class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataWriter_writedispose_w_timestamp
(DDS_DataWriter _this,
const <data> *instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t *source_timestamp);
```
# 3.4.2.31 Class SPACE\_FooDataWriter
The pre-processor generates from IDL type descriptions the application <NameSpace>\_<type>DataWriter classes. For each application data type that is used as DDS\_Topic data type, a typed class <NameSpace>\_<type>DataWriter is derived from the DDS\_DataWriter class. In this paragraph, the class SPACE\_FooDataWriter describes the operations of these derived <NameSpace>\_<type>DataWriter classes as an example for the fictional application type Foo (defined in the module SPACE).
For instance, for an application, the definitions are located in the Space.idl file. The pre-processor will generate a Space.h include file.
A SPACE\_FooDataWriter is attached to exactly one DDS\_Publisher which acts as a factory for it. The SPACE\_FooDataWriter is bound to exactly one DDS\_Topic that has been registered to use a data type Foo (defined in the module SPACE). The DDS\_Topic must exist prior to the SPACE\_FooDataWriter creation.
The interface description of this class is as follows:
```c
/*
* interface SPACE_FooDataWriter
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* SPACE_FooDataWriter_get_statuscondition
* (SPACE_FooDataWriter _this);
*/
/* DDS_StatusMask
```
```c
* SPACE_FooDataWriter_get_status_changes
* (SPACE_FooDataWriter _this);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_enable
* (SPACE_FooDataWriter _this);
*/
/*
* inherited from class DDS_DataWriter
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_set_qos
* (SPACE_FooDataWriter _this,
* const DDS_DataWriterQos *qos);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_qos
* (SPACE_FooDataWriter _this,
* SPACE_FooDataWriterQos *qos);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_set_listener
* (SPACE_FooDataWriter _this,
* const struct DDS_DataWriterListener *a_listener,
* const DDS_StatusMask mask);
*/
/* struct SPACE_FooDataWriterListener
* SPACE_FooDataWriter_get_listener
* (SPACE_FooDataWriter _this);
*/
/* DDS_Topic
* SPACE_FooDataWriter_get_topic
* (SPACE_FooDataWriter _this);
*/
/* DDS_Publisher
* SPACE_FooDataWriter_get_publisher
* (SPACE_FooDataWriter _this);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_wait_for_acknowledgments
* (DDS_DataWriter _this,
* const DDS_Duration_t *max_wait);
*/
```
```c
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_liveliness_lost_status
* (SPACE_FooDataWriter _this,
* DDS_LivelinessLostStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_offered_deadline_missed_status
* (SPACE_FooDataWriter _this,
* DDS_OfferedDeadlineMissedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_offered_incompatible_qos_status
* (SPACE_FooDataWriter _this,
* DDS_OfferedIncompatibleQosStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_publication_matched_status
* (SPACE_FooDataWriter _this,
* DDS_PublicationMatchedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_assert_liveliness
* (SPACE_FooDataWriter _this);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_matched_subscriptions
* (SPACE_FooDataWriter _this,
* DDS_InstanceHandleSeq *subscription_handles);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataWriter_get_matched_subscription_data
* (SPACE_FooDataWriter _this,
* DDS_SubscriptionBuiltinTopicData *subscription_data,
* const DDS_InstanceHandle_t subscription_handle);
*/
/*
* implemented API operations
*/
DDS_InstanceHandle_t
SPACE_FooDataWriter_register_instance
(SPACE_FooDataWriter _this,
const Foo *instance_data);
DDS_InstanceHandle_t
SPACE_FooDataWriter_register_instance_w_timestamp
```
```c
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_Time_t *source_timestamp);
DDS_ReturnCode_t
SPACE_FooDataWriter_unregister_instance
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
SPACE_FooDataWriter_unregister_instance_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
DDS_ReturnCode_t
SPACE_FooDataWriter_write
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle);
DDS_ReturnCode_t
SPACE_FooDataWriter_write_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
DDS_ReturnCode_t
SPACE_FooDataWriter_dispose
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle);
DDS_ReturnCode_t
SPACE_FooDataWriter_dispose_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t *source_timestamp);
DDS_ReturnCode_t
SPACE_FooDataWriter_writedispose
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle);
DDS_ReturnCode_t
SPACE_FooDataWriter_writedispose_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t *source_timestamp);
DDS_ReturnCode_t
SPACE_FooDataWriter_get_key_value
(SPACE_FooDataWriter _this,
```
```c
Foo *key_holder,
const DDS_InstanceHandle_t handle);
DDS_InstanceHandle_t
SPACE_FooDataWriter_lookup_instance
(SPACE_FooDataWriter _this,
Foo *instance_data);
```
The next paragraphs describe the usage of all SPACE\_FooDataWriter operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.4.2.32 SPACE\_FooDataWriter\_assert\_liveliness (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_assert_liveliness
(SPACE_FooDataWriter _this);
```
# 3.4.2.33 SPACE\_FooDataWriter\_dispose
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_dispose
SPACE_FooDataWriter_this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle);
```
# Description
This operation requests the Data Distribution Service to mark the instance for deletion.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the actual instance to be disposed of.
in const DDS\_InstanceHandle\_t instance\_handle - the handle to the instance to be disposed of.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation requests the Data Distribution Service to mark the instance for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DDS\_DataReader and, dependent on the QoSPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their DDS\_InstanceStateKind to DDS\_NOT\_ALIVE\_DISPOSED\_INSTANCE\_ STATE.
When this operation is used, the Data Distribution Service will automatically supply the value of the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DDS\_DataWriter itself and on the containing DDS\_DomainParticipant.
# Effects on DataReaders
Actual deletion of the instance administration in a connected DDS\_DataReader will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DDS\_DataWriters that have previously registered it
- A DDS\_DataWriter can register an instance explicitly by using one of the special operations SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp.
- A DDS\_DataWriter can register an instance implicitly by using the special constant DDS\_HANDLE\_NIL in any of the other DDS\_DataWriter operations.
- A DDS\_DataWriter can unregister an instance explicitly by using one of the special operations SPACE\_FooDataWriter\_unregister\_instance or SPACE\_FooDataWriter\_unregister\_instance\_w\_timestamp.
- A DDS\_DataWriter will unregister all its contained instances implicitly when it is deleted.
\- When a DDS\_DataReader detects a loss of liveliness in one of its connected DDS\_DataWriters, it will consider all instances registered by that DDS\_DataWriter as being implicitly unregistered.
• and the application must have consumed all samples belonging to the instance, either implicitly or explicitly.
\- An application can consume samples explicitly by invoking the SPACE\_FooDataReader\_take operation, or one of its variants.
\- The DDS\_DataReader can consume disposed samples implicitly when the autopurge\_disposed\_samples\_delay of the DDS\_ReaderData LifecycleQosPolicy has expired.
The DDS\_DataReader may also remove instances that haven’t been disposed first: this happens when the autopurge\_nowriter\_samples\_delay of the DDS\_ReaderDataLifecycleQosPolicy has expired after the instance is considered unregistered by all connected DDS\_DataWriters (i.e. when it has a DDS\_InstanceStateKind of DDS\_NOT\_ALIVE\_NO\_WRITERS). See also Section 3.1.3.15, DDS\_ReaderDataLifecycleQosPolicy, on page 99.
# Effects on Transient/Persistent Stores
Actual deletion of the instance administration in the connected Transient and Persistent stores will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DDS\_DataWriters that have previously registered it. (See above.)
• and the period of time specified by the service\_cleanup\_delay attribute in the DDS\_DurabilityServiceQosPolicy on the DDS\_Topic must have elapsed after the instance is considered unregistered by all connected DDS\_DataWriters.
See also Section 3.1.3.4, DDS\_DurabilityServiceQosPolicy, on page 76.
# Instance Handle
The D DS \_ H A N D L E \_N I L handle value can be used for th e parameter instance\_handle. This indicates the identity of the instance is automatically deduced from the instance\_data (by means of the key).
If instance\_handle is any value other than DDS\_HANDLE\_NIL, then it must c o r r e s p o n d t o t h e v a l u e t h a t w a s r e t u r n e d b y e i t h e r t h e SPACE\_FooDataWriter\_register\_instance operation or the SPACE\_FooDataWriter\_register\_instance\_w\_timestamp operation when the instance (identified by its key) was registered. If there is no correspondence, then the result of the operation is unspecified.
The sample that is passed as instance\_data is only used to check for consistency between its key values and the supplied instance\_handle: the sample itself will not actually be delivered to the connected DDS\_DataReaders. Use the SPACE\_FooDataWriter\_writedispose operation if the sample itself should be delivered together with the dispose request.
# Blocking
If the DDS\_HistoryQosPolicy is set to DDS\_KEEP\_ALL\_HISTORY\_QOS, the SPACE\_FooDataWriter\_dispose operation on the DDS\_DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the DDS\_ResourceLimitsQosPolicy, to be exceeded. Under these c i r c u m s t a n c e s , t h e m a x \_ b l o c k i n g \_ t i m e a t t r i b u t e o f t h e R e li a b i l i ty Q o s P o l ic y c o n f i g u r e s t h e m a x i m u m t i m e t h e SPACE\_FooDataWriter\_dispose operation may block (waiting for space to become available). If max\_blocking\_time elapses before the DDS\_DataWriter i s a b l e t o s t o r e t h e m o d i f i c a t i o n w i t h o u t e x c e e d i n g t h e l i m i t s , t h e SPACE\_FooDataWriter\_dispose operation will fail and returns DDS\_RETCODE\_TIMEOUT.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```cpp
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
#endif
```
i By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Since the SPACE\_FooDataWriter\_dispose operation only uses the sample to check for consistency between its key values and the supplied instance\_handle, only those keyfields will be validated against the restrictions imposed by the IDL to C language mapping, where:
• an enum may not exceed the value of its highest label
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead)
• the length of a bounded string may not exceed the limit specified in IDL
If any of these restrictions is violated when validity checking is enabled, then the operation will fail and return a DDS\_RETCODE\_BAD\_PARAMETER. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service is informed that the instance data must be disposed of.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - instance\_handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the instance\_handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy. This caused blocking of the SPACE\_FooDataWriter\_dispose operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.34 SPACE\_FooDataWriter\_dispose\_w\_timestamp
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_dispose_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t instance_handle,
const DDS_Time_t *source_timestamp);
```
# Description
This operation requests the Data Distribution Service to mark the instance for deletion and provides a value for the source\_timestamp explicitly.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the actual instance to be disposed of.
in const DDS\_InstanceHandle\_t instance\_handle - the handle to the instance to be disposed of.
in const DDS\_Time\_t \*source\_timestamp - the timestamp which is provided for the DDS\_DataReader.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_TIMEOUT.
# Detailed Description
This operation performs the same functions as SPACE\_FooDataWriter\_dispose except that the application provides the value for the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service is informed that the instance data must be disposed of.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - instance\_handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the instance\_handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy. This caused blocking of the SPACE\_FooDataWriter\_dispose\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.35 SPACE\_FooDataWriter\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FoodataWriter_enable
(SPACE_FoodataWriter _this);
```
# 3.4.2.36 SPACE\_FooDataWriter\_get\_key\_value
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_key_value
(SPACE_FooDataWriter _this,
Foo *key_holder,
const DDS_InstanceHandle_t handle);
```
# Description
This operation retrieves the key value of a specific instance.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
inout Foo \*key\_holder - the sample in which the key values are stored.
in const DDS\_InstanceHandle\_t handle - the handle to the instance from which to get the key value.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation retrieves the key value of the instance pointed to by instance\_handle. When the operation is called with an DDS\_HANDLE\_NIL h a n d l e v a l u e a s a n i n s t a n c e \_ h a n d l e , t h e o p e r a t i o n w i l l r e t u r n DDS\_RETCODE\_BAD\_PARAMETER. The operation will only fill the fields that form the key inside the key\_holder instance. This means that the non-key fields are not applicable and may contain garbage.
The operation must only be called on registered instances. Otherwise the operation returns the error DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the key\_holder instance contains the key values of the instance.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or key\_holder is not a valid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - this instance is not registered.
# 3.4.2.37 SPACE\_FooDataWriter\_get\_listener (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
```
```txt
struct SPACE_FooDataWriterListener
SPACE_FooDataWriter_get_listener
(SPACE_FooDataWriter _this);
```
# 3.4.2.38 SPACE\_FooDataWriter\_get\_liveliness\_lost\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_liveliness_lost_status
(SPACE_FooDataWriter_this,
DDS_LivelinessLostStatus *status);
```
# 3.4.2.39 SPACE\_FooDataWriter\_get\_matched\_subscription\_data (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_matched_subscription_data
(SPACE_FooDataWriter _this,
DDS_SubscriptionBuiltinTopicData *subscription_data,
const DDS_InstanceHandle_t subscription_handle);
```
# 3.4.2.40 SPACE\_FooDataWriter\_get\_matched\_subscriptions (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_matched_subscriptions
(SPACE_FooDataWriter _this,
DDS_InstanceHandleSeq *subscription_handles);
```
# 3.4.2.41 SPACE\_FooDataWriter\_get\_offered\_deadline\_missed\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
```
```txt
DDS_ReturnCode_t
SPACE_FooDataWriter_get_offered_deadline_missed_status
(SPACE_FooDataWriter _this,
DDS_OfferedDeadlineMissedStatus *status);
```
# 3.4.2.42 SPACE\_FooDataWriter\_get\_offered\_incompatible\_qos\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_offered_incompatible_qos_status
(SPACE_FooDataWriter _this,
DDS_OfferedIncompatibleQosStatus *status);
```
# 3.4.2.43 SPACE\_FooDataWriter\_get\_publication\_matched\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_get_publication_matched_status
(SPACE_FooDataWriter _this,
DDS_PublicationMatchedStatus *status);
```
# 3.4.2.44 SPACE\_FooDataWriter\_get\_publisher (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_Publisher
SPACE_FooDataWriter_get_publisher
(SPACE_FooDataWriter_this);
```
# 3.4.2.45 SPACE\_FooDataWriter\_get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
```
```txt
SPACE_FooDataWriter_get_qos
(SPACE_FooDataWriter_this,
SPACE_FooDataWriterQos *qos);
```
# 3.4.2.46 SPACE\_FooDataWriter\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusMask
SPACE_FoodataWriter_get_status_changes
(SPACE_FoodataWriter_this);
```
# 3.4.2.47 SPACE\_FooDataWriter\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusCondition
SPACE_FooDataWriter_get_statuscondition
(SPACE_FooDataWriter _this);
```
# 3.4.2.48 SPACE\_FooDataWriter\_get\_topic (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_Topic
SPACE_FoodataWriter_get_topic
(SPACE_FoodataWriter _this);
```
# 3.4.2.49 SPACE\_FooDataWriter\_lookup\_instance
# Synopsis
```c
#include <Space.h>
DDS_InstanceHandle_t
SPACE_FooDataWriter_lookup_instance
(SPACE_FooDataWriter _this,
Foo *instance_data);
```
# Description
This operation returns the value of the instance handle which corresponds to the instance\_data.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in Foo \*instance\_data - the instance for which the corresponding instance handle needs to be looked up.
# Return Value
DDS\_InstanceHandle\_t - Result value is the instance handle which corresponds to the instance\_data.
# Detailed Description
This operation returns the value of the instance handle which corresponds to the instance\_data. The instance\_data parameter is only used for the purpose of examining the fields that define the key. The instance handle can be used in any write, dispose or unregister operations (or their timestamped variants) that operate on a specific instance. Note that DDS\_DataWriter instance handles are local, and are not interchangeable with DDS\_DataReader instance handles nor with instance handles of an other DDS\_DataWriter.
This operation does not register the instance in question. If the instance has not been previously registered, if the DDS\_DataWriter is already deleted or if for any other reason the Service is unable to provide an instance handle, the Service will return the special value DDS\_HANDLE\_NIL.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```cpp
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
#endif
```
i
By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Since the SPACE\_FooDataWriter\_lookup\_instance operation merely uses the sample to determine its identity based on the uniqueness of its key values, only the keyfields will be validated against the restrictions imposed by the IDL to C language mapping, where:
• an enum may not exceed the value of its highest label
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead)
• the length of a bounded string may not exceed the limit specified in IDL
If any of these restrictions is violated when validity checking is enabled, then the operation will fail and return a DDS\_HANDLE\_NIL. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
# 3.4.2.50 SPACE\_FooDataWriter\_register\_instance
# Synopsis
```c
#include <Space.h>
DDS_InstanceHandle_t
SPACE_FooDataWriter_register_instance
(SPACE_FooDataWriter _this,
const Foo *instance_data);
```
# Description
This operation informs the Data Distribution Service that the application will be modifying a particular instance.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the new instance, which the application writes to or disposes of.
# Return Value
DDS\_InstanceHandle\_t - Result value is the handle to the Instance, which may be used for writing and disposing of. In case of an error, a DDS\_HANDLE\_NIL handle value is returned.
# Detailed Description
This operation informs the Data Distribution Service that the application will be modifying a particular instance. This operation may be invoked prior to calling any operation that modifies the instance, such as SPACE\_FooDataWriter\_write,
SPACE\_FooDataWriter\_write\_w\_timestamp, SPACE\_FooData Writer\_unregister\_instance, SPACE\_FooDataWriter\_unregister\_ instance\_w\_timestamp, SPACE\_FooDataWriter\_dispose, SPACE\_FooDataWriter\_dispose\_w\_timestamp, SPACE\_FooDataWriter\_ writedispose and SPACE\_FooDataWriter\_writedispose\_w\_timestamp. When the application does register the instance before modifying, the Data Distribution Service will handle the instance more efficiently. It takes as a parameter (instance\_data) an instance (to get the key value) and returns a handle that can be used in successive DDS\_DataWriter operations. In case of an error, a DDS\_HANDLE\_NIL handle value is returned.
The explicit use of this operation is optional as the application can directly call the SPACE\_FooDataWriter\_write, SPACE\_FooDataWriter\_write\_ w\_timestamp, SPACE\_FooDataWriter\_unregister\_instance, SPACE\_FooDataWriter\_unregister\_instance\_w\_timestamp, SPACE\_FooDataWriter\_dispose, SPACE\_FooDataWriter dispose\_w\_timestamp, SPACE\_FooDataWriter\_writedispose and SPACE\_FooDataWriter\_writedispose\_w\_timestamp operations and specify a DDS\_HANDLE\_NIL handle value to indicate that the sample should be examined to identify the instance.
When this operation is used, the Data Distribution Service will automatically supply the value of the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Blocking
If the DDS\_HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the SPACE\_FooDataWriter\_register\_instance operation on the DDS\_DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the DDS\_ResourceLimitsQosPolicy, to b e e x c e e d e d . I n c a s e t h e s y n c h r o n o u s a t t r i b u t e v a l u e o f t h e ReliabilityQosPolicy is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max\_blocking\_time attribute of the ReliabilityQosPolicy configures the maximum time the SPACE\_FooDataWriter\_register\_instance operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DDS\_DataWriter is able to store the modification without exceeding the limits and all expected acknowledgeme nts are receive d, the S PA C E \_ F o oD a t a W r i te r \_ register\_instance operation will fail and returns DDS\_HANDLE\_NIL.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```cpp
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
#endif
```
i By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Since the SPACE\_FooDataWriter\_register\_instance operation merely uses the sample to determine its identity based on the uniqueness of its key values, only the keyfields will be validated against the restrictions imposed by the IDL to C language mapping, where:
• an enum may not exceed the value of its highest label
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead)
• the length of a bounded string may not exceed the limit specified in IDL
If any of these restrictions is violated when validity checking is enabled, then the operation will fail and return a DDS\_HANDLE\_NIL. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
# Multiple Calls
If this operation is called for an already registered instance, it just returns the already allocated instance handle. This may be used to look up and retrieve the handle allocated to a given instance.
# 3.4.2.51 SPACE\_FooDataWriter\_register\_instance\_w\_timestamp
# Synopsis
```c
#include <Space.h>
DDS_InstanceHandle_t
SPACE_FooDataWriter_register_instance_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_Time_t *source_timestamp);
```
# Description
This operation will inform the Data Distribution Service that the application will be modifying a particular instance and provides a value for the source\_timestamp explicitly.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in Foo \*instance\_data - the instance, which the application will write to or dispose of.
in const DDS\_Time\_t \*source\_timestamp - the timestamp used.
# Return Value
DDS\_InstanceHandle\_t - Result value is the handle to the Instance, which must be used for writing and disposing. In case of an error, a DDS\_HANDLE\_NIL handle value is returned.
# Detailed Description
T h i s o p e r a t i o n p e r f o r m s t h e s a m e f u n c t i o n s a s SPACE\_FooDataWriter\_register\_instance except that the application provides the value for the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Multiple Calls
If this operation is called for an already registered instance, it just returns the already allocated instance handle. This may be used to look up and retrieve the handle allocated to a given instance. The source\_timestamp is ignored in that case.
# 3.4.2.52 SPACE\_FooDataWriter\_set\_listener (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_set_listener
(SPACE_FooDataWriter_this,
const struct DDS_DataWriterListener *a_listener,
const DDS_StatusMask mask);
```
# 3.4.2.53 SPACE\_FooDataWriter\_set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_set_qos
(SPACE_FooDataWriter _this,
const DDS_DataWriterQos *qos);
```
# 3.4.2.54 SPACE\_FooDataWriter\_unregister\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_unregister_instance
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle);
```
# Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the instance to which the application was writing or disposing.
in const DDS\_InstanceHandle\_t handle - the handle to the instance that has been used for writing and disposing.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_TIMEOUT.
# Detailed Description
This operation informs the Data Distribution Service that the application will not be modifying a particular instance any more. Therefore, this operation reverses the action of SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp. It should only be called on an instance that is currently registered. This operation should be c a l l e d j u s t o n c e p e r i n s t a n c e , r e g a r d l e s s o f h o w m a n y t i m e s SPACE\_FooDataWriter\_register\_instance was called for that instance. This operation also indicates that the Data Distribution Service can locally remove all information regarding that instance. The application should not attempt to use the handle, previously allocated to that instance, after calling this operation.
When this operation is used, the Data Distribution Service will automatically supply the value of the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Effects
If, after unregistering, the application wants to modify (write or dispose) the instance, it first has to register the instance again, or it has to use the special handle value DDS\_HANDLE\_NIL.
This operation does not indicate that the instance should be deleted (that is the purpose of SPACE\_FooDataWriter\_dispose). This operation just indicates that the DDS\_DataWriter no longer has “anything to say” about the instance. If there is no other DDS\_DataWriter that has registered the instance as well, then the DDS\_InstanceStateKind in all connected DDS\_DataReaders will be changed to DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE, provided this DDS\_InstanceStateKind w a s n o t a l r e a d y s e t t o DDS\_NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE. In the last case the D D S\_ I n s t a nc e S t a t e Ki n d w i l l n o t b e e ff e c t e d b y t h e SPACE\_FooDataWriter\_unregister\_instance call, see also Figure 21:, State Chart of the instance\_state for a Single Instance, on page 632.
This operation can affect the ownership of the data instance. If the DDS\_DataWriter was the exclusive owner of the instance, calling this operation will release that ownership, meaning ownership may be transferred to another, possibly lower strength, DDS\_DataWriter.
The operation must be called only on registered instances. Otherwise the operation returns the error DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Instance Handle
The DDS\_HANDLE\_NIL handle value can be used for the parameter handle. This indicates that the identity of the instance is automatically deduced from the instance\_data (by means of the key).
If handle is any value other than DDS\_HANDLE\_NIL, then it must correspond to the value returned by SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp when the instance (identified by its key) was registered. If there is no correspondence, then the result of the operation is unspecified.
The sample that is passed as instance\_data is used to check for consistency between its key values and the supplied instance\_handle: the sample itself will not actually be delivered to the connected DDS\_DataReaders.
# Blocking
If the DDS\_HistoryQosPolicy is set to DDS\_KEEP\_ALL\_HISTORY\_QOS, then the SPACE\_FooDataWriter\_unregister\_instance operation on the DDS\_DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the DDS\_ResourceLimitsQosPolicy, to b e e x c e e d e d . I n c a s e t h e s y n c h r o n o u s a t t r i b u t e v a l u e o f t h e ReliabilityQosPolicy is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the max\_blocking\_time attribute of the ReliabilityQosPolicy configures the maximum time the SPACE\_FooDataWriter\_unregister\_instance operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DDS\_DataWriter is able to store the modification without exceeding the limits and all expected a c k n o w l e d g e m e n t s a r e r e c e i v e d , t h e
SPACE\_FooDataWriter\_unregister\_instance operation will fail and returns DDS\_RETCODE\_TIMEOUT.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```cpp
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
#endif
```
# i
By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Since the SPACE\_FooDataWriter\_unregister\_instance operation merely uses the sample to check for consistency between its key values and the supplied instance\_handle, only these keyfields will be validated against the restrictions imposed by the IDL to C language mapping:
• an enum may not exceed the value of its highest label.
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead).
• the length of a bounded string may not exceed the limit specified in IDL.
If any of these restrictions is violated when validity checking is enabled, the operation will fail and return a DDS\_RETCODE\_BAD\_PARAMETER. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service is informed that the instance will not be modified any more.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the
SPACE\_FooDataWriter\_unregister\_instance\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.55 SPACE\_FooDataWriter\_unregister\_instance\_w\_timestamp
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_unregister_instance_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
```
# Description
This operation will inform the Data Distribution Service that the application will not be modifying a particular instance any more and provides a value for the source\_timestamp explicitly.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in Foo \*instance\_data - the instance to which the application was writing or disposing.
in const DDS\_InstanceHandle\_t handle - the handle to the instance that has been used for writing and disposing.
in const DDS\_Time\_t \*source\_timestamp - the timestamp used.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
T h i s o p e r a t i o n p e r f o r m s t h e s a m e f u n c t i o n s a s SPACE\_FooDataWriter\_unregister\_instance except that the application provides the value for the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service is informed that the instance will not be modified any more.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy. This caused blocking of the SPACE\_FooDataWriter\_unregister\_ instance\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.56 SPACE\_FooDataWriter\_wait\_for\_acknowledgments (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataWriter for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_wait_for_acknowledgments
(SPACE_FooDataWriter _this,
```
const DDS\_Duration\_t \*max\_wait);
# 3.4.2.57 SPACE\_FooDataWriter\_write
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_write
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle);
```
# Description
This operation modifies the value of a data instance.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the data to be written.
in const DDS\_InstanceHandle\_t handle - the handle to the instance as supplied by SPACE\_FooDataWriter\_register\_instance.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation modifies the value of a data instance. When this operation is used, the Data Distribution Service will automatically supply the value of the source\_timestamp that is made available to connected DDS\_DataReader o b j e c t s . T h i s t i m e s t a m p i s i m p o r t a n t f o r t h e i n t e r p r e t a t i o n o f t h e DDS\_DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DDS\_DataWriter itself and on the containing DDS\_DomainParticipant.
Before writing data to an instance, the instance may be registered with the SPACE\_FooDataWriter\_register\_instance o r SPACE\_FooDataWriter\_register\_instance\_w\_timestamp operation. The handle returned by one of the SPACE\_FooDataWriter\_register\_instance o p e r a t i o n s c a n b e s u p p l i e d t o t h e p a r a m e t e r h a n d l e o f t h e SPACE\_FooDataWriter\_write operation. However, it is also possible to supply the special DDS\_HANDLE\_NIL handle value, which means that the identity of the instance is automatically deduced from the instance\_data (identified by the key).
# Instance Handle
The DDS\_HANDLE\_NIL handle value can be used for the parameter handle. This indicates the identity of the instance is automatically deduced from the instance\_data (by means of the key).
If handle is any value other than DDS\_HANDLE\_NIL, it must correspond to the value returned by SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently. If there is no correspondence between handle and sample, the result of the operation is unspecified.
# Blocking
If the DDS\_HistoryQosPolicy is set to DDS\_KEEP\_ALL\_HISTORY\_QOS, the SPACE\_FooDataWriter\_write operation on the DDS\_DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the DDS\_ResourceLimitsQosPolicy, is exceeded. In case the synchronous attribute value of the ReliabilityQosPolicy is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these c i r c u m s t a n c e s , t h e m a x \_ b l o c k i n g \_ t i m e a t t r i b u t e o f t h e R e li a b i l i ty Q o s P o l ic y c o n f i g u r e s t h e m a x i m u m t i m e t h e SPACE\_FooDataWriter\_write operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DDS\_DataWriter is able to store the modification without exceeding t h e l i m i t s a n d a l l e x p e c t e d a c k n o w l e d g e m e n t s a r e r e c e i v e d , t h e S P AC E \_ F o o Da t a W r i t er \_ w r i t e o p e r a ti o n w i l l f a il a n d r e t u r n s DDS\_RETCODE\_TIMEOUT.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```txt
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
```
# #endif
i By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Before the sample is accepted by the DataWriter, it is validated against the restrictions imposed by the IDL to C language mapping:
• an enum may not exceed the value of its highest label.
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead).
• the length of a bounded string may not exceed the limit specified in IDL.
• the length of a bounded sequence may not exceed the limit specified in IDL.
If any of these restrictions is violated when validity checking is enabled, the operation will fail and return a DDS\_RETCODE\_BAD\_PARAMETER. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
4 Be aware that it is not possible for the middleware to determine whether a union is correctly initialized, since according to the IDL-C language mapping a union just returns its current contents in the format of the requested branch without performing any checks. It is therefore the responsibility of the application programmer to make sure that the requested branch actually corresponds to the currently active branch. Not doing so may result in undefined behaviour as well.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the value of a data instance is modified.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the SPACE\_FooDataWriter\_write operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.58 SPACE\_FooDataWriter\_write\_w\_timestamp
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_write_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
```
# Description
This operation modifies the value of a data instance and provides a value for the source\_timestamp explicitly.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the data to be written.
in const DDS\_InstanceHandle\_t handle - the handle to the instance as supplied by SPACE\_FooDataWriter\_register\_instance.
in const DDS\_Time\_t \*source\_timestamp - the timestamp used.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation performs the same functions as SPACE\_FooDataWriter\_write except that the application provides the value for the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the value of a data instance is modified.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the instance\_data does not correspond to the handle that should have been obtained from this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the SPACE\_FooDataWriter\_register\_instance\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.59 SPACE\_FooDataWriter\_writedispose
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_writedispose
(SPACE_FooDataWriter_this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle);
```
# Description
This operation modifies and disposes a data instance.
# Parameters
in SPACE\_FooDataWriter \_this - the SPACE\_FooDataWriter object on which the operation is operated.
in const Foo \*instance\_data - the data to be written and disposed.
in const DDS\_InstanceHandle\_t instance - the handle to the instance as supplied by SPACE\_FooDataWriter\_register\_instance.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
This operation requests the Data Distribution Service to modify the instance and mark it for deletion. Copies of the instance and its corresponding samples, which are stored in every connected DDS\_DataReader and, dependent on the QoSPolicy settings, also in the Transient and Persistent stores, will be modified and marked for deletion by setting their DDS\_InstanceStateKind to DDS\_NOT\_ALIVE\_ DISPOSED\_INSTANCE\_STATE.
When this operation is used, the Data Distribution Service will automatically supply the value of the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DDS\_DataWriter itself and on the containing DDS\_DomainParticipant.
# Effects on DataReaders
Actual deletion of the instance administration in a connected DDS\_DataReader will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DDS\_DataWriters that have previously registered it.
- A DDS\_DataWriter can register an instance explicitly by using one of the special operations SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp.
- A DDS\_DataWriter can register an instance implicitly by using the special constant DDS\_HANDLE\_NIL in any of the other DDS\_DataWriter operations.
- A DDS\_DataWriter can unregister an instance explicitly by using one of the special operations SPACE\_FooDataWriter\_unregister\_instance or SPACE\_FooDataWriter\_unregister\_ instance\_w\_timestamp.
- A DDS\_DataWriter will unregister all its contained instances implicitly when it is deleted.
- When a DDS\_DataReader detects a loss of liveliness in one of its connected DDS\_DataWriters, it will consider all instances registered by that DDS\_DataWriter as being implicitly unregistered.
• and the application must have consumed all samples belonging to the instance, either implicitly or explicitly.
- An application can consume samples explicitly by invoking the SPACE\_FooDataReader\_take operation, or one of its variants.
- The DDS\_DataReader can consume disposed samples implicitly when the autopurge\_disposed\_samples\_delay of the DDS\_ReaderData LifecycleQosPolicy has expired.
The DDS\_DataReader may also remove instances that haven’t been disposed first: this happens when the autopurge\_nowriter\_samples\_delay of the DDS\_ReaderDataLifecycleQosPolicy has expired after the instance is considered unregistered by all connected DDS\_DataWriters (i.e. when it has a DDS\_InstanceStateKind of DDS\_NOT\_ALIVE\_NO\_WRITERS). See also Section 3.1.3.15, DDS\_ReaderDataLifecycleQosPolicy, on page 99.
# Effects on Transient/Persistent Stores
Actual deletion of the instance administration in the connected Transient and Persistent stores will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DDS\_DataWriters that have previously registered it. (See above.)
• and the period of time specified by the service\_cleanup\_delay attribute in the DDS\_DurabilityServiceQosPolicy on the DDS\_Topic must have elapsed after the instance is considered unregistered by all connected DDS\_DataWriters.
See also Section 3.1.3.4, DDS\_DurabilityServiceQosPolicy, on page 76.
# Instance Handle
The DDS\_HANDLE\_NIL handle value can be used for the parameter handle. This indicates the identity of the instance is automatically deduced from the instance\_data (by means of the key).
If handle is any value other than DDS\_HANDLE\_NIL, it must correspond to the value returned by SPACE\_FooDataWriter\_register\_instance or SPACE\_FooDataWriter\_register\_instance\_w\_timestamp when the instance (identified by its key) was registered. Passing such a registered handle helps the Data Distribution Service to process the sample more efficiently. If there is no correspondence between handle and sample, the result of the operation is unspecified.
The sample that is passed as instance\_data will actually be delivered to the connected DDS\_DataReaders, but will immediately be marked for deletion.
# Blocking
If the DDS\_HistoryQosPolicy is set to DDS\_KEEP\_ALL\_HISTORY\_QOS, the SPACE\_FooDataWriter\_writedispose operation on the DDS\_DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the DDS\_ResourceLimitsQosPolicy, to be exceeded. In case the synchronous attribute value of the ReliabilityQosPolicy is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these c i r c u m s t a n c e s , t h e m a x \_ b l o c k i n g \_ t i m e a t t r i b u t e o f t h e R e li a b i l i ty Q o s P o l ic y c o n f i g u r e s t h e m a x i m u m t i m e t h e SPACE\_FooDataWriter\_writedispose operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DDS\_DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the SPACE\_FooDataWriter\_writedispose operation will fail and returns DDS\_RETCODE\_TIMEOUT.
# Sample Validation
OpenSplice offers the possibility to check the sample that is passed as instance\_data for validity. Because validity checking might reduce the overall performance, it is by default disabled. This has been done by enclosing the validity checking with conditional compiler directives like this:
```cpp
#ifdef OSPL_BOUNDS_CHECK
// check a specific bound.
#endif
```
i By defining a macro called OSPL\_OSPL\_BOUNDS\_CHECK, the validity checking will be included. On most compilers this macro can be defined by passing an additional command line parameter called -DOSPL\_BOUNDS\_CHECK.
Before the sample is accepted by the DataWriter, it is validated against the restrictions imposed by the IDL to C language mapping, where:
• an enum may not exceed the value of its highest label
• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string instead)
• the length of a bounded string may not exceed the limit specified in IDL
• the length of a bounded sequence may not exceed the limit specified in IDL
If any of these restrictions is violated when validity checking is enabled, the operation will fail and return a DDS\_RETCODE\_BAD\_PARAMETER. More specific information about the context of this error will be written to the error log. When validity checking is disabled, any of these violations may result in undefined behaviour.
4 Be aware that it is not possible for the middleware to determine whether a union is correctly initialized, since according to the IDL-C language mapping a union just returns its current contents in the format of the requested branch without performing any checks. It is therefore the responsibility of the application programmer to make sure that the requested branch actually corresponds to the currently active branch. Not doing so may result in undefined behaviour as well.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service has modified the instance and marked it for deletion.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - instance\_handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the instance\_handle has not been registered with this SPACE\_FooDataWriter.
• DDS\_RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the SPACE\_FooDataWriter\_writedispose operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.2.60 SPACE\_FooDataWriter\_writedispose\_w\_timestamp
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataWriter_writedispose_w_timestamp
(SPACE_FooDataWriter _this,
const Foo *instance_data,
const DDS_InstanceHandle_t handle,
const DDS_Time_t *source_timestamp);
```
# Description
This operation requests the Data Distribution Service to modify the instance and mark it for deletion, and provides a value for the source\_timestamp explicitly.
# Parameters
```txt
in SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on which the operation is operated.
in const Foo *instance_data - the data to be written and disposed.
in const DDS_InstanceHandle_t handle - the handle to the instance as supplied by SPACE_FooDataWriter_register_instance.
in const DDS_Time_t *source_timestamp - the timestamp used.
```
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_TIMEOUT.
```
# Detailed Description
T h i s o p e r a t i o n p e r f o r m s t h e s a m e f u n c t i o n s a s SPACE\_FooDataWriter\_writedispose except that the application provides the value for the source\_timestamp that is made available to connected DDS\_DataReader objects. This timestamp is important for the interpretation of the DDS\_DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the Data Distribution Service has modified the instance and marked it for deletion.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataWriter has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataWriter is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
DDS\_RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the DDS\_ReliabilityQosPolicy, DDS\_HistoryQosPolicy and DDS\_ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the SPACE\_FooDataWriter\_writedispose\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the DDS\_ReliabilityQosPolicy elapsed.
# 3.4.3 DDS\_PublisherListener interface
Since a DDS\_Publisher is a DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_PublisherListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DDS\_PublisherListener class. All DDS\_PublisherListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The DDS\_PublisherListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The DDS\_PublisherListener is related to changes in communication status.
The interface description of this class is as follows:
```c
/*
* interface DDS_PublisherListener
*/
/*
* inherited from DDS_DataWriterListener
*/
/* void
* DDS_PublisherListener_on_offered_deadline_missed
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedDeadlineMissedStatus *status);
*/
/* void
* DDS_PublisherListener_on_offered_incompatible_qos
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_OfferedIncompatibleQosStatus *status);
*/
/* void
* DDS_PublisherListener_on_liveliness_lost
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_LivelinessLostStatus *status);
*/
/* void
* DDS_PublisherListener_on_publication_matched
* (void *listener_data,
* DDS_DataWriter writer,
* const DDS_PublicationMatchedStatus *status);
*/
/*
* implemented API operations
```
```c
*/
struct DDS_PublisherListener *
DDS_PublisherListener_alloc
(void);
```
The next paragraphs list all DDS\_PublisherListener operations. Since these operations are all inherited, they are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.4.3.1 DDS\_PublisherListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_PublisherListener *
DDS_PublisherListener_alloc
(void);
```
# Description
This operation creates a new DDS\_PublisherListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_PublisherListener \* - the handle to the newly-created DDS\_PublisherListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
T h i s o p e r a t i o n c r e a t e s a n e w D D S\_ P u b l i s he r L i s t en e r. Th e DDS\_PublisherListener must be created using this operation. In other words, t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p e DDS\_PublisherListener. When the application wants to release the DDS\_PublisherListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_PublisherListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.4.3.2 DDS\_PublisherListener\_on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
```
```c
void
DDS_PublisherListener_on_liveliness_lost
(void *listener_data,
DDS_DataWriter writer,
const DDS_LivelinessLostStatus *status);
```
# 3.4.3.3 DDS\_PublisherListener\_on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_PublisherListener_on_offered_deadline_missed
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedDeadlineMissedStatus *status);
```
# 3.4.3.4 DDS\_PublisherListener\_on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_PublisherListener_on_offered_incompatible_qos
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedIncompatibleQosStatus *status);
```
# 3.4.3.5 DDS\_PublisherListener\_on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataWriterListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_PublisherListener_on_publication_matched
(void *listener_data,
DDS_DataWriter writer,
const DDS_PublicationMatchedStatus *status);
```
# 3.4.4 DDS\_DataWriterListener interface
Since a DDS\_DataWriter is a DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_DataWriterListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must e x t e n d f r o m t h e D D S \_D a t a W r i te r L i s t en e r c l a s s . A l l DDS\_DataWriterListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
NOTE: All operations for this interface must be implemented in the user-defined class; it is up to the application whether an operation is empty or contains some functionality.
The DDS\_DataWriterListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The DDS\_DataWriterListener is related to changes in communication status.
The interface description of this class is as follows:
```c
/*
* interface DDS_DataWriterListener
*/
/*
* abstract external operations
*/
void
DDS_DataWriterListener_on_offered_deadline_missed
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedDeadlineMissedStatus *status);
void
DDS_DataWriterListener_on_offered_incompatible_qos
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedIncompatibleQosStatus *status);
void
DDS_DataWriterListener_on_liveliness_lost
(void *listener_data,
DDS_DataWriter writer,
const DDS_LivelinessLostStatus *status);
void
```
```c
DDS_DataWriterListener_on_publication_matched
(void *listener_data,
DDS_DataWriter writer,
const DDS_PublicationMatchedStatus *status);
/*
* implemented API operations
*/
struct DDS_DataWriterListener *
DDS_DataWriterListener__alloc
(void);
```
The next paragraphs describe the usage of all DDS\_DataWriterListener operations. These abstract operations are fully described because they must be implemented by the application.
# 3.4.4.1 DDS\_DataWriterListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DataWriterListener *
DDS_DataWriterListener__alloc
(void);
```
# Description
This operation creates a new DDS\_DataWriterListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_DataWriterListener \* - the handle to the newly-created DDS\_DataWriterListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This ope ra t ion creates a new D D S \_ D a t aW r i t e r Li s t e n e r. T h e DDS\_DataWriterListener must be created using this operation. In other words, t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p e DDS\_DataWriterListener. When the application wants to release the DDS\_DataWriterListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_DataWriterListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.4.4.2 DDS\_DataWriterListener\_on\_liveliness\_lost (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataWriterListener_on_liveliness_lost
(void *listener_data,
DDS_DataWriter writer,
const DDS_LivelinessLostStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the DDS\_LivelinessLostStatus changes.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataWriter writer - contain a pointer to the DDS\_DataWriter on which the DDS\_LivelinessLostStatus has changed (this is an input to the application).
in const DDS\_LivelinessLostStatus \*status - contain the DDS\_LivelinessLostStatus struct (this is an input to the application).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the DDS\_LivelinessLostStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataWriterListener is installed and enabled for the liveliness lost status. The liveliness lost status will change when the liveliness that the DDS\_DataWriter has committed through its DDS\_LivelinessQosPolicy was not respected. In other words, the DDS\_DataWriter failed to actively signal its liveliness within the offered liveliness period. As a result, the DDS\_DataReader objects will consider the DDS\_DataWriter as no longer “alive”.
The Data Distribution Service will call the DDS\_DataWriterListener operation with a parameter writer, which will contain a pointer to the DDS\_DataWriter on which the conflict occurred and a parameter status, which will contain the DDS\_LivelinessLostStatus struct.
# 3.4.4.3 DDS\_DataWriterListener\_on\_offered\_deadline\_missed (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataWriterListener_on_offered_deadline_missed
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedDeadlineMissedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the DDS\_OfferedDeadlineMissedStatus changes.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataWriter writer - contains a pointer to the DDS\_DataWriter on which the DDS\_OfferedDeadlineMissedStatus has changed (this is an input to the application).
in const DDS\_OfferedDeadlineMissedStatus \*status - contains the DDS\_OfferedDeadlineMissedStatus struct (this is an input to the application).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the DDS\_OfferedDeadlineMissedStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataWriterListener is installed and enabled for the offered deadline missed status. The offered deadline missed status will change when the d e a d l i n e t h a t t h e D D S \_ D a t a W r i t e r h a s c o m m i t t e d t h r o u g h i t s DDS\_DeadlineQosPolicy was not respected for a specific instance.
The Data Distribution Service will call the DDS\_DataWriterListener operation with a parameter writer, which will contain a pointer to the DDS\_DataWriter on which the conflict occurred and a parameter status, which will contain the DDS\_OfferedDeadlineMissedStatus struct.
# 3.4.4.4 DDS\_DataWriterListener\_on\_offered\_incompatible\_qos (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataWriterListener_on_offered_incompatible_qos
(void *listener_data,
DDS_DataWriter writer,
const DDS_OfferedIncompatibleQosStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS changes.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataWriter writer - contain a pointer to the DDS\_DataWriter on which the DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS has changed (this is an input to the application).
in const DDS\_OfferedIncompatibleQosStatus \*status - contain the DDS\_OfferedIncompatibleQosStatus struct (this is an input to the application).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataWriterListener is installed and enabled for the DDS\_OFFERED\_INCOMPATIBLE\_QOS\_STATUS. The incompatible Qos status will change when a DDS\_DataReader object has been discovered by the D D S\_ D a t a W r it e r w i t h t h e s a m e D DS \_ T o p i c an d a requ est e d DDS\_DataReaderQos that was incompatible with the one offered by the DDS\_DataWriter.
The Data Distribution Service will call the DDS\_DataWriterListener operation with a parameter writer, which will contain a pointer to the DDS\_DataWriter on which the conflict occurred and a parameter status, which will contain the DDS\_OfferedIncompatibleQosStatus struct.
# 3.4.4.5 DDS\_DataWriterListener\_on\_publication\_matched (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataWriterListener_on_publication_matched
(DDS_DataWritervoid *listener_data,
DDS_DataWriter writer,
const DDS_PublicationMatchedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when a new match has been discovered for the current publication, or when an existing match has ceased to exist.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataWriter writer - contains a pointer to the DDS\_DataWriter for which a match has been discovered (this is an input to the application provided by the Data Distribution Service).
in const DDS\_PublicationMatchedStatus \*status - contains the DDS\_PublicationMatchedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation must be implemented by the application and is called by the Data Distribution Service when a new match has been discovered for the current publication, or when an existing match has ceased to exist. Usually this means that a new DataReader that matches the Topic and that has compatible Qos as the current DDS\_DataWriter has either been discovered, or that a previously discovered DataReader has ceased to be matched to the current DDS\_DataWriter. A DataReader may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DDS\_DataWriter or when either the
DDS\_DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the DDS\_DomainParticipant\_ignore\_subcription or DDS\_DomainParticipant\_ignore\_publication operations.
The implementation of this Listener operation may be left empty when this functionality is not needed: it will only be called when the relevant D D S\_ D a t a W r it e r L i s te n e r i s i n s t a ll e d a n d e n a b le d f o r t h e DDS\_PUBLICATION\_MATCHED\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataWriter in the parameter writer and the DDS\_PublicationMatchedStatus struct in the parameter status for use by the application.
# 3.5 Subscription Module
Figure 19: The DCPS Subscription Module’s Class Model
This module contains the following classes:
• DDS\_Subscriber
• Subscription type specific classes
• DDS\_DataSample
• DDS\_SampleInfo (struct)
• DDS\_SubscriberListener (interface)
• DDS\_DataReaderListener (interface)
• DDS\_ReadCondition
• DDS\_QueryCondition
“Subscription type specific classes” contains the generic class and the generated data type specific classes. For each data type, a data type specific class <NameSpace>\_<type>DataReader is generated (based on IDL) by calling the pre-processor.
For instance, for the fictional data type Foo (this also applies to other types), defined in the module SPACE; “Subscription type specific classes” contains the following classes:
• DDS\_DataReader (abstract)
• SPACE\_FooDataReader
• DDS\_DataReaderView (abstract)
• SPACE\_FooDataReaderView
A DDS\_Subscriber is an object responsible for receiving published data and making it available (according to the DDS\_SubscriberQos) to the application. It may receive and dispatch DDS\_Topic with data of different specified data types. To access the received data, the application must use a typed DDS\_DataReader attached to the DDS\_Subscriber. Thus, a subscription is defined by the association of a DDS\_DataReader with a DDS\_Subscriber. This association expresses the intent of the application to subscribe to the data described by the DDS\_DataReader in the context provided by the DDS\_Subscriber.
# 3.5.1 Class DDS\_Subscriber
A DDS\_Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions.
A DDS\_Subscriber acts on behalf of one or more DDS\_DataReader objects that are related to it. When it receives data (from the other parts of the system), it i n d i c a t e s t o t h e a p p l i c a t i o n t h a t d a t a i s a v a i l a b l e t h r o u g h i t s DDS\_DataReaderListener and by enabling related DDS\_Conditions. The application can access the list of concerned DDS\_DataReader objects through the operation DDS\_Subscriber\_get\_datareaders and then access the data available through operations on the DDS\_DataReader.
The interface description of this class is as follows:
```c
/*
* interface DDS_Subscriber
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_Subscriber_get_statuscondition
* (DDS_Subscriber _this)
*/
/* DDS_StatusMask
* DDS_Subscriber_get_status_changes
* (DDS_Subscriber _this);
*/
/* DDS_ReturnCode_t
* DDS_Subscriber_enable
* (DDS_Subscriber _this);
*/
/*
* implemented API operations
*/
DDS_DataReader
DDS_Subscriber_create_datareader
(DDS_Subscriber _this,
const DDS_TopicDescription a_topic,
const DDS_DataReaderQos *qos,
const struct DDS_DataReaderListener *a_listener,
const DDS_StatusMask mask);
DDS_ReturnCode_t
DDS_Subscriber_delete_datareader
(DDS_Subscriber _this,
const DDS_DataReader a_datareader);
DDS_ReturnCode_t
DDS_Subscriber_delete_contained_entities
(DDS_Subscriber _this);
DDS_DataReader
DDS_Subscriber_lookup_datareader
(DDS_Subscriber _this,
const DDS_char *topic_name);
DDS_ReturnCode_t
```
```c
DDS_Subscriber_get_datareaders
(DDS_Subscriber _this,
DDS_DataReaderSeq *readers,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
DDS_Subscriber_notify_datareaders
(DDS_Subscriber _this);
DDS_ReturnCode_t
DDS_Subscriber_set_qos
(DDS_Subscriber _this,
const DDS_SubscriberQos *qos);
DDS_ReturnCode_t
DDS_Subscriber_get_qos
(DDS_Subscriber _this,
DDS_SubscriberQos *qos);
DDS_ReturnCode_t
DDS_Subscriber_set_listener
(DDS_Subscriber _this,
const struct DDS_SubscriberListener *a_listener,
const DDS_StatusMask mask);
struct DDS_SubscriberListener
DDS_Subscriber_get_listener
(DDS_Subscriber _this);
DDS_ReturnCode_t
DDS_Subscriber_begin_access
(DDS_Subscriber _this);
DDS_ReturnCode_t
DDS_Subscriber_end_access
(DDS_Subscriber _this);
DDS_DomainParticipant
DDS_Subscriber_get_participant
(DDS_Subscriber _this);
DDS_ReturnCode_t
DDS_Subscriber_set_default_datareader_qos
(DDS_Subscriber _this,
const DDS_DataReaderQos *qos);
DDS_ReturnCode_t
DDS_Subscriber_get_default_datareader_qos
(DDS_Subscriber _this,
```
```c
DDS_DataReaderQos *qos);
DDS_ReturnCode_t
DDS_Subscriber_copy_from_topic_qos
(DDS_Subscriber _this,
DDS_DataReaderQos *a_datareader_qos,
const DDS_TopicQos *a_topic_qos);
```
The next paragraphs describe the usage of all DDS\_Subscriber operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.5.1.1 DDS\_Subscriber\_begin\_access
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_begin_access
(DDS_Subscriber _this);
```
# Description
This operation indicates that the application will begin accessing a coherent and/or ordered set of modifications that spans multiple DataReaders attached to this S u b s c r i b e r. T h e a c c e s s w i l l b e c o m p l e t e d b y a m a t c h i n g c a l l t o DDS\_Subscriber\_end\_access.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_ALREADY_DELETED.
```
# Detailed Description
This operation indicates that the application is about to access a set of coherent and/or ordered samples in any of the DataReader objects attached to the Subscriber. The operation will effectively lock all of the Subscriber’s DataReader objects for any incoming modifications, so that the state of their history remains consistent for the duration of the access. Note that a coherent subscriber should first be enabled, otherwise this operation will return DDS\_RETCODE\_ERROR. See Section 3.5.1.6, DDS\_Subscriber\_enable (inherited), for additional information.
The application is required to use this operation only if the PresentationQosPolicy of the Subscriber to which the DataReader belongs has the access\_scope set to ‘ G R O U P ’ . I n t h e a f o r e m e n t i o n e d c a s e , t h e o p e r a t i o n DDS\_Subscriber\_begin\_access must be called prior to calling any of the sample-accessing operations, namely: get\_datareaders on the Subscriber and read, take, and all their variants on any DataReader. Otherwise the s a m p l e - a c c e s s i n g o p e r a t i o n s w i l l r e t u r n t h e e r r o r DDS\_RETCODE\_PRECONDITION\_NOT\_MET. Once the application has finished accessing the data samples it must call DDS\_Subscriber\_end\_access.
It is not required for the application to call begin\_access/end\_access if the PresentationQosPolicy has the access\_scope set to something other than ‘GROUP’. Calling begin\_access/end\_access in this case is not considered an error and has no effect.
The calls to begin\_access/end\_access may be nested. In that case, the application must call end\_access as many times as it called begin\_access.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - access to coherent/ordered data has successfully started.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter passed to the operation is NULL, or is not pointing to any valid object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
# 3.5.1.2 DDS\_Subscriber\_copy\_from\_topic\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_copy_from_topic_qos
(DDS_Subscriber _this,
DDS_DataReaderQos *a_datareader_qos,
const DDS_TopicQos *a_topic_qos);
```
# Description
This operation will copy the policies in a\_topic\_qos to the corresponding policies in a\_datareader\_qos.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
inout DDS\_DataReaderQos \*a\_datareader\_qos - the destination DDS\_DataReaderQos struct to which the QosPolicy settings will be copied.
in const DDS\_TopicQos \*a\_topic\_qos - the source DDS\_TopicQos, which will be copied.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation will copy the QosPolicy settings in a\_topic\_qos to the corresponding QosPolicy settings in a\_datareader\_qos (replacing the values in a\_datareader\_qos, if present).
This is a “convenience” operation, useful in combination with the operations DDS\_Publisher\_get\_default\_datawriter\_qos and DDS\_Topic\_get\_qos. The operation DDS\_Subscriber\_copy\_from\_topic\_qos can be used to merge the DDS\_DataReader default QosPolicy settings with the corresponding ones on the DDS\_Topic. The resulting DDS\_DataReaderQos can then be used to create a new DDS\_DataReader, or set its DDS\_DataReaderQos.
This operation does not check the resulting a\_datareader\_qos for self consistency. This is because the “merged” a\_datareader\_qos may not be the final one, as the application can still modify some QosPolicy settings prior to applying the DDS\_DataReaderQos to the DDS\_DataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the QosPolicy settings have successfully been copied from the DDS\_TopicQos to the DDS\_DataReaderQos.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.3 DDS\_Subscriber\_create\_datareader
```c
Synopsis
#include <dds_dcps.h>
DDS_DataReader
DDS_Subscriber_create_datareader
(DDS_Subscriber _this,
const DDS_TopicDescription a_topic,
const DDS_DataReaderQos *qos,
const struct DDS_DataReaderListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation creates a DDS\_DataReader with the desired QosPolicy settings, for the desired DDS\_TopicDescription and attaches the optionally specified DDS\_DataWriterListener to it.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const DDS\_TopicDescription a\_topic - a pointer to the DDS\_TopicDescription for which the DDS\_DataReader is created. This may be a DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic.
in const DDS\_DataReaderQos \*qos - the struct with the QosPolicy settings for the new DDS\_DataReader, when these QosPolicy settings are not self consistent, no DDS\_DataReader is created.
in const struct DDS\_DataReaderListener \*a\_listener - a pointer to the DDS\_DataReaderListener instance which will be attached to the new DDS\_DataReader. It is permitted to use DDS\_OBJECT\_NIL as the value of the listener: this behaves as a DDS\_DataWriterListener whose operations perform no action.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_DataReaderListener for a certain status.
# Return Value
DD S \_D at aR ea d er - Return value is a pointer to the newly-created DDS\_DataReader. In case of an error, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a DDS\_DataReader with the desired QosPolicy settings, for the desired DDS\_TopicDescription and attaches the optionally specified DDS\_DataReaderListener to it. The DDS\_TopicDescription may be a DDS\_Topic, DDS\_MultiTopic or DDS\_ContentFilteredTopic. The returned DDS\_DataReader is attached (and belongs) to the DDS\_Subscriber. To delete the DDS\_DataReader the operation DDS\_Subscriber\_delete\_datareader or DDS\_Subscriber\_delete\_contained\_entities must be used. If no read rights are defined for the specific topic then the creation of the DataReader will fail.
# Application Data Type
The DDS\_DataReader returned by this operation is an object of a derived class, specific to the data type associated with the DDS\_TopicDescription. For each a p p l i c a t i o n - d e f i n e d d a t a t y p e < t y p e > t h e r e i s a c l a s s <NameSpace>\_<type>DataReader generated by calling the pre-processor. This data type specific class extends DDS\_DataReader and contains the operations to read data of data type <type>.
Because the DDS\_DataReader may read a DDS\_Topic, DDS\_ContentFilteredTopic or DDS\_MultiTopic, the DDS\_DataReader is associated with the DDS\_TopicDescription. The DDS\_DataWriter can only write a DDS\_Topic, not a DDS\_ContentFilteredTopic or DDS\_MultiTopic, because these two are constructed at the DDS\_Subscriber side.
# QosPolicy
The common application pattern to construct the QosPolicy settings for the DDS\_DataReader is to:
• Retrieve the QosPolicy settings on the associated DDS\_TopicDescription by means of the DDS\_Topic\_get\_qos operation on the DDS\_TopicDescription
• Retrieve the default DDS\_DataReaderQos by means of the DDS\_Subscriber\_get\_default\_datareader\_qos operation on the DDS\_Subscriber
• Combine those two QosPolicy settings and selectively modify policies as desired (DDS\_Subscriber\_copy\_from\_topic\_qos)
• Use the resulting QosPolicy settings to construct the DDS\_DataReader.
• In case the specified QosPolicy settings are not self consistent, no DDS\_DataReader is created and the DDS\_OBJECT\_NIL pointer is returned.
# Default QoS
The constant DDS\_DATAREADER\_QOS\_DEFAULT can be used as parameter qos to create a DDS\_DataReader with the default DDS\_DataReaderQos as set in the DDS\_Subscriber. The effect of using DDS\_DATAREADER\_QOS\_DEFAULT is the s a m e a s c a l l i n g t h e o p e r a t i o n DDS\_Subscriber\_get\_default\_datareader\_qos and using the resulting DDS\_DataReaderQos to create the DDS\_DataReader.
The special DDS\_DATAREADER\_QOS\_USE\_TOPIC\_QOS can be used to create a DDS\_DataReader with a combination of the default DDS\_DataReaderQos and t h e DDS\_TopicQos. T h e e f f e c t o f u s i n g DDS\_DATAREADER\_QOS\_USE\_TOPIC\_QOS is the same as calling the operation DDS\_Subscriber\_get\_default\_datareader\_qos and retrieving the DDS\_TopicQos (by means of the operation DDS\_Topic\_get\_qos) and then c o m b i n i n g t h e s e t w o Q o s P o l i c y s e t t i n g s u s i n g t h e o p e r a t i o n DDS\_Subscriber\_copy\_from\_topic\_qos, whereby any common policy that is set on the DDS\_TopicQos “overrides” the corresponding policy on the default DDS\_DataReaderQos. The resulting DDS\_DataReaderQos is then applied to create the DDS\_DataReader.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_DataReaderListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The fact that the status is reset prior to calling the listener means that if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset.
The following statuses are applicable to the DDS\_DataReaderListener:
```pickle
DDS_REQUESTED_DEADLINE_MISSED_STATUS
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
DDS_SAMPLE_LOST_STATUS
DDS_SAMPLE_REJECTED_STATUS
DDS_DATA_AVAILABLE_STATUS
DDS_LIVELINESS_CHANGED_STATUS
DDS_SUBSCRIPTION_MATCHED_STATUS.
```
Be aware that the DDS\_SUBSCRIPTION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_OBJECT\_NIL.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
In case a communication status is not activated in the m a sk of the DDS\_DataReaderListener, the DDS\_SubscriberListener of the containing DDS\_Subscriber is invoked (if attached and activated for the status that occurred). T h i s a l l o w s t h e a p p l i c a t i o n t o s e t a d e f a u l t b e h a v i o u r i n t h e DDS\_SubscriberListener of the containing DDS\_Subscriber and a DDS\_DataReader specific behaviour when needed. In case the communication status is not activated in the mask of the DDS\_SubscriberListener as well, the c o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h e DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
# 3.5.1.4 DDS\_Subscriber\_delete\_contained\_entities
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_delete_contained_entities
(DDS_Subscriber _this);
```
# Description
This operation deletes all the DDS\_DataReader objects that were created by means of the DDS\_Subscriber\_create\_datareader operation on the DDS\_Subscriber.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes all the DDS\_DataReader objects that were created by means of the DDS\_Subscriber\_create\_datareader operation on the DDS\_Subscriber. In other words, it deletes all contained DDS\_DataReader objects. Prior to deleting each DDS\_DataReader, this operation recursively calls the corresponding DDS\_DataReader\_delete\_contained\_entities operation on each DDS\_DataReader. In other words, all DDS\_DataReader objects in the DDS\_Subscriber are deleted, including the DDS\_QueryCondition and DDS\_ReadCondition objects contained by the DDS\_DataReader.
NOTE: The operation will return DDS\_PRECONDITION\_NOT\_MET if the any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDS\_DataReader cannot be deleted because the application has called a read or take operation and has not called the corresponding return\_loan operation to return the loaned samples. In such cases, the operation does not roll back any entity deletions performed prior to the detection of the problem.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the contained DDS\_Entity objects are deleted and the application may delete the DDS\_Subscriber.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.5.1.5 DDS\_Subscriber\_delete\_datareader
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_delete_datareader
(DDS_Subscriber _this,
const DDS_DataReader a_datareader);
```
# Description
This operation deletes a DDS\_DataReader that belongs to the DDS\_Subscriber.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const DDS\_DataReader a\_datareader - a pointer to the DDS\_DataReader, which is to be deleted.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a DDS\_DataReader that belongs to the DDS\_Subscriber. When the operation is called on a different DDS\_Subscriber as used when the DDS\_DataReader was created, the operation has no effect and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET. The deletion of the DDS\_DataReader is not allowed if there are any DDS\_ReadCondition or DDS\_QueryCondition objects that are attached to the DDS\_DataReader, or when the DDS\_DataReader still contains unreturned loans. In those cases the operation also returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DataReader is deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter a\_datareader is not a valid DDS\_DataReader.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DDS\_Subscriber as used when the DDS\_DataReader was created, the DDS\_DataReader contains one or more DDS\_ReadCondition or DDS\_QueryCondition objects or the DDS\_DataReader still contains unreturned loans.
# 3.5.1.6 DDS\_Subscriber\_enable (inherited)
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_enable
(DDS_Subscriber _this);
```
# Description
This operation is inherited. See the Section 3.1.1, Class DDS\_Entity (abstract), for a general description.
Behaviour when used in combination with group-scope coherent access
In addition to the general description, the enable operation on a Subscriber has special meaning in specific use cases. This applies only to Subscribers with PresentationQoSPolicy coherent\_access set to true with access\_scope set to group.
In this case the subscriber is always created in a disabled state, regardless of the factory’s autoenable\_created\_entities setting. While the subscriber remains disabled, DataReaders can be created that will participate in coherent transactions of the subscriber (See Section 3.5.1.1, DDS\_Subscriber\_begin\_access, and Section 3.5.1.7, DDS\_Subscriber\_end\_access, for more information).
All DataReaders will also be created in a disabled state. Coherency with an access\_scope of group requires data to be delivered as a transaction, atomically, to all eligible readers. Therefore data should not be delivered to any single DataReader immediately after it is created, as usual, but only after the application has finished creating all DataReaders for a given Subscriber. At this point, the application should enable the Subscriber which in turn enables all of its DataReaders.
# 3.5.1.7 DDS\_Subscriber\_end\_access
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_end_access
(DDS_Subscriber _this);
```
# Description
This operation indicates that the application will stop accessing a coherent and/or ordered set of modifications that spans multiple DataReaders attached to this DDS\_Subscriber. This access must have been started by a matching call to DDS\_Subscriber\_begin\_access.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
Indicates that the application has finished accessing the data samples in DataReader objects managed by the Subscriber. This operation must be used to ‘close’ a corresponding begin\_access. The operation will effectively unlock all of the Subscriber’s DataReader objects for incoming modifications, so it is important to invoke it as quickly as possible to avoid an ever increasing backlog of modifications. After calling end\_access the application should no longer access any of the Data or SampleInfo elements returned from the sample-accessing operations. Section 3.5.1.6, DDS\_Subscriber\_enable (inherited), contains additional information about coherent access.
This call must close a previous call to begin\_access otherwise the operation will return the error PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - access to coherent/ordered data has successfully started.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter passed to the operation is NULL, or is not pointing to any valid object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - no matching call to begin\_access has been detected.
# 3.5.1.8 DDS\_Subscriber\_get\_datareaders
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_get_datareaders
(DDS_Subscriber _this,
DDS_DataReaderSeq *readers,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation allows the application to access the DataReader objects that contain samples with the specified s am p le \_ st at e s, vi e w\_ s ta t es , a n d instance\_states.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
inout DDS\_DataReaderSeq \*readers - a sequence which is used to pass the list of all DataReaders that contain samples of the specified sample\_states, view\_states, and instance\_states.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those readers that have samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those readers that have samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those readers that have samples with the desired instance states.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE OUT\_OF\_RESOURCES, DDS\_RETCODE\_NOT\_ENABLED or DDS\_RETCODE\_ PRECONDITION\_NOT\_MET.
# Detailed Description
This operation allows the application to access the DataReader objects that contain samples with the specified s am p le \_ st at e s, vi e w\_ s ta t es , a n d instance\_states.
If the PresentationQosPolicy of the Subscriber to which the DataReader belongs has the access\_scope set to ‘GROUP’, this operation should only be invoked inside a begin\_access/end\_access block. Otherwise it will return the error DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
Depending on the setting of the PresentationQoSPolicy (see Section 3.1.3.14 on page 92), the returned collection of DataReader objects may be:
• a ‘set’ containing each DataReader at most once in no specified order,
• a ‘list’ containing each DataReader one or more times in a specific order.
This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the ‘list’ and read or take exactly one sample from each DataReader. The patterns that an application should use to access data is fully described in Section 3.1.3.14, DDS\_PresentationQosPolicy.
It is allowed to pre-allocate the DataReader sequence prior to invoking this function:
• if the PresentationQosPolicy has access\_scope set to ‘GROUP’ and ordered\_access set to TRUE, the ReaderList will never contain more than the pre-allocated number of elements. Pre-allocating ‘n’ Reader elements this way is convenient in scenario’s where the application only intends to access the first ‘n’ ordered samples. Otherwise the middleware would waste precious CPU cycles composing a list that will only partially be accessed.
• In all other cases, the ReaderList will re-allocated when it is not big enough to accommodate a list describing all DataReaders that have matching samples.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a list of DataReaders matching your description has successfully been composed.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_Subscriber is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the operation is not invoked inside a begin\_access/end\_access block as required by its QosPolicy settings.
# 3.5.1.9 DDS\_Subscriber\_get\_default\_datareader\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_get_default_datareader_qos
(DDS_Subscriber_this,
DDS_DataReaderQos *qos);
```
# Description
This operation gets the default QosPolicy settings of the DDS\_DataReader.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
inout DDS\_DataReaderQos \*qos - a pointer to the DDS\_DataReaderQos struct (provided by the application) in which the default QosPolicy settings for the DDS\_DataReader are written.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation gets the default QosPolicy settings of the DDS\_DataReader (that is the DDS\_DataReaderQos) which is used for newly-created DDS\_DataReader objects, in case the constant DDS\_DATAREADER\_QOS\_DEFAULT is used. The default DDS\_DataReaderQos is only used when the constant is supplied as parameter qos t o s p e c i f y t h e DDS\_DataReaderQos i n t h e DDS\_Subscriber\_create\_datareader operation. The application must provide the DDS\_DataReaderQos struct in which the QosPolicy settings can be stored and pass the qos pointer to the operation. The operation writes the default QosPolicy settings to the struct pointed to by qos. Any settings in the struct are overwritten.
The values retrieved by this operation match the values specified on the last successful call to DDS\_Subscriber\_set\_default\_datareader\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 5: on page 65.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the default DDS\_DataReader QosPolicy settings of this DDS\_Subscriber have successfully been copied into the specified DDS\_DataReaderQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.10 DDS\_Subscriber\_get\_listener
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_SubscriberListener
DDS_Subscriber_get_listener
(DDS_Subscriber _this);
```
# Description
This operation allows access to a DDS\_SubscriberListener.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
s t ru c t D D S \_ S ub s c r i b er L i s t e n er - re s u l t i s a p o in t e r t o t h e DDS\_SubscriberListener attached to the DDS\_Subscriber.
# Detailed Description
This operation allows access to a DDS\_SubscriberListener attached to the DDS\_Subscriber. When no DDS\_SubscriberListener was attached to the DDS\_Subscriber, the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.1.11 DDS\_Subscriber\_get\_participant
# Synopsis
```c
#include <dds_dcps.h>
DDS_DomainParticipant
DDS_Subscriber_get_participant
(DDS_Subscriber_this);
```
# Description
This operation returns the DDS\_DomainParticipant associated with the DDS\_Subscriber or the DDS\_OBJECT\_NIL pointer.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
DDS\_DomainParticipant - a pointer to the DDS\_DomainParticipant associated with the DDS\_Subscriber or the DDS\_OBJECT\_NIL pointer.
# Detailed Description
This operation returns the DDS\_DomainParticipant associated with the DDS\_Subscriber. Note that there is exactly one DDS\_DomainParticipant associated with each DDS\_Subscriber. When the DDS\_Subscriber was already deleted (there is no associated DDS\_DomainParticipant any more), the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.1.12 DDS\_Subscriber\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_get_qos
(DDS_Subscriber_this,
DDS_SubscriberQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DDS\_Subscriber.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
inout DDS\_SubscriberQos \*qos - a pointer to the destination DDS\_SubscriberQos struct in which the QosPolicy settings will be copied.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation allows access to the existing set of QoS policies of a DDS\_Subscriber on which this operation is used. This DDS\_SubscriberQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_Subscriber has successfully been copied into the specified DDS\_SubscriberQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.13 DDS\_Subscriber\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_Subscriber_get_status_changes
(DDS_Subscriber _this);
```
# 3.5.1.14 DDS\_Subscriber\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_Subscriber_get_statuscondition
(DDS_Subscriber_this);
```
# 3.5.1.15 DDS\_Subscriber\_lookup\_datareader
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataReader
DDS_Subscriber_lookup_datareader
(DDS_Subscriber _this,
const DDS_char *topic_name);
```
# Description
This operation returns a previously created DDS\_DataReader belonging to the DDS\_Subscriber which is attached to a DDS\_Topic with the matching topic\_name.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const DDS\_char \*topic\_name - the name of the DDS\_Topic, which is attached to the DDS\_DataReader to look for.
# Return Value
DDS\_DataReader - Return value is a pointer to the DDS\_DataReader found. When no such DDS\_DataReader is found, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation returns a previously created DDS\_DataReader belonging to the DDS\_Subscriber which is attached to a DDS\_Topic with the matching topic\_name. When multiple DDS\_DataReader objects (which satisfy the same condition) exist, this operation will return one of them. It is not specified which one.
This operation may be used on the built-in DDS\_Subscriber, which returns the built-in DDS\_DataReader objects for the built-in DDS\_Topics.
# 3.5.1.16 DDS\_Subscriber\_notify\_datareaders
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_notify_datareaders
(DDS_Subscriber _this);
```
# Description
This operation invokes the DDS\_DataReaderListener\_on\_data\_available operation on DDS\_DataReaderListener objects which are attached to the contained DDS\_DataReader entities having new, available data.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are:
DDS_RETCODE_OK, DDS_RETCODE_ERROR,
DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED
or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation invokes the DDS\_DataReaderListener\_on\_data\_available operation on the DDS\_DataReaderListener objects attached to contained DDS\_DataReader entities that have received information, but which have not yet been processed by those DDS\_DataReaders.
The DDS\_Subscriber\_notify\_datareaders operation ignores the bit mask value of the individual DDS\_DataReaderListener objects, even when the DDS\_DATA\_AVAILABLE\_STATUS bit has not been set on a DDS\_DataReader that w h i c h h a s n e w, a v a i l a b l e d a t a . T h e DDS\_DataReaderListener\_on\_data\_available operation will still be invoked, when the DATA\_AVAILABLE\_STATUS bit has not been set on a DataReader, b u t w i l l n o t p r o p a g a t e t o t h e DDS\_DomainParticipantListener.
When the DDS\_DataReader has attached a NULL listener, the event will be consumed and will not propagate to the DDS\_DomainParticipantListener. (Remember that a NULL listener is regarded as a listener that handles all its events as a NOOP).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - all appropriate listeners have been invoked
• DDS\_RETCODE\_ERROR - an internal error has occurred
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - there are insufficient Data Distribution Service resources to complete this operation
# 3.5.1.17 DDS\_Subscriber\_set\_default\_datareader\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_set_default_datareader_qos
(DDS_Subscriber _this,
const DDS_DataReaderQos *qos);
```
# Description
This operation sets the default DDS\_DataReaderQos of the DDS\_DataReader.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const DDS\_DataReaderQos \*qos - the DDS\_DataReaderQos struct, which contains the new default QosPolicy settings for the newly-created DDS\_DataReaders.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation sets the default DDS\_DataReaderQos of the DDS\_DataReader (that is the struct with the QosPolicy settings). This QosPolicy is used for n e w l y - c r e a t e d D D S \_ D a t a R e a d e r o b j e c t s i n c a s e t h e c o n s t a n t DDS\_DATAREADER\_QOS\_DEFAULT is used as parameter qos to specify the DDS\_DataReaderQos in the DDS\_Subscriber\_create\_datareader operation. This operation checks if the DDS\_DataReaderQos is self consistent. If it i s n o t , t h e o p e r a t i o n h a s n o e ff e c t a n d r e t u r n s DDS\_RETCODE\_INCONSISTENT\_POLICY.
T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b y DDS\_Subscriber\_get\_default\_datareader\_qos.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new default DDS\_DataReaderQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_DataReaderQos. It contains a QosPolicy setting with an invalid DDS\_Duration\_t value, an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.5.1.18 DDS\_Subscriber\_set\_listener
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_set_listener
(DDS_Subscriber _this,
const struct DDS_SubscriberListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation attaches a DDS\_SubscriberListener to the DDS\_Subscriber.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const struct DDS\_SubscriberListener \*a\_listener - a pointer to the DDS\_SubscriberListener instance, which will be attached to the DDS\_Subscriber.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_SubscriberListener for a certain status.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation attaches a DDS\_SubscriberListener to the DDS\_Subscriber. Only one DDS\_SubscriberListener can be attached to each DDS\_Subscriber. If a DDS\_SubscriberListener was already attached, the operation will replace it with the new one. When a\_listener is the DDS\_OBJECT\_NIL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bitmask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_SubscriberListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset. An exception to this rule is the DDS\_OBJECT\_NIL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DDS\_SubscriberListener:
• DDS\_REQUESTED\_DEADLINE\_MISSED\_STATUS (propagated)
• DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• DDS\_SAMPLE\_LOST\_STATUS (propagated)
• DDS\_SAMPLE\_REJECTED\_STATUS (propagated)
• DDS\_DATA\_AVAILABLE\_STATUS (propagated)
• DDS\_LIVELINESS\_CHANGED\_STATUS (propagated)
• DDS\_SUBSCRIPTION\_MATCHED\_STATUS (propagated).
• DDS\_DATA\_ON\_READERS\_STATUS.
Be aware that the DDS\_SUBSCRIPTION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
The Data Distribution Service will trigger the most specific and relevant Listener. In other words, in case a communication status is also activated on the DDS\_DataReaderListener of a contained DDS\_DataReader, the
DDS\_DataReaderListener on that contained DDS\_DataReader is invoked instead of the DDS\_SubscriberListener. This means that a status change on a contained DDS\_DataReader only invokes the DDS\_SubscriberListener if the contained DDS\_DataReader itself does not handle the trigger event generated by the status change.
In case a communication status is not activated in the m as k of th e DDS\_SubscriberListener, the DDS\_DomainParticipantListener of the containing DDS\_DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant and a DDS\_Subscriber specific behaviour when needed. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
The statuses DDS\_DATA\_ON\_READERS\_STATUS and DDS\_DATA AVAILABLE\_STATUS are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a get\_<status\_name>\_status operation and they are mutually exclusive. When new information becomes available to a DataReader, the Data Distribution Service will first look in an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D DS \_ D A T A \_ ON \_ R E A D ER S \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_SubscriberListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.19 DDS\_Subscriber\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_Subscriber_set_qos
(DDS_Subscriber_this,
const DDS_SubscriberQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_Subscriber.
# Parameters
in DDS\_Subscriber \_this - the DDS\_Subscriber object on which the operation is operated.
in const DDS\_SubscriberQos \*qos - contain the new set of QosPolicy settings for the DDS\_Subscriber.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_IMMUTABLE_POLICY or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_Subscriber. The parameter qos must contain the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_Subscriber, which can only be set before the DDS\_Subscriber is enabled, the operation will fail and a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a RETCODE\_INCONSISTENT\_POLICY is returned.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK). If one or more of the partitions in the QoS structure have insufficient access rights configured then the set\_qos function will fail with a DDS\_RETCODE\_PRECONDITION\_NOT\_MET error code.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_SubscriberQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_SubscriberQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_Subscriber has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DDS\_Subscriber.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - returned when insufficient access rights exist for the partition(s) listed in the QoS structure.
# 3.5.2 Subscription Type Specific Classes
“Subscription type specific classes” contains the generic class and the generated data type specific classes. For each data type, a data type specific class <NameSpace>\_<type>DataReader is generated (based on IDL) by calling the pre-processor. In case of data type Foo (this also applies to other types), defined in the module SPACE; “Subscription type specific classes” contains the following classes:
This paragraph describes the generic DDS\_DataReader class and the derived application type specific <NameSpace>\_<type>DataReader classes which together implement the application subscription interface. For each application type, u s e d a s D D S \_ T o p i c d a t a t y p e , t h e p r e - p r o c e s s o r g e n e r a t e s a <NameSpace>\_<type>DataReader class from an IDL type description. The SPACE\_FooDataReader class that would be generated by the pre-processor for a f i c t i o n a l t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e s c r i b e s t h e <NameSpace>\_<type>DataReader classes.
# 3.5.2.1 Class DDS\_DataReader (abstract)
A DDS\_DataReader allows the application:
• to declare data it wishes to receive (i.e., make a subscription)
• to access data received by the associated DDS\_Subscriber.
A DDS\_DataReader refers to exactly one DDS\_TopicDescription (either a DDS\_Topic, a DDS\_ContentFilteredTopic or a DDS\_MultiTopic) that identifies the samples to be read. The DDS\_DataReader may give access to several instances of the data type, which are distinguished from each other by their key.
DDS\_DataReader is an abstract class. It is specialized for each particular application data type. For a fictional application data type “Foo” the specialized class would be SPACE\_FooDataReader.
The interface description of this class is as follows:
```c
/*
* interface DDS_DataReader
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* DDS_DataReader_get_statuscondition
* (DDS_DataReader _this);
*/
/* DDS_StatusMask
* DDS_DataReader_get_status_changes
* (DDS_DataReader _this);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_enable
* (DDS_DataReader _this);
*/
/*
* abstract operations
* (implemented in the data type specific DDS_DataReader)
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
```
```c
* const DDS_long max_samples,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read_w_condition
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_ReadCondition a_condition);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take_w_condition
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_ReadCondition a_condition);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read_next_sample
* (DDS_DataReader _this,
* <data> *data_values,
* DDS_SampleInfo *sample_info);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take_next_sample
* (DDS_DataReader _this,
* <data> *data_values,
* DDS_SampleInfo *sample_info);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read_instance
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
```
```c
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take_instance
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read_next_instance
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take_next_instance
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_read_next_instance_w_condition
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_ReadCondition a_condition);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_take_next_instance_w_condition
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
```
```c
* DDS_SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_ReadCondition a_condition);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_return_loan
* (DDS_DataReader _this,
* DDS_sequence_<data> *data_values,
* DDS_SampleInfoSeq *info_seq);
*/
/* DDS_ReturnCode_t
* DDS_DataReader_get_key_value
* (DDS_DataReader _this,
* <data> *key_holder,
* const DDS_InstanceHandle_t handle);
*/
/* DDS_InstanceHandle_t
* DDS_DataReader_lookup_instance
*/ (DDS_DataReader _this,
* <data> *instance_data);
/*
* implemented API operations
*/
DDS_ReadCondition
DDS_DataReader_create_readcondition
(DDS_DataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_QueryCondition
DDS_DataReader_create_querycondition
(DDS_DataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
DDS_ReturnCode_t
DDS_DataReader_delete_readcondition
(DDS_DataReader _this,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
DDS_DataReader_delete_contained_entities
(DDS_DataReader _this);
DDS_ReturnCode_t
```
```c
DDS_DataReader_set_qos
(DDS_DataReader _this,
const DDS_DataReaderQos *qos);
DDS_ReturnCode_t
DDS_DataReader_get_qos
(DDS_DataReader _this,
DDS_DataReaderQos *qos);
DDS_ReturnCode_t
DDS_DataReader_set_listener
(DDS_DataReader _this,
const struct DDS_DataReaderListener *a_listener,
const DDS_StatusMask mask);
struct DDS_DataReaderListener
DDS_DataReader_get_listener
(DDS_DataReader _this);
DDS_TopicDescription
DDS_DataReader_get_topicdescription
(DDS_DataReader _this);
DDS_Subscriber
DDS_DataReader_get_subscriber
(DDS_DataReader _this);
DDS_ReturnCode_t
DDS_DataReader_get_sample_rejected_status
(DDS_DataReader _this,
DDS_SampleRejectedStatus *status);
DDS_ReturnCode_t
DDS_DataReader_get_liveliness_changed_status
(DDS_DataReader _this,
DDS_LivelinessChangedStatus *status);
DDS_ReturnCode_t
DDS_DataReader_get_requested_deadline_missed_status
(DDS_DataReader _this,
DDS_RequestedDeadlineMissedStatus *status);
DDS_ReturnCode_t
DDS_DataReader_get_requested_incompatible_qos_status
(DDS_DataReader _this,
DDS_RequestedIncompatibleQosStatus *status);
DDS_ReturnCode_t
DDS_DataReader_get_subscription_matched_status
(DDS_DataReader _this,
```
```c
DDS_SubscriptionMatchedStatus *status);
DDS_ReturnCode_t
DDS_DataReader_get_sample_lost_status
(DDS_DataReader _this,
DDS_SampleLostStatus *status);
DDS_ReturnCode_t
DDS_DataReader_wait_for_historical_data
(DDS_DataReader _this,
const DDS_Duration_t *max_wait);
DDS_ReturnCode_t
DDS_DataReader_get_matched_publications
(DDS_DataReader _this,
DDS_InstanceHandleSeq *publication_handles);
DDS_ReturnCode_t
DDS_DataReader_get_matched_publication_data
(DDS_DataReader _this,
DDS_PublicationBuiltinTopicData *publication_data,
const DDS_InstanceHandle_t publication_handle);
DDS_DataReaderView
DDS_DataReader_create_view
(DDS_DataReader _this
const DDS_DataReaderViewQos* qos);
DDS_ReturnCode_t
DDS_DataReader_delete_view
(DDS_DataReader _this,
const DDS_DataReaderView a_view);
DDS_ReturnCode_t
DDS_DataReader_get_default_datareaderview_qos
(DDS_DataReader _this,
DDS_DataReaderViewQos* qos);
DDS_ReturnCode_t
DDS_DataReader_set_default_datareaderview_qos
(DDS_DataReader _this,
DDS_DataReaderViewQos* qos);
```
The following paragraphs describe the usage of all DDS\_DataReader operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited. The abstract operations are listed but not fully described because they are not implemented in this specific class. The full description of these operations is located in the subclasses that contain the data type specific implementation of these operations.
# 3.5.2.2 DDS\_DataReader\_create\_querycondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_QueryCondition
DDS_DataReader_create_querycondition
(DDS_DataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
```
# Description
This operation creates a new DDS\_QueryCondition for the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
in const DDS\_char \*query\_expression - the query string, which must be a subset of the SQL query language as specified in Appendix H, DCPS Queries and Filters.
in const DDS\_StringSeq \*query\_parameters - a sequence of strings which are the parameters used in the SQL query string (i.e., the “%n” tokens in the expression). The number of values in query\_parameters must be equal or greater than the highest referenced %n token in the query\_expression (e.g. if %1 and %8 are used as parameter in the query\_expression, the query\_parameters should at least contain n+1 = 9 values).
# Return Value
DDS\_QueryCondition - Result value is a pointer to the DDS\_QueryCondition.
When the operation fails, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_QueryCondition for the DDS\_DataReader. The returned DDS\_QueryCondition is attached (and belongs) to the DDS\_DataReader. When the operation fails, the DDS\_OBJECT\_NIL pointer is r e t u r n e d . To d e l e t e t h e DD S \_ Q u e r yC o n d i t io n t h e o p e r a t i o n DDS\_DataReader\_delete\_readcondition or DDS\_DataReader\_delete\_ contained\_entities must be used.
# State Masks
The result of the DDS\_QueryCondition also depends on the selection of samples determined by three masks:
• sample\_states is the mask, which selects only those samples with the desired sample states DDS\_READ\_SAMPLE\_STATE, DDS\_NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states DDS\_NEW\_VIEW\_STATE, DDS\_NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states DDS\_ALIVE\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_ DISPOSED\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_ STATE or a combination of these.
# SQL expression
The SQL query string is set by query\_expression which must be a subset of the SQL query language. In this query expression, parameters may be used, which must be set in the sequence of strings defined by the parameter query\_parameters. A parameter is a string which can define an integer, float, string or enumeration. The number of values in query\_parameters must be equal or greater than the highest referenced %n token in the query\_expression (e.g. if %1 and %8 are used as parameter in the query\_expression, the query\_parameters should at least contain n+1 = 9 values).
# 3.5.2.3 DDS\_DataReader\_create\_readcondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReadCondition
DDS_DataReader_create_readcondition
(DDS_DataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation creates a new DDS\_ReadCondition for the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
DDS\_ReadCondition - Result value is a pointer to the DDS\_ReadCondition. When the operation fails, the DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This operation creates a new DDS\_ReadCondition for the DDS\_DataReader. The returned DDS\_ReadCondition is attached (and belongs) to the DDS\_DataReader. When the operation fails, the DDS\_OBJECT\_NIL pointer is returned. To delete the DDS\_ReadCondition the operation DDS\_DataReader\_delete readcondition or DDS\_DataReader\_delete\_contained\_entities must be used.
# State Masks
The result of the DDS\_ReadCondition depends on the selection of samples determined by three masks:
• sample\_states is the mask, which selects only those samples with the desired sample states DDS\_READ\_SAMPLE\_STATE, DDS\_NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states DDS\_NEW\_VIEW\_STATE, DDS\_NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states DDS\_ALIVE\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_ DISPOSED\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_ STATE or a combination of these.
# 3.5.2.4 DDS\_DataReader\_create\_view
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataReaderView
DDS_DataReader_create_view
(DDS_DataReader _this,
const DDS_DataReaderViewQos* qos);
```
# Description
This operation creates a DataReaderView with the desired QosPolicy settings.
# Parameters
```txt
in DDS_DataReader _this - the DDS_DataReader object on which the operation is operated.
in const DDS_DataReaderViewQos* qos - the QosPolicy settings for the DataReaderView.
```
# Return Value
DDS\_DataReaderView - Pointer to the newly-created DataReaderView. In case of error, the NULL pointer is returned.
# Detailed Description
This operation creates a DataReaderView with the desired QosPolicy settings. In case the QosPolicy is invalid, a NULL pointer is returned. The convenience macro DDS\_DATAREADERVIEW\_QOS\_DEFAULT can be used as parameter qos, to create a DataReaderView with the default DataReaderViewQos as set in the DataReader.
# Application Data Type
The DataReaderView returned by this operation is an object of a derived class, specific to the data type associated with the Topic. For each application-defined data type <type> there is a class <type>DataReaderView generated by calling the pre-processor. This data type specific class extends DataReaderView and contains the operations to read and take data of data type <type>.
The typed operations of a DataReaderView exactly mimic those of the DataReader from which it is created.
# 3.5.2.5 DDS\_DataReader\_delete\_contained\_entities
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
```
DDS\_DataReader\_delete\_contained\_entities (DDS\_DataReader \_this);
# Description
This operation deletes all the DDS\_Entity objects that were created by means of one of the “create\_” operations on the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_ OUT\_OF\_RESOURCES or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes all the DDS\_Entity objects that were created by means of one of the “create\_” operations on the DDS\_DataReader. In other words, it deletes all DDS\_QueryCondition and DDS\_ReadCondition objects contained by the DDS\_DataReader.
NOTE: The operation will return DDS\_PRECONDITION\_NOT\_MET if the any of the contained entities is in a state where it cannot be deleted. In such cases, the operation does not roll back any entity deletions performed prior to the detection of the problem.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the contained DDS\_Entity objects are deleted and the application may delete the DDS\_DataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.5.2.6 DDS\_DataReader\_delete\_readcondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_delete_readcondition
(DDS_DataReader _this,
const DDS_ReadCondition a_condition);
```
# Description
This operation deletes a DDS\_ReadCondition or DDS\_QueryCondition which is attached to the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_ReadCondition a\_condition - a pointer to the DDS\_ReadCondition or DDS\_QueryCondition which is to be deleted.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a DDS\_ReadCondition or DDS\_QueryCondition which is attached to the DDS\_DataReader. Since a DDS\_QueryCondition is a specialized DDS\_ReadCondition, the operation can also be used to delete a DDS\_QueryCondition. A DDS\_ReadCondition or DDS\_QueryCondition cannot be deleted when it is not attached to this DDS\_DataReader. When the operation is called on a DDS\_ReadCondition or DDS\_QueryCondition which w a s n o t a t t a c h e d t o t h i s D D S \_ D a t a R e a d e r, t h e o p e r a t i o n r e t u r n s DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_ReadCondition or DDS\_QueryCondition is deleted.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid DDS\_ReadCondition.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DDS\_DataReader, as used when the DDS\_ReadCondition or DDS\_QueryCondition was created.
# 3.5.2.7 DDS\_DataReader\_delete\_view
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_delete_view
(DDS_DataReader_this,
DDS_DataReaderView a_view);
```
# Description
This operation deletes a DataReaderView that belongs to the DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in DDS\_DataReaderView a\_view - a pointer to the DataReaderView which is to be deleted.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes the DataReaderView from the DataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DataReaderView is deleted.
• DDS\_RETCODE\_ERROR - an internal error occurred.
• DDS\_RETCODE\_BAD\_PARAMETER - the DataReaderView parameter is invalid.
• DDS\_RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - the DataReaderView is not associated with this DataReader, or the DataReaderView still contains one or more ReadCondition or QueryCondition objects or an unreturned loan.
# 3.5.2.8 DDS\_DataReader\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_enable
(DDS_DataReader _this);
```
# 3.5.2.9 DDS\_DataReader\_get\_default\_datareaderview\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_default_datareaderview_qos
(DDS_DataReader _this,
DDS_DataReaderViewQos* qos);
```
# Description
This operation gets the default QosPolicy settings of the DataReaderView.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DataReaderViewQos\* qos - a r e f e r e n c e t o t h e DDS\_DataReaderViewQos struct in which the default QosPolicy settings will be stored.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are:
DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR,
DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation gets the default QosPolicy settings of the DDS\_DataReaderView, which are used for newly-created DDS\_DataReaderView objects in case the constant DDS\_DATAREADERVIEW\_QOS\_DEFAULT is used.
The values retrieved by this call match the values specified on the last successful call to DDS\_DataReader\_set\_default\_datareaderview\_qos, or, if this call was never made, the default values as specified in Table 5: on page 65.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the default DDS\_DataReaderViewQosPolicy settings of this DDS\_DataReader have successfully been copied into the provided DDS\_DataReaderViewQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation.
# 3.5.2.10 DDS\_DataReader\_get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_key_value
(DDS_DataReader_this,
<data> *key_holder,
```
const DDS\_InstanceHandle\_t handle);
# 3.5.2.11 DDS\_DataReader\_get\_listener
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DataReaderListener
DDS_DataReader_get_listener
(DDS_DataReader _this);
```
# Description
This operation allows access to a DDS\_DataReaderListener.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
# Return Value
s t ru c t D D S \_ D at a R e a d er L i s t e n er - re s u l t i s a p o in t e r t o t h e DDS\_DataReaderListener attached to the DDS\_DataReader.
# Detailed Description
This operation allows access to a DDS\_DataReaderListener attached to the DDS\_DataReader. When no DDS\_DataReaderListener was attached to the DDS\_DataReader, the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.2.12 DDS\_DataReader\_get\_liveliness\_changed\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_liveliness_changed_status
(DDS_DataReader_this,
DDS_LivelinessChangedStatus *status);
```
# Description
This operation obtains the DDS\_LivelinessChangedStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_LivelinessChangedStatus \*status - the contents of the DDS\_LivelinessChangedStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_LivelinessChangedStatus struct of the DDS\_DataReader. This struct contains the information whether the liveliness of one or more DDS\_DataWriter objects that were writing instances read by the DDS\_DataReader has changed. In other words, some DDS\_DataWriter have become “alive” or “not alive”.
The DDS\_LivelinessChangedStatus can also be monitored using a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_LivelinessChangedStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.13 DDS\_DataReader\_get\_matched\_publication\_data
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_matched_publication_data
(DDS_DataReader _this,
DDS_PublicationBuiltinTopicData *publication_data,
const DDS_InstanceHandle_t publication_handle);
```
# Description
This operation retrieves information on the specified publication that is currently “associated” with the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_PublicationBuiltinTopicData \*publication\_data - a pointer to the sample in which the information about the specified publication is to be stored.
in const DDS\_InstanceHandle\_t publication\_handle - a handle to the publication whose information needs to be retrieved.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves information on the specified publication that is currently “associated” with the DDS\_DataReader. That is, a publication with a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the DDS\_DomainParticipant\_ignore\_publication operation.
The publication\_handle must correspond to a publication currently associated with the DDS\_DataReader, otherwise the operation will fail and return DDS\_RETCODE\_BAD\_PARAMETER. The operation DDS\_DataReader\_ get\_matched\_publications can be used to find the publications that are currently matched with the DDS\_DataReader.
The operation may also fail if the infrastructure does not hold the information necessary to fill in the publication\_data. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the information on the specified publication has successfully been retrieved.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataReader is not enabled.
# 3.5.2.14 DDS\_DataReader\_get\_matched\_publications
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_matched_publications
(DDS_DataReader _this,
DDS_InstanceHandleSeq *publication_handles);
```
# Description
This operation retrieves the list of publications currently "associated" with the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_InstanceHandleSeq \*publication\_handles - a sequence which is used to pass the list of all associated publications.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES or DDS\_RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves the list of publications currently "associated" with the DDS\_DataReader. That is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be “ignored” by means of the DDS\_DomainParticipant\_ignore\_publication operation.
The publication\_handles sequence and its buffer may be pre-allocated by the application and therefore must either be re-used in a subsequent invocation of the DDS\_DataReader\_get\_matched\_publications operation or be released by calling DDS\_free on the returned publication\_handles. If the pre-allocated sequence is not big enough to hold the number of associated publications, the sequence will automatically be (re-)allocated to fit the required size.
The handles returned in the publication\_handles sequence are the ones that are used by the DDS implementation to locally identify the corresponding matched DataWriter entities. You can access more detailed information about a particular p u b l i c a t i o n b y p a s s i n g i t s p u b l ic a t i o n \_ ha n d l e t o e it h e r t h e DDS\_DataReader\_get\_matched\_publication\_data operation or to the DDS\_PublicationBuiltinTopicDataDataReader\_read\_instance operation on the built-in reader for the “DCPSPublication” topic.
Be aware that since DDS\_InstanceHandle\_t is an opaque datatype, it does not necessarily mean that the handles obtained from the DDS\_DataReader get\_matched\_publications operation have the same value as the ones that appear in the instance\_handle field of the DDS\_SampleInfo when retrieving the publication info through corresponding "DCPSPublication" built-in reader. You can’t just compare two handles to determine whether they represent the same publication. If you want to know whether two handles actually do represent the same publication, us e both handles to retrieve their corresponding DDS\_PublicationBuiltinTopicData samples and then compare the key field of both samples.
The operation may fail if the infrastructure does not locally maintain the connectivity information. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the list of associated publications has successfully been obtained.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataReader is not enabled.
# 3.5.2.15 DDS\_DataReader\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_qos
(DDS_DataReader_this,
DDS_DataReaderQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_DataReaderQos \*qos - a reference to the destination DDS\_DataReaderQos struct in which the QosPolicy settings will be copied.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DDS\_DataReader on which this operation is used. This DDS\_DataReaderQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoS policy values applied to this DDS\_DataReader has successfully been copied into the specified DDS\_DataReaderQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.16 DDS\_DataReader\_get\_requested\_deadline\_missed\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_requested_deadline_missed_status
(DDS_DataReader _this,
DDS_RequestedDeadlineMissedStatus *status);
```
# Description
This operation obtains the DDS\_RequestedDeadlineMissedStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_RequestedDeadlineMissedStatus \*status - the contents of the DDS\_RequestedDeadlineMissedStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_RequestedDeadlineMissedStatus struct of the DDS\_DataReader. This struct contains the information whether the deadline that the DDS\_DataReader was expecting through its DDS\_DeadlineQosPolicy was not respected for a specific instance.
The DDS\_RequestedDeadlineMissedStatus can also be monitored using a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_RequestedDeadlineMissedStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.17 DDS\_DataReader\_get\_requested\_incompatible\_qos\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_requested_incompatible_qos_status
(DDS_DataReader _this,
DDS_RequestedIncompatibleQosStatus *status);
```
# Description
This operation obtains the DDS\_RequestedIncompatibleQosStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_RequestedIncompatibleQosStatus \*status - the contents of the DDS\_RequestedIncompatibleQosStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_RequestedIncompatibleQosStatus struct of the DDS\_DataReader. This struct contains the information whether a QosPolicy setting was incompatible with the offered QosPolicy setting.
The Request/Offering mechanism is applicable between the DDS\_DataWriter and the DDS\_DataReader. If the QosPolicy settings between DDS\_DataWriter and DDS\_DataReader are inconsistent, no communication between them is established. In addition the DDS\_DataWriter will be informed via a DDS\_REQUESTED\_INCOMPATIBLE\_QOS status change and the DDS\_DataReader will be informed via an DDS\_OFFERED\_INCOMPATIBLE\_QOS status change.
The DDS\_RequestedIncompatibleQosStatus can also be monitored using a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_RequestedIncompatibleQosStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.18 DDS\_DataReader\_get\_sample\_lost\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_sample_lost_status
(DDS_DataReader _this,
DDS_SampleLostStatus *status);
```
# Description
This operation obtains the DDS\_SampleLostStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_SampleLostStatus \*status - the contents of the DDS\_SampleLostStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_SampleLostStatus struct of the DDS\_DataReader. This struct contains the information whether a sample have been lost. This only applies when the DDS\_ReliabilityQosPolicy is set to DDS\_RELIABLE. If the DDS\_ReliabilityQosPolicy is set to DDS\_BEST\_EFFORT the Data Distribution Service will not report the loss of samples.
The D D S \_ Sa m p l e L o st S t a t u s c a n a l s o b e m o n i t o r e d u s i n g a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_SampleLostStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.19 DDS\_DataReader\_get\_sample\_rejected\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get_sample_rejected_status
(DDS_DataReader _this,
DDS_SampleRejectedStatus *status);
```
# Detailed Description
This operation obtains the DDS\_SampleRejectedStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_SampleRejectedStatus \*status - the contents of the DDS\_SampleRejectedStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_ OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_SampleRejectedStatus struct of the DDS\_DataReader. This struct contains the information whether a received sample has been rejected. Samples may be rejected by the DDS\_DataReader when it runs out of resource\_limits to store incoming samples. Ususally this means that old samples need to be ‘consumed’ (for example by ‘taking’ them instead of ‘reading’ them) to make room for newly incoming samples.
The DDS\_SampleRejectedStatus can also be monitored using a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_SampleRejectedStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.20 DDS\_DataReader\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_DataReader_get_status_changes
(DDS_DataReader _this);
```
# 3.5.2.21 DDS\_DataReader\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_DataReader_get_statuscondition
(DDS_DataReader_this);
```
# 3.5.2.22 DDS\_DataReader\_get\_subscriber
# Synopsis
```c
#include <dds_dcps.h>
DDS_Subscriber
DDS_DataReader_get_subscriber
(DDS_DataReader _this);
```
# Description
This operation returns the DDS\_Subscriber to which the DDS\_DataReader belongs.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
# Return Value
DDS\_Subscriber - Return value is a pointer to the DDS\_Subscriber to which the DDS\_DataReader belongs.
# Detailed Description
This operation returns the DDS\_Subscriber to which the DDS\_DataReader belongs, thus the DDS\_Subscriber that has created the DDS\_DataReader. If the DDS\_DataReader is already deleted, the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.2.23 DDS\_DataReader\_get\_subscription\_matched\_status
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_get Subscription_matched_status
(DDS_DataReader _this,
DDS_SubscriptionMatchedStatus *status);
```
# Description
This operation obtains the DDS\_SubscriptionMatchedStatus struct of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
inout DDS\_SubscriptionMatchedStatus \*status - the contents of the DDS\_SubscriptionMatchedStatus struct of the DDS\_DataReader will be copied into the location specified by status.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ALREADY\_DELETED or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the DDS\_SubscriptionMatchedStatus struct of the DDS\_DataReader. This struct contains the information whether a new match has been discovered for the current subscription, or whether an existing match has ceased to exist.
This means that the status represents that either a DataWriter object has been discovered by the DDS\_DataReader with the same Topic and a compatible Qos, or that a previously-discovered DataWriter has ceased to be matched to the current DDS\_DataReader. A DataWriter may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DDS\_DataReader or when either the DDS\_DataReader or the DataWriter has chosen to put its matching counterpart on its ignore-list using the DDS\_DomainParticipant\_ ignore\_publication or DDS\_DomainParticipant\_ignore\_subscription operations.
The operation may fail if the infrastructure does not hold the information necessary to fill in the DDS\_SubscriptionMatchedStatus. This is the case when OpenSplice is configured not to maintain discovery information in the Networking S e r v i c e . ( S e e t h e d e s c r i p t i o n f o r t h e N e t w o r k i n g S e r v i c e / Discovery/enabled property in the Deployment Manual for more information a b o u t t h i s s u b j e c t . ) I n t h i s c a s e t h e o p e r a t i o n w i l l r e t u r n DDS\_RETCODE\_UNSUPPORTED.
The DDS\_SubscriptionMatchedStatus can also be monitored using a DDS\_DataReaderListener or by using the associated DDS\_StatusCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the current DDS\_SubscriptionMatchedStatus of this DDS\_DataReader has successfully been copied into the specified status parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.24 DDS\_DataReader\_get\_topicdescription
# Synopsis
```c
#include <dds_dcps.h>
DDS_TopicDescription
DDS_DataReader_get_topicdescription
```
(DDS\_DataReader \_this);
# Description
This operation returns the DDS\_TopicDescription which is associated with the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
# Return Value
DDS\_TopicDescription - a pointer to the DDS\_TopicDescription which is associated with the DDS\_DataReader.
# Detailed Description
This operation returns the DDS\_TopicDescription which is associated with the DDS\_DataReader, thus the DDS\_TopicDescription with which the DDS\_DataReader is created. If the DDS\_DataReader is already deleted, the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.2.25 DDS\_DataReader\_lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_InstanceHandle_t
DDS_DataReader_lookup_instance
(DDS_DataReader _this,
<data> *instance_data);
```
# 3.5.2.26 DDS\_DataReader\_read (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
#include <dds\_dcps.h>
```c
DDS_ReturnCode_t
DDS_DataReader_read
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.27 DDS\_DataReader\_read\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_read_instance
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.28 DDS\_DataReader\_read\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_read_next_instance
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
```
```dart
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.29 DDS\_DataReader\_read\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_read_next_instance_w_condition
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# 3.5.2.30 DDS\_DataReader\_read\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_read_next_sample
(DDS_DataReader _this,
<data> *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.31 DDS\_DataReader\_read\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_read_w_condition
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# 3.5.2.32 DDS\_DataReader\_return\_loan (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_return_loan
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq);
```
# 3.5.2.33 DDS\_DataReader\_set\_default\_datareaderview\_qos
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_set_default_datareaderview_qos
(DDS_DataReader _this,
DDS_DataReaderViewQos* qos);
```
# Description
This operation sets the default DDS\_DataReaderViewQos of the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_DataReaderViewQos\* qos - the DDS\_DataReaderViewQos struct which contains the default QosPolicy settings for newly-created DDS\_DataReaderView objects.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are:
DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_BAD_PARAMETER,
DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new default DataReaderViewQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_BAD\_PARAMETER - the DataReaderViewQos parameter is invalid.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation.
# 3.5.2.34 DDS\_DataReader\_set\_listener
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_set_listener
(DDS_DataReader_this,
const struct DDS_DataReaderListener *a_listener,
const DDS_StatusMask mask);
```
# Description
This operation attaches a DDS\_DataReaderListener to the DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const struct DDS\_DataReaderListener \*a\_listener - a pointer to the DDS\_DataReaderListener instance, which will be attached to the DDS\_DataReader.
in const DDS\_StatusMask mask - a bit-mask in which each bit enables the invocation of the DDS\_DataReaderListener for a certain status.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_UNSUPPORTED, DDS\_RETCODE\_ ALREADY\_DELETED or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a DDS\_DataReaderListener to the DDS\_DataReader. Only one DDS\_DataReaderListener can be attached to each DDS\_DataReader. If a DDS\_DataReaderListener was already attached, the operation will replace it with the new one. When a\_listener is the DDS\_OBJECT\_NIL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bitmask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each c o m m u n i c a t i o n s t a t u s a c t i v a t e d i n t h e m a s k , t h e a s s o c i a t e d DDS\_DataReaderListener operation is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get\_<status\_name>\_status from inside the listener it will see the status already reset. An exception to this rule is the DDS\_OBJECT\_NIL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DDS\_DataReaderListener:
```pickle
DDS_REQUESTED_DEADLINE_MISSED_STATUS
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
DDS_SAMPLE_LOST_STATUS
DDS_SAMPLE_REJECTED_STATUS
DDS_DATA_AVAILABLE_STATUS
DDS_LIVELINESS_CHANGED_STATUS
DDS_SUBSCRIPTION_MATCHED_STATUS.
```
Be aware that the DDS\_SUBSCRIPTION\_MATCHED\_STATUS is not applicable when the infrastructure does not have the information available to determine connectivity. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See also the description of the NetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation will return DDS\_RETCODE\_UNSUPPORTED.
Status bits are declared as a constant and can be used by the application in an OR operation to create a tailored mask. The special constant DDS\_STATUS\_MASK\_NONE can be used to indicate that the created entity should not respond to any of its available statuses. The DDS will therefore attempt to propagate these statuses to its factory. The special constant STATUS\_MASK\_ANY\_V1\_2 can be used to select all applicable statuses specified in the “Data Distribution Service for Real-time Systems Version 1.2” specification.
# Status Propagation
In case a communication status is not activated in the m as k of th e DDS\_DataReaderListener, the DDS\_SubscriberListener of the containing DDS\_Subscriber is invoked (if attached and activated for the status that occurred). T h i s a l l o w s t h e a p p l i c a t i o n t o s e t a d e f a u l t b e h a v i o u r i n t h e DDS\_SubscriberListener of the containing DDS\_Subscriber and a DDS\_DataReader specific behaviour when needed. In case the communication status is not activated in the mask of the DDS\_SubscriberListener as well, the c o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h e DDS\_DomainParticipantListener o f t h e c o n t a i n i n g DDS\_DomainParticipant. In case the DDS\_DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.
The statuses DDS\_DATA\_ON\_READERS\_STATUS and DDS\_DATA AVAILABLE\_STATUS are “Read Communication Statuses” and are an exception to all other plain communication statuses: they have no corresponding status structure that can be obtained with a get\_<status\_name>\_status operation and they are mutually exclusive. When new information becomes available to a DataReader, the Data Distribution Service will first look in an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D DS \_ D A T A \_ ON \_ R E A D ER S \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DataReaderListener is attached.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.35 DDS\_DataReader\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_set_qos
(DDS_DataReader _this,
const DDS_DataReaderQos *qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DataReader.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_DataReaderQos \*qos - the new set of QosPolicy settings for the DDS\_DataReader.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_IMMUTABLE_POLICY or DDS_RETCODE_INCONSISTENT_POLICY.
```
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DDS\_DataReader. The parameter qos contains the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_DataReader, which can only be set before t h e D D S \_ D a t a R e a d e r i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed. When qos contains conflicting QosPolicy settings (not self-consistent), the operation will fail and a DDS\_RETCODE\_INCONSISTENT\_POLICY is returned.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the new DDS\_DataReaderQos is set.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DDS\_DataReaderQos. It contains a QosPolicy setting with an invalid DDS\_Duration\_t value, an enum value that is outside its legal boundaries or a sequence that has inconsistent memory settings.
• DDS\_RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DDS\_DataReader.
• DDS\_RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.5.2.36 DDS\_DataReader\_take (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.37 DDS\_DataReader\_take\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take_instance
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.38 DDS\_DataReader\_take\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take_next_instance
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
```
```txt
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.39 DDS\_DataReader\_take\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take_next_instance_w_condition
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# 3.5.2.40 DDS\_DataReader\_take\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take_next_sample
(DDS_DataReader _this,
<data> *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.41 DDS\_DataReader\_take\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReader class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the fictional data type Foo (defined in the module SPACE) derived SPACE\_FooDataReader class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_take_w_condition
(DDS_DataReader _this,
DDS_sequence_<data> *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# 3.5.2.42 DDS\_DataReader\_wait\_for\_historical\_data
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_wait_for_historical_data
(DDS_DataReader _this,
const DDS_Duration_t *max_wait);
```
# Description
This operation will block the application thread until all “historical” data is received.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_Duration\_t \*max\_wait - the maximum duration to block for the DDS\_DataReader\_wait\_for\_historical\_data, after which the a p p l i c a t i o n t h r e a d i s u n b l o c k e d . T h e s p e c i a l c o n s t a n t DDS\_DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are:
```javascript
DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT or DDS_RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation behaves differently for DDS\_DataReader objects which have a non-DDS\_VOLATILE\_DURABILITY\_QOS DDS\_DurabilityQosPolicy and for DDS\_DataReader objects which have a DDS\_VOLATILE\_DURABILITY\_QOS DDS\_DurabilityQosPolicy.
As soon as an application enables a non-DDS\_VOLATILE\_DURABILITY\_QOS DDS\_DataReader it will start receiving both “historical” data, i.e. the data that was written prior to the time the DDS\_DataReader joined the domain, as well as any new data written by the DDS\_DataWriter objects. There are situations where the application logic may require the application to wait until all “historical” data is r e c e i v e d . T h i s i s t h e p u r p o s e o f t h e DDS\_DataReader\_wait\_for\_historical\_data operation.
As soon as an application enables a DDS\_VOLATILE\_DURABILITY\_QOS DataReader it will not start receiving “historical” data but only new data written by t h e DDS\_DataWriter o b j e c t s . By c a l l i n g DDS\_DataReader\_wait\_for\_historical\_data the DDS\_DataReader explicitly requests the Data Distribution Service to start receiving also the “historical” data and to wait until either all “historical” data is received, or the duration specified by the max\_wait parameter has elapsed, whichever happens first.
# Thread blocking
The operation DDS\_DataReader\_wait\_for\_historical\_data blocks the calling thread until either all “historical” data is received, or the duration specified by the max\_wait parameter elapses, whichever happens first. A return value of DDS\_RETCODE\_OK indicates that all the “historical” data was received; a return value of DDS\_RETCODE\_TIMEOUT indicates that max\_wait elapsed before all the data was received.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the “historical” data is received.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the DDS\_DataReader is not enabled.
• DDS\_RETCODE\_TIMEOUT - not all data is received before max\_wait elapsed.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - can happen when requesting conditional alignment on non-volatile readers or a historical data request is already in progress or complete.
# 3.5.2.43 DDS\_DataReader\_wait\_for\_historical\_data\_w\_condition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReader_wait_for_historical_data_w_condition
(DDS_DataReader _this
const DDS_string filter_expression,
const DDS_StringSeq* filter_parameters,
const DDS_Time_t* min_source_timestamp,
const DDS_Time_t* max_source_timestamp
const DDS_ResourceLimitsQosPolicy* resource_limits,
const DDS_Duration_t* max_wait)
```
# Description
This operation will block the application thread until all historical data that matches the supplied conditions is received.
NOTE: This operation only makes sense when the receiving node has configured its durability service as an On\_Request alignee. (See also the description of the OpenSplice/DurabilityService/NameSpaces/Policy[@alignee] attribute in the Deployment Guide.) Otherwise the Durability Service will not distinguish between separate reader requests and still inject the full historical data set in each reader.
Additionally, when creating the DataReader, the DurabilityQos.kind of the DataReaderQos needs to be set to VOLATILE, to ensure that historical data that potentially is available already at creation time is not immediately delivered to the DataReader at that time.
# Parameters
in DDS\_DataReader \_this - the DDS\_DataReader object on which the operation is operated.
in const DDS\_string\* filter\_expression - the SQL expression (subset of SQL), which defines the filtering criteria (NULL when no SQL filtering is needed).
in const DDS\_StringSeq\* filter\_parameters – sequence of strings with the parameter values used in the SQL expression (i.e., the number of %n tokens in the expression). The number of values in expression\_parameters must be equal to or greater than the highest referenced %n token in the filter\_expression (e.g. if %1 and %8 are used as parameters in the filter\_expression, the expression\_parameters should contain at least n + 1 = 9 values).
in const DDS\_Time\_t\* min\_source\_timestamp - Filter out all data published before this time. The special constant DDS\_TIMESTAMP\_INVALID c a n b e u s e d w h e n n o m i n i m u m f i l t e r i s n e e d e d . T h e v a l u e o f min\_source\_timestamp.sec must be less than 0x7fffffff otherwise it will be recognized as TIMESTAMP\_INVALID\_SEC.
in const DDS\_Time\_t\* max\_source\_timestamp - Filter out all data published after this time. The special constant DDS\_TIMESTAMP\_INVALID can b e u s e d w h e n n o m a x i m u m f i l t e r i s n e e d e d . T h e v a l u e o f max\_source\_timestamp.sec must be less than 0x7fffffff otherwise it will be recognized as TIMESTAMP\_INVALID\_SEC.
in const DDS\_ResourceLimitsQosPolicy\* resource\_limits - Specifies limits on the maximum amount of historical data that may be received.
in const DDS\_Duration\_t\* max\_wait - The maximum duration the application thread is blocked during this operation.
# Return Value
DDS\_ReturnCode\_t - Possible return codes of the operation are: DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_PRECONDITION\_NOT\_MET, DDS\_RETCODE\_ALREADY\_DELETED, DDS\_RETCODE\_NOT\_ENABLED, DDS\_RETCODE\_TIMEOUT.
# Detailed Description
T h i s o p e r a t i o n i s s i m i l a r t o t h e DDS\_DataReader\_wait\_for\_historical\_data operation, but instead of inserting all historical data into the DataReader, only data that matches the conditions expressed by the parameters to this opération is inserted. For more information about historical data please refer to section 3.5.2.42 on page 461.
By using filter\_expression and filter\_parameters, data can be selected or discarded based on content. The filter\_expression must adhere to SQL syntax of the WHERE clause as described in Appendix H, DCPS Queries and Filters. Constraints on the age of data can be set by using the min\_source\_timestamp and max\_source\_timestamp parameters. Only data published within this timeframe will be selected. Note that DDS\_TIMESTAMP\_INVALID is also accepted as a lower or upper timeframe limit. The amount of selected data can be further reduced by the resource\_limits parameter. This QosPolicy allows to set a limit on the number of samples, instances and samples per instance that are to be received.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the historical data is received.
• DDS\_RETCODE\_ERROR - an internal error occurred.
• DDS\_RETCODE\_BAD\_PARAMETER - any of the parameters is invalid, including resource\_limits that do not meet constraints set on the DataReader.
• RETCODE\_PRECONDITION\_NOT\_MET - No Durability service is available, or can happen when requesting conditional alignment on non-volatile readers or a historical data request is already in progress or complete.
• DDS\_RETCODE\_ALREADY\_DELETED - the DataReader is already deleted.
• DDS\_RETCODE\_NOT\_ENABLED - the DataReader is not enabled.
• DDS\_RETCODE\_TIMEOUT - not all data is received before max\_wait elapsed.
# 3.5.2.44 Class SPACE\_FooDataReader
The pre-processor generates from IDL type descriptions the application <NameSpace>\_<type>DataReader classes. For each application data type that is used as DDS\_Topic data type, a typed class <NameSpace>\_<type>DataReader is derived from the DDS\_DataReader class. In this paragraph, the class SPACE\_FooDataReader describes the operations of these derived <NameSpace>\_<type>DataReader classes as an example for the fictional application type Foo (defined in the module SPACE).
For instance, for an application, the definitions are located in the Space.idl file. The pre-processor will generate a Space.h include file.
# State masks
A SPACE\_FooDataReader refers to exactly one DDS\_TopicDescription (either a DDS\_Topic, a DDS\_ContentFilteredTopic or a DDS\_MultiTopic) that identifies the data to be read. Therefore it refers to exactly one data type. The DDS\_Topic must exist prior to the SPACE\_FooDataReader creation. The SPACE\_FooDataReader may give access to several instances of the data type, w h i c h a r e d i s t i n g u i s h e d f r o m e a c h o t h e r b y t h e i r k e y. T h e SPACE\_FooDataReader is attached to exactly one DDS\_Subscriber which acts as a factory for it.
The interface description of this class is as follows:
```c
/*
* interface SPACE_FooDataReader
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* SPACE_FooDataReader_get_statuscondition
* (SPACE_FooDataReader _this);
*/
/* DDS_StatusMask
* SPACE_FooDataReader_get_status_changes
* (SPACE_FooDataReader _this);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_enable
* (SPACE_FooDataReader _this);
*/
/*
* inherited from class DDS_DataReader
*/
/* DDS_ReadCondition
* SPACE_FooDataReader_create_readcondition
* (SPACE_FooDataReader _this,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/* DDS_QueryCondition
* SPACE_FooDataReader_create_querycondition
* (SPACE_FooDataReader _this,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
```
```c
* const DDS_InstanceStateMask instance_states,
* const DDS_char *query_expression,
* const DDS_StringSeq *query_parameters);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_delete_readcondition
* (SPACE_FooDataReader _this,
* const DDS_ReadCondition a_condition);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_delete_contained_entities
* (SPACE_FooDataReader _this);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_set_qos
* (SPACE_FooDataReader _this,
* const DDS_DataReaderQos *qos);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_qos
* (SPACE_FooDataReader _this,
* SPACE_FooDataReaderQos *qos);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_set_listener
* (SPACE_FooDataReader _this,
* const struct DDS_DataReaderListener *a_listener,
* const DDS_StatusMask mask);
*/
/* struct SPACE_FooDataReaderListener
* SPACE_FooDataReader_get_listener
* (SPACE_FooDataReader _this);
*/
/* DDS_TopicDescription
* SPACE_FooDataReader_get_topicdescription
* (SPACE_FooDataReader _this);
*/
/* DDS_Subscriber
* SPACE_FooDataReader_get_subscriber
* (SPACE_FooDataReader _this);
```
```c
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_sample_rejected_status
* (SPACE_FooDataReader _this,
* DDS_SampleRejectedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_liveliness_changed_status
* (SPACE_FooDataReader _this,
* DDS_LivelinessChangedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_requested_deadline_missed_status
* (SPACE_FooDataReader _this,
* DDS_RequestedDeadlineMissedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_requested_incompatible_qos_status
* (SPACE_FooDataReader _this,
* DDS_RequestedIncompatibleQosStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get Subscription_matched_status
* (SPACE_FooDataReader _this,
* DDS_SubscriptionMatchedStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_sample_lost_status
* (SPACE_FooDataReader _this,
* DDS_SampleLostStatus *status);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_wait_for_historical_data
* (SPACE_FooDataReader _this,
* const DDS_Duration_t *max_wait);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_matched_publications
* (SPACE_FooDataReader _this,
* DDS_InstanceHandleSeq *publication_handles);
*/
/* DDS_ReturnCode_t
* SPACE_FooDataReader_get_matched_publication_data
```
```c
* (SPACE_FooDataReader _this,
* DDS_PublicationBuiltinTopicData *publication_data,
* const DDS_InstanceHandle_t publication_handle);
*/
/*
* implemented API operations
*/
DDS_ReturnCode_t
SPACE_FooDataReader_read
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_take
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_read_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReader_take_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_sample
(SPACE_FooDataReader _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_sample
(SPACE_FooDataReader _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
DDS_ReturnCode_t
```
```c
SPACE_FooDataReader_read_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_take_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_instance_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_instance_w_condition
(SPACE_FooDataReader _this,
```
```c
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FoodataReader_return_loan
(SPACE_FoodataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq);
DDS_ReturnCode_t
SPACE_FoodataReader_get_key_value
(SPACE_FoodataReader _this,
Foo *key_holder,
const DDS_InstanceHandle_t handle);
DDS_InstanceHandle_t
SPACE_FoodataReader_lookup_instance
(SPACE_FoodataReader _this,
Foo *instance_data);
```
The next paragraphs describe the usage of all SPACE\_FooDataReader operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.5.2.45 SPACE\_FooDataReader\_create\_querycondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_QueryCondition
SPACE_FooDataReader_create_querycondition
(SPACE_FooDataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
```
# 3.5.2.46 SPACE\_FooDataReader\_create\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReadCondition
```
```txt
SPACE_FooDataReader_create_readcondition
(SPACE_FooDataReader _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.2.47 SPACE\_FooDataReader\_delete\_contained\_entities (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_delete_contained_entities
(SPACE_FooDataReader _this);
```
# 3.5.2.48 SPACE\_FooDataReader\_delete\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_delete_readcondition
(SPACE_FooDataReader _this,
const DDS_ReadCondition a_condition);
```
# 3.5.2.49 SPACE\_FooDataReader\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_enable
(SPACE_FooDataReader _this);
```
# 3.5.2.50 SPACE\_FooDataReader\_get\_key\_value
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_key_value
(SPACE_FooDataReader _this,
Foo *key_holder,
const DDS_InstanceHandle_t handle);
```
# Description
This operation retrieves the key value of a specific instance.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout Foo \*key\_holder - the sample in which the key values are stored.
in const DDS\_InstanceHandle\_t handle - the handle to the instance from which to get the key value.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation retrieves the key value of the instance pointed to by instance\_handle. When the operation is called with an DDS\_HANDLE\_NIL h a n d l e v a l u e a s a n i n s t a n c e \_ h a n d l e , t h e o p e r a t i o n w i l l r e t u r n DDS\_RETCODE\_BAD\_PARAMETER. The operation will only fill the fields that form the key inside the key\_holder instance. This means that the non-key fields are not applicable and may contain garbage.
The operation must only be called on registered instances. Otherwise the operation returns the error DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the key\_holder instance contains the key values of the instance.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - handle is not a valid handle or key\_holder is not a valid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - this instance is not registered.
# 3.5.2.51 SPACE\_FooDataReader\_get\_listener (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
struct SPACE_FooDataReaderListener
SPACE_FooDataReader_get_listener
(SPACE_FooDataReader_this);
```
# 3.5.2.52 SPACE\_FooDataReader\_get\_liveliness\_changed\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_liveliness_changed_status
(SPACE_FooDataReader _this,
DDS_LivelinessChangedStatus *status);
```
# 3.5.2.53 SPACE\_FooDataReader\_get\_matched\_publication\_data (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_matched_publication_data
(SPACE_FooDataReader_this,
DDS_PublicationBuiltinTopicData *publication_data,
const DDS_InstanceHandle_t publication_handle);
```
# 3.5.2.54 SPACE\_FooDataReader\_get\_matched\_publications (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_matched_publications
(SPACE_FooDataReader_this,
DDS_InstanceHandleSeq *publication_handles);
```
# 3.5.2.55 SPACE\_FooDataReader\_get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_qos
(SPACE_FooDataReader _this,
DDS_DataReaderQos *qos);
```
# 3.5.2.56 SPACE\_FooDataReader\_get\_requested\_deadline\_missed\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_requested_deadline_missed_status
(SPACE_FooDataReader _this,
DDS_RequestedDeadlineMissedStatus *status);
```
# 3.5.2.57 SPACE\_FooDataReader\_get\_requested\_incompatible\_qos\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_requested_incompatible_qos_status
(SPACE_FooDataReader_this,
DDS_RequestedIncompatibleQosStatus *status);
```
# 3.5.2.58 SPACE\_FooDataReader\_get\_sample\_lost\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_sample_lost_status
(SPACE_FooDataReader_this,
DDS_SampleLostStatus *status);
```
# 3.5.2.59 SPACE\_FooDataReader\_get\_sample\_rejected\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_sample_rejected_status
(SPACE_FooDataReader_this,
DDS_SampleRejectedStatus *status);
```
# 3.5.2.60 SPACE\_FooDataReader\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusMask
SPACE_FoodataReader_get_status_changes
(SPACE_FoodataReader_this);
```
# 3.5.2.61 SPACE\_FooDataReader\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusCondition
SPACE_FooDataReader_get_statuscondition
(SPACE_FooDataReader _this);
```
# 3.5.2.62 SPACE\_FooDataReader\_get\_subscriber (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_Subscriber
SPACE_FoodDataReader_get_subscriber
(SPACE_FoodDataReader_this);
```
# 3.5.2.63 SPACE\_FooDataReader\_get\_subscription\_matched\_status (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_get_subscription_matched_status
(SPACE_FooDataReader _this,
DDS_SubscriptionMatchedStatus *status);
```
# 3.5.2.64 SPACE\_FooDataReader\_get\_topicdescription (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_TopicDescription
SPACE_FooDataReader_get_topicdescription
(SPACE_FooDataReader_this);
```
# 3.5.2.65 SPACE\_FooDataReader\_lookup\_instance
# Synopsis
```c
#include <Space.h>
DDS_InstanceHandle_t
SPACE_FooDataReader_lookup_instance
(SPACE_FooDataReader _this,
Foo *instance_data);
```
# Description
This operation returns the value of the instance handle which corresponds to the instance\_data.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
in Foo \*instance\_data - the instance for which the corresponding instance handle needs to be looked up.
# Return Value
DDS\_InstanceHandle\_t - Result value is the instance handle which corresponds to the instance\_data.
# Detailed Description
This operation returns the value of the instance handle which corresponds to the instance\_data. The instance handle can be used in read operations that operate on a specific instance. Note that DDS\_DataReader instance handles are local, and are not interchangeable with DDS\_DataWriter instance handles nor with instance handles of an other DDS\_DataReader. If the DDS\_DataReader is already deleted, the handle value DDS\_HANDLE\_NIL is returned.
# 3.5.2.66 SPACE\_FooDataReader\_read
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader. The data is returned by the parameters data\_values and info\_seq. The number of samples that is returned is limited by the parameter max\_samples. This operation is part of the specialized class which is generated for the particular application data type (in this case type Foo) that is being read. If the SPACE\_FooDataReader has no samples that meet the constraints, the return value is DDS\_RETCODE\_NO\_DATA.
# State masks
The SPACE\_FooDataReader\_read operation depends on a selection of the samples by using three masks:
• sample\_states is the mask, which selects only those samples with the desired sample states DDS\_READ\_SAMPLE\_STATE, DDS\_NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states DDS\_NEW\_VIEW\_STATE, DDS\_NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states DDS\_ALIVE\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_ DISPOSED\_INSTANCE\_STATE, DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_ STATE or a combination of these.
# Destination Order
In any case, the relative order between the samples of one instance is consistent with the DDS\_DestinationOrderQosPolicy of the DDS\_Subscriber.
When the DDS\_DestinationOrderQosPolicy k i n d i s DDS\_BY\_RECEPTION\_TIMESTAMP\_DESTINATIONORDER\_QOS, the samples belonging to the same instances will appear in the relative order in which they were received (FIFO)
When the DDS\_DestinationOrderQosPolicy k i n d i s DDS\_BY\_SOURCE\_TIMESTAMP\_DESTINATIONORDER\_QOS, the samples belonging to the same instances will appear in the relative order implied by the source\_timestamp.
# Data sample
In addition to the sample sequence (data\_values), the operation also returns a sequence of DDS\_SampleInfo structures with the parameter info\_seq. The info\_seq structures and data\_values also determine the behaviour of this operation.
# Resource control
The initial (input) properties of the data\_values and info\_seq sequences determine the precise behaviour of the SPACE\_FooDataReader\_read operation. The sequences are modelled as having three properties: the current-length (\_length), the maximum length (\_maximum), and whether or not the sequence container owns the memory of the elements within (\_release).
The initial (input) values of the \_length, \_maximum, and \_release properties for the data\_values and info\_seq sequences govern the behaviour of the SPACE\_FooDataReader\_read operation as specified by the following rules:
• The values of \_length, \_maximum, and \_release for the two sequences must be identical. Otherwise SPACE\_FooDataReader\_read returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET
• On successful output, the values of \_length, \_maximum, and \_release are the same for both sequences
• If the input \_maximum==0, the data\_values and info\_seq sequences are filled with elements that are “loaned” by the SPACE\_FooDataReader. On output, \_release is FALSE, \_length is set to the number of values returned,
and \_maximum is set to a value verifying \_maximum>=\_length. In this case the application will need to “return the loan” to the Data Distribution Service using the SPACE\_FooDataReader\_return\_loan operation
• If the input \_maximum>0 and the input \_release==FALSE, the SPACE\_FooDataReader\_read operation will fail and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET. This avoids the potential hard-to-detect memory leaks caused by an application forgetting to “return the loan”
• If input \_maximum>0 and the input \_release==TRUE, the SPACE\_FooDataReader\_read operation will copy the Foo samples and info\_seq values into the elements already inside the sequences. On output, \_release is TRUE, \_length is set to the number of values copied, and \_maximum will remain unchanged. The application can control where the copy is placed and the application does not need to “return the loan”. The number of samples copied depends on the relative values of \_maximum and max\_samples:
\- If \_maximum==DDS\_LENGTH\_UNLIMITED, at most \_maximum values are copied. The use of this variant lets the application limit the number of samples returned to what the sequence can accommodate;
\- If max\_samples<=\_maximum, at most max\_samples values are copied. The use of this variant lets the application limit the number of samples returned to fewer than what the sequence can accommodate;
\- If max\_samples>\_maximum, the SPACE\_FooDataReader\_read operation will fail and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET. This avoids the potential confusion where the application expects to be able to access up to max\_samples, but that number can never be returned, even if they are available in the SPACE\_FooDataReader, because the output sequence cannot accommodate them.
# Buffer Loan
As described above, upon return the data\_values and info\_seq sequences may contain elements “loaned” from the Data Distribution Service. If this is the case, the application will need to use the SPACE\_FooDataReader\_return\_loan operation to return the “loan” once it is no longer using the data in the sequence. Upon return from SPACE\_FooDataReader\_return\_loan, the sequence has \_maximum==0 and \_release==FALSE.
The application can determine whether it is necessary to “return the loan” or not, based on the state of the sequences, when the SPACE\_FooDataReader\_read operation was called, or by accessing the “\_release” property. However, in many cases it may be simpler to always call SPACE\_FooDataReader\_return\_loan, as this operation is harmless (i.e. leaves all elements unchanged) if the sequence does not have a loan.
To avoid potential memory leaks, it is not allowed to change the length of the data\_values and info\_seq structures for which \_release==FALSE. Furthermore, deleting a sequence for which \_release==FALSE is considered to be an error except when the sequence is empty.
# Data Sequence
On output, the sequence of data values and the sequence of DDS\_SampleInfo structures are of the same length and are in an one-to-one correspondence. Each D D S \_ S a m p l e I n f o s t r u c t u r e s p r o v i d e s i n f o r m a t i o n , s u c h a s t h e source\_timestamp, the sample\_state, view\_state, and instance\_state, etc., about the matching sample.
Some elements in the returned sequence may not have valid data: the valid\_data field in the DDS\_SampleInfo indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the DDS\_SampleInfo that communicates a change in the instance\_state of an instance for which there is no ‘real’ sample available.
For example, when an application always ‘takes’ all available samples of a particular instance, there is no sample available to report the disposal of that instance. In such a case the DDS\_DataReader will insert a dummy sample into the data\_values sequence to accompany the DDS\_SampleInfo element in the info\_seq sequence that communicates the disposal of the instance.
The act of reading a sample sets its sample\_state to DDS\_READ\_SAMPLE\_STATE. If the sample belongs to the most recent generation of the instance, it also sets the view\_state of the instance to DDS\_NOT\_NEW\_VIEW\_STATE. It does not affect the instance\_state of the instance.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
\- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
\- the \_maximum>0 and the \_release==FALSE.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.67 SPACE\_FooDataReader\_read\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the single instance, the samples belong to.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NO_DATA.
```
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the S P AC E \_ F o o Da t a R e a d er. T h e b e h a v i o u r i s i d e n t ic a l t o SPACE\_FooDataReader\_read except for that all samples returned belong to the single specified instance whose handle is a\_handle. Upon successful return, the data collection will contain samples all belonging to the same instance. The data is returned by the parameters data\_values and info\_seq. The corresponding DDS\_SampleInfo.instance\_handle in info\_seq will have the value of a\_handle. The DDS\_DataReader will check that each sample belongs to the specified instance (indicated by a\_handle) otherwise it will not place the sample in the returned collection.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
\- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
\- the \_maximum>0 and the \_release==FALSE.
\- the handle ==DDS\_HANDLE\_NIL.
\- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.68 SPACE\_FooDataReader\_read\_next\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NO_DATA.
```
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader. The behaviour i s s i m i l a r t o SPACE\_FooDataReader\_read\_instance (all samples returned belong to a single instance) except that the actual instance is not directly specified. Rather the samples will all belong to the ‘next’ instance with instance\_handle ‘greater’ (according to some internal-defined order) than a\_handle, that has available samples. The data is returned by the parameters data\_values and info\_seq. The corresponding DDS\_SampleInfo.instance\_handle in info\_seq will has the value of the next instance with respect to a\_handle.
# Instance Order
The internal-defined order is not important and is implementation specific. The important thing is that, according to the Data Distribution Service, all instances are ordered relative to each other. This ordering is between the instances, that is, it does not depend on the actual samples received. For the purposes of this explanation it is ‘as if’ each instance handle was represented as a unique integer.
The behaviour of SPACE\_FooDataReader\_read\_next\_instance is ‘as if’ the DDS\_DataReader invoked SPACE\_FooDataReader\_read\_instance passing the smallest instance\_handle among all the ones that:
• are greater than a\_handle
• have available samples (i.e. samples that meet the constraints imposed by the specified states).
The special value DDS\_HANDLE\_NIL is guaranteed to be ‘less than’ any valid i n s t a n c e \_ h a n d l e . S o t h e u s e o f t h e p a r a m e t e r v a l u e a\_handle==DDS\_HANDLE\_NIL will return the samples for the instance which has the smallest instance\_handle among all the instances that contains available samples.
# Typical use
The operation SPACE\_FooDataReader\_read\_next\_instance is intended to be used in an application-driven iteration where the application starts by passing a\_handle==DDS\_HANDLE\_NIL, examines the samples returned, and then uses the instance\_handle returned in the DDS\_SampleInfo as the value of a\_handle argument to the next call to SPACE\_FooDataReader\_read\_next\_instance. The iteration continues until SPACE\_FooDataReader\_read\_next\_instance returns the return value DDS\_RETCODE\_NO\_DATA.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
\- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
\- the \_maximum>0 and the \_release==FALSE.
\- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.69 SPACE\_FooDataReader\_read\_next\_instance\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_instance_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in const DDS\_ReadCondition a\_condition - a pointer to a DDS\_ReadCondition or DDS\_QueryCondition which filters the data before it is returned by the read operation.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or D D S\_ Q u e r y C on d i t i o n . Th e b e h a v io u r i s i d e n t i c a l t o SPACE\_FooDataReader\_read\_next\_instance except for that the samples are filtered by a DDS\_ReadCondition or DDS\_QueryCondition. When using a D D S \_ R e a d C o n d i t i o n , t h e r e s u l t i s t h e s a m e a s t h e SPACE\_FooDataReader\_read\_next\_instance operation with the same state parameters filled in as for the DDS\_create\_readcondition. In this way, the application can avoid repeating the same parameters, specified when creating the DDS\_ReadCondition. When using a DDS\_QueryCondition, a content based filtering can be done. When either using a DDS\_ReadCondition or D D S\_ Q u e r y C on d i t i o n , t h e c o n d i t io n m u s t b e c r e a t e d b y t h i s SPACE\_FooDataReader. Otherwise the operation will fail and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - one or more of the data\_values, or info\_seq and a\_condition parameters is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the DDS\_ReadCondition or DDS\_QueryCondition is not attached to this SPACE\_FooDataReader.
- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.70 SPACE\_FooDataReader\_read\_next\_sample
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read_next_sample
(SPACE_FooDataReader _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.71 SPACE\_FooDataReader\_read\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_read_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or DDS\_QueryCondition.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_ReadCondition a\_condition - a pointer to a DDS\_ReadCondition or DDS\_QueryCondition which filters the data before it is returned by the SPACE\_FooDataReader\_read operation.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or DDS\_QueryCondition. The condition pointer from both SPACE\_FooDataReader\_create\_readcondition or SPACE\_FooDataReader\_create\_querycondition may be used. The behaviour is identical to SPACE\_FooDataReader\_read except for that the samples are filtered by a DDS\_ReadCondition or DDS\_QueryCondition. When u s i n g a D D S \_ R e a d C o n d i t i o n , t h e r e s u l t i s t h e s a m e a s t h e SPACE\_FooDataReader\_read operation with the same state parameters filled in as for the SPACE\_FooDataReader\_create\_readcondition. In this way, the application can avoid repeating the same parameters, specified when creating the DDS\_ReadCondition. When using a DDS\_QueryCondition, a content based filtering can be done. When either using a DDS\_ReadCondition or D D S\_ Q u e r y C on d i t i o n , t h e c o n d i t io n m u s t b e c r e a t e d b y t h i s SPACE\_FooDataReader. Otherwise the operation will fail and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - one or more of the data\_values, or info\_seq and a\_condition parameters is an invalid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the DDS\_ReadCondition or DDS\_QueryCondition is not attached to this SPACE\_FooDataReader.
- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.72 SPACE\_FooDataReader\_return\_loan
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_return_loan
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq);
```
# Description
This operation indicates to the DDS\_DataReader that the application is done accessing the sequence of data\_values and info\_seq.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the sample data sequence which was loaned from the DDS\_DataReader.
inout DDS\_SampleInfoSeq \*info\_seq - the DDS\_SampleInfo structure sequence which was loaned from the DDS\_DataReader.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED or DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation indicates to the SPACE\_FooDataReader that the application is done accessing the sequence of data\_values and info\_seq obtained by some earlier i nv oc a ti o n o f t h e op e r a t i on S P AC E \_ F o o D at a R e a d er \_ r e a d or SPACE\_FooDataReader\_take (or any of the similar operations) on the SPACE\_FooDataReader.
The data\_values and info\_seq must belong to a single related pair; that is, they should correspond to a pair returned from a single call to the operation SPACE\_FooDataReader\_read or SPACE\_FooDataReader\_take. The data\_values and info\_seq must also have been obtained from the same DDS\_DataReader to which they are returned. If either of these conditions is not met the operation will fail and returns DDS\_RETCODE\_PRECONDITION\_NOT\_MET.
# Buffer Loan
The operation SPACE\_FooDataReader\_return\_loan allows implementations of the SPACE\_FooDataReader\_read and SPACE\_FooDataReader\_take operations to “loan” buffers from the Data Distribution Service to the application and in this manner provide “zero-copy” access to the data. During the loan, the Data Distribution Service will guarantee that the data\_values and info\_seq are not modified.
It is not necessary for an application to return the loans immediately after calling the operation SPACE\_FooDataReader\_read or SPACE\_FooDataReader\_take. However, as these buffers correspond to internal resources inside the DDS\_DataReader, the application should not retain them indefinitely.
# Calling SPACE\_FooDataReader\_return\_loan
The use of the SPACE\_FooDataReader\_return\_loan operation is only necessary if the call to the operation SPACE\_FooDataReader\_read or SPACE\_FooDataReader\_take “loaned” buffers to the application. This only occurs if the data\_values and info\_seq sequences had \_maximum=0 at the time the operation SPACE\_FooDataReader\_read or SPACE\_FooDataReader\_take was called. The application may also examine the ‘\_release’ property of the collection to determine where there is an outstanding loan. However, calling the operation SPACE\_FooDataReader\_return\_loan on a pair of sequences that does not have a loan is safe and has no side effects.
If the pair of sequences had a loan, upon return from the operation SPACE\_FooDataReader\_return\_loan the pair of sequences has \_maximum=0.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the DDS\_DataReader is informed that the sequences will not be used any more.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the data\_values and info\_seq do not belong to a single related pair.
- the data\_values and info\_seq were not obtained from this SPACE\_FooDataReader.
# 3.5.2.73 SPACE\_FooDataReader\_set\_listener (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_set_listener
(SPACE_FooDataReader _this,
const struct DDS_DataReaderListener *a_listener,
const DDS_StatusMask mask);
```
# 3.5.2.74 SPACE\_FooDataReader\_set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_set_qos
(SPACE_FooDataReader_this,
const DDS_DataReaderQos *qos);
```
# 3.5.2.75 SPACE\_FooDataReader\_take
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader, so it can not b e r e a d o r t a k e n a g a i n . T h e b e h a v i o u r i s i d e n t i c a l t o SPACE\_FooDataReader\_read except for that the samples are removed from the SPACE\_FooDataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available and removed from the SPACE\_FooDataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
\- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
\- the \_maximum>0 and the \_release==FALSE.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.76 SPACE\_FooDataReader\_take\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the single instance, the samples belong to.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader, so it can not be read or taken again. The behaviour is identical to SPACE\_FooDataReader\_read\_instance except for that the samples are removed from the SPACE\_FooDataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available and removed from the SPACE\_FooDataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
- the handle ==DDS\_HANDLE\_NIL.
- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.77 SPACE\_FooDataReader\_take\_next\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_instance
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in const DDS\_SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in const DDS\_ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in const DDS\_InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader, so it can not be read or taken again. The behaviour is identical to SPACE\_FooDataReader\_read\_next\_instance except for that the samples are removed from the SPACE\_FooDataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available and removed from the SPACE\_FooDataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - either or both of data\_values or info\_seq is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.78 SPACE\_FooDataReader\_take\_next\_instance\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_instance_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReader and by doing so, removes the data from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in const DDS\_ReadCondition a\_condition - a pointer to a DDS\_ReadCondition or DDS\_QueryCondition which filters the data before it is returned by the read operation.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or DDS\_QueryCondition and by doing so, removes the data from the SPACE\_FooDataReader, so it can not be read or taken again. The behaviour is identical to SPACE\_FooDataReader\_read\_next\_instance\_w\_condition except for that the samples are removed from the SPACE\_FooDataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available and removed from the SPACE\_FooDataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - one or more of the data\_values, info\_seq and a\_condition parameters is an invalid pointer or a\_handle is not a valid handle.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the DDS\_ReadCondition or DDS\_QueryCondition is not attached to this SPACE\_FooDataReader.
- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
- the handle has not been registered with this DataReader.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.79 SPACE\_FooDataReader\_take\_next\_sample
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take_next_sample
(SPACE_FooDataReader _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.80 SPACE\_FooDataReader\_take\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_take_w_condition
(SPACE_FooDataReader _this,
DDS_sequence_Foo *data_values,
DDS_SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or DDS\_QueryCondition and by doing so, removes the data from the SPACE\_FooDataReader.
# Parameters
in SPACE\_FooDataReader \_this - the SPACE\_FooDataReader object on which the operation is operated.
inout DDS\_sequence\_Foo \*data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout DDS\_SampleInfoSeq \*info\_seq - the returned DDS\_SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in const DDS\_long max\_samples - the maximum number of samples that is returned.
in const DDS\_ReadCondition a\_condition - a pointer to a DDS\_ReadCondition or DDS\_QueryCondition which filters the data before it is returned by the SPACE\_FooDataReader\_read operation.
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED, DDS\_RETCODE\_OUT\_OF\_RESOURCES, DDS\_RETCODE\_ NOT\_ENABLED, DDS\_RETCODE\_PRECONDITION\_NOT\_MET or DDS\_RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the SPACE\_FooDataReader, filtered by a DDS\_ReadCondition or DDS\_QueryCondition and by doing so, removes the data from the SPACE\_FooDataReader, so it can not be read or taken a g a i n . T h e b e h a v i o u r i s i d e n t i c a l t o SPACE\_FooDataReader\_read\_w\_condition except for that the samples are removed from the SPACE\_FooDataReader.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - a sequence of data values is available and removed from the SPACE\_FooDataReader.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - one or more of the data\_values, or info\_seq and a\_condition parameters is an invalid pointer.
• DDS\_RETCODE\_ALREADY\_DELETED - the SPACE\_FooDataReader has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• DDS\_RETCODE\_NOT\_ENABLED - the SPACE\_FooDataReader is not enabled.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the DDS\_ReadCondition or DDS\_QueryCondition is not attached to this SPACE\_FooDataReader.
- the max\_samples>\_maximum and max\_samples is not DDS\_LENGTH\_UNLIMITED.
- one or more values of \_length, \_maximum, and \_release for the two sequences are not identical.
- the \_maximum>0 and the \_release==FALSE.
• DDS\_RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.81 SPACE\_FooDataReader\_wait\_for\_historical\_data (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_wait_for_historical_data
(SPACE_FooDataReader _this,
const DDS_Duration_t *max_wait);
```
# 3.5.2.82 SPACE\_FooDataReader\_wait\_for\_historical\_data\_w\_condition (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReader_wait_for_historical_data_w_condition
(Space_FooDataReader _this,
const DDS_string filter_expression,
const DDS_StringSeq* filter_parameters,
const DDS_Time_t* min_source_timestamp,
const DDS_Time_t* max_source_timestamp
const DDS_ResourceLimitsQosPolicy* resource_limits,
const DDS_Duration_t* max_wait)
```
# 3.5.3 Class DDS\_DataSample
A DDS\_DataSample represents an atom of data information (i.e. one value for an i n s t a n c e ) a s r e t u r n e d b y t h e DDS\_DataReader ’s DDS\_DataReader\_read/SPACE\_FooDataReader\_take operations. It consists of two parts: A DDS\_SampleInfo and the Data itself. The Data part is the data as produced by a DDS\_Publisher. The DDS\_SampleInfo part contains additional information related to the data provided by the Data Distribution Service.
# 3.5.4 Struct DDS\_SampleInfo
The struct DDS\_SampleInfo represents the additional information that accompanies the data in each sample that is read or taken.
The interface description of this struct is as follows:
```c
struct DDS_SampleInfo
{
DDS_SampleStateKind sample_state;
DDS_ViewStateKind view_state;
DDS_InstanceStateKind instance_state;
DDS_Time_t source_timestamp;
DDS_InstanceHandle_t instance_handle;
DDS_InstanceHandle_t publication_handle;
DDS_long disposed_generation_count;
DDS_long no_writers_generation_count;
DDS_long sample_rank;
DDS_long generation_rank;
DDS_long absolute_generation_rank;
DDS_boolean valid_data;
DDS_Time_t reception_timestamp;
};
/*
* implemented API operations
* <no operations>
*/
```
The next paragraph describes the usage of the DDS\_SampleInfo struct.
# 3.5.4.1 DDS\_SampleInfo
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_SampleInfo
{
DDS_SampleStateKind sample_state;
DDS_ViewStateKind view_state;
DDS_InstanceStateKind instance_state;
DDS_Time_t source_timestamp;
DDS_InstanceHandle_t instance_handle;
DDS_InstanceHandle_t publication_handle;
DDS_long disposed_generation_count;
DDS_long no_writers_generation_count;
DDS_long sample_rank;
DDS_long generation_rank;
DDS_long absolute_generation_rank;
```
```txt
DDS_boolean valid_data;
DDS_Time_t reception_timestamp;
};
```
# Description
The struct DDS\_SampleInfo represents the additional information that accompanies the data in each sample that is read or taken.
# Attributes
DDS\_SampleStateKind sample\_state - whether or not the corresponding data sample has already been read.
DDS\_ViewStateKind view\_state - whether the DDS\_DataReader has already seen samples of the most-current generation of the related instance.
DDS\_InstanceStateKind instance\_state - whether the instance is alive, has no writers or is disposed of.
DDS\_Time\_t source\_timestamp - the time provided by the DDS\_DataWriter when the sample was written.
DDS\_InstanceHandle\_t instance\_handle - the handle that identifies locally the corresponding instance.
DDS\_InstanceHandle\_t publication\_handle - the handle that identifies locally the DDS\_DataWriter that modified the instance. In fact it is an instance\_handle of the built-in DCPSPublication sample that describes this DDS\_DataWriter. It can be used as a parameter to the DDS\_DataReader \_get\_matched\_publication\_data operation to obtain this built-in DCPSPublication sample.
DDS\_long disposed\_generation\_count - the number of times the instance has become alive after it was disposed of explicitly by a DDS\_DataWriter.
DDS\_long no\_writers\_generation\_count - the number of times the instance has become alive after it was disposed of because there were no DDS\_DataWriter objects.
DDS\_long sample\_rank - the number of samples related to the same instance that are found in the collection returned by a DDS\_DataReader\_read or DDS\_DataReader\_take operation.
DDS\_long generation\_rank - the generation difference between the time the sample was received and the time the most recent sample in the collection was received.
DDS\_long absolute\_generation\_rank - the generation difference between the time the sample was received and the time the most recent sample was received.
DDS\_boolean valid\_data - whether the DataSample contains any meanigful data. If not, the sample is only used to communicate a change in the instance\_state of the instance.
DDS\_Time\_t reception\_timestamp - the time provided by the DataReader when the sample was received.
# Detailed Description
The struct DDS\_SampleInfo represents the additional information that accompanies the data in each sample that is read or taken.
# Sample Information
The struct DDS\_SampleInfo represents the additional information that accompanies the data in each sample that is read or taken.
# Generations
A generation is defined as: ‘the number of times an instance has become alive (with instance\_state==DDS\_ALIVE\_INSTANCE\_STATE) at the time the sample was received’. Note that the generation counters are initialized to zero when a Reader first detects a never-seen-before instance.
Two types of generations are distinguished: disposed\_generation\_count and no\_writers\_generation\_count.
A f t e r a D D S \_ D at a W r i t er d i s p o s e s a n i n s t a n c e , t h e disposed\_generation\_count for all Readers that already knew that instance will be incremented the next time the instance is written again.
If the DDS\_DataReader detects that there are no live DDS\_DataWriter entities, the i n s ta n c e \_ s t at e of the s a m p le \_ i n f o w i l l c h a n g e f r o m DDS\_ALIVE\_INSTANCE\_STATE to DDS\_NOT\_ALIVE\_NO\_WRITERS\_ I N S T A N C E \_ S T A T E . T h e n e x t t i m e t h e i n s t a n c e i s w r i t t e n , no\_writers\_generation\_count will be incremented.
# Sample Information
DDS\_SampleInfo is the additional information that accompanies the data in each sample that is read or taken. It contains the following information:
• sample\_state (DDS\_READ\_SAMPLE\_STATE or DDS\_NOT\_READ\_SAMPLE STATE) indicates whether or not the corresponding data sample has already been read
• view\_state, (DDS\_NEW\_VIEW\_STATE, or DDS\_NOT\_NEW\_VIEW\_STATE) indicates whether the DDS\_DataReader has already seen samples of the most-current generation of the related instance
• instance\_state (DDS\_ALIVE\_INSTANCE\_STATE, DDS\_NOT\_ALIVE DISPOSED\_INSTANCE\_STATE, or DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_ STATE) indicates whether the instance is alive, has no writers or if it has been disposed of:
\- DDS\_ALIVE\_INSTANCE\_STATE if this instance is currently in existence
\- DDS\_NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE if this instance was disposed of by a DDS\_DataWriter
\- DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE none of the DDS\_DataWriter objects currently “alive” (according to the DDS\_LivelinessQosPolicy) are writing the instance.
• source\_timestamp indicates the time provided by the DDS\_DataWriter when the sample was written
• instance\_handle indicates locally the corresponding instance
• publication\_handle is used by the DDS implementation to locally identify the corresponding source DataWriter. You can access more detailed information about this particular publication by passing its publication\_handle to either the DDS\_DataReader\_get\_matched\_publication\_data operation or to the DDS\_PublicationBuiltinTopicDataDataReader\_read\_instance operation on the built-in reader for the “DCPSPublication” topic.
# A
Be aware that since DDS\_InstanceHandle\_t is an opaque datatype, it does not necessarily mean that the handle obtained from the publication\_handle has the same value as the one that appears in the instance\_handle field of the DDS\_SampleInfo when retrieving the publication info through corresponding "DCPSPublication" built-in reader. You can’t just compare two handles to determine whether they represent the same publication. If you want to know whether two handles actually do represent the same publication, use both handles to retrieve their corresponding DDS\_PublicationBuiltinTopicData samples and then compare the key field of both samples.
• disposed\_generation\_count indicates the number of times the instance has become alive after it was disposed of explicitly by a DDS\_DataWriter, at the time the sample was received
• no\_writers\_generation\_count indicates the number of times the instance has become alive after its instance\_state has been DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE, at the time the sample was received
• sample\_rank indicates the number of samples related to the same instance that follow in the collection returned by a DDS\_DataReader\_read or DDS\_DataReader\_take operation
• generation\_rank indicates the generation difference (number of times the instance was disposed of and become alive again) between the time the sample was received and the time the most recent sample in the collection (related to the same instance) was received
• absolute\_generation\_rank indicates the generation difference (number of times the instance was disposed of and become alive again) between the time the sample was received and the time the most recent sample (which may not be in the returned collection), related to the same instance, was received.
• valid\_data indicates whether the corresponding data value contains any meaningful data. If not, the data value is just a ‘dummy’ sample for which only the keyfields have been assigned. It is used to accompany the DDS\_SampleInfo that communicates a change in the instance\_state of an instance for which there is no ‘real’ sample available.
• reception\_timestamp indicates the time provided by the DDS\_DataReader when the sample was inserted.
NOTE: This is an OpenSplice-specific extension to the DDS\_SampleInfo struct and is not part of the DDS Specification.
# 3.5.5 DDS\_SubscriberListener Interface
Since a DDS\_Subscriber is a kind of DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_SubscriberListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must e x t e n d f r o m t h e D D S \_S u b s c r i be r L i s t en e r c l a s s . A l l DDS\_SubscriberListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The DDS\_SubscriberListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The DDS\_SubscriberListener is related to changes in communication status.
The interface description of this class is as follows:
```txt
/*
* interface DDS_SubscriberListener
*/
/*
* inherited from class DDS_DataReaderListener
```
```c
/*
* void
* DDS_SubscriberListener_on_requested_deadline_missed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedDeadlineMissedStatus *status);
*
*/
* void
* DDS_SubscriberListener_on_requested_incompatible_qos
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_RequestedIncompatibleQosStatus *status);
*
*/
* void
* DDS_SubscriberListener_on_sample_rejected
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleRejectedStatus *status);
*
*/
* void
* DDS_SubscriberListener_on_liveliness_changed
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_LivelinessChangedStatus *status);
*
*/
* void
* DDS_SubscriberListener_on_data_available
* (void *listener_data,
* DDS_DataReader reader);
*
*/
* void
* DDS_SubscriberListener_on_subscription_matched
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SubscriptionMatchedStatus *status);
*
*/
* void
* DDS_SubscriberListener_on_sample_lost
* (void *listener_data,
* DDS_DataReader reader,
* const DDS_SampleLostStatus *status);
*
*/
* abstract external operations
*/
```
```c
void
DDS_SubscriberListener_on_data_on_readers
(void *listener_data,
DDS_Subscriber subs);
/*
* implemented API operations
*/
struct DDS_SubscriberListener *
DDS_SubscriberListener__alloc
(void);
```
The next paragraphs list all DDS\_SubscriberListener operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited. The abstract operation is fully described since it must be implemented by the application.
# 3.5.5.1 DDS\_SubscriberListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_SubscriberListener *
DDS_SubscriberListener__alloc
(void);
```
# Description
This operation creates a new DDS\_SubscriberListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_SubscriberListener \* - Return value is the handle to the newly-created DDS\_SubscriberListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This ope ra t ion creates a new D D S \_ S u b sc r i b e r Li s t e n e r. T h e DDS\_SubscriberListener must be created using this operation. In other words, t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p e DDS\_SubscriberListener. When the application wants to release the DDS\_SubscriberListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_SubscriberListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.5.5.2 DDS\_SubscriberListener\_on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_data_available
(void *listener_data,
DDS_DataReader reader);
```
# 3.5.5.3 DDS\_SubscriberListener\_on\_data\_on\_readers (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_data_on_readers
(void *listener_data,
DDS_Subscriber subs);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when new data is available.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_Subscriber subs - contain a pointer to the DDS\_Subscriber for which data is available (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when new data is available for this DDS\_Subscriber. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant D D S\_ S u b s c r ib e r L i s te n e r i s i n s t a ll e d a n d e n a b le d f o r t h e DDS\_DATA\_ON\_READERS\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_Subscriber in the parameter subs for use by the application.
T h e s t a t u s e s DDS\_DATA\_ON\_READERS\_STATUS a n d DDS\_DATA\_AVAILABLE\_STATUS will occur together. In case these status changes occur, the Data Distribution Service will look for an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D DS \_ D A T A \_ ON \_ R E A D ER S \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look for an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
Note that if DDS\_SubscriberListener\_on\_data\_on\_readers is called, then t h e D a t a D i s t r i b u t i o n S e r v i c e w i l l n o t t r y t o c a l l DDS\_SubscriberListener\_on\_data\_available, however, the application can force a call to the callback function on\_data\_available of DDS\_DataReaderListener objects that have data by means of the notify\_datareaders operation.
# 3.5.5.4 DDS\_SubscriberListener\_on\_liveliness\_changed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_liveliness_changed
(void *listener_data,
DDS_DataReader reader,
const DDS_LivelinessChangedStatus *status);
```
# 3.5.5.5 DDS\_SubscriberListener\_on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_requested_deadline_missed
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedDeadlineMissedStatus *status);
```
# 3.5.5.6 DDS\_SubscriberListener\_on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_requested_incompatible_qos
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedIncompatibleQosStatus *status) =0;
```
# 3.5.5.7 DDS\_SubscriberListener\_on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_sample_lost
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleLostStatus *status);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.5.8 DDS\_SubscriberListener\_on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_sample_rejected
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleRejectedStatus *status);
```
# 3.5.5.9 DDS\_SubscriberListener\_on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderListener for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_SubscriberListener_on_subscription_matched
(void *listener_data,
DDS_DataReader reader,
const DDS_SubscriptionMatchedStatus *status);
```
# 3.5.6 DDS\_DataReaderListener interface
Since a DDS\_DataReader is a kind of DDS\_Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DDS\_DataReaderListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must e x t e n d f r o m t h e D D S \_D a t a R e a de r L i s t en e r c l a s s . A l l DDS\_DataReaderListener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
All operations for this interface must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
The DDS\_DataReaderListener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous status change events, such as a missed deadline, violation of a QosPolicy setting, etc. The DDS\_DataReaderListener is related to changes in communication status.
The interface description of this class is as follows:
```c
/*
* interface DDS_DataReaderListener
*/
/*
* abstract external operations
*/
void
DDS_DataReaderListener_on_requested_deadline_missed
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedDeadlineMissedStatus *status);
void
DDS_DataReaderListener_on_requested_incompatible_qos
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedIncompatibleQosStatus *status);
void
```
```c
DDS_DataReaderListener_on_sample_rejected
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleRejectedStatus *status);
void
DDS_DataReaderListener_on_liveliness_changed
(void *listener_data,
DDS_DataReader reader,
const DDS_LivelinessChangedStatus *status);
void
DDS_DataReaderListener_on_data_available
(void *listener_data,
DDS_DataReader reader);
void
DDS_DataReaderListener_on_subscription_matched
(void *listener_data,
DDS_DataReader reader,
const DDS_SubscriptionMatchedStatus *status);
void
DDS_DataReaderListener_on_sample_lost
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleLostStatus *status);
/*
* implemented API operations
*/
struct DDS_DataReaderListener *
DDS_DataReaderListener_alloc
(void);
```
The next paragraphs describe the usage of all DDS\_DataReaderListener operations. These abstract operations are fully described because they must be implemented by the application.
# 3.5.6.1 DDS\_DataReaderListener\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DataReaderListener *
DDS_DataReaderListener__alloc
(void);
```
# Description
This operation creates a new DDS\_DataReaderListener.
# Parameters
```txt
<none>
```
# Return Value
struct DDS\_DataReaderListener \* - Return value is the handle to the newly-created DDS\_DataReaderListener. In case of an error, a DDS\_OBJECT\_NIL pointer is returned.
# Detailed Description
This ope ra t ion creates a new D D S \_ D a t aR e a d e r Li s t e n e r. T h e DDS\_DataReaderListener must be created using this operation. In other words, t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p e DDS\_DataReaderListener. When the application wants to release the DDS\_DataReaderListener it must be released using DDS\_free.
I n c a s e t h e r e a r e i n s u f f i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h e DDS\_DataReaderListener, a DDS\_OBJECT\_NIL pointer is returned instead.
# 3.5.6.2 DDS\_DataReaderListener\_on\_data\_available (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_data_available
(void *listener_data,
DDS_DataReader reader);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when new data is available.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - contain a pointer to the DDS\_DataReader for which data is available (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when new data is available for this DDS\_DataReader. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant D D S\_ D a t a R e ad e r L i s te n e r i s i n s t a ll e d a n d e n a b le d f o r t h e DDS\_DATA\_AVAILABLE\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader for use by the application.
T h e s t a t u s e s DDS\_DATA\_ON\_READERS\_STATUS a n d DDS\_DATA\_AVAILABLE\_STATUS will occur together. In case these status changes occur, the Data Distribution Service will look for an attached and activated DDS\_SubscriberListener or DDS\_DomainParticipantListener (in that o r d e r ) f o r t h e D D S\_ D A T A \_ ON \_ R E A D E RS \_ S T A T US . I n c a s e t h e DDS\_DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look for an attached and activated DDS\_DataReaderListener, DDS\_SubscriberListener or DDS\_DomainParticipantListener for the DDS\_DATA\_AVAILABLE\_STATUS (in that order).
Note that if DDS\_SubscriberListener\_on\_data\_on\_readers is called, then t h e D a t a D i s t r i b u t i o n S e r v i c e w i l l n o t t r y t o c a l l DDS\_DataReaderListener\_on\_data\_available, however, the application can force a call to the DDS\_DataReader objects that have data by means of the DDS\_Subscriber\_notify\_datareaders operation.
# 3.5.6.3 DDS\_DataReaderListener\_on\_liveliness\_changed (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_liveliness_changed
(void *listener_data,
DDS_DataReader reader,
const DDS_LivelinessChangedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the liveliness of one or more DDS\_DataWriter objects that were writing instances read through this DDS\_DataReader has changed.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - contain a pointer to the DDS\_DataReader for which the liveliness of one or more DDS\_DataWriter objects has changed (this is an input to the application provided by the Data Distribution Service).
in const DDS\_LivelinessChangedStatus \*status - contain the DDS\_LivelinessChangedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the liveliness of one or more DDS\_DataWriter objects that were writing instances read through this DDS\_DataReader has changed. In other words, some DDS\_DataWriter have become “alive” or “not alive”. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant D D S\_ D a t a R ea d e r L i s te n e r i s i n s t a ll e d a n d e n a b le d f o r t h e DDS\_LIVELINESS\_CHANGED\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader and the DDS\_LivelinessChangedStatus struct for use by the application.
# 3.5.6.4 DDS\_DataReaderListener\_on\_requested\_deadline\_missed (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_requested_deadline_missed
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedDeadlineMissedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the deadline that the DDS\_DataReader was expecting through its DDS\_DeadlineQosPolicy was not respected.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - contain a pointer to the DDS\_DataReader for which the deadline was missed (this is an input to the application provided by the Data Distribution Service).
in const DDS\_RequestedDeadlineMissedStatus \*status - contain the DDS\_RequestedDeadlineMissedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the deadline that the DDS\_DataReader was expecting through its DDS\_DeadlineQosPolicy was not respected for a specific instance. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataReaderListener is installed and enabled for the DDS\_REQUESTED\_DEADLINE\_MISSED\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader and the DDS\_RequestedDeadlineMissedStatus struct in the parameter status for use by the application.
# 3.5.6.5 DDS\_DataReaderListener\_on\_requested\_incompatible\_qos (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_requested_incompatible_qos
(void *listener_data,
DDS_DataReader reader,
const DDS_RequestedIncompatibleQosStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS changes.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - a pointer to the DDS\_DataReader provided by the Data Distribution Service.
in const DDS\_RequestedIncompatibleQosStatus \*status - the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS struct provided by the Data Distribution Service.
# Return Value
<none>
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataReaderListener is installed and enabled for the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader and the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS struct in the parameter status, for use by the application.
The application can use this operation as a callback function implementing a proper response to the status change. This operation is enabled by setting the DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS in the mask in the call to DDS\_DataReader\_set\_listener. When the DDS\_DataReaderListener on t h e DDS\_DataReader i s n o t e n a b l e d f o r t h e DDS\_REQUESTED\_INCOMPATIBLE\_QOS\_STATUS, the status change will propagate to the DDS\_SubscriberListener of the DDS\_Subscriber (if enabled) or to the DDS\_DomainParticipantListener of the DDS\_DomainParticipant (if enabled).
# 3.5.6.6 DDS\_DataReaderListener\_on\_sample\_lost (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_sample_lost
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleLostStatus *status);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.6.7 DDS\_DataReaderListener\_on\_sample\_rejected (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
```
```c
DDS_DataReaderListener_on_sample_rejected
(void *listener_data,
DDS_DataReader reader,
const DDS_SampleRejectedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when a sample has been rejected.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - contain a pointer to the DDS\_DataReader for which a sample has been rejected (this is an input to the application provided by the Data Distribution Service).
in const DDS\_SampleRejectedStatus \*status - contain the DDS\_SampleRejectedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation is the external operation (interface, which must be implemented by the application) that is called by the Data Distribution Service when a (received) sample has been rejected. Samples may be rejected by the DDS\_DataReader when it runs out of resource\_limits to store incoming samples. Ususally this means that old samples need to be ‘consumed’ (for example by ‘taking’ them instead of ‘reading’ them) to make room for newly incoming samples.
The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DDS\_DataReaderListener is installed and enabled for the DDS\_SAMPLE\_REJECTED\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader and the DDS\_SampleRejectedStatus struct in the parameter status for use by the application.
# 3.5.6.8 DDS\_DataReaderListener\_on\_subscription\_matched (abstract)
# Synopsis
```c
#include <dds_dcps.h>
void
DDS_DataReaderListener_on_subscription_matched
```
```c
(void *listener_data,
DDS_DataReader reader,
const DDS_SubscriptionMatchedStatus *status);
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when a new match has been discovered for the current subscription, or when an existing match has ceased to exist.
# Parameters
inout void \*listener\_data - a pointer to a user-defined object which may be used for identification of the Listener.
in DDS\_DataReader reader - contains a pointer to the DDS\_DataReader for which a match has been discovered (this is an input to the application provided by the Data Distribution Service).
in const SubscriptionMatchedStatus \*status - contains the SubscriptionMatchedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
```txt
<none>
```
# Detailed Description
This operation must be implemented by the application and is called by the Data Distribution Service when a new match has been discovered for the current subscription, or when an existing match has ceased to exist. Usually this means that a new DataWriter that matches the Topic and that has compatible Qos as the current DDS\_DataReader has either been discovered, or that a previously discovered DataWriter has ceased to be matched to the current DDS\_DataReader. A DataWriter may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DDS\_DataReader or when either the DDS\_DataReader or the DataWriter has chosen to put its matching counterpart on its ignore-list using the DDS\_DomainParticipant\_ignore\_publication or DDS\_DomainParticipant\_ignore\_subcription operations.
The implementation of this Listener operation may be left empty when this functionality is not needed: it will only be called when the relevant D D S\_ D a t a R ea d e r L i s te n e r i s i n s t a ll e d a n d e n a b le d f o r t h e DDS\_SUBSCRIPTION\_MATCHED\_STATUS.
The Data Distribution Service will provide a pointer to the DDS\_DataReader in the parameter reader and the DDS\_SubscriptionMatchedStatus struct in the parameter status for use by the application.
# 3.5.7 Class DDS\_ReadCondition
The DDS\_DataReader objects can create a set of DDS\_ReadCondition (and DDS\_StatusCondition) objects which provide support (in conjunction with DDS\_WaitSet objects) for an alternative communication style between the Data Distribution Service and the application (i.e., wait-based rather than notification-based).
DDS\_ReadCondition objects allow an DDS\_DataReader to specify the data samples it is interested in (by specifying the desired sample-states, view-states, and instance-states); see the parameter definitions for DDS\_DataReader's DDS\_DataReader\_create\_readcondition operation. This allows the Data Distribution Service to trigger the condition only when suitable information is available. DDS\_ReadCondition objects are to be used in conjunction with a DDS\_WaitSet. More than one DDS\_ReadCondition may be attached to the same DDS\_DataReader.
The interface description of this class is as follows:
```c
/*
* interface DDS_ReadCondition
*/
/*
* inherited from DDS_Condition
*/
/* DDS_boolean
* DDS_ReadCondition_get_trigger_value
* (DDS_ReadCondition _this);
*/
/*
* implemented API operations
*/
DDS_SampleStateMask
DDS_ReadCondition_get_sample_state_mask
(DDS_ReadCondition _this);
DDS_ViewStateMask
DDS_ReadCondition_get_view_state_mask
(DDS_ReadCondition _this);
DDS_InstanceStateMask
DDS_ReadCondition_get_instance_state_mask
(DDS_ReadCondition _this);
DDS_DataReader
DDS_ReadCondition_get_datareader
(DDS_ReadCondition _this);
```
The next paragraphs describe the usage of all DDS\_ReadCondition operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.5.7.1 DDS\_ReadCondition\_get\_datareader
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataReader
DDS_ReadCondition_get_datareader
(DDS_ReadCondition _this);
```
# Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ D a t a R e a d e r a s s o c i a t e d w i t h t h e DDS\_ReadCondition.
# Parameters
in DDS\_ReadCondition \_this - the DDS\_ReadCondition object on which the operation is operated.
# Return Value
DDS\_DataReader - Result value is a pointer to the DDS\_DataReader.
# Detailed Description
T h i s o p e r a t i o n r e t u r n s t h e D D S \_ D a t a R e a d e r a s s o c i a t e d w i t h t h e DDS\_ReadCondition. Note that there is exactly one DDS\_DataReader associated with each DDS\_ReadCondition (i.e. the DDS\_DataReader that created the DDS\_ReadCondition object).
# 3.5.7.2 DDS\_ReadCondition\_get\_instance\_state\_mask
# Synopsis
```c
#include <dds_dcps.h>
DDS_InstanceStateMask
DDS_ReadCondition_get_instance_state_mask
(DDS_ReadCondition _this);
```
# Description
This operation returns the set of instance\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
# Parameters
in DDS\_ReadCondition \_this - the DDS\_ReadCondition object on which the operation is operated.
# Return Value
DDS\_InstanceStateMask - Result value are the instance\_states specified when the DDS\_ReadCondition was created.
# Detailed Description
This operation returns the set of instance\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
The instance\_states returned are the instance\_states specified when the DDS\_ReadCondition was created. instance\_states can be DDS\_ALIVE\_INSTANCE\_STATE,
DDS\_NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE,
DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE or a combination of these.
# 3.5.7.3 DDS\_ReadCondition\_get\_sample\_state\_mask
# Synopsis
```c
#include <dds_dcps.h>
DDS_SampleStateMask
DDS_ReadCondition_get_sample_state_mask
(DDS_ReadCondition _this);
```
# Description
This operation returns the set of sample\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
# Parameters
in DDS\_ReadCondition \_this - the DDS\_ReadCondition object on which the operation is operated.
# Return Value
DDS\_SampleStateMask - Result value are the sample\_states specified when the DDS\_ReadCondition was created.
# Detailed Description
This operation returns the set of sample\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
The sample\_states returned are the sample\_states specified when the DDS\_ReadCondition was created. sample\_states can be DDS\_READ\_SAMPLE\_STATE, DDS\_NOT\_READ\_SAMPLE\_STATE or both.
# 3.5.7.4 DDS\_ReadCondition\_get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Condition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_boolean
DDS_ReadCondition_get_trigger_value
(DDS_ReadCondition _this);
```
# 3.5.7.5 DDS\_ReadCondition\_get\_view\_state\_mask
# Synopsis
```c
#include <dds_dcps.h>
DDS_ViewStateMask
DDS_ReadCondition_get_view_state_mask
(DDS_ReadCondition _this);
```
# Description
This operation returns the set of view\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
# Parameters
in DDS\_ReadCondition \_this - the DDS\_ReadCondition object on which the operation is operated.
# Return Value
DDS\_ViewStateMask - Result value are the view\_states specified when the DDS\_ReadCondition was created.
# Detailed Description
This operation returns the set of view\_states that are taken into account to determine the trigger\_value of the DDS\_ReadCondition.
The view\_states returned are the view\_states specified when the DDS\_ReadCondition was created. view\_states can be DDS\_NEW\_VIEW\_STATE, DDS\_NOT\_NEW\_VIEW\_STATE or both.
# 3.5.8 Class DDS\_QueryCondition
DDS\_QueryCondition objects are specialized DDS\_ReadCondition objects that allow the application to specify a filter on the locally available data. The DDS\_DataReader objects accept a set of DDS\_QueryCondition objects for the DDS\_DataReader and provide support (in conjunction with DDS\_WaitSet objects) for an alternative communication style between the Data Distribution Service and the application (i.e., wait-based rather than notification-based).
# Query Function
DDS\_QueryCondition objects allow an application to specify the data samples it is interested in (by specifying the desired sample-states, view-states, instance-states and query expression); see the parameter definitions for DDS\_DataReader's DDS\_DataReader\_read/DDS\_DataReader\_take operations. This allows the Data Distribution Service to trigger the condition only when suitable information is available. DDS\_QueryCondition objects are to be used in conjunction with a DDS\_WaitSet. More than one DDS\_QueryCondition may be attached to the same DDS\_DataReader.
The query (query\_expression) is similar to an SQL WHERE clause and can be parameterized by arguments that are dynamically changeable with the DDS\_QueryCondition\_set\_query\_parameters operation.
The interface description of this class is as follows:
```c
/*
* interface DDS_QueryCondition
*/
/*
* inherited from DDS_ReadCondition
*/
/* DDS_SampleStateMask
* DDS_QueryCondition_get_sample_state_mask
* (DDS_QueryCondition _this);
*/
/* DDS_ViewStateMask
* DDS_QueryCondition_get_view_state_mask
* (DDS_QueryCondition _this);
*/
/* DDS_InstanceStateMask
* DDS_QueryCondition_get_instance_state_mask
* (DDS_QueryCondition _this);
*/
/* DDS_DataReader
* DDS_QueryCondition_get_datareader
* (DDS_QueryCondition _this);
```
```c
*/
/* DDS_boolean
* DDS_QueryCondition_get_trigger_value
* (DDS_QueryCondition _this);
*/
/*
* implemented API operations
*/
DDS_string
DDS_QueryCondition_get_query_expression
(DDS_QueryCondition _this);
DDS_ReturnCode_t
DDS_QueryCondition_get_query_parameters
(DDS_QueryCondition _this,
DDS_StringSeq *query_parameters);
DDS_ReturnCode_t
DDS_QueryCondition_set_query_parameters
(DDS_QueryCondition _this,
const DDS_StringSeq *query_parameters);
```
The next paragraphs describe the usage of all DDS\_QueryCondition operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.5.8.1 DDS\_QueryCondition\_get\_datareader (inherited)
This operation is inherited and therefore not described here. See the class DDS\_ReadCondition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataReader
DDS_QueryCondition_get_datareader
(DDS_QueryCondition _this);
```
# 3.5.8.2 DDS\_QueryCondition\_get\_instance\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class DDS\_ReadCondition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_InstanceStateMask
DDS_QueryCondition_get_instance_state_mask
(DDS_QueryCondition _this);
```
# 3.5.8.3 DDS\_QueryCondition\_get\_query\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QueryCondition_get_query_parameters
(DDS_QueryCondition _this,
DDS_StringSeq *query_parameters);
```
# Description
This operation returns the query\_parameters associated with the DDS\_QueryCondition.
# Parameters
in DDS\_QueryCondition \_this - the DDS\_QueryCondition object on which the operation is operated.
inout DDS\_StringSeq \*query\_parameters - a handle to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation obtains the query\_parameters associated with the DDS\_QueryCondition. That is, the parameters specified on the last successful call t o DDS\_QueryCondition\_set\_query\_parameters or, if DDS\_QueryCondition\_set\_query\_parameters was never called, the arguments specified when the DDS\_QueryCondition were created. The resulting handle contains a sequence of strings with the parameters used in the SQL expression (i.e., the %n tokens in the expression). The number of parameters in the result sequence will exactly match the number of %n tokens in the query expression associated with the DDS\_QueryCondition.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of query parameters applied to this DDS\_QueryCondition has successfully been copied into the specified query\_parameters parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_QueryCondition has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.8.4 DDS\_QueryCondition\_get\_query\_expression
# Synopsis
```c
#include <dds_dcps.h>
DDS_string
DDS_QueryCondition_get_query_expression
(DDS_QueryCondition _this);
```
# Description
T h i s o p e r a t i o n r e t u r n s t h e q u e r y e x p r e s s i o n a s s o c i a t e d w i t h t h e DDS\_QueryCondition.
# Parameters
in DDS\_QueryCondition \_this - the DDS\_QueryCondition object on which the operation is operated.
# Return Value
DDS\_string - Result value is a pointer to the query expression associated with the DDS\_QueryCondition.
# Detailed Description
T h i s o p e r a t i o n r e t u r n s t h e q u e r y e x p r e s s i o n a s s o c i a t e d w i t h t h e DDS\_QueryCondition. That is, the expression specified when the DDS\_QueryCondition was created. The operation will return DDS\_OBJECT\_NIL when there was an internal error or when the DDS\_QueryCondition was already deleted. If there were no parameters, an empty sequence is returned.
It is the applications responsibility to free the allocated memory for the DDS\_StringSeq.
# 3.5.8.5 DDS\_QueryCondition\_get\_sample\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class DDS\_ReadCondition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_SampleStateMask
DDS_QueryCondition_get_sample_state_mask
(DDS_QueryCondition _this);
```
# 3.5.8.6 DDS\_QueryCondition\_get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class DDS\_ReadCondition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_boolean
DDS_QueryCondition_get_trigger_value
(DDS_QueryCondition _this);
```
# 3.5.8.7 DDS\_QueryCondition\_get\_view\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class DDS\_ReadCondition for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ViewStateMask
DDS_QueryCondition_get_view_state_mask
(DDS_QueryCondition _this);
```
# 3.5.8.8 DDS\_QueryCondition\_set\_query\_parameters
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QueryCondition_set_query_parameters
(DDS_QueryCondition _this,
const DDS_StringSeq *query_parameters);
```
# Description
T h i s o p e r a t i o n c h a n g e s t h e q u e r y p a r a m e t e r s a s s o c i a t e d w i t h t h e DDS\_QueryCondition.
# Parameters
in DDS\_QueryCondition \_this - the DDS\_QueryCondition object on which the operation is operated.
in const DDS\_StringSeq \*query\_parameters - a sequence of strings which are the parameters used in the SQL query string (i.e., the “%n” tokens in the expression).
# Return Value
D D S \_ R e t u r n C o d e \_ t - P o s s i b l e r e t u r n c o d e s o f t h e o p e r a t i o n a r e : DDS\_RETCODE\_OK, DDS\_RETCODE\_ERROR, DDS\_RETCODE\_ILLEGAL\_ OPERATION, DDS\_RETCODE\_BAD\_PARAMETER, DDS\_RETCODE\_ ALREADY\_DELETED or DDS\_RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
T h i s o p e r a t i o n c h a n g e s t h e q u e r y p a r a m e t e r s a s s o c i a t e d w i t h t h e DDS\_QueryCondition. The parameter query\_parameters is a sequence of strings which are the parameters values used in the SQL query string (i.e., the “%n” tokens in the expression). The number of values in query\_parameters must be equal or greater than the highest referenced %n token in the query\_expression (e.g. if %1 and %8 are used as parameter in the query\_expression, the query\_parameters should at least contain n+1 = 9 values).
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the query parameters associated with the DDS\_QueryCondition are changed.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_BAD\_PARAMETER - the number of parameters in query\_parameters does not match the number of “%n” tokens in the expression for this DDS\_QueryCondition or one of the parameters is an illegal parameter.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_QueryCondition has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.9 Class DDS\_DataReaderView (abstract)
A DataReaderView allows the application to create an additional view on the dataset stored in a DataReader. The view is expressed by an (optional) alternative key list specified in the DDS\_DataReaderViewQos, which allows it to specify an alternative storage spectrum. Applications might prefer such an alternative storage spectrum (for example by adding or removing key-fields) because it may help them to process the samples in a different order/cohesion than what they will have when they use the original key-list.
A DataReaderView has the following properties:
• Any DDS\_DataReaderView belongs to exactly one DDS\_DataReader.
• A DDS\_DataReader can have zero to many DDS\_DataReaderViews attached (all with their own key\_list definitions).
• The DDS\_DataReaderView has the same interface as the DDS\_DataReader with its read and take variants, including w\_condition and next\_instance, next\_sample, etc. It also supports DDS\_ReadConditions and DDS\_QueryConditions like a DDS\_DataReader does.
• Any sample that is inserted into the DataReader will introduce a corresponding DataViewSample in all its attached DataReaderViews in a ViewInstance as defined by the keys specified in the DataReaderView Qos key\_list when the view was created.
• Like samples in a DataReader, DataViewSamples in a DataReaderView belong to exactly one ViewInstance. Instances in the dataReaderView do not have any instance state information though. The instance state information found in the SampleInfo for each DataReaderView sample is copied from the corresponding DataReader sample.
• Whenever a sample is taken from the DataReader, its corresponding samples in all attached DataReaderViews will be removed as well. The same goes for samples that are pushed out of the DataReader instance history (in case of a KEEP\_LAST HistoryQosPolicy) or for samples whose lifespan expired.
• A ViewInstance always has an infinite history depth; samples can not be pushed out of the view.
• Whenever a sample is taken from a DataReaderView, it is removed from that DataReaderView but not from the DataReader, nor from any of its other views. If all samples in a ViewInstance are taken, then that ViewInstance is destroyed.
DDS\_DataReaderView is an abstract class. It is specialized for each particular application data type. For a fictional application data type "Foo" (defined in the module SPACE) the specialized class would be SPACE\_FooDataReaderView.
The interface description of this class is as follows:
```c
/*
* interface DDS_DataReaderView
*/
/*
* inherited from class DDS_Entity
*/
```
```c
/* DDS_StatusCondition
* DDS_DataReaderView_get_statuscondition
* (DDS_DataReaderView _this);
*/
/*
* DDS_StatusMask
* DDS_DataReaderView_get_status_changes
* (DDS_DataReaderView _this);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_enable
* (DDS_DataReaderView _this);
*/
/*
* abstract operations
* (implemented in the data type specific DDS_DataReaderView)
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_get_key_value
* (DDS_DataReaderView _this,
* <data> *key_holder,
* const DDS_InstanceHandle_t handle);
*/
/*
* DDS_InstanceHandle_t
* DDS_DataReaderView_lookup_instance
* (DDS_DataReaderView _this,
* const <data> *instance_data);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read_instance
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
```
```c
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read_next_instance
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read_next_instance_w_condition
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_ReadCondition a_condition);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read_next_sample
* (DDS_DataReaderView _this,
* <data> *received_data,
* DDS_SampleInfo *sample_info);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_read_w_condition
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_ReadCondition a_condition);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_return_loan
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq);
*/
/*
*/
```
```c
* DDS_ReturnCode_t
* DDS_DataReaderView_take
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_take_instance
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_take_next_instance
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_take_next_instance_w_condition
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_InstanceHandle_t a_handle,
* const DDS_ReadCondition a_condition);
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_take_next_sample
* (DDS_DataReaderView _this,
* <data> *received_data,
* DDS_SampleInfo *sample_info);
```
```c
*/
/*
* DDS_ReturnCode_t
* DDS_DataReaderView_take_w_condition
* (DDS_DataReaderView _this,
* DDS_sequence_<data> *data_values,
* SampleInfoSeq *info_seq,
* const DDS_long max_samples,
* const DDS_ReadCondition a_condition);
*/
/*
* implemented API operations
*/
DDS_QueryCondition
DDS_DataReaderView_create_querycondition
(DDS_DataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
DDS_ReadCondition
DDS_DataReaderView_create_readcondition
(DDS_DataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
DDS_DataReaderView_delete_contained_entities
(DDS_DataReaderView _this);
DDS_ReturnCode_t
DDS_DataReaderView_delete_readcondition
(DDS_DataReaderView _this,
const DDS_ReadCondition a_condition);
DDS_DataReader
DDS_DataReaderView_get_datareader
(DDS_DataReaderView _this);
DDS_ReturnCode_t
DDS_DataReaderView_get_qos
(DDS_DataReaderView _this,
DDS_DataReaderViewQos *qos);
DDS_ReturnCode_t
DDS_DataReaderView_set_qos
```
```javascript
(DDS_DataReaderView _this,
const DDS_DataReaderViewQos *qos);
```
The next paragraphs describe the usage of all DataReaderView operations. The inherited and abstract operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited and in the data type specific classes in which they are implemented.
Because the DataReaderView closely follows DataReader semantics, a lot of operations are identical. In those cases where the operation on the DataReaderView is identical to the one on the DataReader, no full description is given but the operation on the DataReader or its respective type specific class is referenced.
# 3.5.9.1 DDS\_DataReaderView\_create\_querycondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_QueryCondition
DDS_DataReaderView_create_querycondition
(DDS_DataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
```
# Description
This operation creates a new QueryCondition for the DataReaderView. For a full d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 2 , DDS\_DataReader\_create\_querycondition, on page 427, which describes this operation in detail for the DataReader class.
# 3.5.9.2 DDS\_DataReaderView\_create\_readcondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReadCondition
DDS_DataReaderView_create_readcondition
(DDS_DataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation creates a new ReadCondition for the DataReaderView. For a full description please refer to Section 3.5.2.3, DDS\_DataReader\_create\_readcondition, on page 428, which describes this operation in detail for the DataReader class.
# 3.5.9.3 DDS\_DataReaderView\_delete\_contained\_entities
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_delete_contained_entities
(DDS_DataReaderView _this);
```
# Description
This operation deletes all the entities that were created by means of one of the "create\_" operations on the DataReaderView. For a full description please refer to Section 3.5.2.5, DDS\_DataReader\_delete\_contained\_entities, on page 430, which describes this operation in detail for the DataReader class.
# 3.5.9.4 DDS\_DataReaderView\_delete\_readcondition
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_delete_readcondition
(DDS_DataReaderView _this,
DDS_ReadCondition a_condition);
```
# Description
This operation deletes a ReadCondition or QueryCondition which is attached to the DataReaderView. For a full description please refer to Section 3.5.2.5, DDS\_DataReader\_delete\_contained\_entities, on page 430, which describes this operation in detail for the DataReader class.
# 3.5.9.5 DDS\_DataReaderView\_enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_enable
(DDS_DataReaderView _this);
```
# 3.5.9.6 DDS\_DataReaderView\_get\_datareader
# Synopsis
```c
#include <dds_dcps.h>
DDS_DataReader
DDS_DataReaderView_get_datareader
(DDS_DataReaderView _this);
```
# Description
Retrieves the DataReader to which this DataReaderView is attached.
# Parameters
in DDS\_DataReaderView - the DDS\_DataReaderView object on which the operation is operated.
# Return Value
DDS\_DataReader - Return value is a pointer to the DDS\_DataReader to which the DDS\_DataReaderView belongs.
# Detailed Description
This operation returns a pointer to the DDS\_DataReader from which the DDS\_DataReaderView was originally created. If the DDS\_DataReaderView is already deleted, the DDS\_OBJECT\_NIL pointer is returned.
# 3.5.9.7 DDS\_DataReaderView\_get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_get_key_value
(DDS_DataReaderView _this,
<data> *key_holder,
const DDS_InstanceHandle_t handle);
```
# 3.5.9.8 DDS\_DataReaderView\_get\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_get_qos
(DDS_DataReaderView_this,
DDS_DataReaderViewQos *qos);
```
# Description
This operation allows access to the existing set of QoS policies of a D D S\_ D a t a R e ad e r V i e w o n w h ic h t h i s o p e r a t i o n i s u s e d . T h i s DDS\_DataReaderViewQos is stored at the location pointed to by the qos parameter.
# Parameters
in DDS\_DataReaderView - the DDS\_DataReaderView object on which the operation is operated.
inout DataReaderViewQos \*qos - a pointer to the destination DDS\_DataReaderViewQos struct in which the QosPolicy settings will be copied.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation allows access to the existing set of QoS policies of a D D S\_ D a t a R e ad e r V i e w o n w h ic h t h i s o p e r a t i o n i s u s e d . T h i s DDS\_DataReaderViewQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• DDS\_RETCODE\_OK - the existing set of QoSPolicy values applied to this DDS\_DataReaderView has successfully been copied into the specified DDS\_DataReaderViewQos parameter.
• DDS\_RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• DDS\_RETCODE\_ALREADY\_DELETED - the DDS\_DataReaderView has already been deleted.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.9.9 DDS\_DataReaderView\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusMask
DDS_DataReaderView_get_status_changes
(DDS_DataReaderView _this);
```
# 3.5.9.10 DDS\_DataReaderView\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <dds_dcps.h>
DDS_StatusCondition
DDS_DataReaderView_get_statuscondition
(DDS_DataReaderView _this);
```
# 3.5.9.11 DDS\_DataReaderView\_lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_InstanceHandle_t
DDS_DataReaderView_lookup_instance
(DDS_DataReaderView _this,
const <data> *instance_data);
```
# 3.5.9.12 DDS\_DataReaderView\_read (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.13 DDS\_DataReaderView\_read\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read_instance
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.14 DDS\_DataReaderView\_read\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read_next_instance
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.15 DDS\_DataReaderView\_read\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read_next_instance_w_condition
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# 3.5.9.16 DDS\_DataReaderView\_read\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read_next_sample
(DDS_DataReaderView _this,
<data> *data_values,
DDS_SampleInfo *sample_info);
```
# 3.5.9.17 DDS\_DataReaderView\_read\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_read_w_condition
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# 3.5.9.18 DDS\_DataReaderView\_return\_loan (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_return_loan
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq);
```
# 3.5.9.19 DDS\_DataReaderView\_set\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_set_qos
(DDS_DataReaderView _this,
const DDS_DataReaderViewQos *qos);
```
# Description
T h i s o p e r a t i o n r e p l a c e s t h e e x i s t i n g s e t o f Q o s P o l i c y s e t t i n g s f o r a DDS\_DataReaderView.
# Parameters
in DDS\_DataReaderView - the DDS\_DataReaderView object on which the operation is operated.
in const DDS\_DataReaderViewQos \*qos - the new set of QosPolicy settings for the DDS\_DataReaderView.
# Return Value
```txt
DDS_ReturnCode_t - Possible return codes of the operation are: DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_IMMUTABLE_POLICY.
```
# Detailed Description
T h i s o p e r a t i o n r e p l a c e s t h e e x i s t i n g s e t o f Q o s P o l i c y s e t t i n g s f o r a DDS\_DataReaderView.
The parameter qos contains the QosPolicy settings which is checked for self-consistency and mutability. When the application tries to change a QosPolicy setting for an enabled DDS\_DataReaderView, which can only be set before the D D S \_ D a t a R e a d e r V i e w i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d a DDS\_RETCODE\_IMMUTABLE\_POLICY is returned. In other words, the application must provide the presently set QosPolicy settings in case of the immutable QosPolicy settings. Only the mutable QosPolicy settings can be changed.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided that the operation returned DDS\_RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new DataReaderViewQos is set.
• RETCODE\_ERROR - an internal error has occurred.
• DDS\_RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataReaderViewQos. It contains NULL pointer strings or strings that do not represent accessible attributes of the datatype.
• RETCODE\_ALREADY\_DELETED - the DDS\_DataReaderView has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a value different from the one set during enabling of the DataReader.
# 3.5.9.20 DDS\_DataReaderView\_take (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.21 DDS\_DataReaderView\_take\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take_instance
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.22 DDS\_DataReaderView\_take\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take_next_instance
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.9.23 DDS\_DataReaderView\_take\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take_next_instance_w_condition
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# 3.5.9.24 DDS\_DataReaderView\_take\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take_next_sample
(DDS_DataReaderView _this,
<data> *data_values,
DDS_SampleInfo *sample_info);
```
# 3.5.9.25 DDS\_DataReaderView\_take\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <NameSpace>\_<type>DataReaderView class. Therefore, to use this operation, the data type specific implementation of this operation in its respective derived class must be used. For further explanation see the description for the f i c t i o n a l d a t a t y p e F o o ( d e f i n e d i n t h e m o d u l e S P A C E ) d e r i v e d SPACE\_FooDataReaderView class.
Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_DataReaderView_take_w_condition
(DDS_DataReaderView _this,
DDS_sequence_<data> *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# 3.5.10 Class SPACE\_FooDataReaderView
T h e p r e p r o c e s s o r g e n e r a t e s f r o m I D L t y p e d e s c r i p t i o n s t h e <NameSpace>\_<type>DataReaderView classes. For each application data type w h i c h i s u s e d a s To p i c d a t a t y p e , a t y p e d c l a s s <NameSpace>\_<type>DataReaderView is derived from the D D S \_ D a t a R e a d e r V i e w c l a s s . I n t h i s p a r a g r a p h , t h e c l a s s SPACE\_FooDataReaderView describes the operations of these derived <NameSpace>\_<type>DataReaderView classes as an example for the fictional application type Foo (defined in the module SPACE).
For instance, for an application, the definitions are located in the Space.idl file.
The pre-processor will generate a Space.h include file.
The interface description of this class is as follows:
```c
/*
* interface SPACE_FooDataReaderView
*/
/*
* inherited from class DDS_Entity
*/
/* DDS_StatusCondition
* SPACE_FooDataReaderView_get_statuscondition
* (SPACE_FooDataReaderView _this);
*/
/*
* DDS_StatusMask
* SPACE_FooDataReaderView_get_status_changes
* (SPACE_FooDataReaderView _this);
*/
/*
* DDS_ReturnCode_t
* SPACE_FooDataReaderView_enable
* (SPACE_FooDataReaderView _this);
*/
/*
* inherited from class DDS_DataReaderView
*/
/*
* DDS_QueryCondition
* SPACE_FooDataReaderView_create_querycondition
* (SPACE_FooDataReaderView _this,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states,
* const DDS_char *query_expression,
* const DDS_StringSeq *query_parameters);
*/
/*
*/
```
```c
* DDS_ReadCondition
* SPACE_FooDataReaderView_create_readcondition
* (SPACE_FooDataReaderView _this,
* const DDS_SampleStateMask sample_states,
* const DDS_ViewStateMask view_states,
* const DDS_InstanceStateMask instance_states);
*/
/*
* DDS_ReturnCode_t
* SPACE_FooDataReaderView_delete_contained_entities
* (SPACE_FooDataReaderView _this);
*/
/*
* DDS_ReturnCode_t
* SPACE_FooDataReaderView_delete_readcondition
* (SPACE_FooDataReaderView _this,
* const DDS_ReadCondition a_condition);
*/
/*
* DDS_DataReader
* SPACE_FooDataReaderView_get_datareader
* (SPACE_FooDataReaderView _this);
*/
/*
* DDS_ReturnCode_t
* SPACE_FooDataReaderView_get_qos
* (SPACE_FooDataReaderView _this,
* DDS_DataReaderViewQos *qos);
*/
/*
* DDS_ReturnCode_t
* SPACE_FooDataReaderView_set_qos
* (SPACE_FooDataReaderView _this,
* const DDS_DataReaderViewQos *qos);
*/
/*
* implemented API operations
*/
DDS_ReturnCode_t
SPACE_FooDataReaderView_get_key_value
(SPACE_FooDataReaderView _this,
Foo *key_holder,
const DDS_InstanceHandle_t handle);
DDS_InstanceHandle_t
SPACE_FooDataReaderView_lookup_instance
(SPACE_FooDataReaderView _this,
const Foo *instance_data);
```
```c
DDS_ReturnCode_t
SPACE_FooDataReaderView_read
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_instance_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_sample
(SPACE_FooDataReaderView _this,
Foo *received_data,
DDS_SampleInfo *sample_info);
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_w_condition
(SPACE_FooDataReaderView _this,
```
```c
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReaderView_return_loan
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_next_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_next_instance_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
```
```c
const DDS_ReadCondition a_condition);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_next_sample
(SPACE_FooDataReaderView _this,
Foo *received_data,
DDS_SampleInfo *sample_info);
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
The next paragraphs describe the usage of all SPACE\_FooDataReaderView operations. The inherited operations are listed but not fully described because they are not implemented in this class. The full description of these operations is given in the classes from which they are inherited.
# 3.5.10.1 SPACE\_FooDataReaderView\_create\_querycondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_QueryCondition
SPACE_FooDataReaderView_create_querycondition
(SPACE_FooDataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states,
const DDS_char *query_expression,
const DDS_StringSeq *query_parameters);
```
# 3.5.10.2 SPACE\_FooDataReaderView\_create\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReadCondition
SPACE_FooDataReaderView_create_readcondition
(SPACE_FooDataReaderView _this,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# 3.5.10.3 SPACE\_FooDataReaderView\_delete\_contained\_entities
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_delete_contained_entities
(SPACE_FooDataReaderView _this);
```
# 3.5.10.4 SPACE\_FooDataReaderView\_delete\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_delete_readcondition
(SPACE_FooDataReaderView _this,
const DDS_ReadCondition a_condition);
```
# 3.5.10.5 SPACE\_FooDataReaderView\_enable (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_enable
(SPACE_FooDataReaderView _this);
```
# 3.5.10.6 SPACE\_FooDataReaderView\_get\_datareader (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation
# Synopsis
```c
#include <Space.h>
DDS_DataReader
SPACE_FooDataReaderView_get_datareader(SPACE_FooDataReaderView _this);
```
# 3.5.10.7 SPACE\_FooDataReaderView\_get\_key\_value
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_get_key_value
(SPACE_FooDataReaderView _this,
Foo *key_holder,
const DDS_InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.8 SPACE\_FooDataReaderView\_get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_get_qos
(SPACE_FooDataReaderView _this,
DDS_DataReaderViewQos *qos);
```
# 3.5.10.9 SPACE\_FooDataReaderView\_get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusMask
SPACE_FoodDataReaderView_get_status_changes
(SPACE_FoodDataReaderView _this);
```
# 3.5.10.10 SPACE\_FooDataReaderView\_get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class DDS\_Entity for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_StatusCondition
SPACE_FooDataReaderView_get_statuscondition
(SPACE_FooDataReaderView _this);
```
# 3.5.10.11 SPACE\_FooDataReaderView\_lookup\_instance
# Synopsis
```c
#include <Space.h>
DDS_InstanceHandle_t
SPACE_FooDataReaderView_lookup_instance
(SPACE_FooDataReaderView _this,
const Foo* instance_data)
```
# Description
This operation returns the value of the instance handle which corresponds to the instance\_data. For a full description please refer to paragraph '3.5.2.60 l o o k u p \_ i n s t a n c e ' w h i c h d e s c r i b e s t h i s o p e r a t i o n i n d e t a i l f o r t h e S P A C E \_ F o o D a t a R e a d e r c l a s s . N o t e t h a t i n s t a n c e s i n t h e S P AC E \_ F o o D at a R e a d er V i e w are no t de fin ed by th e k eys of th e DDS\_TopicDescription but by the key list in the DDS\_DataReaderView QosPolicy.
# 3.5.10.12 SPACE\_FooDataReaderView\_read
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
T h i s o p e r a t i o n r e a d s a s e q u e n c e o f F o o s a m p l e s f r o m t h e SPACE\_FooDataReaderView. For a full description please refer to Section 3.5.2.66, SPACE\_FooDataReader\_read, on page 478, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.13 SPACE\_FooDataReaderView\_read\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_instance
(SPACE_FooDataReaderView _this,
```
```txt
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReaderView. For a full description please refer to Section 3.5.2.67, SPACE\_FooDataReader\_read\_instance, on page 483, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.14 SPACE\_FooDataReaderView\_read\_next\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReaderView. For a full description please refer to Section 3.5.2.68, SPACE\_FooDataReader\_read\_next\_instance, on page 485, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.15 SPACE\_FooDataReaderView\_read\_next\_instance\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_instance_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
```
const DDS\_ReadCondition a\_condition);
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReaderView, filtered by a DDS\_ReadCondition or DDS\_QueryCondition. For a full description please refer to Section 3.5.2.69, SPACE\_FooDataReader\_read\_next\_instance\_w\_condition, on page 488, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.16 SPACE\_FooDataReaderView\_read\_next\_sample
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_next_sample
(SPACE_FooDataReaderView _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.17 SPACE\_FooDataReaderView\_read\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_read_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# Description
T h i s o p e r a t i o n r e a d s a s e q u e n c e o f F o o s a m p l e s f r o m t h e SPACE\_FooDataReaderView, filtered by a DDS\_ReadCondition or DDS\_QueryCondition. For a full description please refer to Section 3.5.2.71, SPACE\_FooDataReader\_read\_w\_condition, on page 490, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.18 SPACE\_FooDataReaderView\_return\_loan
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FoodDataReaderView_return_loan
```
```txt
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq);
```
# Description
This operation indicates to the SPACE\_FooDataReaderView that the application is done accessing the sequence of data\_values and info\_seq. For a full description please refer to Section 3.5.2.72, SPACE\_FooDataReader\_return\_loan, o n p a g e 4 9 2 , w h i c h d e s c r i b e s t h i s o p e r a t i o n i n d e t a i l f o r t h e SPACE\_FooDataReader class.
# 3.5.10.19 SPACE\_FooDataReaderView\_set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DDS\_DataReaderView for further explanation.
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_set_qos
(SPACE_FooDataReaderView _this,
const DDS_DataReaderViewQos *qos);
```
# 3.5.10.20 SPACE\_FooDataReaderView\_take
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_take
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
T h i s o p e r a t i o n r e a d s a s e q u e n c e o f F o o s a m p l e s f r o m t h e SPACE\_FooDataReaderView and by doing so, removes the data from the SPACE\_FooDataReaderView, but not from the SPACE\_FooDataReader that it b e l o n g s t o . F o r a f u l l d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 7 5 , SPACE\_FooDataReader\_take, on page 495, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.21 SPACE\_FooDataReaderView\_take\_instance
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_instance
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_SampleStateMask sample_states,
const DDS_ViewStateMask view_states,
const DDS_InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of a single instance from the SPACE\_FooDataReaderView and by doing so, removes the data from the SPACE\_FooDataReaderView, but not from the SPACE\_FooDataReader that it b e l o n g s t o . F o r a f u l l d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 7 6 , SPACE\_FooDataReader\_take\_instance, on page 497, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.22 SPACE\_FooDataReaderView\_take\_next\_instance
# Synopsis
```c
#include <Space.h>
ReturnCode_t
take_next_instance
(FooSeq *data_values,
SampleInfoSeq *info_seq,
DDS_long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReaderView and by doing so, removes the data from the SPACE\_FooDataReaderView, but not from the SPACE\_FooDataReader that it b e l o n g s t o . F o r a f u l l d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 7 7 , SPACE\_FooDataReader\_take\_next\_instance, on page 499, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.23 SPACE\_FooDataReaderView\_take\_next\_instance\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_next_instance_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_InstanceHandle_t a_handle,
const DDS_ReadCondition a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the SPACE\_FooDataReaderView, filtered by a DDS\_ReadCondition or DDS\_QueryCondition and by doing so, removes the data from the SPACE\_FooDataReaderView, but not from the SPACE\_FooDataReader that it b e l o n g s t o . F o r a f u l l d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 7 8 , SPACE\_FooDataReader\_take\_next\_instance\_w\_condition, on page 501, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.5.10.24 SPACE\_FooDataReaderView\_take\_next\_sample
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_next_sample
(SPACE_FooDataReaderView _this,
Foo *data_values,
DDS_SampleInfo *sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.25 SPACE\_FooDataReaderView\_take\_w\_condition
# Synopsis
```c
#include <Space.h>
DDS_ReturnCode_t
SPACE_FooDataReaderView_take_w_condition
(SPACE_FooDataReaderView _this,
DDS_sequence_Foo *data_values,
SampleInfoSeq *info_seq,
const DDS_long max_samples,
const DDS_ReadCondition a_condition);
```
# Description
T h i s o p e r a t i o n r e a d s a s e q u e n c e o f F o o s a m p l e s f r o m t h e SPACE\_FooDataReaderView, filtered by a DDS\_ReadCondition or DDS\_QueryCondition and by doing so, removes the data from the SPACE\_FooDataReaderView, but not from the SPACE\_FooDataReader that it b e l o n g s t o . F o r a f u l l d e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 8 0 , SPACE\_FooDataReader\_take\_w\_condition, on page 503, which describes this operation in detail for the SPACE\_FooDataReader class.
# 3.6 QosProvider
The QosProvider API allows users to specify the QoS settings of their DCPS entities outside of application code in XML. The QosProvider is delivered as part of the DCPS API of OpenSplice and has no factory. It is not associated with a DDS\_DomainParticipant, so it can be be obtained by a normal allocation.
# 3.6.1 Class DDS\_QosProvider
The DDS\_QosProvider class provides access to the QoS settings that are specified in an XML file. The interface is as follows:
```c
/* Allocator */
DDS_QosProvider
DDS_QosProvider_alloc (
const char *uri,
const char *profile);
/* API operations */
DDS_ReturnCode_t
DDS_QosProvider_get_participant_qos(
DDS_QosProvider_this,
DDS_DomainParticipantQos *qos,
const char *id);
DDS_ReturnCode_t
DDS_QosProvider_get_topic_qos(
DDS_QosProvider_this,
DDS_TopicQos *qos,
const char *id);
DDS_ReturnCode_t
DDS_QosProvider_get_subscriber_qos(
DDS_QosProvider_this,
DDS_SubscriberQos *qos,
const char *id);
DDS_ReturnCode_t
DDS_QosProvider_get_datareader_qos(
```
```c
DDS_QosProvider _this,
DDS_DataReaderQos *qos,
const char *id);
DDS_ReturnCode_t
DDS_QosProvider_get_publisher_qos(
DDS_QosProvider _this,
DDS_PublisherQos *qos,
const char *id);
DDS_ReturnCode_t
DDS_QosProvider_get_datawriter_qos(
DDS_QosProvider _this,
DDS_DataWriterQos *qos,
const char *id);
```
# 3.6.1.1 DDS\_QosProvider\_\_alloc
# Synopsis
```c
#include <dds_dcps.h>
DDS_QosProvider
DDS_QosProvider__alloc (
const char *uri,
const char *profile);
```
# Description
Constructs a new DDS\_QosProvider based on the provided uri and profile.
# Parameters
in char \* uri - A Uniform Resource Identifier (URI) that points to the location where the QoS profile needs to be loaded from. Currently only URI’s with a ‘file’ scheme that point to an XML file are supported. If profiles and/or QoS settings are not uniquely identifiable by name within the resource pointed to by uri, a random one of them will be stored.
in char \* profile - The name of the QoS profile that serves as the default QoS profile for the DDS\_QosProvider\_get\_\*\_qos(...) operations.
# Return Value
A DDS\_QosProvider instance that is instantiated with all profiles and/or QoS’s loaded from the location specified by the provided uri.
Construction of the DDS\_QosProvider will fail under the following conditions:
— No uri is provided.
— The resource pointed to by uri cannot be found.
— The content of the resource pointed to by uri is malformed (e.g., malformed XML).
# 3.6.1.2 DDS\_QosProvider\_get\_participant\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_participant_qos(
DDS_QosProvider _this,
DDS_DomainParticipantQos *qos,
const char *id);
```
# Description
Resolves the DDS\_DomainParticipantQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_DomainParticipantQos \* qos - A pointer to the destination DDS\_DomainParticipantQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_DomainParticipantQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# 3.6.1.3 DDS\_QosProvider\_get\_topic\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_topic_qos(
DDS_QosProvider _this,
DDS_TopicQos *qos,
const char *id);
```
# Description
Resolves the DDS\_TopicQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_TopicQos \* qos - A pointer to the destination DDS\_TopicQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_TopicQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# 3.6.1.4 DDS\_QosProvider\_get\_subscriber\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_subscriber_qos(
DDS_QosProvider _this,
DDS_SubscriberQos *qos,
const char *id);
```
# Description
Resolves the DDS\_SubscriberQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_SubscriberQos \* qos - A pointer to the destination DDS\_SubscriberQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_SubscriberQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# 3.6.1.5 DDS\_QosProvider\_get\_datareader\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_datareader_qos(
DDS_QosProvider _this,
DDS_DataReaderQos *qos,
const char *id);
```
# Description
Resolves the DDS\_DataReaderQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_DataReaderQos \* qos - A pointer to the destination DDS\_DataReaderQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_DataReaderQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# 3.6.1.6 DDS\_QosProvider\_get\_publisher\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_publisher_qos(
DDS_QosProvider _this,
DDS_PublisherQos *qos,
const char *id);
```
# Description
Resolves the DDS\_PublisherQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_PublisherQos \* qos - A pointer to the destination DDS\_PublisherQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_PublisherQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# 3.6.1.7 DDS\_QosProvider\_get\_datawriter\_qos
# Synopsis
```c
#include <dds_dcps.h>
DDS_ReturnCode_t
DDS_QosProvider_get_datawriter_qos(
DDS_QosProvider _this,
DDS_DataWriterQos *qos,
const char *id);
```
# Description
Resolves the DDS\_DataWriterQos identified by the id from the uri the DDS\_QosProvider \_this is associated with.
# Parameters
in DDS\_QosProvider \_this - The DDS\_QosProvider on which the operation is performed.
inout DDS\_DataWriterQos \* qos - A pointer to the destination DDS\_DataWriterQos in which the QoS policy settings will be copied.
in char \* id - The fully-qualified name that identifies a QoS within the uri associated with the DDS\_QosProvider or a name that identifies a QoS within the uri associated with the DDS\_QosProvider instance relative to its default QoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names and all others are interpreted as names relative to the default QoS profile of the DDS\_QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the DDS\_QosProvider.
# Return Value
The operation may return:
• DDS\_RETCODE\_OK - If qos has been initialized successfully.
• DDS\_RETCODE\_NO\_DATA - If no DDS\_DataWriterQos that matches the provided id can be found within the uri associated with the DDS\_QosProvider.
• DDS\_RETCODE\_BAD\_PARAMETER - If \_this and/or qos is NULL.
• DDS\_RETCODE\_PRECONDITION\_NOT\_MET - If the DDS\_QosProvider instance is not properly initialized.
• DDS\_RETCODE\_OUT\_OF\_RESOURCES - If not enough memory is available to perform the operation.
• DDS\_RETCODE\_ERROR - If an internal error occurred.
# APPENDICES
# Appendix
# A
# Quality Of Service
Each DDS\_Entity is accompanied by an <DDS\_Entity>Qos structure that implements the basic mechanism for an application to specify Quality of Service attributes. This structure consists of DDS\_Entity specific QosPolicy attributes. QosPolicy attributes are structured types where each type specifies the information that controls an DDS\_Entity related (configurable) attribute of the Data Distribution Service.
# Affected Entities
Each DDS\_Entity can be configured with a set of QosPolicy settings. However, any DDS\_Entity cannot support any QosPolicy. For instance, a DDS\_DomainParticipant supports different QosPolicy settings than a DDS\_Topic or a DDS\_Publisher. The set of QosPolicy settings is implemented as a struct of QosPolicy structs, identified as <DDS\_Entity>Qos. Each <DDS\_Entity>Qos struct only contains those QosPolicy structs relevant to the specific DDS\_Entity. The <DDS\_Entity>Qos struct serves as the parameter to operations which require a Qos. <DDS\_Entity>Qos struct is the API implementation of the QoS. Depending on the specific <DDS\_Entity>Qos, it controls the behaviour of a DDS\_Topic, DDS\_DataWriter, DDS\_DataReader, DDS\_Publisher, DDS\_Subscriber, DDS\_DomainParticipant or DDS\_DomainParticipantFactory1.
# Basic Usage
The basic way to modify or set the <DDS\_Entity>Qos is by using an DDS\_<Entity>\_get\_qos operation to get all QosPolicy settings from this DDS\_Entity (that is the <DDS\_Entity>Qos), modify several specific QosPolicy settings and put them back using an DDS\_<DDS\_Entity>\_set\_qos operation to set all QosPolicy settings on this DDS\_Entity (that is the <DDS\_Entity>Qos). A n e x a m p l e o f t h e s e o p e r a t i o n s f o r t h e D D S \_ D a t a W r i t e r Q o s a r e
DDS\_Publisher\_get\_default\_datawriter\_qos and DDS\_Publisher\_ set\_default\_datawriter\_qos, which take the DDS\_DataWriterQos as a parameter.
The interface description of this struct is as follows:
```c
/*
* struct <name>QosPolicy
* see appendix
*/
* struct <DDS_Entity>Qos
*/
struct DDS_DomainParticipantFactoryQos
{ DDS_EntityFactoryQosPolicy entity_factory; };
struct DDS_DomainParticipantQos
{ DDS_UserDataQosPolicy user_data;
DDS_EntityFactoryQosPolicy entity_factory;
DDS_SchedulingQosPolicy watchdog_scheduling;
DDS_SchedulingQosPolicy listener_scheduling; };
struct DDS_TopicQos
{ DDS_TopicDataQosPolicy topic_data;
DDS_DurabilityQosPolicy durability;
DDS_DurabilityServiceQosPolicy durability_service;
DDS_DeadlineQosPolicy deadline;
DDS_LatencyBudgetQosPolicy latency_budget;
DDS_LivelinessQosPolicy liveliness;
DDS_ReliabilityQosPolicy reliability;
DDS_DestinationOrderQosPolicy destination_order;
DDS_HistoryQosPolicy history;
DDS_ResourceLimitsQosPolicy resource_limits;
DDS_TransportPriorityQosPolicy transport_priority;
DDS_LifespanQosPolicy lifespan;
DDS_OwnershipQosPolicy ownership; };
struct DDS_DataWriterQos
{ DDS_DurabilityQosPolicy durability;
DDS_DeadlineQosPolicy deadline;
DDS_LatencyBudgetQosPolicy latency_budget;
DDS_LivelinessQosPolicy liveliness;
DDS_ReliabilityQosPolicy reliability;
DDS_DestinationOrderQosPolicy destination_order;
DDS_HistoryQosPolicy history;
DDS_ResourceLimitsQosPolicy resource_limits;
DDS_TransportPriorityQosPolicy transport_priority;
DDS_LifespanQosPolicy lifespan;
DDS_UserDataQosPolicy user_data;
DDS_OwnershipQosPolicy ownership;
DDS_OwnershipStrengthQosPolicy ownership_strength;
DDS_WriteDataLifecycleQosPolicy writer_data_lifecycle; };
struct DDS_PublisherQos
```
```c
{ DDS_PresentationQosPolicy presentation;
DDS_PartitionQosPolicy partition;
DDS_GroupDataQosPolicy group_data;
DDS_EntityFactoryQosPolicy entity_factory; };
struct DDS_DataReaderQos
{ DDS_DurabilityQosPolicy durability;
DDS_DeadlineQosPolicy deadline;
DDS_LatencyBudgetQosPolicy latency_budget;
DDS_LivelinessQosPolicy liveliness;
DDS_ReliabilityQosPolicy reliability;
DDS_DestinationOrderQosPolicy destination_order;
DDS_HistoryQosPolicy history;
DDS_ResourceLimitsQosPolicy resource_limits;
DDS_UserDataQosPolicy user_data;
DDS_OwnershipQosPolicy ownership;
DDS_TimeBasedFilterQosPolicy time_based_filter;
DDS_ReaderDataLifecycleQosPolicy reader_data_lifetime;};
struct DDS_SubscriberQos
{ DDS_PresentationQosPolicy presentation;
DDS_PartitionQosPolicy partition;
DDS_GroupDataQosPolicy group_data;
DDS_EntityFactoryQosPolicy entity_factory; };
/*
* define <DDS_Entity>_QOS_DEFAULT
*/
#define DDS_PARTICIPANT_QOS_DEFAULT
#define DDS_TOPIC_QOS_DEFAULT
#define DDS_DATAWRITER_QOS_DEFAULT
#define DDS_PUBLISHER_QOS_DEFAULT
#define DDS_DATAREADER_QOS_DEFAULT
#define DDS_SUBSCRIBER_QOS_DEFAULT
#define DDS_DATAWRITER_QOS_USE_TOPIC_QOS
#define DDS_DATAREADER_QOS_USE_TOPIC_QOS
/*
* implemented API operations
* <no operations>
*/
```
The next paragraphs describe the usage of each <DDS\_Entity>Qos struct.
# DDS\_DataReaderQos
# Synopsis
```c
#include <dds_dcps.h>
struct DDS_DataReaderQos
{ DDS_DurabilityQosPolicy durability;
DDS_DeadlineQosPolicy deadline;
DDS_LatencyBudgetQosPolicy latency_budget;
```
```txt
DDS_LivelinessQosPolicy liveliness;
DDS_ReliabilityQosPolicy reliability;
DDS_DestinationOrderQosPolicy destination_order;
DDS_HistoryQosPolicy history;
DDS_ResourceLimitsQosPolicy resource_limits;
DDS_UserDataQosPolicy user_data;
DDS_OwnershipQosPolicy ownership;
DDS_TimeBasedFilterQosPolicy time_based_filter;
DDS_ReaderDataLifecycleQosPolicy reader_data_lifecycle;};
```
# Description
This struct provides the basic mechanism for an application to specify Quality of Service attributes for a DDS\_DataReader.
# Attributes
DDS\_DurabilityQosPolicy durability - whether the data should be stored for late joining readers. See Section 3.1.3.3 on page 73 for more detailed information about these settings.
DDS\_DeadlineQosPolicy deadline - the period within which a new sample is expected. See Section 3.1.3.1 on page 69 for more detailed information about these settings.
DDS\_LatencyBudgetQosPolicy latency\_budget - used by the Data Distribution Service for optimization. See Section 3.1.3.8 on page 83 for more detailed information about these settings.
DDS\_LivelinessQosPolicy liveliness - the way the liveliness of the DDS\_DataReader is asserted to the Data Distribution Service. See Section 3.1.3.10 on page 85 for more detailed information about these settings.
DDS\_ReliabilityQosPolicy reliability - the reliability of the data distribution. See Section 3.1.3.16 on page 102 for more detailed information about these settings.
DDS\_DestinationOrderQosPolicy destination\_order - the order in which the DDS\_DataReader timely orders the data. See Section 3.1.3.2 on page 71 for more detailed information about these settings.
DDS\_HistoryQosPolicy history - how samples should be stored. See Section 3.1.3.7 on page 80 for more detailed information about these settings.
DDS\_ResourceLimitsQosPolicy resource\_limits - the maximum amount of resources to be used. See Section 3.1.3.17 on page 104 for more detailed information about these settings.
DDS\_UserDataQosPolicy user\_data - used to attach additional information to the DDS\_DataReader. See Section 3.1.3.22 on page 110 for more detailed information about these settings.
DDS\_OwnershipQosPolicy ownership - whether a DataWriter exclusively owns an instance. See Section 3.1.3.11 on page 87 for more detailed information about these settings.
DDS\_TimeBasedFilterQosPolicy time\_based\_filter - the maximum data rate at which the DDS\_DataReader will receive changes. See Section 3.1.3.19 on page 107 for more detailed information about these settings.
DDS\_ReaderDataLifecycleQosPolicy reader\_data\_lifecycle - d e t e r m i n e s w h e t h e r i n s t a n c e s t a t e c h a n g e s ( e i t h e r DDS\_NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE o r DDS\_NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE) are presented to the user when no corresponding samples are available to communicate them. Also it determines how long an instance state change remains available to a user that does not explicitly consume them. See Section 3.1.3.15 on page 99 for more detailed information about these settings.
# Detailed Description
A QosPolicy can be set when the DDS\_DataReader is created with the DDS\_Subscriber\_create\_datareader operation (or modified with the DDS\_DataReader\_set\_qos operation). Both operations take the DDS\_DataReaderQos struct as a parameter. There may be cases where several policies are in conflict. Consistency checking is performed each time the policies are modified when they are being created and, in case they are already enabled, via the DDS\_DataReader\_set\_qos operation.
Some QosPolicy have “immutable” semantics meaning that they can only be specified either at DDS\_DataReader creation time or prior to calling the DDS\_DataReader\_enable operation on the DDS\_DataReader.
See Struct QosPolicy on page 59 for a list of all <name>QosPolicy settings, their meaning, characteristics and possible values, as well as if it applies to a DDS\_DataReader.
The initial value of the default DDS\_DataReaderQos in the DDS\_Subscriber are given in the following table:
Table 19: DDS\_DATAREADER\_QOS\_DEFAULT
| DDS_Entity | Status Name | Description |
| DDS_Topic | DDS_INCONSISTENT_TOPIC_STATUS | Another DDS_Topic exists with the same name but with different characteristics. |
| DDS_Subscriber | DDS_DATA_ON_READERS_STATUS | New information is available. |
| DDS_DataReader | DDS_SAMPLE_REJECTED_STATUS | A (received) sample has been rejected. |
| DDS_LIVELINESS_CHANGED_STATUS | The liveliness of one or more DDS_DataWriter objects, that were writing instances read through the DDS_DataReader objects has changed. Some DDS_DataWriter object have become “alive” or “not alive”. |
| DDS_REQUESTED_DEADLINE_MISSED_STATUS | The deadline that the DDS_DataReader was expecting through its DDS_DeadlineQosPolicy was not respected for a specific instance. |
| DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what is offered. |
| DDS_DATA_AVAILABLE_STATUS | New information is available. |
| DDS_SAMPLE_LOST_STATUS | A sample has been lost (never received). |
| DDS_SUBSCRIPTION_MATCHED_STATUS | The DDS_DataReader has found a DDS_DataWriter that matches the ZWDDS_Topic and has compatible QoS. |
| DDS_DataWriter | DDS_LIVELINESS_LOST_STATUS | The liveliness that the DDS_DataWriter has committed through its DDS_LivelinessQosPolicy was not respected; thus DDS_DataReader objects will consider the DDS_DataWriter as no longer “alive”. |
| DDS_OFFERED_DEADLINE_MISSED_STATUS | The deadline that the DDS_DataWriter has committed through its DDS_DeadlineQosPolicy was not respected for a specific instance. |
| DDS_OFFERED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what was requested. |
| DDS_PUBLICATION_MATCHED_STATUS | The DDS_DataWriter has found DDS_DataReader that matches the DDS_Topic and has compatible QoS. |
The statuses may be classified in:
• read communication statuses: i.e., those that are related to arrival of data, namely DDS\_DATA\_ON\_READERS and DDS\_DATA\_AVAILABLE
• plain communication statuses: i.e., all the others.
For each plain communication status, there is a corresponding status struct. The i n f o r m a t i o n f r o m t h i s s t r u c t c a n b e r e t r i e v e d w i t h t h e o p e r a t i o n s get\_<status\_name>\_status. For example, to get the DDS\_INCONSISTENT\_TOPIC status (which information is stored in the DDS\_InconsistentTopicStatus struct), the application must call the operation DDS\_Topic\_get\_inconsistent\_topic\_status. A plain communication status can only be read from the DDS\_Entity on which it is applicable. For the read communication statuses there is no struct available to the application.
# Communication Status Event
Conceptually associated with each DDS\_Entity communication status is a logical StatusChangedFlag. This flag indicates whether that particular communication status has changed since the last time the status was ‘read’ by the application (there is no actual read-operation to read the StatusChangedFlag). The StatusChangedFlag is only conceptually needed to explain the behaviour of a Listener, therefore, it is not important whether this flag actually exists. A Listener will only be activated when the StatusChangedFlag changes from FALSE to TRUE (provided the Listener is attached and enabled for this particular status). The conditions which cause the StatusChangedFlag to change is slightly different for the plain communication status and the read communication status.
For the plain communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever the plain communication status changes and it is reset to FALSE each time the application accesses the plain communication status via the proper get\_<status\_name>\_status operation on the DDS\_Entity.
The communication status is also reset to FALSE whenever the associated Listener operation is called as the Listener implicitly accesses the status which is passed as a parameter to the operation. The fact that the status is reset prior to c a l l i n g t h e l i s t e n e r m e a n s t h a t i f t h e a p p l i c a t i o n c a l l s t h e get\_<status\_name>\_status from inside the listener it will see the status already reset.
An exception to this rule is when the associated Listener is the nil listener, in other word, a listener with value DDS\_OBJECT\_NIL. Such a listener is treated as a NOOP1 for all statuses activated in its bitmask and the act of calling this 'nil' listener does not reset the corresponding communication statuses.
Figure 24: Plain Communication Status State Chart
For example, the value of the StatusChangedFlag associated with the DDS\_RequestedDeadlineMissedStatus will become TRUE each time a new d e a d l i n e p a s s e s ( w h i c h i n c r e a s e s t h e t o t a l \_ c o u n t f i e l d w i t h i n DDS\_RequestedDeadlineMissedStatus). The value changes to FALSE when t h e a p p l i c a t i o n a c c e s s e s t h e s t a t u s v i a t h e c o r r e s p o n d i n g DDS\_DataReader\_get\_requested\_deadline\_missed\_status operation on the proper DDS\_Entity, or when the the on\_requested\_deadline\_missed operation on the Listener attached to this DDS\_Entity or one its containing entities is invoked.
For the read communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE when data arrives, or when the InstanceState of a contained instance changes. This can be caused by either:
• The arrival of the notification that an instance has been disposed by:
- the DDS\_DataWriter that owns it if its OwnershipQosPolicyKind = DDS\_EXCLUSIVE\_OWNERSHIP\_QOS
- or by any DDS\_DataWriter if its OwnershipQosPolicyKind = DDS\_SHARED\_OWNERSHIP\_QOS.
• The loss of liveliness of the DDS\_DataWriter of an instance for which there is no other DDS\_DataWriter.
• The arrival of the notification that an instance has been unregistered by the only DDS\_DataWriter that is known to be writing the instance.
The read communication statuses are reset to FALSE again in the following circumstances:
• The status flag of the DDS\_DATA\_AVAILABLE\_STATUS becomes FALSE when either the corresponding listener operation (on\_data\_available) is called, or the read or take operation (or any of its variants) is called on the associated DDS\_DataReader.
Figure 25: Read Communication Status DDS\_DataReader Statecraft
• The status flag of the DDS\_DATA\_ON\_READERS\_STATUS becomes FALSE when any of the following events occurs:
- The corresponding listener operation (on\_data\_on\_readers) is called on the corresponding DDS\_Subscriber.
- The on\_data\_available listener operation is called on any DDS\_DataReader belonging to the DDS\_Subscriber.
- The read or take operation (or any of its variants) is called on any DDS\_DataReader belonging to the DDS\_Subscriber.
Figure 26: DDS\_Subscriber Statecraft for a Read Communication Status
# Listeners
The Listeners provide for an event-based mechanism to asynchronously inform the application of a status change event. Listeners are applicable for both the read communication statuses and the plain communication statuses. When one of these status change events occur, the associated Listener is activated, provided some pre-conditions are satisfied. When the Listener is activated, it will call the corresponding on\_<status\_name> operation of that Listener. Each on\_<status\_name> operation available in the Listener of an DDS\_Entity is also available in the Listener of the factory of the DDS\_Entity.
For both the read communication statuses and the plain communication statuses a Listener is only activated when a Listener is attached to this particular DDS\_Entity and enabled for this particular status. Statuses are enabled according to the DDS\_StatusKindMask parameter that was passed at creation time of the DDS\_Entity, or that was passed to the DDS\_<DDS\_Entity>\_set\_listener operation .
When an event occurs for a particular DDS\_Entity and for a particular status, but the applicable Listener is not activated for this status, the status is propagated up to the factory of this DDS\_Entity. For this factory, the same propagation rules apply. When even the DDS\_DomainParticipantListener is not attached or enabled for this status, the application will not be notified about this event. This means that a status change on a contained DDS\_Entity only invokes the Listener of its factory if the Listener of the contained DDS\_Entity itself does not handle the trigger event generated by the status change.
Figure 27: DCPS Listeners
The event propagation is also applicable to the read communication statuses. H o w e v e r, s i n c e t h e e v e n t h e r e i s t h e a r r i v a l o f d a t a , b o t h t h e DDS\_DATA\_ON\_READERS and DDS\_DATA\_AVAILABLE status are TRUE. The Data Distribution Service will first attempt to handle the DDS\_DATA\_ON\_READERS status and try to activate the DDS\_SubscriberListener. When this Listener is not a c t i v a t e d f o r t h i s s t a t u s , t h e e v e n t w i l l p r o p a g a t e t o t h e DDS\_DomainParticipantListener. Only when the DDS\_DATA\_ON\_READERS status can not be handled, the Data Distribution Service will attempt to handle the DDS\_DATA\_AVAILABLE status and try to activate the DDS\_DataReaderListener. In case this Listener is not activated for this status, the event will follow the propagation rules as described above.
# Conditions and Waitsets
The DDS\_Conditions in conjunction with DDS\_WaitSets provide for a wait-based mechanism to synchronously inform the application of status changes. A DDS\_Condition can be either a DDS\_ReadCondition, DDS\_QueryCondition, DDS\_StatusCondition or DDS\_GuardCondition. To create a DDS\_Condition one of the following operations can be used:
• DDS\_ReadCondition created by DDS\_DataReader\_create\_readcondition
• DDS\_QueryCondition created by DDS\_DataReader\_create\_querycondition
• DDS\_StatusCondition retrieved by DDS\_<Entity>\_get\_statuscondition on an DDS\_<Entity>
• DDS\_GuardCondition created by the C operation DDS\_GuardCondition\_\_alloc
Note that the DDS\_QueryCondition is a specialized DDS\_ReadCondition. The DDS\_GuardCondition is a different kind of DDS\_Condition since it is not c o n t r o l l e d b y a s t a t u s b u t d i r e c t l y b y t h e a p p l i c a t i o n ( w h e n a DDS\_GuardCondition is initially created, the trigger\_value is FALSE). The DDS\_StatusCondition is present by default with each DDS\_Entity, therefore, it does not have to be created.
Figure 28: DCPS DDS\_WaitSets
A DDS\_WaitSet may have one or several DDS\_Conditions attached to it. An application thread may block execution (blocking may be limited by a timeout) by waiting on a DDS\_WaitSet until the trigger\_value of one or more of the DDS\_Conditions become TRUE. When a DDS\_Condition, whose trigger\_value evaluates to TRUE, is attached to a DDS\_WaitSet that is currently being waited on (using the DDS\_WaitSet\_wait operation), the DDS\_WaitSet will unblock immediately.
This (wait-based) mechanism is generally used as follows:
• The application creates a DDS\_WaitSet
• The application indicates which relevant information it wants to be notified of, by creating or retrieving DDS\_Condition objects (DDS\_StatusCondition, DDS\_ReadCondition, DDS\_QueryCondition or DDS\_GuardCondition) and attach them to a DDS\_WaitSet
• It then waits on that DDS\_WaitSet (using DDS\_WaitSet\_wait) until the trigger\_value of one or several DDS\_Condition objects (in the DDS\_WaitSet) become TRUE
• When the thread is unblocked, the application uses the result of the DDS\_WaitSet\_wait (i.e., the list of DDS\_Condition objects with trigger\_value==TRUE) to actually get the information:
- if the condition is a DDS\_StatusCondition and the status changes refer to a plain communication status, by calling get\_status\_changes and then get\_<communication\_status> on the relevant DDS\_Entity
- if the condition is a DDS\_StatusCondition and the status changes refer to the read communication status:
DDS\_DATA\_ON\_READERS, by calling get\_status\_changes and then DDS\_Subscriber\_get\_datareaders on the relevant DDS\_Subscriber and then DDS\_DataReader\_read/DDS\_DataReader\_take on the returned DDS\_DataReader objects
DDS\_DATA\_AVAILABLE, by calling get\_status\_changes and then DDS\_DataReader\_read/DDS\_DataReader\_take on the relevant DDS\_DataReader.
\- if it is a DDS\_ReadCondition or a DDS\_QueryCondition, by calling directly DDS\_DataReader\_read\_w\_condition / DDS\_DataReader\_take\_ w\_condition on the DDS\_DataReader with the DDS\_Condition as a parameter.
Figure 29: DCPS DDS\_Conditions
No extra information is passed from the Data Distribution Service to the application when a DDS\_WaitSet\_wait returns only the list of triggered DDS\_Condition objects. Therefore, it is the application responsibility to investigate which DDS\_Condition objects have triggered the DDS\_WaitSet.
# Blocking Behaviour
The result of a DDS\_WaitSet\_wait operation depends on the state of the DDS\_WaitSet, which in turn depends on whether at least one attached DDS\_Condition has a trigger\_value of TRUE. If the DDS\_WaitSet\_wait operation is called on DDS\_WaitSet with state BLOCKED it will block the calling thread. If DDS\_WaitSet\_wait is called on a DDS\_WaitSet with state UNBLOCKED it will return immediately. In addition, when the DDS\_WaitSet transitions from state BLOCKED to state UNBLOCKED it wakes up the thread (if any) that had called DDS\_WaitSet\_wait on it. Note that there can only be one thread waiting on a single DDS\_WaitSet.
Figure 30: Blocking Behaviour of a Waitset State Chart
# DDS\_StatusCondition Trigger State
The trigger\_value of a DDS\_StatusCondition is the boolean OR of the StatusChangedFlag of all the communication statuses to which it is sensitive. T h a t i s , t r i g g e r \_ v a l u e = = F A L S E o n l y i f a l l t h e v a l u e s o f t h e StatusChangedFlags are FALSE.
The sensitivity of the DDS\_StatusCondition to a particular communication status is controlled by the bit-mask of enabled\_statuses set on the DDS\_Condition by means of theDDS\_StatusCondition\_set\_ enabled\_statuses operation.
# DDS\_ReadCondition and DDS\_QueryCondition Trigger State
Similar to the DDS\_StatusCondition, a DDS\_ReadCondition also has a trigger\_value that determines whether the attached DDS\_WaitSet is BLOCKED or UNBLOCKED. However, unlike the DDS\_StatusCondition, the trigger\_value of the DDS\_ReadCondition is tied to the presence of at least one sample managed by the Data Distribution Service with SampleState, ViewState, and InstanceState matching those of the DDS\_ReadCondition. Additionally, for the DDS\_QueryCondition, the data associated with the sample, must be such that the query\_expression evaluates to TRUE.
The fact that the trigger\_value of a DDS\_ReadCondition is dependent on the presence of samples on the associated DDS\_DataReader implies that a single DDS\_DataReader\_take operation can potentially change the trigger\_value of several DDS\_ReadCondition or DDS\_QueryCondition objects. For example, if all samples are taken, any DDS\_ReadCondition or DDS\_QueryCondition o b j e c t s a s s o c i a t e d w i t h t h e D D S \_ D a t a R e a d e r t h a t h a d t h e i r trigger\_value==TRUE before will see the trigger\_value change to FALSE. Note that this does not guarantee that DDS\_WaitSet objects, that had those DDS\_Condition objects separately attached to, will not be woken up. Once we have trigger\_value==TRUE on a DDS\_Condition it may wake up the D D S \_ W a i t S e t i t w a s a t t a c h e d t o , t h e c o n d i t i o n t r a n s i t i o n s t o trigger\_value==FALSE does not 'un-wake up' the DDS\_WaitSet as 'un-wakening' is not possible. The consequence is that an application blocked on a DDS\_WaitSet may return from the wait with a list of DDS\_Condition objects some of which are no longer “active”. This is unavoidable if multiple threads are concurrently waiting on separate DDS\_WaitSet objects and taking data associated with the same D DS \_D at aR ea de r D DS \_E nt it y. In ot her wor ds, a DDS\_WaitSet\_wait may return with a list of DDS\_Condition objects which all have a trigger\_value==FALSE. This only means that at some point one or more of the DDS\_Condition objects have had a trigger\_value==TRUE but no longer do.
# DDS\_GuardCondition Trigger State
The trigger\_value of a DDS\_GuardCondition is completely controlled by the application via the operation DDS\_GuardCondition\_set\_trigger\_value. This DDS\_Condition can be used to implement an application-defined wake-up of the blocked thread.
# Appendix
# G
# DDS\_Topic Definitions
The Data Distribution Service distributes its data in structured data types, called topics. The first step when using the Data Distribution Service consists of defining these topics. Since the Data Distribution Service supports using several programming languages, OMG IDL is used for this purpose. This appendix describes how to define the topics.
# DDS\_Topic Definition Example
All data distributed using the Data Distribution Service has to be defined as a topic. A topic is a structured data type, like a C-struct with several members. Whenever the application needs to read or write data, it will be reading or writing topics. The definition of each topic it will be using has to be written in (a subset of) OMG IDL. For example:
```c
module SPACE {
struct Foo {
long userID; // owner of message
long long index; // message index per owner
string content; // message body
};
#pragma keylist Foo
};
```
This is the definition of a topic called Foo, used for sending and receiving messages (as an example). Even though the topic is defined using IDL, the Data Distribution Service will be using an equivalent C-struct which is accessed by the application using the type specific operations. Generation of the typed classes is achieved by invoking the Data Distribution Service IDL pre-processor: idlpp -l c -S <idl\_filename>.idl, a tool which translates the IDL topic definition into an equivalent C definition. The -l C option indicates that C-code has to be generated, the -S option indicates that this C code should be StandAlone C code, i.e. it must not have any dependency on external ORB libraries. In this example, the pre-processor will generate the classes SPACE\_FooTypeSupport, SPACE\_FooDataWriter and SPACE\_FooDataReader which contain the type specific operations.
The prefix SPACE\_ is generated from the IDL-module-name. The types of the fields are prescribed by the IDL-to-C mapping. After the Data Distribution Service IDL-pre-processor is run, the application will use the generated code.
# Complex Topics
The Foo topic is relatively simple, but the Data Distribution Service is capable of distributing more complex topics as well. In fact, any definition following the OpenSplice IDL subset is allowed. For a reference of this subset, see the BNF-notation in Appendix , Data Distribution Service IDL Subset in BNF Notation. It is important to know that the pre-processor accepts all IDL constructs but only the subset is being processed.
Apart from the trivial data types, the Data Distribution Service is capable of handling fixed-length arrays, bounded and unbounded sequences, union types and enumerations. Types can be nested, e.g. a struct can contain a struct field or an array of structs, or a sequence of strings or an array of sequences containing structs. For more information regarding the IDL to C mapping.
# IDL Pre-processor
This section contains the specification of the subset of OMG IDL that can be used to define the topics.
# IDL to Host Language Mapping
The Data Distribution Service IDL pre-processor translates the IDL-definition of the topics into language specific code. This translation is executed according to the OMG IDL mappings. Since the Data Distribution Service uses data-structures only, not all IDL-features are implemented by the pre-processor. Usually, the IDL definition consists of a module defining several structs and typedefs.
# Data Distribution Service IDL Keywords
The identifiers listed in this appendix are reserved for use as keywords in IDL and may not be used otherwise, unless escaped with a leading underscore.
| Name | Type | Description |
| key | BuiltinTopicKey_t | Global unique identifier of the Topic |
| name | String | Name of the Topic |
| type_name | String | Type name of the Topic (i.e. the fully scoped IDL name) |
| durability | DurabilityQosPolicy | QosPolicy attached to the Topic |
| durability_service | DurabilityServiceQosPolicy | QosPolicy attached to the Topic |
| deadline | DeadlineQosPolicy | QosPolicy attached to the Topic |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the Topic |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the Topic |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the Topic |
| transport_priority | TransportPriorityQosPolicy | QosPolicy attached to the Topic |
| lifespan | LifespanQosPolicy | QosPolicy attached to the Topic |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the Topic |
| history | HistoryQosPolicy | QosPolicy attached to the Topic |
| resource_limits | ResourceLimitsQosPolicy | QosPolicy attached to the Topic |
| ownership | OwnershipQosPolicy | QosPolicy attached to the Topic |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic |
# PublicationBuiltinTopicData
The DCPSPublication topic communicates the existence of datawriters by means of the PublicationBuiltinTopicData datatype. Each PublicationBuiltinTopicData sample in a Domain represents a datawriter in that Domain: a new PublicationBuiltinTopicData instance is created when a newly added DataWriter is enabled, and it is disposed when that DataWriter is deleted. An updated PublicationBuiltinTopicData sample is written each time the DataWriter (or the Publisher to which it belongs) modifies a QosPolicy that applies to the entities connected to it. Also will it be updated when the writer looses or regains its liveliness.
The PublicationBuiltinTopicData Topic is also used to return data through the get\_matched\_publication\_data operation on the DataReader as described in Section 3.5.2.13, DDS\_DataReader\_get\_matched\_publication\_data, on page 437.
Table 30: PublicationBuiltinTopicData Members
| Name | Type | Description |
| key | BuiltinTopicKey_t | Global unique identifier of the DataWriter |
| participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataWriter belongs |
| topic_name | String | Name of the Topic used by the DataWriter |
| type_name | String | Type name of the Topic used by the DataWriter |
| durability | DurabilityQosPolicy | QosPolicy attached to the DataWriter |
| deadline | DeadlineQosPolicy | QosPolicy attached to the DataWriter |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataWriter |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the DataWriter |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the DataWriter |
| lifespan | LifespanQosPolicy | QosPolicy attached to the DataWriter |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataWriter |
| user_data | UserDataQosPolicy | QosPolicy attached to the DataWriter |
| ownership | OwnershipQosPolicy | QosPolicy attached to the DataWriter |
| ownership_strength | OwnershipStrengthQosPolicy | QosPolicy attached to the DataWriter |
| presentation | PresentationQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
| partition | PartitionQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by the DataWriter |
| group_data | GroupDataQosPolicy | QosPolicy attached to the Publisher to which the DataWriter belongs |
# SubscriptionBuiltinTopicData
The DCPSSubscription topic communicates the existence of datareaders by means of the SubscriptionBuiltinTopicData datatype. Each SubscriptionBuiltinTopicData sample in a Domain represents a datareader in that Domain: a new SubscriptionBuiltinTopicData instance is created when a newly added DataReader is enabled, and it is disposed when that
DataReader is deleted. An updated SubscriptionBuiltinTopicData sample is written each time the DataReader (or the Subscriber to which it belongs) modifies a QosPolicy that applies to the entities connected to it.
The SubscriptionBuiltinTopicData Topic is also used to return data through the get\_matched\_subscription\_data operation on the DataWriter as described in Section 3.4.2.9, DDS\_DataWriter\_get\_matched\_subscription\_data, on page 326.
Table 31: SubscriptionBuiltinTopicData Members
| Name | Type | Description |
| key | BuiltinTopicKey_t | Global unique identifier of the DataReader |
| participant_key | BuiltinTopicKey_t | Global unique identifier of the Participant to which the DataReader belongs |
| topic_name | String | Name of the Topic used by the DataReader |
| type_name | String | Type name of the Topic used by the DataReader |
| durability | DurabilityQosPolicy | QosPolicy attached to the DataReader |
| deadline | DeadlineQosPolicy | QosPolicy attached to the DataReader |
| latency_budget | LatencyBudgetQosPolicy | QosPolicy attached to the DataReader |
| liveliness | LivelinessQosPolicy | QosPolicy attached to the DataReader |
| reliability | ReliabilityQosPolicy | QosPolicy attached to the DataReader |
| ownership | LifespanQosPolicy | QosPolicy attached to the DataReader |
| destination_order | DestinationOrderQosPolicy | QosPolicy attached to the DataReader |
| user_data | UserDataQosPolicy | QosPolicy attached to the DataReader |
| time_based_filter | TimeBasedFilterQosPolicy | QosPolicy attached to the DataReader |
| presentation | PresentationQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
| partition | PartitionQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
| topic_data | TopicDataQosPolicy | QosPolicy attached to the Topic used by the DataReader |
| group_data | GroupDataQosPolicy | QosPolicy attached to the Subscriber to which the DataReader belongs |
# Other builtin topics
There are a number of other built-in topics that have not been mentioned. These topics (e.g. DCPSDelivery, DCPSHeartbeat and potentially some others) are proprietary and for internal use only. Users are discouraged from doing anything with these topics, so as not to interfere with internal mechanisms that rely on them. The structure of these topics may change without notification.
Appendices
# BIBLIOGRAPHY
# Bibliography
[1] OMG Data Distribution Service Revised Final Adopted Specification ptc/04-03-07, Object Management Group
[2] OMG C Language Mapping Specification formal/99-07-35, Object Management Group (OMG)
[3] OMG The Common Object Request Broker: Architecture and Specification, Version 3.0, formal/02-06-01, Object Management Group
Bibliography
# GLOSSARY
# G l o s s a r y
Acronyms