| ReturnCode_t | Return Code Description |
| RETCODE_OK | Successful return |
| RETCODE_ERROR | Generic, unspecified error |
| RETCODE_BAD_PARAMETER | Illegal parameter value |
| RETCODE_UNSUPPORTED | Unsupported operation or QosPolicy setting. Can only be returned by operations that are optional or operations that uses an optionalQoS as a parameter |
| RETCODE_ALREADY_DELETED | The object target of this operation has already been deleted |
| RETCODE_OUT_OF_RESOURCES | Service ran out of the resources needed to complete the operation |
| RETCODE_NOT_ENABLED | Operation invoked on an Entity that is not yet enabled |
| RETCODE_IMMUTABLE_POLICY | Application attempted to modify an immutable QosPolicy |
| RETCODE_INCONSISTENT_POLICY | Application specified a set of policies that are not consistent with each other |
| RETCODE_PRECONDITION_NOT_MET | A pre-condition for the operation was not met |
| RETCODE_TIMEOUT | The operation timed out |
| RETCODE_ILLEGAL_OPERATION | An operation was invoked on an inappropriate object or at an inappropriate time (as determined by QosPolicies that control the behaviour of the object in question). There is no precondition that could be changed to make the operation succeed.⚠This code can not be returned in C++. |
| RETCODE_NO_DATA | Indicates a situation where the operation did not return any data |
The name scope (name space) of these return codes is DDS. The operation return codes RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED and RETCODE\_ALREADY\_DELETED are default for operations that return an operation return code and are therefore not explicitly mentioned in the DDS specification. However, in this manual they are mentioned along with each operation.
Some operations are not implemented. These operations are mentioned including their synopsis, but not described in this manual and return RETCODE\_UNSUPPORTED when called from the application. See Appendix B, API Constants and Types.
The return code RETCODE\_ILLEGAL\_OPERATION can never be returned in C++: it indicates that you tried to invoke an operation on the wrong class, which in a real Object Oriented language like C++ is never possible.
# 1.1 Thread Safety
All operations are thread safe.
# 1.2 Signal Handling
Every application that participates in a domain should register signal-handlers in order to protect the data distribution service in case of an exception or termination r e q u e s t . T h i s i s d o n e a u t o m a t i c a l l y w h e n t h e a p p l i c a t i o n c a l l s t h e DDS::DomainParticipantFactory::get\_instance operation. The data distribution service distinguishes between two kinds of signals: synchronous (i.e. exceptions) and asynchronous signals (i.e. termination requests).
# 1.2.1 Synchronous Signals
The data distribution service registers a signal-handler for the following synchronous signals: SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGBUS, SIGSEGV and SIGSYS. If a signal-handler is already registered for any of these signals it will be chained by the handlers registered by the data distribution service. Upon receiving any of the mentioned signals, the signal-handler will synchronously detach the application from the domain and call any chained handler if available. This allows core dumps to be created when an error occurs in application-code, without sacrificing the integrity of the data distribution service. Because the signal is processed synchronously, the offending thread will not be able to continue.
Synchronous signals can also be received asynchronously from another process (i.e. 'kill -ABRT <pid>'). This is handled by the signal-handlers registered by the data distribution service and the behaviour will mimic the behaviour of a regular synchronous signal, occurring at the point in the application when the signal is received. A log message will be recorded stating that an asynchronously received synchronous signal occurred, including the source of the signal.
# 1.2.2 Asynchronous Signals
The asynchronous signal-handlers are only registered by the data distribution service if the application did not already register a handler, nor set the ignore-flag for these signals. If the data distribution service handlers are registered, the default handlers are chained. The signels that are handled are: SIGINT, SIGQUIT, SIGTERM, SIGHUP and SIGPIPE. When receiving any of these signals, the handlers of the data distribution service will ensure a disconnection from the domain. The default handler will in turn cause the application to terminate immediately.
# 1.3 Memory Management
When objects are being created, they will occupy memory space. To avoid memory leaks when they are not used any more, these objects will have to be deleted in order to release the memory space. However, when using pointers, it is difficult to keep track of which object has been released and which has not. When objects are not being released, the memory leak will finally use up all the resources and the application will fail.
# 1.3.1 Reference Count
The DDS API is described as a collection of IDL interfaces in the PSM. According to the IDL to C++ language mapping these interfaces must be mapped onto C++ classes that inherit from a CORBA::Object class. OpenSplice can currently borrow this class from any ORB installed on your system, but it also provides its own implementation libraries: which library is used depends on whether you use the Corba C++ API (CCPP) or the standalone C++ API (SACPP).
In order to cope with the memory management problems described above, CORBA objects keep some internal administration. In this administration, a reference count is included. This reference count holds the number of references to the object (assuming ownership). In other words, when a second reference is being made to the same object, the reference count in the internal administration of the object, must be increased. This way, both references may assume ownership of the same object. When one of the references runs out of scope, the reference count must be decreased by one. In this case the object must not be released because the reference count has not reach zero yet. Only when the second reference runs out of scope, the reference count reaches zero and the object must be released.
# 1.3.2 Reference Types
CORBA defines two types of references. The first one is the basic <class>\_ptr type. When this type is used, the application must explicitly increase or decrease the reference count. The second one is the <class>\_var type. This type is a smart pointer, which automatically updates the reference count of an object when that object is assigned to it and also updates the reference of the previous assigned object. When this type is used, the application does not have to increase or decrease the reference count. Best practice is to use these <class>\_var types instead of the <class>\_ptr types. However, under certain conditions a <class>\_ptr type must be used (refer to Section 1.3.2.2, Var Reference Types).
# 1.3.2.1 Pointer Types
When using <class>\_ptr types the application must explicitly increase or decrease the reference count, by using the CORBA defined functions:
\_duplicate - creates another reference to the object. The object is not being copied but only the reference count in the internal administration of the object is increased and a new <class>\_ptr type is returned. Both references have ownership. In other words, when one of them runs out of scope, the reference count must be decreased by calling \_release. Only when \_release is called for both of them, the object is removed;
\_release - informs the CORBA object that the application will not be using the reference any more. As a result, the operation will explicitly decrease the reference count of an object. After releasing, the application must not use the reference because from this moment on, it is unknown whether the object still exists.
When more references to <class>\_ptr type are made by assignment, the reference count is not increased. When more references to <class>\_ptr type are made by \_duplicate, the reference count is increased on every call. Therefore \_release must be called once for every \_duplicate to decrease the reference count.
# 1.3.2.2 Var Reference Types
To prevent errors, CORBA defines the <class>\_var types which assumes ownership of the object it is referring to. An \_var type is considered to be a smart pointer, which not only includes the reference to the object but also automatically updates the internal reference count of the object.
# 1.3.2.3 Assignment
Assignment for <class>\_ptr types and <class>\_var types is defined for:
```txt
<class>_ptr types to <class>_var types
<class>_var types to <class>_var types
<class>_var types to <class>_ptr types
```
For ins ta nce , the res ult of a c r e a te \_ p u b l i sh e r (which re turns a Publisher\_ptr) can directly be assigned to a Publisher\_var type. This assignment would transfer ownership of the Publisher object to the reference of Publisher\_var type.
```c
My_Publisher_var = create_publisher(PUBLISHER_QOS_DEFAULT,
```
```txt
PublisherListener::_nil());
```
This assignment will wrap the return type Publisher\_ptr in type Publisher\_var and transfer ownership to My\_Publisher\_var. In other words, when My\_Publisher\_var runs out of scope, the Publisher is automatically removed.
The next assignment does not concern <class>\_var types, but is only presented to show what will happen when a <class>\_var type is not used.
```cpp
My_Publisher_ptr = create_publisher(PUBLISHER_QOS_DEFAULT, PublisherListener::_nil());
```
This assignment will not wrap, but only makes a copy of the return type Publisher\_ptr. The reference count is not automatically updated and the application has to make sure to release the object. In other words, when My\_Publisher\_ptr runs out of scope, the Publisher is not automatically removed and can not be removed any more since there is no reference available (not even by delete\_contained\_entities).
```txt
Another_Publisher_var = My_Publisher_var;
```
This assignment will create another reference to the Publisher. The object is not being copied but only the reference count in the internal administration of the Publisher\_var type is increased. Both Another\_Publisher\_var and My\_Publisher\_var have ownership. In other words, when one of them runs out of scope, the reference count is decreased. Only when both of them run out of scope, the Publisher is removed.
```txt
Another_Publisher_ptr = My_Publisher_var;
```
This assignment will type cast the type Publisher\_var to type Publisher\_ptr and only makes a copy of the reference My\_Publisher\_var. The ownership is not transferred and the application may not release the object on account of Another\_Publisher\_ptr because the internal reference count was not increased. However, the application must be careful not to use Another\_Publisher\_ptr when My\_Publisher\_var runs out of scope because in that case, the Publisher is automatically removed and the Another\_Publisher\_ptr variable is invalid.
# Var Reference Types Side Effect
As mentioned, under certain conditions a <class>\_ptr type must be used, because the <class>\_var type will cause a problem when a type cast is being done on an object. For example, the cast of an object of class DataWriter to the class <type>DataWriter.
When creating a DataWriter, the create\_datawriter operation returns a generic DataWriter\_ptr type (which we assign to DataWriter\_var). However, an object of the DataWriter class does not have a write operation. To be able to use such a typed operation, the application must perform a dynamic cast to the <type>DataWriter\_ptr type. For example, when we have a DataWriter for the type Foo, it looks like:
```txt
GenericWriter_var = create_datawriter(MyTopic, MyWriterQos, _nil);
My_Writer_var = dynamic_cast<FooDataWriter_ptr> GenericWriter_var.in());
```
The problem here is that there are two DataWriter\_var type references to the object without a duplication. This is because a cast only copies the same information and does not increase the internal counter. In other words, both DataWriter\_var types considers to be the sole owner of the object, and therefore do not increase its reference counter. When one of the DataWriter\_var types run out of scope, the entire object is removed, because the internal administration only had one reference accounted for. Therefore, when the second DataWriter\_var type runs out of scope, the behaviour of your application has become undefined (most probably the application will eventually crash). This problem can be solved by using an explicit call to the DataWriter::\_duplicate operation before assigning it to the second \_var type, or by using a DataWriter\_ptr type instead of a DataWriter\_var type because a DataWriter\_ptr type does not automatically decrease the reference counter when it runs out of scope.
```txt
GenericWriter_ptr = create_datawriter(MyTopic, MyWriterQos, _nil);
My_Writer_var =
dynamic_cast<FooDataWriter_ptr>(GenericWriter_ptr.in());
```
Note in this case that GenericWriter\_ptr must not be used after the assignment, since it will not be valid as soon as My\_Writer\_var runs out of scope.
# 1.4 Listener Interfaces
The Listener provides a generic mechanism (actually a callback function) for the Data Distribution Service to notify the application of relevant asynchronous communication status change events, such as a missed deadline, violation of a QosPolicy setting, etc.
The Listener interfaces are designed as an interface at PIM level. In other words, such an interface is part of the application which must implement the interface operations. A user-defined class for these operations must be provided by the application which must extend from the specific Listener class (according to the IDL-to-C++ specification an interface in IDL is mapped on a class in the C++ programming language). All Listener operations must be implemented in the user-defined class, it is up to the application whether an operation is empty or contains some functionality.
Each DCPS Entity supports its own specialized kind of Listener. Therefore, the following Listeners are available:
• DomainParticipantListener
• ExtDomainParticipantListener
• TopicListener
• ExtTopicListener
• PublisherListener
• DataWriterListener
• SubscriberListener
• DataReaderListener
Since a DataReader an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener must be of type DataReaderListener. A user-defined class must be provided by the application (for instance My\_DataReaderListener) which must extend from the DataReaderListener class. All 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.
As an example, one of the operations in the DataReaderListener is the on\_liveliness\_changed. This operation (implemented by the application) will be called by the Data Distribution Service when the liveliness of the associated DataWriter has changed. In other words, it serves as a callback function to the event of a change in liveliness. The parameters of the operation are supplied by the Data Distribution Service. In this example, the reference to the DataReader and the status of the liveliness are provided.
# 1.5 Inheritance of Abstract Operations
The information provided in this guide is based on:
• the PIM part of the DDS-DCPS specification for module descriptions
• the PSM part of the DDS-DCPS specification for class and operation descriptions.
Refer to the OMG’s Data Distribution Service Revised Final Adopted Specification, ptc/04-03-07, for additional information.
At PIM level, inheritance is used to define abstract classes and operations. The OMG IDL PSM defines the interface for an application to interact with the Data Distribution Service (see Appendix C, Platform Specific Model IDL Interface). The DCPS API for the C++ language is as specified in the OMG’s C++ Language Mapping Specification.
Inheritance of operations is not implemented when different type parameters for the same operation are used. In this case operations are implemented in their respective derived class (e.g. get\_qos and set\_qos). These operations are commented out in the IDL PSM.
# 2 DCPS Modules
DCPS is divided into five modules, which are described briefly in this chapter. Each module consists of several classes as defined at PIM level in the DDS-DCPS specification. Some of the classes as described in the PIM are implemented as a struct in the PSM; these classes are treated as a class in this chapter according to the PIM with a remark about their implementation (struct). In the next chapter their actual implementations are described.
Each class contains several operations, which may be abstract. Those classes, which are implemented as a struct do not have any operations. The modules and the classes are ordered conform the DDS-DCPS specification. The classes, interfaces, structs and operations are described in the next chapter.
Figure 2 DCPS Module Composition
# 2.1 Functionality
The modules listed below provide the associated functions in the Data Distribution Service:
Infrastructure Module - This module defines the abstract classes and interfaces, which are refined by the other modules. It also provides the support for the interaction between the application and the Data Distribution Service (event-based and state-based);
Domain Module - This module contains the DomainParticipant class, which is the entry point of the application and DomainParticipantListener interface;
To p i c - D e f i n i t i o n M o d u l e - T h i s m o d u l e c o n t a i n s t h e T o p i c , ContentFilteredTopic and MultiTopic classes. It also contains the TopicListener interface and all support to define Topic objects and assign QosPolicy settings to them;
Publication Module - This module contains the Publisher and DataWriter classes. It also contains the PublisherListener and DataWriterListener interfaces;
Subscription Module - This module contains the Subscriber, DataReader, ReadCondition and QueryCondition classes. It also contains the SubscriberListener and DataReaderListener interfaces.
# 2.2 Infrastructure Module
This module defines the abstract classes and interfaces, which, in the PIM definition, are refined by the other modules. It also provides the support for the interaction between the application and the Data Distribution Service (event-based and state-based). The event-based interaction is supported by Listeners, the state-based interaction is supported by WaitSets and Conditions.
Figure 3 DCPS Infrastructure Module’s Class Model
This module contains the following classes:
• Entity (abstract)
• DomainEntity (abstract)
• QosPolicy (abstract, struct)
• Listener (interface)
• Status (abstract, struct)
• WaitSet
• Condition
• GuardCondition
• StatusCondition
# 2.3 Domain Module
This module contains the class DomainParticipant, which acts as an entry point of the Data Distribution Service and acts as a factory for many of the classes. The DomainParticipant also acts as a container for the other objects that make up the Data Distribution Service. It isolates applications within the same Domain from other applications in a different Domain on the same set of computers. A Domain is a “virtual network” and applications with the same domainId are isolated from applications with a different domainId. In this way, several independent distributed applications can coexist in the same physical network without interfering, or even being aware of each other.
Figure 4 DCPS Domain Module’s Class Model
This module contains the following classes:
• DomainParticipant
• DomainParticipantFactory
• DomainParticipantListener (interface)
• Domain (not depicted)
# 2.4 Topic-Definition Module
This module contains the Topic, ContentFilteredTopic and MultiTopic classes. It also contains the TopicListener interface and all support to define Topic objects and assign QosPolicy settings to them.
Figure 5 DCPS Topic-Definition Module’s Class Model
This module contains the following classes:
• TopicDescription (abstract)
• Topic
• ContentFilteredTopic
• MultiTopic
• TopicListener (interface)
• Topic-Definition type specific classes
“Topic-Definition type specific classes” contains the generic class and the generated data type specific classes. In case of data type Foo (this also applies to other types); “Topic-Definition type specific classes” contains the following classes:
• TypeSupport (abstract)
• FooTypeSupport
Figure 6 Data Type “Foo” Typed Classes for Pre-processor Generation
# 2.5 Publication Module
This module supports writing of the data, it contains the Publisher and DataWriter classes. It also contains the PublisherListener and DataWriterListener interfaces. Furthermore, it contains all support needed for publication.
Figure 7 DCPS Publication Module’s Class Model
This module contains the following classes:
• Publisher
• Publication type specific classes
• PublisherListener (interface)
• DataWriterListener (interface)
“Publication type specific classes” contains the generic class and the generated data type specific classes. In case of data type Foo (this also applies to other types); “Publication type specific classes” contains the following classes:
• DataWriter (abstract)
• FooDataWriter
# 2.6 Subscription Module
This module supports access to the data, it contains the Subscriber, DataReader, ReadCondition and QueryCondition classes. It also contains the SubscriberListener and DataReaderListener interfaces. Furthermore, it contains all support needed for subscription.
Figure 8 DCPS Subscription Module’s Class Model
This module contains the following classes:
• Subscriber
• Subscription type specific classes
• DataSample
• SampleInfo (struct)
• SubscriberListener (interface)
• DataReaderListener (interface)
• ReadCondition
• QueryCondition
“Subscription type specific classes” contains the generic class and the generated data type specific classes. In case of data type Foo (this also applies to other types); “Subscription type specific classes” contains the following classes:
• DataReader (abstract)
• FooDataReader
# CHAPTER
# 3 DCPS Classes and Operations
This chapter describes, for each module, its classes and operations in detail. Each module consists of several classes as defined at PIM level in the DDS-DCPS specification. Some of the classes are implemented as a struct in the PSM. Some of the other classes are abstract, which means that they contain some abstract operations.
The Listener interfaces are designed as an interface at PIM level. In other words, the application must implement the interface operations. Therefore, all Listener classes are abstract. A user-defined class for these operations must be provided by the application which must extend from the specific Listener class. All Listener operations must be implemented in the user-defined class. It is up to the application whether an operation is empty or contains some functionality.
Each class contains several operations, which may be abstract (base class). Abstract operations are not implemented in their base class, but in a type specific class or an application defined class (in case of a Listener). Classes that are implemented as a struct do not have any operations. Some operations are inherited, which means that they are implemented in their base class.
The abstract operations in a class are listed (including their synopsis), but not implemented in that class. These operations are implemented in their respective derived classes. The interfaces are fully described, since they must be implemented by the application.
# 3.1 Infrastructure Module
Figure 9 DCPS Infrastructure Module’s Class Model
This module contains the following classes:
• Entity (abstract)
• DomainEntity (abstract)
• QosPolicy (abstract, struct)
• Listener (interface)
• Status (abstract, struct)
• WaitSet
• Condition
• GuardCondition
• StatusCondition
• ErrorInfo
# 3.1.1 Class Entity (abstract)
This class is the abstract base class for all the DCPS objects. It acts as a generic class for Entity objects.
The interface description of this class is as follows:
```txt
class Entity
{
//
}
```
```c
// abstract operations (implemented in class
// DomainParticipant, Topic,
// Publisher, DataWriter, Subscriber and DataReader)
//
// ReturnCode_t
// set_qos
// (const EntityQos& qos);
// ReturnCode_t
// get_qos
// (EntityQos& qos);
// ReturnCode_t
// set_listener
// (EntityListener_ptr a_listener,
// StatusMask mask);
// EntityListener_ptr
// get_listener
// (void);
//
// implemented API operations
//
ReturnCode_t
enable
(void);
StatusCondition_ptr
get_statuscondition
(void);
StatusMask
get_status_changes
(void);
InstanceHandle_t
get_instance_handle
(void);
};
```
The next paragraphs list all Entity operations. 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 given in the subclasses, which contain the type specific implementation of these operations.
# 3.1.1.1 enable
# Scope
DDS::Entity
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
enable
```
(void);
# Description
This operation enables the Entity on which it is being called when the Entity was created with the EntityFactoryQosPolicy set to FALSE.
# Parameters
<none>
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation enables the Entity. Created Entity objects can start in either an e n a b l e d o r d i s a b l e d s t a t e . T h i s i s c o n t r o l l e d b y t h e v a l u e o f t h e EntityFactoryQosPolicy on the corresponding factory for the Entity. Enabled entities are immediately activated at creation time meaning all their immutable QoS settings can no longer be changed. Disabled Entities are not yet activated, so it is still possible to change there immutable QoS settings. However, once activated the immutable QoS settings can no longer be changed.
Creating disabled entities can make sense when the creator of the Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.
The default setting of EntityFactoryQosPolicy is such that, by default, entities are created in an enabled state so that it is not necessary to explicitly call enable on newly created entities.
The enable operation is idempotent. Calling enable on an already enabled Entity returns RETCODE\_OK and has no effect.
If an Entity has not yet been enabled, the only operations that can be invoked on it are: the ones to set, get or copy the QosPolicy settings, the ones that set (or get) the listener, the ones that get the StatusCondition, the get\_status\_changes operation (although the status of a disabled entity never changes), and the ‘factory’ operations that create, delete or lookup1 other Entities. Other operations will return the error RETCODE\_NOT\_ENABLED.
Entities created from a factory that is disabled, are created disabled regardless of the setting of the EntityFactoryQosPolicy.
Calling enable on an Entity whose factory is not enabled will fail and return RETCODE\_PRECONDITION\_NOT\_MET.
If the EntityFactoryQosPolicy has autoenable\_created\_entities set to TRUE, the enable operation on the factory will automatically enable all Entities created from the factory.
The Listeners associated with an Entity are not called until the Entity is enabled. Conditions associated with an Entity that is not enabled are "inactive", that is, have a trigger\_value which is FALSE.
# Return Code
When the operation returns:
• RETCODE\_OK - the application enabled the Entity (or it was already enabled)
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the factory of the Entity is not enabled.
# 3.1.1.2 get\_instance\_handle
# Scope
DDS::Entity
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
get_instance_handle
(void);
```
# Description
This operation returns the instance\_handle of the built-in topic sample that represents the specified Entity.
# Parameters
<none>
# Return Value
InstanceHandle\_t - Result value is the instance\_handle of the built-in topic sample that represents the state of this Entity.
# Detailed Description
The relevant state of some Entity objects are distributed using built-in topics. Each built-in topic sample represents the state of a specific Entity and has a unique instance\_handle. This operation returns the instance\_handle of the built-in topic sample that represents the specified Entity.
Some Entities (Publisher and Subscriber) do not have a corresponding built-in topic sample, but they still have an instance\_handle that uniquely identifies the Entity. The instance\_handles obtained this way can also be used to check whether a specific Entity is located in a specific DomainParticipant. (See Section 3.2.1.2, contains\_entity, on page 135.)
# 3.1.1.3 get\_listener (abstract)
This abstract operation is defined as a generic operation to access a Listener. Each subclass derived from this class, DomainParticipant, Topic, Publisher, Subscriber, DataWriter and DataReader will provide a class specific implementation of this abstract operation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
EntityListener_ptr
get_listener
(void);
```
# 3.1.1.4 get\_qos (abstract)
This abstract operation is defined as a generic operation to access a struct with the QosPolicy settings. Each subclass derived from this class, DomainParticipant, Topic, Publisher, Subscriber, DataWriter and DataReader will provide a class specific implementation of this abstract operation.
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(EntityQos& qos);
```
# 3.1.1.5 get\_status\_changes
# Scope
```autohotkey
DDS::Entity
```
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
StatusMask
```
```txt
get_status_changes
(void);
```
# Description
This operation returns a mask with the communication statuses in the Entity that are “triggered”.
# Parameters
```txt
<none>
```
# Return Value
StatusMask - a bit mask in which each bit shows which value has changed.
# Detailed Description
This operation returns a mask with the communication statuses in the Entity that are triggered. That is the set of communication statuses whose value have changed since the last time the application called this operation. This operation shows whether a change has occurred even when the status seems unchanged because the status changed back to the original status.
When the Entity is first created or if the Entity is not enabled, all communication statuses are in the “un-triggered” state so the mask returned by the operation is empty.
The result value is a bit mask in which each bit shows which value has changed. The relevant bits represent one of the following statuses:
• INCONSISTENT\_TOPIC\_STATUS
• OFFERED\_DEADLINE\_MISSED\_STATUS
• REQUESTED\_DEADLINE\_MISSED\_STATUS
• OFFERED\_INCOMPATIBLE\_QOS\_STATUS
• REQUESTED\_INCOMPATIBLE\_QOS\_STATUS
• SAMPLE\_LOST\_STATUS
• SAMPLE\_REJECTED\_STATUS
• DATA\_ON\_READERS\_STATUS
• DATA\_AVAILABLE\_STATUS
• LIVELINESS\_LOST\_STATUS
• LIVELINESS\_CHANGED\_STATUS
• PUBLICATION\_MATCHED\_STATUS
• SUBSCRIPTION\_MATCHED\_STATUS
• ALL\_DATA\_DISPOSED\_TOPIC\_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 StatusMask. Not all statuses are relevant to all Entity objects. See the respective Listener interfaces for each Entity for more information.
# 3.1.1.6 get\_statuscondition
# Scope
```autohotkey
DDS::Entity
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# Description
This operation allows access to the StatusCondition associated with the Entity.
# Parameters
```txt
<none>
```
# Return Value
StatusCondition - the StatusCondition of the Entity.
# Detailed Description
Each Entity has a StatusCondition associated with it. This operation allows access to the StatusCondition associated with the Entity. The returned condition can then be added to a WaitSet so that the application can wait for specific status changes that affect the Entity.
# 3.1.1.7 set\_listener (abstract)
This abstract operation is defined as a generic operation to access a Listener. Each subclass derived from this class, DomainParticipant, Topic, Publisher, Subscriber, DataWriter and DataReader will provide a class specific implementation of this abstract operation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_listener
(EntityListener_ptr a_listener,
```
StatusMask mask);
# 3.1.1.8 set\_qos (abstract)
This abstract operation is defined as a generic operation to modify the QosPolicy settings. Each subclass derived from this class, DomainParticipant, Topic, Publisher, Subscriber, DataWriter and DataReader will provide a class-specific implementation of this abstract operation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const EntityQos& qos);
```
# 3.1.2 Class DomainEntity (abstract)
This class is the abstract base class for the all entities except DomainParticipant. The main purpose is to express that DomainParticipant is a special kind of Entity, which acts as a container of all other Entity objects, but cannot contain another DomainParticipant within itself. Therefore, this class is not part of the IDL interface in the DCPS PSM description.
The class DomainEntity does not contain any operations.
# 3.1.3 Struct QosPolicy
Each Entity provides an <Entity>Qos structure that implements the basic mechanism for an application to specify Quality of Service attributes. This structure consists of Entity specific QosPolicy attributes. QosPolicy attributes are structured types where each type specifies the information that controls an Entity related (configurable) property of the Data Distribution Service.
All QosPolicies applicable to an Entity are aggregated in a corresponding <Entity>Qos, which is a compound structure that is set atomically so that it represents a coherent set of QosPolicy attributes.
Compound types are used whenever multiple attributes must be set coherently to define a consistent attribute for a QosPolicy.
A full description of any <Entity>Qos is given in Appendix A, Quality Of Service. The complete list of individual QosPolicy settings and their meaning is described below.
Figure 10 QosPolicy Settings
# Requested/Offered
In several cases, for communications to occur properly (or efficiently), a QosPolicy on the requesting side must be compatible with a corresponding QosPolicy on the offering side. For example, if a DataReader requests to receive data reliably while the corresponding DataWriter defines a best-effort QosPolicy, communication will not happen as requested. This means that the specification for QosPolicy follows the Requested/Offered (RxO) pattern while trying to maintain the desirable decoupling of publication and subscription as much as possible. When using this pattern:
• the requesting side can specify a requested attribute for a particular QosPolicy
• the offering side specifies an offered attribute for that QosPolicy
The Data Distribution Service will then determine whether the attribute requested by the requesting side is compatible with what is offered by the offering side. Only when the two QosPolicy settings are compatible, communication is established. If the two QosPolicy settings are not compatible, the Data Distribution Service will not establish communication between the two Entity objects and notify this fact by means of the OFFERED\_INCOMPATIBLE\_QOS status on the offering side and the REQUESTED\_INCOMPATIBLE\_QOS status on the requesting side. The application can detect this fact by means of a Listener or Condition.
The interface description of these QosPolicies is as follows:
```c
// struct <Entity>Qos
// see appendix
//
// struct <name>QosPolicy
//
struct UserDataQosPolicy
{ OctetSeq value; };
struct TopicDataQosPolicy
{ OctetSeq value; };
struct GroupDataQosPolicy
{ OctetSeq value; };
struct TransportPriorityQosPolicy
{ Long value; };
struct LifespanQosPolicy
{ Duration_t duration; };
enum DurabilityQosPolicyKind
{ VOLATILE_DURABILITY_QOS,
TRANSIENT_LOCAL_DURABILITY_QOS,
TRANSIENT_DURABILITY_QOS,
PERSISTENT_DURABILITY_QOS };
struct DurabilityQosPolicy
{ DurabilityQosPolicyKind kind; };
enum PresentationQosPolicyAccessScopeKind
{ INSTANCE_PRESENTATION_QOS,
TOPIC_PRESENTATION_QOS,
GROUP_PRESENTATION_QOS };
struct PresentationQosPolicy
{ PresentationQosPolicyAccessScopeKind access_scope;
Boolean coherent_access;
Boolean ordered_access; };
struct DeadlineQosPolicy
```
```c
{ Duration_t period; };
struct LatencyBudgetQosPolicy
{ Duration_t duration; };
enum OwnershipQosPolicyKind
{ SHARED_OWNERSHIP_QOS,
EXCLUSIVE_OWNERSHIP_QOS };
struct OwnershipQosPolicy
{ OwnershipQosPolicyKind kind; };
struct OwnershipStrengthQosPolicy
{ Long value; };
enum LivelinessQosPolicyKind
{ AUTOMATIC_LIVELINESS_QOS,
MANUAL_BY_PARTICIPANT_LIVELINESS_QOS,
MANUAL_BY_TOPIC_LIVELINESS_QOS };
struct LivelinessQosPolicy
{ LivelinessQosPolicyKind kind;
Duration_t lease_duration; };
struct TimeBasedFilterQosPolicy
{ Duration_t minimum_separation; };
struct PartitionQosPolicy
{ StringSeq name; };
enum ReliabilityQosPolicyKind
{ BEST_EFFORT_RELIABILITY_QOS,
RELIABLE_RELIABILITY_QOS };
struct ReliabilityQosPolicy
{ ReliabilityQosPolicyKind kind;
Duration_t max_blocking_time;
Boolean synchronous; };
enum DestinationOrderQosPolicyKind
{ BY_RECEPTION_timestamp_DESTINATIONORDER_QOS,
BY_SOURCE_timestamp_DESTINATIONORDER_QOS };
struct DestinationOrderQosPolicy
{ DestinationOrderQosPolicyKind kind; };
enum HistoryQosPolicyKind
{ KEEP_LAST_HISTORY_QOS,
KEEP_ALL_HISTORY_QOS };
struct HistoryQosPolicy
{ HistoryQosPolicyKind kind;
Long depth; };
struct ResourceLimitsQosPolicy
{ Long max_samples;
Long max_instances;
Long max_samples_per_instance; };
struct EntityFactoryQosPolicy
{ Boolean autoenable_created_entities; };
struct WriterDataLifecycleQosPolicy
{ Boolean autodispose_unregistered_instances; };
enum InvalidSampleVisibilityQosPolicyKind
{ NO_INVALID_SAMPLES,
MINIMUM_INVALID_SAMPLES,
```
```c
ALL_INVALID_SAMPLES };
struct InvalidSampleVisibilityQosPolicy
{ InvalidSampleVisibilityQosPolicyKind kind; };
struct ReaderDataLifecycleQosPolicy
{ Duration_t autopurge_nowriter_samples_delay;
Duration_t autopurge_disposed_samples_delay;
Boolean autopurge_dispose_all;
Boolean enable_invalid_samples; /* deprecated */
InvalidSampleVisibilityQosPolicy
invalid_sample_visibility; };
struct DurabilityServiceQosPolicy
{ Duration_t service_cleanup_delay;
HistoryQosPolicyKind history_kind;
Long history_depth;
Long max_samples;
Long max_instances;
Long max_samples_per_instance; };
enum SchedulingClassQosPolicyKind
{ SCHEDULE_DEFAULT,
SCHEDULE_TIMESHARING,
SCHEDULE_REALTIME };
struct SchedulingClassQosPolicy
{ SchedulingClassQosPolicyKind kind; };
enum SchedulingPriorityQosPolicyKind
{ PRIORITY_RELATIVE,
PRIORITY_ABSOLUTE };
struct SchedulingPriorityQosPolicy
{ SchedulingPriorityQosPolicyKind kind; };
struct SchedulingQosPolicy
{ SchedulingClassQosPolicy scheduling_class;
SchedulingPriorityQosPolicy scheduling_priority_kind;
long scheduling_priority; };
struct SubscriptionKeyQosPolicy
{ Boolean use_key_list,
StringSeq key_list };
struct ReaderLifespanQosPolicy
{ Boolean use_lifespan,
Duration_t duration };
struct ShareQosPolicy
{ String name,
Boolean enable };
struct ViewKeyQosPolicy
{ Boolean use_key_list;
StringSeq key_list };
```
# Default Attributes
The default attributes of each QosPolicy are listed in Table 2 below.
Table 2 QosPolicy Default Attributes
| QosPolicy | Attribute | Value |
| user_data | value.length | 0 |
| topic_data | value.length | 0 |
| group_data | value.length | 0 |
| transport_priority | value | 0 |
| lifespan | duration | DURATION_INFINITE |
| durability | kind | VOLATILE_DURABILITY_QOS |
| presentation | access_scope | INSTANCE_PRESENTATION_QOS |
| coherent_access | FALSE |
| ordered_access | FALSE |
| deadline | period | DURATION_INFINITE |
| latency_budget | duration | 0 |
| ownership_strength | value | 0 |
| ownership | kind | SHARED_OWNERSHIP_QOS |
| liveliness | kind | AUTOMATIC_LIVELINESS_QOS |
| lease_duration | DURATION_INFINITE |
| time_based_filter | minimum_separation | 0 |
| partition | name.length | 0 |
| reliability | kind | BEST_EFFORT_RELIABILITY_QOS |
| max_blocking_time | 100 ms |
| synchronous | FALSE |
| destination_order | kind | BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS |
| history | kind | KEEP_LAST_HISTORY_QOS |
| depth | 1 |
| resource_limits | max_samples | LENGTH_UNLIMITED |
| max_instances | LENGTH_UNLIMITED |
| max_samples_per_instance | LENGTH_UNLIMITED |
| entity_factory | autoenable_created_entities | TRUE |
| writer_data_lifecycle | autodispose_unregistered_instances | TRUE |
| reader_data_lifecycle | autopurge_nowriter_samples_delay | DURATION_INFINITE |
| autopurge_disposed_samples_delay | DURATION_INFINITE |
| autopurge_dispose_all | FALSE |
| enable_invalid_samples | TRUE |
| invalid_sample_visibilityy.kind | 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 | SCHEDULE_DEFAULT |
| scheduling_priority_kind.kind | PRIORITY_RELATIVE |
| scheduling_priority | 0 |
| subscription_keys | use_key_list | FALSE |
| key_list.length | 0 |
| reader_lifespan | use_lifespan | FALSE |
| duration | 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 $^ { \mathrm { { \infty } } } \mathrm { { R x O } ^ { \mathrm { { \circ } } } }$ (Requested/Offered) property. The RxO property of each QosPolicy is listed in Table 3 on page 40.
# Please note:
• A RxO 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 Entity is enabled. In other words, a QosPolicy with changeable setting of No is considered “immutable” and can only be specified either at Entity creation time or prior to calling the enable operation on the Entity.
When the application tries to change a QosPolicy with changeable setting of No, 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 RETCODE\_IMMUTABLE\_POLICY.
The basic way to modify or set the <Entity>Qos is by using a get\_qos and set\_qos operation to get all QosPolicy settings from this Entity (that is the <Entity>Qos), modify several specific QosPolicy settings and put them back using an user operation to set all QosPolicy settings on this Entity (that is the <Entity>Qos). An example of these operations for the DataWriter are get\_qos and set\_qos, which take the <Entity>Qos as a parameter.
The “RxO” setting and the “changeable” setting of each QosPolicy are listed in Table 3 below.
Table 3 QosPolicy Basics
| QosPolicy | Concerns Entity | RxO | Changeable After Enabling |
| user_data | DomainParticipant DataReader DataWriter | No | Yes |
| topic_data | Topic | No | Yes |
| group_data | Publisher Subscriber | No | Yes |
| transport_priority | Topic DataWriter | Not applicable | Yes |
| lifespan | Topic DataWriter | Not applicable | Yes |
| durability | Topic DataReader DataWriter | Yes | No |
| presentation | Publisher Subscriber | Yes | No |
| deadline | Topic DataReader DataWriter | Yes | Yes |
| latency_budget | Topic DataReader DataWriter | Yes | Yes |
| ownership | Topic DataReader DataWriter | Yes | No |
| ownership_strength | DataWriter | Not applicable | Yes |
| liveliness | Topic DataReader DataWriter | Yes | No |
| time_based_filter | DataReader | Not applicable | Yes |
| partition | Publisher Subscriber | No | Yes |
| reliability | Topic DataReader DataWriter | Yes | No |
| destination_order | Topic DataReader DataWriter | Yes | No |
| history | Topic DataReader DataWriter | No | No |
| resource_limits | Topic DataReader DataWriter | No | No |
| entity_factory | DomainParticipantFactoryDomainParticipantPublisherSubscriber | No | Yes |
| writer_data_lifecycle | DataWriter | Not applicable | Yes |
| reader_data_lifecycle | DataReader | Not applicable | Yes |
| durability_service | Topic | No | No |
| scheduling | DomainParticipant | Not applicable | No |
| subscription_keys | DataReader | Not applicable | No |
| reader_lifespan | DataReader | Not applicable | Yes |
| share | DataReaderSubscriber | Not applicable | NoNo |
| view_keys | DataReaderView | Not applicable | No |
The following paragraphs describe the usage of each <name>QosPolicy struct.
# 3.1.3.1 DeadlineQosPolicy
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct DeadlineQosPolicy
{ 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
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 DataReader expects a new sample or, in case of a DataWriter, the period in which it expects applications to write the sample. The default value of the period is DURATION\_INFINITE, indicating that there is no deadline. The QosPolicy may be used to monitor the real-time behaviour, a Listener or a StatusCondition may be used to catch the event that is generated when a deadline is missed.
DeadlineQosPolicy is instance oriented (i.e. the period is monitored for each individual instance).
The exact consequences of a missed deadline depend on the Entity in which it ocurred, and the OwnershipQosPolicy value of that Entity:
• In case a DataWriter misses an instance deadline (regardless of its OwnershipQosPolicy setting), an offered\_deadline\_missed\_status is raised, which can be detected by either a Listener or a StatusCondition. There are no further consequences.
• In case DataReader misses an instance deadline, a requested\_deadline\_missed\_status is raised, which can be detected by either a Listener or a StatusCondition. In case the OwnershipQosPolicy is set to SHARED, there are no further consequences. In case the OwnershipQosPolicy is set to EXCLUSIVE, the ownership of that instance on that particular DataReader is transferred to the next available highest strength 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) DataWriters to transfer ownership to, the instance\_state remains unchanged. See also Section 3.1.3.11, OwnershipQosPolicy.
This QosPolicy is applicable to a DataReader, a DataWriter and a Topic. After enabling of the concerning Entity, this QosPolicy may be changed by using the set\_qos operation.
# Requested/Offered
In case the Requested/Offered QosPolicy are incompatible, the notification O F FE R E D \_ I N CO M P A T I BL E \_ Q O S s ta tu s on th e offering s id e an d REQUESTED\_INCOMPATIBLE\_QOS status on the requesting side is raised.
Table 4 DeadlineQosPolicy
| Entity | Status | Meaning |
| Topic | INCONSISTENT_TOPIC_STATUS | Another Topic exists with the same name but with different characteristics. |
| ALL_DATA_DISPOSED_TOPIC_STATUS | All instances of the Topic have been disposed by the dispose_all_data operation on that topic. |
| Subscriber | DATA_ON_READERS_STATUS | New information is available. |
| DataReader | SAMPLE_REJECTED_STATUS | A (received) sample has been rejected. |
| LIVELINESS_CHANGED_STATUS | The liveliness of one or more DataWriter objects that were writing instances read through the DataReader has changed. Some DataWriter have become “alive” or “not alive”. |
| REQUESTED_DEADLINE_MISSED_STATUS | The deadline that the DataReader was expecting through its DeadlineQosPolicy was not respected for a specific instance. |
| REQUESTED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what is offered. |
| DATA_AVAILABLE_STATUS | New information is available. |
| SAMPLE_LOST_STATUS | A sample has been lost (never received). |
| SUBSCRIPTION_MATCH_STATUS | The DataReader has found a DataWriter that matches the Topic and has compatible QoS. |
| DataWriter | LIVELINESS_LOST_STATUS | The liveliness that the DataWriter has committed through its LivelinessQosPolicy was not respected; thus DataReader objects will consider the DataWriter as no longer “alive”. |
| OFFERED_DEADLINE_MISSED_STATUS | The deadline that the DataWriter has committed through its DeadlineQosPolicy was not respected for a specific instance. |
| OFFERED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what was requested. |
| PUBLICATION_MATCH_STATUS | The DataWriter has found DataReader that matches the Topic and has compatible QoS. |
A 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 InconsistentTopicStatus value, the application must call the operation get\_inconsistent\_topic\_status.
Conceptually associated with each 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 Status, the StatusChangedFlag 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 Entity.
A flag set means that a change has occurred since the last time the application has read its value.
Figure 12 DCPS Status Values
Each 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 <name>Status
//
struct InconsistentTopicStatus
{ Long total_count;
Long total_count_change; };
struct AllDataDisposedTopicStatus
{ Long total_count;
Long total_count_change; }
struct SampleLostStatus
{ Long total_count;
Long total_count_change; };
enum SampleRejectedStatusKind
{ NOT_REJECTED,
REJECTED_BY_INSTANCES_LIMIT,
REJECTED_BY_SAMPLES_LIMIT,
REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT };
struct SampleRejectedStatus
{ Long total_count;
Long total_count_change;
SampleRejectedStatusKind last_reason;
```
```c
InstanceHandle_t last_instance_handle; };
struct LivelinessLostStatus
{ Long total_count;
Long total_count_change; };
struct LivelinessChangedStatus
{ Long alive_count;
Long not_alive_count;
Long alive_count_change;
Long not_alive_count_change;
InstanceHandle_t last_publication_handle; };
struct OfferedDeadlineMissedStatus
{ Long total_count;
Long total_count_change;
InstanceHandle_t last_instance_handle; };
struct RequestedDeadlineMissedStatus
{ Long total_count;
Long total_count_change;
InstanceHandle_t last_instance_handle; };
struct OfferedIncompatibleQosStatus
{ Long total_count;
Long total_count_change;
QosPolicyId_t last_policy_id;
QosPolicyCountSeq policies; };
struct RequestedIncompatibleQosStatus
{ Long total_count;
Long total_count_change;
QosPolicyId_t last_policy_id;
QosPolicyCountSeq policies; };
struct PublicationMatchedStatus
{ Long total_count;
Long total_count_change;
Long current_count;
Long current_count_change;
InstanceHandle_t last Subscription_handle; };
struct SubscriptionMatchedStatus
{ Long total_count;
Long total_count_change;
Long current_count;
Long current_count_change;
InstanceHandle_t last Publication_handle; };
// implemented API operations
// <no operations>
```
The next paragraphs describe the usage of each <name>Status struct.
# 3.1.5.1 InconsistentTopicStatus
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct InconsistentTopicStatus
{ Long total_count;
Long total_count_change; };
```
# Description
This struct contains the statistics about attempts to create other Topics with the same name but with different characteristics.
# Attributes
Long total\_count - the total detected cumulative count of Topic creations, whose name matches the Topic to which this Status is attached and whose characteristics are inconsistent.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
# Detailed Description
This struct contains the statistics about attempts to create other Topics with the same name but with different characteristics.
The attribute total\_count holds the total detected cumulative count of Topic creations, whose name matches the Topic to which this Status is attached and whose characteristics are inconsistent.
The attribute total\_count\_change holds the incremental number of inconsistent Topics, since the last time the Listener was called or the Status was read.
# 3.1.5.2 LivelinessChangedStatus
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct LivelinessChangedStatus
{ Long alive_count;
Long not_alive_count;
Long alive_count_change;
Long not_alive_count_change;
```
InstanceHandle\_t last\_publication\_handle; };
# Description
This struct contains the statistics about whether the liveliness of one or more connected DataWriter objects has changed.
# Attributes
Long alive\_count - the total count of currently alive DataWriter objects that write the topic read by the DataReader to which this Status is attached.
Long not\_alive\_count - the total count of currently not alive DataWriter objects that wrote the topic read by the DataReader to which this Status is attached.
Long alive\_count\_change - the change in alive\_count since the last time the Listener was called or the Status was read.
Long not\_alive\_count\_change - the change in not\_alive\_count since the last time the Listener was called or the Status was read.
InstanceHandle\_t last\_publication\_handle - handle to the last 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 DataWriter objects that were writing instances read through the DataReader has changed. In other words, some DataWriter have become “alive” or “not alive”.
The attribute alive\_count holds the total number of currently alive DataWriter objects that write the topic read by the DataReader to which this Status is attached. This count increases when a newly-matched DataWriter asserts its liveliness for the first time or when a DataWriter previously considered to be not alive reasserts its liveliness. The count decreases when a 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 DataWriters that wrote the topic read by the DataReader to which this Status is attached, and that are no longer asserting their liveliness. This count increases when a DataWriter considered alive fails to assert its liveliness and becomes not alive for some reason other than the normal deletion of that DataWriter. It decreases when a previously not alive 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 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 Status was read.
The attribute last\_publication\_handle contains the instance handle to the PublicationBuiltinTopicData instance that represents the last datawriter whose change in liveliness caused this status to change. Be aware that this handle be lo ng s t o an oth er d a t a r e a d e r, t h e PublicationBuiltinTopicDataDataReader in the builtin-subscriber, and has n o m e a n i n g i n t h e c o n t e x t o f t h e d a t a r e a d e r f r o m w h i c h t h e LivelinessChangedStatus was obtained. If the builtin-subscriber has not explicitly been obtained using get\_builtin\_subscriber on the DomainParticipant, t h e n t h e r e i s n o PublicationBuiltinTopicDataDataReader as well, in which case the last\_publication\_handle will be set to HANDLE\_NIL.
# 3.1.5.3 LivelinessLostStatus
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct LivelinessLostStatus
{ Long total_count;
Long total_count_change; };
```
# Description
This struct contains the statistics about whether the liveliness of the DataWriter to w h i c h t h i s S t a t u s i s a t t a c h e d h a s b e e n c o m m i t t e d t h r o u g h i t s LivelinessQosPolicy.
# Attributes
Long total\_count - the total cumulative count of times the DataWriter to which this Status is attached failed to actively signal its liveliness within the offered liveliness period.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
# Detailed Description
This struct contains the statistics about whether the liveliness of the DataWriter to w h i c h t h i s S t a t u s i s a t t a c h e d h a s b e e n c o m m i t t e d t h r o u g h i t s LivelinessQosPolicy. In other words, whether the DataWriter failed to actively signal its liveliness within the offered liveliness period. In such a case, the connected DataReader objects will consider the DataWriter as no longer “alive”.
The attribute total\_count holds the total cumulative number of times that the previously-alive 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 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 Status was read.
# 3.1.5.4 OfferedDeadlineMissedStatus
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct OfferedDeadlineMissedStatus
{ Long total_count
Long total_count_change
InstanceHandle_t last_instance_handle }
```
# Description
This struct contains the statistics about whether the deadline that the DataWriter to which this Status is attached has committed through its DeadlineQosPolicy was not respected for a specific instance.
# Attributes
Long total\_count - the total cumulative count of times the DataWriter to which this Status is attached failed to write within its offered deadline.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
InstanceHandle\_t last\_instance\_handle - the handle to the last instance in the DataWriter to which this Status is attached, for which an offered deadline was missed.
# Detailed Description
This struct contains the statistics about whether the deadline that the DataWriter to which this Status is attached has committed through its 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 DataWriter to which this 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 Status was read.
The attribute last\_instance\_handle holds the handle to the last instance in the DataWriter to which this Status is attached, for which an offered deadline was missed.
# 3.1.5.5 OfferedIncompatibleQosStatus
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct OfferedIncompatibleQosStatus
{ Long total_count
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
Long total\_count - the total cumulative count of DataReader objects discovered by the DataWriter with the same Topic and Partition and with a requested DataReaderQos that was incompatible with the one offered by the DataWriter.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the 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 DataWriter discovered a DataReader for the same Topic and a requested DataReaderQos that is incompatible with the one offered by the 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 DataWriter and the DataReader. If the QosPolicy settings between DataWriter and DataReader are incompatible, no communication between them is established. In addition the DataWriter will be informed via a REQUESTED\_INCOMPATIBLE\_QOS status change and the DataReader will be informed via an OFFERED\_INCOMPATIBLE\_QOS status change.
• the DataWriter and the Durability Service (as a built-in DataReader). If the QosPolicy settings between DataWriter and the Durability Service are inconsistent, no communication between them is established. In that case data published by the DataWriter will not be maintained by the service and as a consequence will not be available for late joining DataReaders. The QosPolicy of the Durability Service in the role of DataReader is specified by the DurabilityServiceQosPolicy in the Topic.
• the Durability Service (as a built-in DataWriter) and the DataReader. If the QosPolicy settings between the Durability Service and the DataReader are inconsistent, no communication between them is established. In that case the Durability Service will not publish historical data to late joining DataReaders. The QosPolicy of the Durability Service in the role of DataWriter is specified by the DurabilityServiceQosPolicy in the Topic.
The attribute total\_count holds the total cumulative count of DataReader objects discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the 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 DataWriter discovered an incompatible DataReader for the same 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 13, Overview of all named QosPolicy indexes for an overview of all these constants.
Table 13 Overview of all named QosPolicy indexes
| Index name | Index Value |
| INVALID_QOS_POLICY_ID | 0 |
| USERDATA_QOS_POLICY_ID | 1 |
| DURABILITY_QOS_POLICY_ID | 2 |
| PRESENTATION_QOS_POLICY_ID | 3 |
| DEADLINE_QOS_POLICY_ID | 4 |
| LATENCYBUDGET_QOS_POLICY_ID | 5 |
| OWNERSHIP_QOS_POLICY_ID | 6 |
| OWNERSHIPSTRENGTH_QOS_POLICY_ID | 7 |
| LIVELINESS_QOS_POLICY_ID | 8 |
| TIMEBASEDFILTER_QOS_POLICY_ID | 9 |
| PARTITION_QOS_POLICY_ID | 10 |
| RELIABILITY_QOS_POLICY_ID | 11 |
| DESTINATIONORDER_QOS_POLICY_ID | 12 |
| HISTORY_QOS_POLICY_ID | 13 |
| RESOURCELIMITS_QOS_POLICY_ID | 14 |
| ENTITYFACTORY_QOS_POLICY_ID | 15 |
| WRITERDATALIFECYCLE_QOS_POLICY_ID | 16 |
| READERDATALIFECYCLE_QOS_POLICY_ID | 17 |
| TOPICDATA_QOS_POLICY_ID | 18 |
| GROUPDATA_QOS_POLICY_ID | 19 |
| TRANSPORTPRIORITY_QOS_POLICY_ID | 20 |
| LIFESPAN_QOS_POLICY_ID | 21 |
| DURABILITYSERVICE_QOS_POLICY_ID | 22 |
# 3.1.5.6 PublicationMatchedStatus
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct PublicationMatchedStatus
{ Long total_count
Long total_count_change
Long current_count;
```
Long current\_count\_change; 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
Long total\_count - Total cumulative count of DataReaders compatible with the concerned DataWriter.
Long total\_count\_change - The change in total\_count since the last time the Status was read.
Long current\_count - Total count of DataReaders that are currently available and compatible with the DataWriter.
Long current\_count\_change - The change in current\_count since the last time the Status was read.
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 RequestedDeadlineMissedStatus
Scope
DDS
Synopsis
#include <ccpp\_dds\_dcps.h>
```txt
struct RequestedDeadlineMissedStatus
{ Long total_count
Long total_count_change
InstanceHandle_t last_instance_handle }
```
# Description
This struct contains the statistics about whether the deadline that the DataReader to which this Status is attached was expecting through its DeadlineQosPolicy, was not respected for a specific instance.
# Attributes
Long total\_count - the total cumulative count of the missed deadlines detected for any instance read by the DataReader to which this Status is attached.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
InstanceHandle\_t last\_instance\_handle - the handle to the last instance in the DataReader to which this Status is attached for which a missed deadline was detected.
# Detailed Description
This struct contains the statistics about whether the deadline that the DataReader to which this Status is attached was expecting through its 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 DataReader.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the Status was read.
The attribute last\_instance\_handle holds the handle to the last instance in the DataReader for which a missed deadline was detected.
# 3.1.5.8 RequestedIncompatibleQosStatus
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct RequestedIncompatibleQosStatus
{ Long total_count
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
Long total\_count - the total cumulative count of DataWriter objects, discovered by the DataReader to which this Status is attached, with the same Topic and an offered DataWriterQos that was incompatible with the one requested by the DataReader.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
QosPolicyId\_t last\_policy\_id - the <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 DataReader discovered a DataWriter with the same Topic and an offered DataWriterQos that is incompatible with the one requested by the 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 DataWriter and the DataReader. If the QosPolicy settings between DataWriter and DataReader are incompatible, no communication between them is established. In addition the DataWriter will be informed via a REQUESTED\_INCOMPATIBLE\_QOS status change and the DataReader will be informed via an OFFERED\_INCOMPATIBLE\_QOS status change.
• the DataWriter and the Durability Service (as a built-in DataReader). If the QosPolicy settings between DataWriter and the Durability Service are inconsistent, no communication between them is established. In that case data published by the DataWriter will not be maintained by the service and as a consequence will not be available for late joining DataReaders. The QosPolicy of the Durability Service in the role of DataReader is specified by the DurabilityServiceQosPolicy in the Topic.
• the Durability Service (as a built-in DataWriter) and the DataReader. If the QosPolicy settings between the Durability Service and the DataReader are inconsistent, no communication between them is established. In that case the Durability Service will not publish historical data to late joining DataReaders. The QosPolicy of the Durability Service in the role of DataWriter is specified by the DurabilityServiceQosPolicy in the Topic.
The attribute total\_count holds the total cumulative count of DataWriter objects discovered by the DataReader with the same Topic and an offered DataWriterQos that was incompatible with the one requested by the DataReader.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the Status was read.
The attribute last\_policy\_id holds the <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 DataReader discovered an incompatible DataWriter for the same 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 13, Overview of all named QosPolicy indexes, on page 101 for an overview of all these constants.
# 3.1.5.9 SampleLostStatus
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct SampleLostStatus
{ Long total_count
Long total_count_change }
```
# Description
This struct contains the statistics about whether a sample has been lost (never received).
# Attributes
Long total\_count - the total cumulative count of all samples lost across all instances of data published under the Topic.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the 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 Topic.
total\_count holds the total cumulative count of all samples lost across all instances of data published under the Topic.
total\_count\_change holds the change in total\_count since the last time the Listener was called or the Status was read.
# 3.1.5.10 SampleRejectedStatus
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
enum SampleRejectedStatusKind
{ NOT_REJECTED
REJECTED_BY_INSTANCES_LIMIT,
REJECTED_BY_SAMPLES_LIMIT,
REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT }
struct SampleRejectedStatus
{ Long total_count
Long total_count_change
SampleRejectedStatusKind last_reason
InstanceHandle_t last_instance_handle }
```
# Description
This struct contains the statistics about samples that have been rejected.
# Attributes
Long total\_count - the total cumulative count of samples rejected by the DataReader to which this Status is attached.
Long total\_count\_change - the change in total\_count since the last time the Listener was called or the Status was read.
SampleRejectedStatusKind last\_reason - the reason for rejecting the last sample.
InstanceHandle\_t last\_instance\_handle - the handle to the instance which would have been 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 DataReader to which this Status is attached.
The attribute total\_count\_change holds the change in total\_count since the last time the Listener was called or the Status was read.
The attribute last\_reason holds the reason for rejecting the last sample. The attribute can have the following values:
• NOT\_REJECTED - no sample has been rejected yet.
• REJECTED\_BY\_INSTANCES\_LIMIT - the sample was rejected because it would exceed the maximum number of instances set by the ResourceLimitsQosPolicy.
• REJECTED\_BY\_SAMPLES\_LIMIT - the sample was rejected because it would exceed the maximum number of samples set by the ResourceLimits QosPolicy.
• REJECTED\_BY\_SAMPLES\_PER\_INSTANCE\_LIMIT - the sample was rejected because it would exceed the maximum number of samples per instance set by the 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 SubscriptionMatchedStatus
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct SubscriptionMatchedStatus
{ Long total_count
Long total_count_change
Long current_count;
Long current_count_change;
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
Long total\_count - Total cumulative count of DataWriters compatible with the concerned DataReader.
Long total\_count\_change - The change in total\_count since the last time the Status was read.
Long current\_count - Total count of DataWriters that are currently available and compatible with the DataWriter.
Long current\_count\_change - The change in current\_count since the last time the Status was read.
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 AllDataDisposedTopicStatus
# Scope
DDS
# Synopsis
```tcl
#include <ccpp_dds_dcps.h>
struct AllDataDisposedTopicStatus
{ Long total_count
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 ALL\_DATA\_DISPOSED\_TOPIC\_STATUS event on the Topic to which this Status is attached.
# Attributes
L o n g t o t a l \_ c o u n t - t h e t o t a l d e t e c t e d c u m u l a t i v e c o u n t o f ALL\_DATA\_DISPOSED\_TOPIC\_STATUS events.
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 ALL\_DATA\_DISPOSED\_TOPIC\_STATUS event on the Topic to which this Status is a t t a c h e d . T h e S t a t u s i s d i r e c t l y r e l a t e d t o t h e i n v o c a t i o n o f t h e 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 WaitSet
A WaitSet object allows an application to wait until one or more of the attached Condition objects evaluates to TRUE or until the timeout expires.
The WaitSet has no factory and must be created by the application. It is directly created as an object by using WaitSet constructors.
Figure 13 DCPS WaitSets
The interface description of this class is as follows:
```cpp
class WaitSet
{
//
// implemented API operations
//
ReturnCode_t
wait
(ConditionSeq& active_conditions,
const Duration_t& timeout);
ReturnCode_t
attach_condition
(Condition_ptr cond);
ReturnCode_t
detach_condition
(Condition_ptr cond);
ReturnCode_t
get_conditions
```
```txt
(ConditionSeq& attached_conditions);
};
```
The following paragraphs describe the usage of all WaitSet operations.
# 3.1.6.1 attach\_condition
# Scope
```autohotkey
DDS::WaitSet
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
attach_condition
(Condition_ptr cond);
```
# Description
This operation attaches a Condition to the WaitSet.
# Parameters
in Condition\_ptr cond - a pointer to a Condition.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER or RETCODE\_OUT\_OF\_ RESOURCES.
# Detailed Description
This operation attaches a Condition to the WaitSet. The parameter cond must be either a ReadCondition, QueryCondition, StatusCondition or GuardCondition. To get this parameter see:
• ReadCondition created by create\_readcondition
• QueryCondition created by create\_querycondition
• StatusCondition retrieved by get\_statuscondition on an Entity
• GuardCondition created by the C++ operation new.
When a GuardCondition is initially created, the trigger\_value is FALSE.
When a Condition, whose trigger\_value evaluates to TRUE, is attached to a WaitSet that is currently being waited on (using the wait operation), the WaitSet will unblock immediately.
# Return Code
When the operation returns:
• RETCODE\_OK - the Condition is attached to the WaitSet
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - the parameter cond is not a valid Condition\_ptr
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.1.6.2 detach\_condition
# Scope
DDS::WaitSet
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
detach_condition
(Condition_ptr cond);
```
# Description
This operation detaches a Condition from the WaitSet.
# Parameters
in Condition\_ptr cond - a pointer to a Condition in the WaitSet.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_OUT\_OF\_ RESOURCES or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation detaches a Condition from the WaitSet. If the Condition was n o t a t t a c h e d t o t h i s W a i t S e t , t h e o p e r a t i o n r e t u r n s RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the Condition is detached from the WaitSet.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter cond is not a valid Condition\_ptr.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the Condition was not attached to this WaitSet.
# 3.1.6.3 get\_conditions
# Scope
DDS::WaitSet
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_conditions
(ConditionSeq_out attached_conditions);
```
# Description
This operation retrieves the list of attached conditions.
# Parameters
inout ConditionSeq& attached\_conditions - a reference to a sequence which is used to pass the list of attached conditions.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation retrieves the list of attached conditions in the WaitSet. The parameter attached\_conditions is a reference to a sequence which afterwards will refer to the sequence of attached conditions. The attached\_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 get\_conditions operation or be released by invoking its destructor either implicitly or explicitly. If the pre-allocated sequence is not big enough to hold the number of triggered 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 n o c o n d i t i o n s a t t a c h e d , o r w i ll c o n t a i n a l i s t o f R e a d C o n d i t i o n , QueryCondition, StatusCondition and GuardCondition. These conditions previously have been attached by attach\_condition and were created by there respective create operation:
• ReadCondition created by create\_readcondition
• QueryCondition created by create\_querycondition
• StatusCondition retrieved by get\_statuscondition on an Entity
• GuardCondition created by the C++ operation new.
# Return Code
When the operation returns:
• RETCODE\_OK - the list of attached conditions is returned
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.1.6.4 wait
# Scope
DDS::WaitSet
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
wait
(ConditionSeq& active_conditions,
const 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 WaitSet.
# Parameters
inout 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 Duration\_t& timeout - the maximum duration to block for the wait, after which the application thread is unblocked. The special constant DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_TIMEOUT or 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 WaitSet. If all of the conditions attached to the WaitSet have a trigger\_value of FALSE, the wait operation will block the calling thread. The result of the operation is the c o n t i n u a t i o n o f t h e a p p l i c a t i o n t h r e a d a f t e r w h i c h t h e r e s u l t i s l e f t i n active\_conditions. This is a reference to a sequence, which will contain the list of all the attached conditions that have a trigger\_value of TRUE. The 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 wait operation or be released by invoking its destructor either implicitly or explicitly. If the pre-allocated sequence is not big enough to hold the number of triggered Conditions, the sequence will automatically be (re-)allocated to fit the required size. The parameter timeout specifies the maximum duration for the wait to block the calling application thread (when none of the attached conditions h a s a t r i g g e r \_ v a l u e o f T R U E ) . I n t h a t c a s e t h e r e t u r n v a l u e i s RETCODE\_TIMEOUT and the active\_conditions sequence is left empty. Since it is not allowed for more than one application thread to be waiting on the same W a i t S e t , t h e o p e r a t i o n r e t u r n s i m m e d i a t e l y w i t h t h e v a l u e RETCODE\_PRECONDITION\_NOT\_MET when the wait operation is invoked on a WaitSet which already has an application thread blocking on it.
# Return Code
When the operation returns:
• RETCODE\_OK - at least one of the attached conditions has a trigger\_value of TRUE.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_TIMEOUT - the timeout has elapsed without any of the attached conditions becoming TRUE.
• RETCODE\_PRECONDITION\_NOT\_MET - the WaitSet already has an application thread blocking on it.
# 3.1.7 Class Condition
This class is the base class for all the conditions that may be attached to a WaitSet. This base class is specialized in three classes by the Data Distribution Service: GuardCondition, StatusCondition and ReadCondition (also there is a QueryCondition which is a specialized ReadCondition).
Each Condition has a trigger\_value that can be TRUE or FALSE and is set by the Data Distribution Service (except a GuardCondition) depending on the evaluation of the Condition.
Figure 14 DCPS Conditions
The interface description of this class is as follows:
```cpp
class Condition
{
//
// implemented API operations
//
Boolean
get_trigger_value
(void);
};
```
The next paragraph describes the usage of the Condition operation.
# 3.1.7.1 get\_trigger\_value
# Scope
```autohotkey
DDS::Condition
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
Boolean
get_trigger_value
(void);
```
# Description
This operation returns the trigger\_value of the Condition.
# Parameters
```txt
<none>
```
# Return Value
Boolean - is the trigger\_value.
# Detailed Description
A Condition has a trigger\_value that can be TRUE or FALSE and is set by the Data Distribution Service (except a GuardCondition). This operation returns the trigger\_value of the Condition.
# 3.1.8 Class GuardCondition
A GuardCondition object is a specific Condition whose trigger\_value is completely under the control of the application. The GuardCondition has no factory and must be created by the application. The GuardCondition is directly created as an object by using the GuardCondition constructor. When a GuardCondition is initially created, the trigger\_value is FALSE. The purpose of the GuardCondition is to provide the means for an application to manually wake up a WaitSet. This is accomplished by attaching the GuardCondition to the W a i t s e t a n d s e t t i n g th e t r i g g er \_ v a l u e b y means of t he set\_trigger\_value operation.
The interface description of this class is as follows:
```cpp
class GuardCondition
{
//
// inherited from Condition
//
// Boolean
// get_trigger_value
```
```c
// (void);
//
// implemented API operations
//
ReturnCode_t
set_trigger_value
(Boolean value);
};
```
The next paragraphs describe the usage of all 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 get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class Condition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
Boolean
get_trigger_value
(void);
```
# 3.1.8.2 set\_trigger\_value
# Scope
DDS::GuardCondition
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_trigger_value
(Boolean value);
```
# Description
This operation sets the trigger\_value of the GuardCondition.
# Parameters
in Boolean value - the boolean value to which the GuardCondition is set.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK or RETCODE\_ERROR.
# Detailed Description
A GuardCondition object is a specific 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 WaitSet. This operation sets the trigger\_value of the GuardCondition to the parameter value. The GuardCondition is directly created using the GuardCondition constructor. When a GuardCondition is initially created, the trigger\_value is FALSE.
# Return Code
When the operation returns:
• RETCODE\_OK - the specified trigger\_value has successfully been applied.
• RETCODE\_ERROR - an internal error has occurred.
# 3.1.9 Class StatusCondition
Entity objects that have status attributes also have a StatusCondition, access is provided to the application by the get\_statuscondition operation.
The communication statuses whose changes can be communicated to the application depend on the Entity. The following table shows the relevant statuses for each Entity.
Table 14 Status Per Entity
| Label | Value | Meaning. |
| ERRORCODE_UNDEFINED | 0 | Error has not (yet) been categorized. |
| ERRORCODE_ERROR | 1 | Unexpected error. |
| ERRORCODE_OUT_OF_RESOURCES | 2 | Not enough resources to complete the operation. |
| ERRORCODE_CREATION_KERNEL_ENTITY_FAILED | 3 | The kernel was not able to create the entity. Probably there is not enough shared memory available. |
| ERRORCODE_INVALID_VALUE | 4 | A value is passed that is outside its valid bounds. |
| ERRORCODE_INVALID_DURATION | 5 | A Duration is passed that is outside its valid bounds or that has not been normalized properly. |
| ERRORCODE_INVALID_TIME | 6 | A Time is passed that is outside its valid bounds or that has not been normalized properly. |
| ERRORCODE_ENTITY_INUSE | 7 | Attempted to delete an entity that is still in use. |
| ERRORCODE_CONTAINS_ENTITIES | 8 | Attempted to delete a factory that still contains entities. |
| ERRORCODE_ENTITY_UNKNOWN | 9 | A pointer to an unknown entity has been passed. |
| ERRORCODE_HANDLE_NOT_REGISTERED | 10 | A handle has been passed that is no longer in use. |
| ERRORCODE_HANDLE_NOT_MATCH | 11 | A handle has been passed to an entity to which it does not belong. |
| ERRORCODE_HANDLE_INVALID | 12 | An unknown handle has been passed. |
| ERRORCODE_INVALID_SEQUENCE | 13 | A sequence has been passed that has inconsistent variables (e.g. length > maximum, buffer equals NULL while maximum > 0, etc.) |
| ERRORCODE_UNSUPPORTED_VALUE | 14 | A value has been passed that is not (yet) supported. |
| ERRORCODE_INCONSISTENT_VALUE | 15 | A value has been passed that is inconsistent |
| ERRORCODE_IMMUTABLE_QOS_POLICY | 16 | Attempted to modify a QosPolicy that is immutable. |
| ERRORCODE_INCONSISTENT_QOS | 17 | Attempted to set QosPolicy values that are mutually inconsistent. |
| ERRORCODE_UNSUPPORTED_QOS_POLICY | 18 | Attempted to pass a QosPolicy setting that is not (yet) supported. |
| ERRORCODE_CONTAINS_CONDITIONS | 19 | Attempted to delete a WaitSet that still has Conditions attached to it. |
| ERRORCODE_CONTAINS_LOANS | 20 | Attempted to delete a DataReader/DataView that has unreturned loans. |
| ERRORCODE_INCONSISTENT_TOPIC | 21 | Attempted to create a topic that is inconsistent with existing topic definitions. |
# 3.1.10.3 get\_message
# Scope
```autohotkey
DDS::ErrorInfo
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_message
(char* & message);
```
# Description
This operation retrieves the description of the latest error.
# Parameters
inout char\*& message - Reference to a string holding the latest description.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, 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, RETCODE\_NO\_DATA is returned and NULL is assigned to the message parameter.
# 3.1.10.4 get\_location
# Scope
```autohotkey
DDS::ErrorInfo
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_location
(char*& location);
```
# Description
This operation retrieves the location or context of the latest error.
# Parameters
inout char\*& message - Pointer to a string holding the location of the latest error.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, 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, RETCODE\_NO\_DATA is returned and NULL is assigned to the location parameter.
# 3.1.10.5 get\_source\_line
# Scope
DDS::ErrorInfo
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_source_line
(char*& source_line);
```
# Description
This operation retrieves the location within the sourcecode of the latest error.
# Parameters
inout char\*& source\_line - Pointer to a string holding the sourcecode information of the latest error.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, 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, RETCODE\_NO\_DATA is returned and NULL is assigned to the source\_line parameter.
# 3.1.10.6 get\_stack\_trace
# Scope
DDS::ErrorInfo
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_stack_trace
(char*& 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:
• DomainParticipant
• DomainParticipantFactory
• DomainParticipantListener (interface).
• Domain (not depicted)
# 3.2.1 Class DomainParticipant
All the DCPS Entity objects are attached to a DomainParticipant.
A 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 Publishers and the Subscribers attached to the same Domain can interact.
This class implements several functions:
• it acts as a container for all other Entity objects
• it acts as a factory for the Publisher, Subscriber, Topic, ContentFilteredTopic and MultiTopic objects
• it provides access to the built-in Topic objects
• it provides information about 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:
```cpp
class DomainParticipant
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
```
```c
// enable
// (void);
//
// implemented API operations
//
Publisher_ptr
create_publisher
(const PublisherQos& qos,
PublisherListener_ptr a_listener,
StatusMask mask);
ReturnCode_t
delete_publisher
(Publisher_ptr p);
Subscriber_ptr
create_subscriber
(const SubscriberQos& qos,
SubscriberListener_ptr a_listener,
StatusMask mask);
ReturnCode_t
delete_subscriber
(Subscriber_ptr s);
Subscriber_ptr
get_builtin_subscriber
(void);
Topic_ptr
create_topic
(const char* topic_name,
const char* type_name,
const TopicQos& qos,
TopicListener_ptr a_listener,
StatusMask mask);
ReturnCode_t
delete_topic
(Topic_ptr a_topic);
Topic_ptr
find_topic
(const char* topic_name,
const Duration_t& timeout);
TopicDescription_ptr
lookup_topicdescription
(const char* name);
ContentFilteredTopic_ptr
create_contentfilteredtopic
(const char* name,
Topic_ptr related_topic,
const char* filter_expression,
const StringSeq& expression_parameters);
ReturnCode_t
delete_contentfilteredtopic
(ContentFilteredTopic_ptr
```
```c
a_contentfilteredtopic);
MultiTopic_ptr
create_multitopic
(const char* name,
const char* type_name,
const char* subscription_expression,
const StringSeq& expression_parameters);
ReturnCode_t
delete_multitopic
(MultiTopic_ptr a_multitopic);
ReturnCode_t
delete_contained_entities
(void);
ReturnCode_t
set_qos
(const DomainParticipantQos& qos);
ReturnCode_t
get_qos
(DomainParticipantQos& qos);
ReturnCode_t
set_listener
(DomainParticipantListener_ptr a_listener,
StatusMask mask);
DomainParticipantListener_ptr
get_listener
(void);
ReturnCode_t
ignore_participant
(InstanceHandle_t handle);
ReturnCode_t
ignore_topic
(InstanceHandle_t handle);
ReturnCode_t
ignore_publication
(InstanceHandle_t handle);
ReturnCode_t
ignore_subscription
(InstanceHandle_t handle);
DomainId_t
get_domain_id
(void);
ReturnCode_t
get_discovered_participants
(InstanceHandleSeq& participant_handles);
ReturnCode_t
get_discovered_participant_data
(ParticipantBuiltinTopicData& participant_data,
InstanceHandle_t handle);
ReturnCode_t
get_discovered_topics
```
```txt
(InstanceHandleSeq& topic_handles);
ReturnCode_t
get_discovered_topic_data
(TopicBuiltinTopicData& topic_data,
InstanceHandle_t handle);
ReturnCode_t
assert_liveliness
(void);
ReturnCode_t
set_default_publisher_qos
(const PublisherQos& qos);
ReturnCode_t
get_default_publisher_qos
(PublisherQos& qos);
ReturnCode_t
set_default_subscriber_qos
(const SubscriberQos& qos);
ReturnCode_t
get_default_subscriber_qos
(SubscriberQos& qos);
ReturnCode_t
set_default_topic_qos
(const TopicQos& qos);
ReturnCode_t
get_default_topic_qos
(TopicQos& qos);
Boolean
contains_entity
(InstanceHandle_t a_handle);
ReturnCode_t
get_current_time
(Time_t& current_time);
};
```
The next paragraphs describe the usage of all 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 assert\_liveliness
# Scope
DDS::DomainParticipant
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
assert_liveliness
(void);
```
# Description
This operation asserts the liveliness for the DomainParticipant.
# Parameters
```txt
<none>
```
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation will manually assert the liveliness for the DomainParticipant. This way, the Data Distribution Service is informed that the DomainParticipant is still alive. This operation only needs to be used when the DomainParticipant contains DataWriters with the LivelinessQosPolicy set to MANUAL\_BY\_PARTICIPANT\_LIVELINESS\_QOS, and it will only affect the liveliness of those DataWriters.
Writing data via the write operation of a DataWriter will assert the liveliness on the D at aW ri te r itself and its D om ai n Pa rt ic ip an t. Therefore, assert\_liveliness is only needed when not writing regularly.
The liveliness should be asserted by the application, depending on the LivelinessQosPolicy.
# Return Code
When the operation returns:
• RETCODE\_OK - the liveliness of this DomainParticipant has successfully been asserted.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.2 contains\_entity
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
Boolean
contains_entity
(InstanceHandle_t a_handle);
```
# Description
This operation checks whether or not the given Entity represented by a\_handle is created by the DomainParticipant or any of its contained entities.
# Parameters
in InstanceHandle\_t a\_handle - an Entity in the Data Distribution System.
# Return Value
Boolean - TRUE if a\_handle represents an Entity that is created by the DomainParticipant or any of its contained Entities. 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 DomainParticipant itself (TopicDescription, Publisher or Subscriber) or created by any of its contained entities (DataReader, ReadCondition, QueryCondition, DataWriter, etc.).
Return value is TRUE if a\_handle represents an Entity that is created by the DomainParticipant or any of its contained Entities. Otherwise the return value is FALSE.
# 3.2.1.3 create\_contentfilteredtopic
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ContentFilteredTopic_ptr
create_contentfilteredtopic
(const char* name,
Topic_ptr related_topic,
const char* filter_expression,
const StringSeq& expression_parameters);
```
# Description
This operation creates a ContentFilteredTopic for a DomainParticipant in order to allow DataReaders to subscribe to a subset of the topic content.
# Parameters
in const char\* name - the name of the ContentFilteredTopic.
in Topic\_ptr related\_topic - the pointer to the base topic on which the filtering will be applied. Therefore, a filtered topic is based on an existing Topic.
in const char\* filter\_expression - the SQL expression (subset of SQL), which defines the filtering.
in const StringSeq& expression\_parameters - the handle to a sequence of strings with the parameter value used in the SQL expression (i.e., the number o f % n t o k e n s i n t h e e x p r e s s i o n ) . 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).
# Return Value
ContentFilteredTopic\_ptr - the pointer to the newly created ContentFilteredTopic. In case of an error, a NULL pointer is returned.
# Detailed Description
This operation creates a ContentFilteredTopic for a DomainParticipant in order to allow 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 ContentFilteredTopic only relates to the samples published under the related\_topic, which have been filtered according to their content. The resulting ContentFilteredTopic only exists at the DataReader side and will never be published. The samples of the related\_topic are filtered according to the SQL e x p r e s s i o n ( w h i c h i s a s u b s e t o f S Q L ) a s d e f i n e d i n t h e p a r a m e t e r 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 Topics. It is an SQL expression where the WHERE clause gives the content filter.
# 3.2.1.4 create\_multitopic
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
MultiTopic_ptr
create_multitopic
(const char* name,
const char* type_name,
const char* subscription_expression,
const StringSeq& expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation creates a MultiTopic for a DomainParticipant in order to allow DataReaders to subscribe to a filtered/re-arranged combination and/or subset of the content of several topics.
# Parameters
in const char\* name - the name of the multi topic.
in const char\* type\_name - the name of the type of the MultiTopic. This type\_name must have been registered using register\_type prior to calling this operation.
in const char\* subscription\_expression - the SQL expression (subset of SQL), which defines the selection, filtering, combining and re-arranging of the sample data.
in const StringSeq& expression\_parameters - the handle to a sequence of strings with the parameter value used in the SQL expression (i.e., the number o f % n t o k e n s i n t h e e x p r e s s i o n ) . 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 subscription\_expression (e.g. if %1 and %8 are used as para m ete r in the s u b s cr i p t i o n \_e x p r e s si o n , t h e expression\_parameters should at least contain n+1 = 9 values).
# Return Value
MultiTopic\_ptr - is the pointer to the newly created MultiTopic. In case of an error, a NULL pointer is returned.
# Detailed Description
This operation creates a MultiTopic for a DomainParticipant in order to allow DataReaders to subscribe to a filtered/re-arranged combination and/or subset of the content of several topics. Before the MultiTopic can be created, the type\_name of the MultiTopic must have been registered prior to calling this operation. Registering is done, using the register\_type operation from 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 (subset of SQL) defined in subscription\_expression. The subscription\_expression may also contain parameters, which appear as %n t o k e n s i n t h e e x p r e s s i o n . T h e s e p a r a m e t e r s a r e d e f i n e d i n 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 Topics. It is an SQL expression where the SELECT clause provides the fields to be kept, the FROM part provides the names of the Topics that are searched for those fields, and the WHERE clause gives the content filter. The 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 DataReader, which is associated with a MultiTopic only accesses information which exist locally in the DataReader, based on the Topics used in the subscription\_expression. The actual MultiTopic will never be produced, only the individual Topics.
# 3.2.1.5 create\_publisher
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
Publisher_ptr
create_publisher
(const PublisherQos& qos,
```
PublisherListener\_ptr a\_listener, StatusMask mask);
# Description
This operation creates a Publisher with the desired QosPolicy settings and if applicable, attaches the optionally specified PublisherListener to it.
# Parameters
in const PublisherQos& qos - a collection of QosPolicy settings for the new Publisher. In case these settings are not self consistent, no Publisher is created.
in PublisherListener\_ptr a\_listener - a pointer to the PublisherListener instance which will be attached to the new Publisher. It is permitted to use NULL as the value of the listener: this behaves as a PublisherListener whose operations perform no action.
in StatusMask mask - a bit-mask in which each bit enables the invocation of the PublisherListener for a certain status.
# Return Value
Publisher\_ptr - Return value is a pointer to the newly created Publisher. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a Publisher with the desired QosPolicy settings and if applicable, attaches the optionally specified PublisherListener to it. When the PublisherListener is not applicable, the NULL pointer must be supplied instead. To d e l e t e t h e Pu b l i s h e r t h e o p e r a t i o n d el e t e \_ p u bl i s h e r or delete\_contained\_entities must be used.
In case the specified QosPolicy settings are not consistent, no Publisher is created and the NULL pointer is returned. The NULL pointer can also be returned when insufficient access rights exist for the partition(s) listed in the provided QoS structure.
# Default QoS
The constant PUBLISHER\_QOS\_DEFAULT can be used as parameter qos to create a Publisher with the default PublisherQos as set in the DomainParticipant. The effect of using PUBLISHER\_QOS\_DEFAULT is the same as calling the operation get\_default\_publisher\_qos and using the resulting PublisherQos to create the 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 communication status activated in the mask, the associated 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 PublisherListener:
• OFFERED\_DEADLINE\_MISSED\_STATUS (propagated)
• OFFERED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• LIVELINESS\_LOST\_STATUS (propagated)
• PUBLICATION\_MATCHED\_STATUS (propagated).
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.
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 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 which are applicable to the PublisherListener.
# 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 DataWriterListener of a contained DataWriter, the DataWriterListener on that contained DataWriter is invoked instead of the PublisherListener. This means that a status change on a contained DataWriter only invokes the PublisherListener if the contained 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 PublisherListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a P u b l i s h e r s p e c i f i c b e h a v i o u r w h e n n e e d e d . I n c a s e t h e 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 create\_subscriber
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
Subscriber_ptr
create_subscriber
(const SubscriberQos& qos,
SubscriberListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation creates a Subscriber with the desired QosPolicy settings and if applicable, attaches the optionally specified SubscriberListener to it.
# Parameters
in const SubscriberQos& qos - a collection of QosPolicy settings for the new Subscriber. In case these settings are not self consistent, no Subscriber is created.
i n SubscriberListener\_ptr a\_listener - a pointer to the SubscriberListener instance which will be attached to the new Subscriber. It is permitted to use NULL as the value of the listener: this behaves as a SubscriberListener whose operations perform no action.
in StatusMask mask - a bit-mask in which each bit enables the invocation of the SubscriberListener for a certain status.
# Return Value
Subscriber\_ptr - Return value is a pointer to the newly created Subscriber. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a Subscriber with the desired QosPolicy settings and if applicable, attaches the optionally specified SubscriberListener to it. When the SubscriberListener is not applicable, the NULL pointer must be supplied instead. To delete the Subscriber the operation delete\_subscriber or delete\_contained\_entities must be used.
In case the specified QosPolicy settings are not consistent, no Subscriber is created and the NULL pointer is returned. The NULL pointer can also be returned when insufficient access rights exist for the partition(s) listed in the provided QoS structure.
# Default QoS
The constant SUBSCRIBER\_QOS\_DEFAULT can be used as parameter qos to create a S u b s c r i be r w i th t h e d e f a u lt Su b s c r i b er Q o s a s s e t i n t h e Domainparticipant. The effect of using SUBSCRIBER\_QOS\_DEFAULT is the same as calling the operation get\_default\_subscriber\_qos and using the resulting SubscriberQos to create the 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 communication status activated in the mask, the associated 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 SubscriberListener:
```txt
- REQUESTED_DEADLINE_MISSED_STATUS (propagated)
- REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)
- SAMPLE_LOST_STATUS (propagated)
- SAMPLE_REJECTED_STATUS (propagated)
- DATA_AVAILABLE_STATUS (propagated)
- LIVELINESS_CHANGED_STATUS (propagated)
- SUBSCRIPTION_MATCHED_STATUS (propagated).
- DATA_ON_READERS_STATUS.
```
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.
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 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 which are applicable to the PublisherListener.
# 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 DataReaderListener of a contained DataReader, the DataReaderListener on that contained DataReader is invoked instead of the SubscriberListener. This means that a status change on a contained DataReader only invokes the SubscriberListener if the contained 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 SubscriberListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a S u b s c r i b e r s p e c i f i c b e h a v i o u r w h e n n e e d e d . I n c a s e t h e 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 DATA\_ON\_READERS\_STATUS and 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 D i s t r i b u t i o n S e r v i c e w i l l f i r s t l o o k i n a n a t t a c h e d a n d a c t i v a t e d SubscriberListener or DomainParticipantListener (in that order) for the DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener o r DomainParticipantListener for the DATA\_AVAILABLE\_STATUS (in that order).
# 3.2.1.7 create\_topic
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
Topic_ptr
create_topic
(const char* topic_name,
const char* type_name,
const TopicQos& qos,
TopicListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation creates a reference to a new or existing Topic under the given name, for a specific type, with the desired QosPolicy settings and if applicable, attaches the optionally specified TopicListener to it.
# Parameters
in const char\* topic\_name - the name of the Topic to be created. A new Topic will only be created, when no Topic, with the same name, is found within the DomainParticipant.
in const char\* type\_name - a local alias of the data type, which must have been registered before creating the Topic.
in const TopicQos& qos - a collection of QosPolicy settings for the new Topic. In case these settings are not self consistent, no Topic is created.
in TopicListener\_ptr a\_listener - a pointer to the TopicListener instance which will be attached to the new Topic. It is permitted to use NULL as the value of the listener: this behaves as a TopicListener whose operations perform no action.
in StatusMask mask - a bit-mask in which each bit enables the invocation of the TopicListener for a certain status.
# Return Value
Topic\_ptr - Return value is a pointer to the new or existing Topic. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a reference to a new or existing Topic under the given name, for a specific type, with the desired QosPolicy settings and if applicable, attaches the optionally specified TopicListener to it. When the TopicListener is not applicable, the NULL pointer must be supplied instead. In case the specified QosPolicy settings are not consistent, no Topic is created and the NULL pointer is r e t u r n e d . To d e l e t e t h e T o p i c t h e o p e r a t i o n d e l e t e \_ t o p i c o r delete\_contained\_entities must be used.
# Default QoS
The constant TOPIC\_QOS\_DEFAULT can be used as parameter qos to create a Topic with the default TopicQos as set in the DomainParticipant. The effect of using TOPIC\_QOS\_DEFAULT is the same as calling the operation get\_default\_topic\_qos and using the resulting TopicQos to create the Topic.
The Topic is bound to the type type\_name. Prior to creating the Topic, the type\_name must have been registered with the Data Distribution Service. Registering the type\_name is done using the data type specific register\_type operation.
# Existing Topic Name
B e f o r e c r e a t i n g a n e w T o p i c , t h i s o p e r a t i o n p e r f o r m s a lookup\_topicdescription for the specified topic\_name. When a Topic is found with the same name in the current domain, the QoS and type\_name of the found Topic are matched against the parameters qos and type\_name. When they are the same, no Topic is created but a new proxy of the existing Topic is returned. When they are not exactly the same, no Topic is created and the NULL pointer is returned.
When a Topic is obtained multiple times, it must also be deleted that same number of times using delete\_topic or calling delete\_contained\_entities once to delete all the proxies.
# Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. For each create, a new proxy is created. Therefore the Topic must be deleted the same number of times, as the Topic was created with the same topic\_name per Domain. In other words, each reference (local proxy) must be deleted separately.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated 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 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 TopicListener:
• INCONSISTENT\_TOPIC\_STATUS.
The following statuses are applicable to the ExtTopicListener:
• ALL\_DATA\_DISPOSED\_TOPIC\_STATUS
NOTE: The DDS::STATUS\_MASK\_ANY\_V1\_2 mask does not include the ALL\_DATA\_DISPOSED\_TOPIC\_STATUS bit, because this is an OpenSplice extension.
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 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 which are applicable to the PublisherListener.
# Status Propagation
In case a communication status is not activated in the mask of the TopicListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a Topic specific behaviour when needed. In case the 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.8 delete\_contained\_entities
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all the Entity objects that were created on the DomainParticipant.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes all the Entity objects that were created on the DomainParticipant. In other words, it deletes all Publisher, Subscriber, Topic, ContentFilteredTopic and MultiTopic objects. Prior to deleting each contained Entity, this operation regressively calls the corresponding delete\_contained\_entities operation on each Entity (if applicable). In other words, all Entity objects in the Publisher and Subscriber are deleted, including the DataWriter and DataReader. Also the QueryCondition and ReadCondition objects contained by the DataReader are deleted.
# Topic
Since a Topic is a global concept in the system, access is provided through a local proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. Such a proxy is created by the create\_topic or find\_topic operation. When a reference to the same Topic was created multiple times (either by create\_topic or find\_topic), all references (local proxies) are deleted. With the last proxy, the Topic itself is also removed from the system.
NOTE: The operation will return 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 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:
• RETCODE\_OK - the contained Entity objects are deleted and the application may delete the DomainParticipant.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.2.1.9 delete\_contentfilteredtopic
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_contentfilteredtopic
(ContentFilteredTopic_ptr a_contentfilteredtopic);
```
# Description
This operation deletes a ContentFilteredTopic.
# Parameters
in ContentFilteredTopic\_ptr a\_contentfilteredtopic - a reference to the ContentFilteredTopic, which is to be deleted.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a ContentFilteredTopic.
The deletion of a ContentFilteredTopic is not allowed if there are any existing DataReader objects that are using the ContentFilteredTopic. If the delete\_contentfilteredtopic operation is called on a ContentFilteredTopic with existing DataReader objects attached to it, it will return PRECONDITION\_NOT\_MET.
The delete\_contentfilteredtopic operation must be called on the same DomainParticipant object used to create the ContentFilteredTopic. If delete\_contentfilteredtopic is called on a different DomainParticipant the operation will have no effect and it will return PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the ContentFilteredTopic is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_contentfilteredtopic is not a valid ContentFilteredTopic\_ptr
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DomainParticipant, as used when the ContentFilteredTopic was created, or the ContentFilteredTopic is being used by one or more DataReader objects.
# 3.2.1.10 delete\_multitopic
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_multitopic
(MultiTopic_ptr a_multitopic);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation deletes a MultiTopic.
# Parameters
in MultiTopic\_ptr a\_multitopic - a pointer to the MultiTopic, which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation deletes a MultiTopic.
The deletion of a MultiTopic is not allowed if there are any existing DataReader objects that are using the MultiTopic. If the delete\_multitopic operation is called on a MultiTopic with existing DataReader objects attached to it, it will return RETCODE\_PRECONDITION\_NOT\_MET.
The de l e t e \_ m ul t i t o p ic o p e r a t i o n m u s t b e c a l l e d o n t h e s a m e D o ma i n P a r t ic i p a n t o b j e c t u s e d t o c re a t e t h e M u l t iT o p i c . If delete\_multitopic is called on a different DomainParticipant the operation will have no effect and it will return RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the MultiTopic is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_multitopic is not a valid MultiTopic\_ptr
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DomainParticipant, as used when the MultiTopic was created, or the MultiTopic is being used by one or more DataReader objects.
# 3.2.1.11 delete\_publisher
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_publisher
(Publisher_ptr p);
```
# Description
This operation deletes a Publisher.
# Parameters
in Publisher\_ptr p - a pointer to the Publisher, which is to be deleted.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a Publisher. A Publisher cannot be deleted when it has any attached DataWriter objects. When the operation is called on a Publisher w i t h DataWriter o b j e c t s , t h e o p e r a t i o n r e t u r n s RETCODE\_PRECONDITION\_NOT\_MET. When the operation is called on a different DomainParticipant, as used when the Publisher was created, the operation has no effect and returns RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the Publisher is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter p is not a valid Publisher\_ptr
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DomainParticipant, as used when the Publisher was created, or the Publisher contains one or more DataWriter objects.
# 3.2.1.12 delete\_subscriber
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_subscriber
(Subscriber_ptr s);
```
# Description
This operation deletes a Subscriber.
# Parameters
in Subscriber\_ptr s - a pointer to the Subscriber, which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation deletes a Subscriber. A Subscriber cannot be deleted when it has any attached DataReader objects. When the operation is called on a S u bs c r i b e r w i t h D a t a R ea d e r o b j e c t s , t h e o p e r a t i o n r e t u r n s RETCODE\_PRECONDITION\_NOT\_MET. When the operation is called on a different DomainParticipant, as used when the Subscriber was created, the operation has no effect and returns RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the Subscriber is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter s is not a valid Subscriber\_ptr
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DomainParticipant, as used when the Subscriber was created, or the Subscriber contains one or more DataReader objects.
# 3.2.1.13 delete\_topic
# Scope
DDS::DomainParticipant
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_topic
(Topic_ptr a_topic);
```
# Description
This operation deletes a Topic.
# Parameters
in Topic\_ptr a\_topic - a pointer to the Topic, which is to be deleted.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes a Topic. A Topic cannot be deleted when there are any DataReader, DataWriter, ContentFilteredTopic or MultiTopic objects, which are using the Topic. When the operation is called on a Topic referenced by any of these objects, the operation returns RETCODE\_PRECONDITION\_NOT\_MET. When the operation is called on a different DomainParticipant, as used when t h e T o p i c w a s c r e a t e d , 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 RETCODE\_PRECONDITION\_NOT\_MET.
# Local proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference is actually not a reference to a Topic but to the local proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. Such a proxy is created by the create\_topic or find\_topic operation. This operation will delete the local proxy. When a reference to the same Topic was created multiple times (either by create\_topic or find\_topic), each reference (local proxy) must be deleted separately. When this proxy is the last proxy for this Topic, the Topic itself is also removed from the system. As mentioned, a proxy may only be deleted when there are no other entities attached to it. However, it is possible to delete a proxy while there are entities attached to a different proxy.
# Return Code
When the operation returns:
• RETCODE\_OK - the Topic is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_topic is not a valid Topic\_ptr
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DomainParticipant, as used when the Topic was created, or the Topic is still referenced by other objects.
# 3.2.1.14 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.2.1.15 find\_topic
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
Topic_ptr
find_topic
(const char* topic_name,
const Duration_t& timeout);
```
# Description
This operation gives access to an existing (or ready to exist) enabled Topic, based on its topic\_name.
# Parameters
in const char\* topic\_name - the name of the Topic that the application wants access to.
in const Duration\_t& timeout - the maximum duration to block for the DomainParticipant\_find\_topic, after which the application thread is unblocked. The special constant DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
Topic\_ptr - Return value is a pointer to the Topic found.
# Detailed Description
This operation gives access to an existing Topic, based on its topic\_name. The operation takes as arguments the topic\_name of the Topic and a timeout.
If a Topic of the same topic\_name already exists, it gives access to this Topic. Otherwise it waits (blocks the caller) until another mechanism creates it. This other mechanism can be another thread, a configuration tool, or some other Data Distribution Service utility. If after the specified timeout the Topic can still not be found, the caller gets unblocked and the NULL pointer is returned.
A Topic obtained by means of find\_topic, must also be deleted by means of delete\_topic so that the local resources can be released. If a Topic is obtained multiple times it must also be deleted that same number of times using delete\_topic or calling delete\_contained\_entities once to delete all the proxies.
A T o p i c t h a t i s o b t a i n e d b y m e a n s o f f i n d \_ t o p i c i n a s p e c i f i c DomainParticipant can only be used to create DataReaders and DataWriters in that DomainParticipant if its corresponding TypeSupport has been registered to that same DomainParticipant.
# Local Proxy
Since a Topic is a global concept in the system, access is provided through a local proxy. In other words, the reference returned is actually not a reference to a Topic but to a locally created proxy. The Data Distribution Service propagates Topics and makes remotely created Topics locally available through this proxy. For each time this operation is called, a new proxy is created. Therefore the Topic must be deleted the same number of times, as the Topic was created with the same topic\_name per Domain. In other words, each reference (local proxy) must be deleted separately.
# 3.2.1.16 get\_builtin\_subscriber
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
Subscriber_ptr
get_builtin_subscriber
(void);
```
# Description
This operation returns the built-in Subscriber associated with the DomainParticipant.
# Parameters
<none>
# Return Value
Subscriber\_ptr - Result value is a pointer to the built-in Subscriber associated with the DomainParticipant.
# Detailed Description
This operation returns the built-in Subscriber associated with the DomainParticipant. Each DomainParticipant contains several built-in Topic objects. The built-in Subscriber contains the corresponding DataReader objects to access them. All these DataReader objects belong to a single built-in Subscriber. Note that there is exactly one built-in Subscriber associated with each DomainParticipant.
# 3.2.1.17 get\_current\_time
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_current_time
(Time_t& current_time);
```
# Description
This operation returns the value of the current time that the Data Distribution Service uses to time-stamp written data as well as received data in current\_time.
# Parameters
inout Time\_t& current\_time - the value of the current time as used by the Data Distribution System. The input value of current\_time is ignored.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation returns the value of the current time that the Data Distribution Service uses to time-stamp written data as well as received data in current\_time. The input value of current\_time is ignored by the operation.
# Return Code
When the operation returns:
• RETCODE\_OK - the value of the current time is returned in current\_time.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter current\_time is not a valid reference.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.18 get\_default\_publisher\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_publisher_qos
(PublisherQos& qos);
```
# Description
This operation gets the struct with the default Publisher QosPolicy settings of the DomainParticipant.
# Parameters
inout PublisherQos& qos - a reference to the PublisherQos struct (provided by the application) in which the default QosPolicy settings for the Publisher are written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation gets the struct with the default Publisher QosPolicy settings of the DomainParticipant (that is the PublisherQos) which is used for newly created Publisher objects, in case the constant PUBLISHER\_QOS\_DEFAULT is used. The default PublisherQos is only used when the constant is supplied as parameter qos to specify the PublisherQos in the create\_publisher operation. The application must provide the PublisherQos struct in which the QosPolicy settings can be stored and pass the qos reference to the operation. The operation writes the default QosPolicy settings to the struct referenced 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 set\_default\_publisher\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 2 on page 38
# Return Code
When the operation returns:
• RETCODE\_OK - the default Publisher QosPolicy settings of this DomainParticipant have successfully been copied into the specified PublisherQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.19 get\_default\_subscriber\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_subscriber_qos
(SubscriberQos& qos);
```
# Description
This operation gets the struct with the default Subscriber QosPolicy settings of the DomainParticipant.
# Parameters
inout SubscriberQos& qos - a reference to the QosPolicy struct (provided by the application) in which the default QosPolicy settings for the Subscriber is written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation gets the struct with the default Subscriber QosPolicy settings of the DomainParticipant (that is the SubscriberQos) which is used for newly created Subscriber objects, in case the constant SUBSCRIBER\_QOS\_DEFAULT is used. The default SubscriberQos is only used when the constant is supplied as parameter qos to specify the SubscriberQos in the create\_subscriber operation. The application must provide the QoS struct in which the policy can be stored and pass the qos reference to the operation. The operation writes the default QosPolicy to the struct referenced 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 set\_default\_subscriber\_qos, or, if the call was never made, the default values as specified for each QosPolicy defined in Table 2 on page 38
# Return Code
When the operation returns:
• RETCODE\_OK - the default Subscriber QosPolicy settings of this DomainParticipant have successfully been copied into the specified SubscriberQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.20 get\_default\_topic\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_topic_qos
(TopicQos& qos);
```
# Description
This operation gets the struct with the default Topic QosPolicy settings of the DomainParticipant.
# Parameters
inout TopicQos& qos - a reference to the QosPolicy struct (provided by the application) in which the default QosPolicy settings for the Topic is written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation gets the struct with the default Topic QosPolicy settings of the DomainParticipant (that is the TopicQos) which is used for newly created Topic objects, in case the constant TOPIC\_QOS\_DEFAULT is used. The default TopicQos is only used when the constant is supplied as parameter qos to specify the TopicQos in the create\_topic operation. The application must provide the QoS struct in which the policy can be stored and pass the qos reference to the operation. The operation writes the default QosPolicy to the struct referenced 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 set\_default\_topic\_qos, or, if the call was never made, the default values as specified for each QosPolicy defined in Table 2 on page 38
# Return Code
When the operation returns:
• RETCODE\_OK - the default Topic QosPolicy settings of this DomainParticipant have successfully been copied into the specified TopicQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.21 get\_discovered\_participants
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dcps.h>
ReturnCode_t
get_discovered_participants
(InstanceHandleSeq& participant_handles);
```
# Description
This operation retrieves the list of DomainParticipants that have been discovered in the domain.
# Parameters
inout InstanceHandleSeqHolder participant\_handles - a sequence which is used to pass the list of all associated participants.
# Return Value
int - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ILLEGAL\_OPERATION, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves the list of DomainParticipants that have been discovered in the domain and that the application has not indicated should be “ignored” by means of the DomainParticipant ignore\_participant operation.
The participant\_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 get\_discovered\_participants operation or be released by calling free on the returned participant\_handles. If the pre-allocated sequence is not big enough to hold the number of associated participants, the sequence will automatically be (re-)allocated to fit the required size. The handles returned in the participant\_handles sequence are the ones that are used by the DDS implementation to locally identify the corresponding matched Participant entities. You can access more detailed information about a particular participant by p a s s i n g i t s participant\_handle t o t h e get\_discovered\_participant\_data operation.
# Return Code
When the operation returns:
• RETCODE\_OK - the list of associated participants has been successfully obtained.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” participants.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.22 get\_discovered\_participant\_data
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dcps.h>
ReturnCode_t
get_discovered_participant_data
(ParticipantBuiltinTopicData& participant_data,
InstanceHandle_t participant_handle);
```
# Description
This operation retrieves information on a DomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been “ignored” by means of the DomainParticipant ignore\_participant operation.
# Parameters
in DomainParticipant \_this - the DomainParticipant object on which the operation is operated.
inout ParticipantBuiltinTopicData \*participant\_data - a pointer to the sample in which the information about the specified partition is to be stored.
in const InstanceHandle\_t participant\_handle - a handle to the participant whose information needs to be retrieved.
# Return Value
int - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ILLEGAL\_OPERATION, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves information on a DomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been “ignored” by means of the DomainParticipant ignore\_participant operation.
The partition\_handle must correspond to a partition currently associated with the DomainParticipant, otherwise the operation will fail and return RETCODE\_ERROR. The operation get\_discovered\_participant\_data can be used to find more detailed information about a particular participant that is found with the get\_discovered\_participants operation.
# Return Code
When the operation returns:
• RETCODE\_OK - the information on the specified partition has been successfully retrieved.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” partition.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.23 get\_discovered\_topics
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dcps.h>
ReturnCode_t
get_discovered_topics
(InstanceHandleSeq& topic_handles);
```
# Description
This operation retrieves the list of Topics that have been discovered in the domain.
# Parameters
inout InstanceHandleSeq \*topic\_handles - a sequence which is used to pass the list of all associated topics.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ILLEGAL_OPERATION, RETCODE_UNSUPPORTED, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, or RETCODE_NOT_ENABLED.
```
# Detailed Description
This operation retrieves the list of Topics that have been discovered in the domain and that the application has not indicated should be “ignored” by means of the DomainParticipant ignore\_topic operation.
The topic\_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 get\_discovered\_topics operation or be released by calling free on the returned topic\_handles. If the pre-allocated sequence is not big enough to hold the number of associated participants, the sequence will automatically be (re-)allocated to fit the required size. The handles returned in the topic\_handles sequence are the ones that are used by the DDS implementation to locally identify the corresponding matched Topic entities. You can access more detailed information a b o u t a p a r t i c u l a r t o p i c b y p a s s i n g i t s t o p i c \_ h a n d l e t o t h e get\_discovered\_topic\_data operation.
# Return Code
When the operation returns:
• RETCODE\_OK - the list of associated topics has been successfully obtained.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” topics.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.24 get\_discovered\_topic\_data
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dcps.h>
ReturnCode_t
get_discovered_topic_data
(TopicBuiltinTopicData& topic_data,
InstanceHandle_t handle);
```
# Description
This operation retrieves information on a Topic that has been discovered on the network. The topic must have been created by a participant in the same domain as the participant on which this operation is invoked and must not have been “ignored” by means of the DomainParticipant ignore\_topic operation.
# Parameters
inout TopicBuiltinTopicData \*topic\_data - a pointer to the sample in which the information about the specified topic is to be stored.
in const InstanceHandle\_t topic\_handle - a handle to the topic whose information needs to be retrieved.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ILLEGAL_OPERATION, RETCODE_UNSUPPORTED, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, or RETCODE_NOT_ENABLED.
```
# Detailed Description
This operation retrieves information on a Topic that has been discovered on the network. The topic must have been created by a participant in the same domain as the participant on which this operation is invoked and must not have been “ignored” by means of the DomainParticipant ignore\_topic operation.
The topic\_handle must correspond to a topic currently associated with the Dom ainPa rtici pant , otherwise the operation will fail and return RETCODE\_ERROR. The operation get\_discovered\_topic\_data can be used to find more detailed information about a particular topic that is found with the get\_discovered\_topics operation.
# Return Code
When the operation returns:
• RETCODE\_OK - the information on the specified topic has successfully been retrieved.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ILLEGAL\_OPERATION - the operation is invoked on an inappropriate object.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” topics.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DomainParticipant is not enabled.
# 3.2.1.25 get\_domain\_id
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
DomainId_t
get_domain_id
(void);
```
# 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 o m a i n I d o f t h e D o m a i n to wh i ch t hi s DomainParticipant is attached.
# Parameters
<none>
# Return Value
DomainId\_t - result is the DomainId.
# Detailed Description
Th i s o p e ra t io n re t u rn s t h e D o m a i n I d o f t h e D o m a i n t o w h i c h t h i s DomainParticipant is attached. See also section 3.2.2.1, create\_participant, on page 185).
# 3.2.1.26 get\_listener
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DomainParticipantListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a DomainParticipantListener.
# Parameters
```txt
<none>
```
# Return Value
D o ma i n P a r t ic i p a n t Li s t e n e r \_p t r - r e s u lt i s a p o i n t e r t o t h e DomainParticipantListener attached to the DomainParticipant.
# Detailed Description
This operation allows access to a DomainParticipantListener attached to the DomainParticipant. When no DomainParticipantListener was attached to the DomainParticipant, the NULL pointer is returned.
# 3.2.1.27 get\_property
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_property
(Property& a_property);
```
# Description
This function queries the value of a property set on a DomainParticipant.
# Parameters
inout 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 DomainParticipant.
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_BAD\_PARAMETER, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_UNSUPPORTED.
# Detailed Description
This operation looks up the property specified by a\_property.name in the 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.
# Return Code
When the operation returns:
• RETCODE\_OK - a\_property.value has been set to the current value of the property.
• RETCODE\_BAD\_PARAMETER - an invalid value has been specified.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_UNSUPPORTED a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.2.1.28 get\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DomainParticipantQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DomainParticipant.
# Parameters
inout DomainParticipantQos& qos - a reference to the destination DomainParticipantQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a D o ma i n P a r t ic i p a n t o n w h i c h t h is o p e r a ti o n i s u s e d . T h i s DomainparticipantQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this DomainParticipant has successfully been copied into the specified DomainParticipantQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.29 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.2.1.30 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition
get_statuscondition_ptr
(void);
```
# 3.2.1.31 ignore\_participant
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
ignore_participant
(InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.2.1.32 ignore\_publication
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
ignore_publication
(InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.2.1.33 ignore\_subscription
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
ignore_subscription
(InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.2.1.34 ignore\_topic
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
ignore_topic
(InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.2.1.35 lookup\_topicdescription
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
TopicDescription_ptr
lookup_topicdescription
(const char* name);
```
# Description
This operation gives access to a locally-created TopicDescription, with a matching name.
# Parameters
in const char\* name - the name of the TopicDescription to look for.
# Return Value
TopicDescription\_ptr - Return value is a pointer to the TopicDescription found. When no such TopicDescription is found, the NULL pointer is returned.
# Detailed Description
The operation lookup\_topicdescription gives access to a locally-created TopicDescription, based on its name. The operation takes as argument the name of the TopicDescription.
If one or more local TopicDescription proxies (see also section 3.2.1.15) of the same name already exist, a pointer to one of the already existing local proxies is returned: lookup\_topicdescription will never create a new local proxy. That means that the proxy that is returned does not need to be deleted separately from its original. When no local proxy exists, it returns the NULL pointer. The operation never blocks.
The operation lookup\_topicdescription may be used to locate any locally-created Topic, ContentFilteredTopic and MultiTopic object.
# 3.2.1.36 set\_default\_publisher\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_default_publisher_qos
(const PublisherQos& qos);
```
# Description
This operation sets the default PublisherQos of the DomainParticipant.
# Parameters
in const PublisherQos& qos - a collection of QosPolicy settings, which contains the new default QosPolicy settings for the newly created Publishers.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation sets the default PublisherQos of the DomainParticipant (that is the struct with the QosPolicy settings) which is used for newly created Publisher objects, in case the constant PUBLISHER\_QOS\_DEFAULT is used. The default PublisherQos is only used when the constant is supplied as parameter qos to specify the PublisherQos in the create\_publisher operation. The PublisherQos is always self consistent, because its policies do not depend on e a c h o t h e r. T h i s m e a n s t h a t t h i s o p e r a t i o n n e v e r r e t u r n s t h e RETCODE\_INCONSISTENT\_POLICY. The values set by this operation are returned by get\_default\_publisher\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default PublisherQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid PublisherQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.37 set\_default\_subscriber\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_default_subscriber_qos
(const SubscriberQos& qos);
```
# Description
This operation sets the default SubscriberQos of the DomainParticipant.
# Parameters
in const SubscriberQos& qos - a collection of QosPolicy settings, which contains the new default QosPolicy settings for the newly created Subscribers.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation sets the default SubscriberQos of the DomainParticipant (that is the struct with the QosPolicy settings) which is used for newly created Subscriber objects, in case the constant SUBSCRIBER\_QOS\_DEFAULT is used. The default SubscriberQos is only used when the constant is supplied as parameter qos to specify the SubscriberQos in the create\_subscriber operation. The SubscriberQos is always self consistent, because its policies do not depend on each other. This means that this operation never returns the RETCODE\_INCONSISTENT\_POLICY. The values set by this operation are returned by get\_default\_subscriber\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default SubscriberQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid PublisherQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.38 set\_default\_topic\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_default_topic_qos
(const TopicQos& qos);
```
# Description
This operation sets the default TopicQos of the DomainParticipant.
# Parameters
in const TopicQos& qos - a collection of QosPolicy settings, which contains the new default QosPolicy settings for the newly created Topics.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation sets the default TopicQos of the DomainParticipant (that is the struct with the QosPolicy settings) which is used for newly created Topic objects, in case the constant TOPIC\_QOS\_DEFAULT is used. The default TopicQos is only used when the constant is supplied as parameter qos to specify the TopicQos in the create\_topic operation. This operation checks if the TopicQos is self c o n s i s t e n t . I f i t i s n o t , t h e o p e r a t i o n h a s n o e f f e c t a n d r e t u r n s RETCODE\_INCONSISTENT\_POLICY. The values set by this operation are returned by get\_default\_topic\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default TopicQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid TopicQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.2.1.39 set\_listener
# Scope
```cpp
DDS::DomainParticipant
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_listener
(DomainParticipantListener_ptr a_listener, StatusMask mask);
```
# Description
This operation attaches a D o ma i nP a rt i ci p an tL i st e ne r to th e DomainParticipant.
# Parameters
```txt
in DomainParticipantListener_ptr a_listener - a pointer to the DomainParticipantListener instance, which will be attached to the DomainParticipant.
in StatusMask mask - a bit mask in which each bit enables the invocation of the DomainParticipantListener for a certain status.
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_UNSUPPORTED, RETCODE_ALREADY_DELETED or RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation attaches a D o ma i nP a rt i ci p an tL i st e ne r to th e DomainParticipant. Only one DomainParticipantListener can be attached to each DomainParticipant. If a DomainParticipantListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# 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
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 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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DomainParticipantListener:
- INCONSISTENT_TOPIC_STATUS (propagated)
- OFFERED_DEADLINE_MISSED_STATUS (propagated)
- REQUESTED_DEADLINE_MISSED_STATUS (propagated)
- OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)
- REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)
- SAMPLE_LOST_STATUS (propagated)
- SAMPLE_REJECTED_STATUS (propagated)
- DATA_ON_READERS_STATUS (propagated)
- DATA_AVAILABLE_STATUS (propagated)
- LIVELINESS_LOST_STATUS (propagated)
- LIVELINESS_CHANGED_STATUS (propagated)
- PUBLICATION_MATCHED_STATUS (propagated)
- SUBSCRIPTION_MATCHED_STATUS (propagated)
Be aware that the PUBLICATION\_MATCHED\_STATUS and 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return 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 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 which are applicable to the PublisherListener.
# 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 DomainParticipantListener. This means that a status change on a contained entity only invokes the DomainParticipantListener if the contained entity itself does not handle the trigger event generated by the status change.
The statuses DATA\_ON\_READERS\_STATUS and 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 D i s t r i b u t i o n S e r v i c e w i l l f i r s t l o o k i n a n a t t a c h e d a n d a c t i v a t e d SubscriberListener or DomainParticipantListener (in that order) for the DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener or DomainParticipant Listener for the DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• RETCODE\_OK - the DomainParticipantListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.40 set\_property
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_property
(const Property& a_property);
```
# Description
This function sets a property on a DomainParticipant.
# Parameters
in Property a\_property - on specifies the property (in a\_property.name) and its new value (in a\_property.value).
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_BAD\_PARAMETER, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or 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:
• RETCODE\_OK - the property has been set.
• RETCODE\_BAD\_PARAMETER - an invalid value has been specified.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_UNSUPPORTED a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.2.1.41 set\_qos
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_qos
(const DomainParticipantQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DomainParticipant.
# Parameters
in const DomainParticipantQos& qos - new set of QosPolicy settings for the DomainParticipant.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a DomainParticipant. The parameter qos contains 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new DomainParticipantQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DomainParticipant has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.1.42 delete\_historical\_data
# Scope
DDS::DomainParticipant
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_historical_data
(const string partition_expression,
const string topic_expression);
```
# Description
This operation deletes all historical TRANSIENT and PERSISTENT data that is storedby the durability service that is configured to support this DomainParticipant.
# Parameters
in const string partition\_expression - An expression to define a filter on partitions.
in const string topic\_expression - An expression to define a filter on topic names.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, 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:
• RETCODE\_OK - all data matching the topic and partition expressions has been deleted.
• RETCODE\_ERROR - an internal error has occurred.
# 3.2.2 Class DomainParticipantFactory
The purpose of this cl ass is to allow the creation and destruction of DomainParticipant objects. DomainParticipantFactory itself has no factory. It is a pre-existing singleton object that can be accessed by means of the get\_instance operation on the DomainParticipantFactory class.
The pre-defined value TheParticipantFactory can also be used as an alias for the singleton factory returned by the operation get\_instance.
The interface description of this class is as follows:
```cpp
class DomainParticipantFactory
{
//
// implemented API operations
//
static DomainParticipantFactory_ptr
get_instance
(void);
DomainParticipant_ptr
create_participant
(DomainId_t domainId,
const DomainParticipantQos& qos,
DomainParticipantListener_ptr a_listener,
```
```txt
StatusMask mask);
ReturnCode_t
delete_participant
(DomainParticipant_ptr a_participant);
DomainParticipant_ptr
lookup_participant
(DomainId_t domainId);
ReturnCode_t
set_default_participant_qos
(const DomainParticipantQos& qos);
ReturnCode_t
get_default_participant_qos
(DomainParticipantQos& qos);
ReturnCode_t
set_qos
(const DomainParticipantFactoryQos& qos);
ReturnCode_t
get_qos
(DomainParticipantFactoryQos& qos);
ReturnCode_t
delete_domain
(Domain_ptr a_domain);
Domain
lookup_domain
(const DomainId_t domainId);
ReturnCode_t
delete_contained_entities
(void);
ReturnCode_t
detach_all_domains
(Boolean block_operations,
Boolean delete_entities);
};
```
The next paragraphs describe the usage of all DomainParticipantFactory operations.
# 3.2.2.1 create\_participant
# Scope
DDS::DomainParticipantFactory
# Synopsis
```txt
#include <cpp_dds_dcps.h>
DomainParticipant_ptr
create_participant
(DomainId_t domainId,
const DomainParticipantQos& qos,
DomainParticipantListener_ptr a_listener,
```
StatusMask mask);
# Description
This operation creates a new DomainParticipant which will join the domain identified by domainId, with the desired DomainParticipantQos and attaches the optionally specified DomainParticipantListener to it.
# Parameters
in const DomainId\_t domainId - the ID of the Domain to which the 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 DomainParticipantQos& qos - a DomainParticipantQos for the new DomainParticipant. When this set of QosPolicy settings is inconsistent, no DomainParticipant is created.
in DomainParticipantListener\_ptr a\_listener - a pointer to the DomainParticipantListener instance which will be attached to the new DomainParticipant. It is permitted to use NULL as the value of the listener: this behaves as a DomainParticipantListener whose operations perform no action.
in StatusMask mask - a bit-mask in which each bit enables the invocation of the DomainParticipantListener for a certain status.
# Return Value
D o ma i n P a r ti c i p a n t \_p t r - a p o i n t e r t o t h e n e w l y c r e a t e d DomainParticipant. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a new DomainParticipant, with the desired D o ma i n P a r ti c i p a n t Qo s a n d a tt a c h e s t h e o p t i o n a l l y s p e c i fi e d DomainParticipantListener to it. The 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 DomainParticipant is created and the operation returns the NULL pointer. To delete the DomainParticipant the operation delete\_participant must be used.
# Identifying the Domain
The DomainParticipant will attach to the Domain that is specified by the domainId parameter. This parameter consists of an 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 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 PARTICIPANT\_QOS\_DEFAULT can be used as parameter qos to create a DomainParticipant with the default DomainParticipantQos as set in the DomainParticipantfactory. T h e e f f e c t o f u s i n g PARTICIPANT\_QOS\_DEFAULT is the same as calling the operation get\_default\_participant\_qos and using the resulting DomainParticipantQos to create the 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 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 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 DomainParticipantListener:
```txt
- INCONSISTENT_TOPIC_STATUS (propagated)
- OFFERED_DEADLINE_MISSED_STATUS (propagated)
- REQUESTED_DEADLINE_MISSED_STATUS (propagated)
- OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)
- REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)
- SAMPLE_LOST_STATUS (propagated)
- SAMPLE_REJECTED_STATUS (propagated)
```
```prolog
- DATA_ON_READERS_STATUS (propagated)
- DATA_AVAILABLE_STATUS (propagated)
- LIVELINESS_LOST_STATUS (propagated)
- LIVELINESS_CHANGED_STATUS (propagated)
- PUBLICATION_MATCHED_STATUS (propagated)
- SUBSCRIPTION_MATCHED_STATUS (propagated).
```
Be aware that the PUBLICATION\_MATCHED\_STATUS and 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.
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 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 which are applicable to the PublisherListener.
# 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 DomainParticipantListener. This means that a status change on a contained entity only invokes the DomainParticipantListener if the contained entity itself does not handle the trigger event generated by the status change.
The statuses DATA\_ON\_READERS\_STATUS and 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 D i s t r i b u t i o n S e r v i c e w i l l f i r s t l o o k i n a n a t t a c h e d a n d a c t i v a t e d SubscriberListener or DomainParticipantListener (in that order) for the DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener or DomainParticipant Listener for the DATA\_AVAILABLE\_STATUS (in that order).
# 3.2.2.2 delete\_participant
# Scope
```txt
DDS::DomainParticipantFactory
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_participant
(DomainParticipant_ptr a_participant);
```
# Description
This operation deletes a DomainParticipant.
# Parameters
in DomainParticipant\_ptr a\_participant - a pointer to the DomainParticipant, which is to be deleted.
# Return Value
ReturnCode\_t - return codes can be RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_ PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes a DomainParticipant. A DomainParticipant cannot be deleted when it has any attached Entity objects. When the operation is called on a DomainParticipant with existing Entity objects, the operation returns RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the DomainParticipant is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_participant is not a valid DomainParticipant\_ptr
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the DomainParticipant contains one or more Entity objects.
# 3.2.2.3 get\_default\_participant\_qos
# Scope
DDS::DomainParticipantFactory
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_participant_qos
(DomainParticipantQos& qos);
```
# Description
T h i s o p e r a ti o n g e t s t h e d e f a u l t D o m a i nP a r t i c i pa n t Q o s o f t h e DomainParticipantFactory.
# Parameters
inout DomainParticipantQos& qos - a reference to the DomainParticipantQos struct (provided by the application) in which the default DomainParticipantQos for the DomainParticipant is written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
T h i s o p e r a ti o n g e t s t h e d e f a u l t D o m a i nP a r t i c i pa n t Q o s o f t h e DomainParticipantFactory (that is the struct with the QosPolicy settings) which is used for newly created DomainParticipant objects, in case the constant PARTICIPANT\_QOS\_DEFAULT is used. The default DomainParticipantQos is only used when the constant is supplied as parameter qos to specify the DomainParticipantQos in the create\_participant operation. The application must provide the DomainParticipantQos struct in which the QosPolicy settings can be stored and provide a reference to the struct. The operation writes the default QosPolicy settings to the struct referenced 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 set\_default\_participant\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 2 on page 38
# Return Code
When the operation returns:
• RETCODE\_OK - the default DomainParticipant QosPolicy settings of this DomainParticipantFactory have successfully been copied into the specified DomainParticipantQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.4 get\_instance
# Scope
DDS::DomainParticipantFactory
# Synopsis
```c
#include <ccpp_dds_dcps.h>
static DomainParticipantFactory_ptr
get_instance
(void);
```
# Description
This operation returns the DomainParticipantFactory singleton.
# Parameters
<none>
# Return Value
DomainParticipantFactory\_ptr - a pointer to the DomainParticipantFactory.
# Detailed Description
This operation returns the DomainParticipantFactory singleton. The operation is idempotent, that is, it can be called multiple times without side-effects and it returns the same DomainParticipantFactory instance.
T h e o p e r a t i o n i s s t a t i c a n d m u s t b e c a l l e d u p o n i t s c l a s s (DomainParticipantFactory::get\_instance).
The pre-defined value TheParticipantFactory can also be used as an alias for the singleton factory returned by the operation get\_instance.
# 3.2.2.5 get\_qos
# Scope
DDS::DomainParticipantFactory
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DomainParticipantFactoryQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DomainParticipantFactory.
# Parameters
inout DomainParticipantFactoryQos& qos - a reference to the destination DomainparticipantFactoryQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DomainParticipantFactory on which this operation is used. This DomainparticipantFactoryQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this DomainParticipantFactory has successfully been copied into the specified DomainParticipantFactoryQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.6 lookup\_participant
# Scope
```txt
DDS::DomainParticipantFactory
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DomainParticipant_ptr
```
```txt
lookup_participant
(DomainId_t domainId);
```
# Description
This operation retrieves a previously created DomainParticipant belonging to the specified domainId.
# Parameters
in const DomainId\_t domainId - the ID of the Domain for which a joining DomainParticipant should be retrieved. This should be the ID as specified in the configuration file.
# Return Value
D o ma i n P a r t ic i p a n t \_p t r - R e tu r n v a l u e i s a p o in t e r t o t h e DomainParticipant retrieved. When no such DomainParticipant is found, the NULL pointer is returned.
# Detailed Description
This operation retrieves a previously created DomainParticipant belonging to the specified domainId. If no such DomainParticipant exists, the operation will return NULL.
The domainId used to search for a specific 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 DomainParticipant.
If multiple DomainParticipant entities belonging to the specified domainId exist, then the operation will return one of them. It is not specified which one. See also section 3.2.2.1, create\_participant, on page 185.
# 3.2.2.7 set\_default\_participant\_qos
# Scope
```txt
DDS::DomainParticipantFactory
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_default_participant_qos
(const DomainParticipantQos& qos);
```
# Description
T h i s o p e r a ti o n s e ts t h e d e f a u l t D o m a i n P ar t i c i p an t Q o s o f t h e DomainParticipantFactory.
# Parameters
in const DomainParticipantQos& qos - the DomainParticipantQos struct, which contains the new default DomainParticipantQos for the newly created DomainParticipants.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
T h i s o p e r a t i o n s e ts t h e d e f a u l t D o m a i n P ar t i c i p an t Q o s o f t h e DomainParticipantFactory (that is the struct with the QosPolicy settings) which is used for newly created DomainParticipant objects, in case the constant PARTICIPANT\_QOS\_DEFAULT is used. The default DomainParticipantQos is only used when the constant is supplied as parameter qos to specify the DomainParticipantQos in the create\_participant operation. The DomainParticipantQos is always self consistent, because its policies do not d e p e n d o n e a c h o t h e r. T h i s m e a n s t hi s o p e r a t i o n n e v e r r e t ur n s t h e 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 get\_default\_participant\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default DomainParticipantQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.8 set\_qos
# Scope
DDS::DomainParticipantFactory
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const DomainParticipantFactoryQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DomainParticipantFactory.
# Parameters
in const DomainParticipantFactoryQos& qos - must contain the new set of QosPolicy settings for the DomainParticipantFactory.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new DomainParticipantFactoryQos is set.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.9 delete\_domain
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_domain
(Domain_ptr a_domain);
```
# Description
This operation deletes a Domain proxy.
# Parameters
in Domain\_ptr a\_domain - a pointer to the Domain proxy, which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation deletes a Domain proxy.
# Return Code
When the operation returns:
• RETCODE\_OK - the Domain proxy is deleted.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_domain is not a valid Domain proxy.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.2.10 lookup\_domain
# Synopsis
```c
#include <ccpp_dds_dcps.h>
Domain_ptr
lookup_domain
(const DomainId_t domainId);
```
# Description
This operation retrieves a previously created Domain proxy belonging to the specified domainId or creates a new Domain proxy if no Domain proxy yet exists but the Domain itself is available.
# Parameters
in const DomainId\_t domainId - the ID of the Domain for which a Domain proxy should be retrieved. This should be the ID as specified in the configuration file.
# Return Value
Domain\_ptr - Return value is a pointer to the Domain proxy retrieved. When no such Domain proxy is found or could be created, the NULL pointer is returned.
# Detailed Description
This operation retrieves a previously created Domain proxy belonging to the specified domainId or creates a new Domain proxy if no Domain proxy was found, but the DomainId does refer to a valid Domain. If no such Domain exists or could be created, the operation will return NULL. See also section 3.2.2.1, create\_participant, on page 185.
# 3.2.2.11 delete\_contained\_entities
# Scope
DDS::DomainParticipantFactory
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all of the Entity objects that were created on the DomainParticipantFactory.
# Parameters
<none>
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_ERROR, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes all of the Entity objects that were created on the DomainParticipantFactory (it deletes all contained DomainParticipant objects). Prior to deleting each contained Entity, this operation regressively calls the corresponding delete\_contained\_entities operation on each Participant. In other words, this operation cleans up all Entity objects in the process.
NOTE: The operation will return 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 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:
• RETCODE\_OK - all of the contained Entity objects are deleted.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.2.2.12 detach\_all\_domains
# Scope
DDS::DomainParticipantFactory
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
detach_all_domains(
Boolean block_operations, Boolean delete_entities);
```
# Description
This operation will safely detach the application from all domains it is currently participating in.
# Parameters
```txt
in Boolean block_operations –
Indicates whether the application wants any operations that are called while detaching to be blocked or not.
in Boolean delete_entities –
Indicates whether the application DDS entities in the ‘connected’ domains must be deleted synchronously during detaching.
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are:
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 that 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 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:
• RETCODE\_OK – the application is detached from all domains.
# 3.2.3 Class 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 Publishers and the 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 Domain
*/
class Domain {
ReturnCode_t
create_persistent_snapshot(
const char* partition_expression,
const char* topic_expression,
const char* URI);
};
```
The following sections describe the usage of all Domain operations.
# 3.2.3.1 create\_persistent\_snapshot
# Synopsis
```txt
#include <ccpp_dds_dcps.h>
ReturnCode_t
create_persistent_snapshot(
const char* partition_expression,
const char* topic_expression,
const 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 char\* partition\_expression - The expression of all partitions involved in the snapshot; this may contain wildcards.
in char\* topic\_expression - The expression of all topics involved in the snapshot; this may contain wildcards.
in char\* uri - The location where to store the snapshot. Currently only directories are supported.
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
```txt
RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED or 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:
• RETCODE\_OK – The persistent snapshot is (being) created.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter partition\_expression, topic\_expression or uri is NULL.
• RETCODE\_ALREADY\_DELETED - the Domain proxy has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.2.4 DomainParticipantListener interface
Since a DomainParticipant is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DomainParticipantListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DomainParticipantListener class. All 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 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 deadline, violation of a QosPolicy setting, etc. The DomainParticipantListener is related to changes in communication status StatusConditions.
The interface description of this class is as follows:
```cpp
class DomainParticipantListener
{
//
// inherited from TopicListener
//
// void
// on_inconsistent_topic
// (Topic_ptr the_topic,
// const InconsistentTopicStatus& status) = 0;
//
// inherited from PublisherListener
//
// void
// on_offered_deadline_missed
// (DataWriter_ptr writer,
// const OfferedDeadlineMissedStatus& status) = 0;
//
// void
// on_offered_incompatible_qos
// (DataWriter_ptr writer,
// const OfferedIncompatibleQosStatus& status) = 0;
//
// void
// on_liveliness_lost
// (DataWriter_ptr writer,
// const LivelinessLostStatus& status) = 0;
```
```c
// void
// on_publication_matched
// (DataWriter_ptr writer,
// const PublicationMatchedStatus& status) = 0;
//
// inherited from SubscriberListener
//
// void
// on_data_on_readers
// (Subscriber_ptr subs) = 0;
// void
// on_requested_deadline_missed
// (DataReader_ptr reader,
// const RequestedDeadlineMissedStatus& status) = 0;
// void
// on_requested_incompatible_qos
// (DataReader_ptr reader,
// const RequestedIncompatibleQosStatus& status) = 0;
// void
// on_sample_rejected
// (DataReader_ptr reader,
// const SampleRejectedStatus& status) = 0;
// void
// on_liveliness_changed
// (DataReader_ptr reader,
// const LivelinessChangedStatus& status) = 0;
// void
// on_data_available
// (DataReader_ptr reader) = 0;
// void
// on_subscription_matched
// (DataReader_ptr reader,
// const SubscriptionMatchedStatus& status) = 0;
// void
// on_sample_lost
// (DataReader_ptr reader,
// const SampleLostStatus& status) = 0;
//
// implemented API operations
// <no operations>
//
};
```
The next paragraphs list all 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 on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_data_available
(DataReader_ptr reader) = 0;
```
# 3.2.4.2 on\_data\_on\_readers (inherited, abstract)
This operation is inherited and therefore not described here. See the class SubscriberListener for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
void
on_data_on_readers
(Subscriber_ptr subs) = 0;
```
# 3.2.4.3 on\_inconsistent\_topic (inherited, abstract)
This operation is inherited and therefore not described here. See the class TopicListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_inconsistent_topic
(Topic_ptr the_topic,
const InconsistentTopicStatus& status) = 0;
```
# 3.2.4.4 on\_liveliness\_changed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_changed
```
```typescript
(DataReader_ptr reader,
const LivelinessChangedStatus& status) = 0;
```
# 3.2.4.5 on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_lost
(DataWriter_ptr writer,
const LivelinessLostStatus& status) = 0;
```
# 3.2.4.6 on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_deadline_missed
(DataWriter_ptr writer,
const OfferedDeadlineMissedStatus& status) = 0;
```
# 3.2.4.7 on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_incompatible_qos
(DataWriter_ptr writer,
const OfferedIncompatibleQosStatus& status) = 0;
```
# 3.2.4.8 on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_publication_matched
(DataWriter_ptr writer,
```
```typescript
const PublicationMatchedStatus& status) = 0;
```
# 3.2.4.9 on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_deadline_missed
(DataReader_ptr reader,
const RequestedDeadlineMissedStatus& status) = 0;
```
# 3.2.4.10 on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_incompatible_qos
(DataReader_ptr reader,
const RequestedIncompatibleQosStatus& status) = 0;
```
# 3.2.4.11 on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on_sample_lost
(DataReader_ptr reader,
const SampleLostStatus& status) = 0;
```
# 3.2.4.12 on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_sample_rejected
(DataReader_ptr reader,
const SampleRejectedStatus& status) = 0;
```
# 3.2.4.13 on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on Subscription_matched
(DataReader_ptr reader,
const SubscriptionMatchedStatus& status) = 0;
```
# 3.2.5 ExtDomainParticipantListener interface
The ExtDompainParticipantListener 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:
```cpp
class ExtDomainParticipantListener : ExtTopicListener,
DomainParticipantListener
{
//
// inherited from TopicListener
//
// void
// on_inconsistent_topic
// (Topic_ptr the_topic,
// const InconsistentTopicStatus& status) = 0;
// inherited from ExtTopicListener
//
// void
// on_all_data_disposed
// (Topic_ptr the_topic) = 0;
//
// inherited from PublisherListener
//
// void
// on_offered_deadline_missed
// (DataWriter_ptr writer,
// const OfferedDeadlineMissedStatus& status) = 0;
// void
// on_offered_incompatible_qos
```
```txt
// (DataWriter_ptr writer,
// const OfferedIncompatibleQosStatus& status) = 0;
// void
// on_liveliness_lost
// (DataWriter_ptr writer,
// const LivelinessLostStatus& status) = 0;
// void
// on_publication_matched
// (DataWriter_ptr writer,
// const PublicationMatchedStatus& status) = 0;
//
// inherited from SubscriberListener
//
// void
// on_data_on_readers
// (Subscriber_ptr subs) = 0;
// void
// on_requested_deadline_missed
// (DataReader_ptr reader,
// const RequestedDeadlineMissedStatus& status) = 0;
// void
// on_requested_incompatible_qos
// (DataReader_ptr reader,
// const RequestedIncompatibleQosStatus& status) = 0;
// void
// on_sample_rejected
// (DataReader_ptr reader,
// const SampleRejectedStatus& status) = 0;
// void
// on_liveliness_changed
// (DataReader_ptr reader,
// const LivelinessChangedStatus& status) = 0;
// void
// on_data_available
// (DataReader_ptr reader) = 0;
// void
// on_subscription_matched
// (DataReader_ptr reader,
// const SubscriptionMatchedStatus& status) = 0;
// void
// on_sample_lost
// (DataReader_ptr reader,
// const SampleLostStatus& status) = 0;
//
// implemented API operations
// <no operations>
//
};
```
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 on\_all\_data\_disposed (inherited, abstract)
This operation is inherited and therefore not described here. See the class ExtTopicListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_all_data_disposed
(Topic_ptr the_topic) = 0;
```
# 3.2.5.2 on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_data_available
(DataReader_ptr reader) = 0;
```
# 3.2.5.3 on\_data\_on\_readers (inherited, abstract)
This operation is inherited and therefore not described here. See the class SubscriberListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_data_on_readers
(Subscriber_ptr subs) = 0;
```
# 3.2.5.4 on\_inconsistent\_topic (inherited, abstract)
This operation is inherited and therefore not described here. See the class TopicListener for further explanation.
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
void
on_inconsistent_topic
(Topic_ptr the_topic,
```
```typescript
const InconsistentTopicStatus& status) = 0;
```
# 3.2.5.5 on\_liveliness\_changed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_changed
(DataReader_ptr reader,
const LivelinessChangedStatus& status) = 0;
```
# 3.2.5.6 on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_lost
(DataWriter_ptr writer,
const LivelinessLostStatus& status) = 0;
```
# 3.2.5.7 on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_deadline_missed
(DataWriter_ptr writer,
const OfferedDeadlineMissedStatus& status) = 0;
```
# 3.2.5.8 on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_incompatible_qos
(DataWriter_ptr writer,
const OfferedIncompatibleQosStatus& status) = 0;
```
# 3.2.5.9 on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_publication_matched
(DataWriter_ptr writer,
const PublicationMatchedStatus& status) = 0;
```
# 3.2.5.10 on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_deadline_missed
(DataReader_ptr reader,
const RequestedDeadlineMissedStatus& status) = 0;
```
# 3.2.5.11 on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_incompatible_qos
(DataReader_ptr reader,
const RequestedIncompatibleQosStatus& status) = 0;
```
# 3.2.5.12 on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on_sample_lost
(DataReader_ptr reader,
const SampleLostStatus& status) = 0;
```
# 3.2.5.13 on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_sample_rejected
(DataReader_ptr reader,
const SampleRejectedStatus& status) = 0;
```
# 3.2.5.14 on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on Subscription_matched
(DataReader_ptr reader,
const SubscriptionMatchedStatus& status) = 0;
```
# 3.3 Topic-Definition Module
Figure 16 DCPS Topic-Definition Module’s Class Model
This module contains the following classes:
• TopicDescription (abstract)
• Topic
• ContentFilteredTopic
• MultiTopic
• 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 <type>TypeSupport is generated (based on IDL) by calling the pre-processor.
Figure 17 Data Type “Foo” Typed Classes Pre-processor Generation
For instance, for the fictional data type Foo (this also applies to other types) “Topic-Definition type specific classes” contains the following classes:
• TypeSupport (abstract)
• FooTypeSupport.
Topic objects conceptually fit between publications and subscriptions. Publications must be known in such a way that subscriptions can refer to them unambiguously. A Topic is meant to fulfil that purpose: it associates a name (unique in the Domain), a data type, and TopicQos related to the data itself.
# 3.3.1 Class 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 T o p i c , ContentFilteredTopic and MultiTopic.
The TopicDescription attribute type\_name defines an unique data type that is made available to the Data Distribution Service via the TypeSupport. TopicDescription has also a name that allows it to be retrieved locally.
```txt
The interface description of this class is as follows:
class TopicDescription
{
//
```
```c
// implemented API operations
//
char*
get_type_name
(void);
char*
get_name
(void);
DomainParticipant_ptr
get_participant
(void);
};
```
The next paragraphs describe the usage of all TopicDescription operations.
# 3.3.1.1 get\_name
# Scope
```txt
DDS::TopicDescription
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_name
(void);
```
# Description
This operation returns the name used to create the TopicDescription.
# Parameters
```txt
<none>
```
# Return Value
```txt
char* - is the name of the TopicDescription.
```
# Detailed Description
This operation returns the name used to create the TopicDescription.
# 3.3.1.2 get\_participant
# Scope
```txt
DDS::TopicDescription
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DomainParticipant_ptr
```
```c
get_participant
(void);
```
# Description
This operation returns the DomainParticipant associated with the TopicDescription or the NULL pointer.
# Parameters
```txt
<none>
```
# Return Value
DomainParticipant\_ptr - a pointer to the DomainParticipant associated with the TopicDescription or the NULL pointer.
# Detailed Description
This operation returns the DomainParticipant associated with the TopicDescription. Note that there is exactly one DomainParticipant associated with each TopicDescription. When the TopicDescription was already deleted (there is no associated DomainParticipant any more), the NULL pointer is returned.
# 3.3.1.3 get\_type\_name
# Scope
```txt
DDS::TopicDescription
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_type_name
(void);
```
# Description
This operation returns the registered name of the data type associated with the TopicDescription.
# Parameters
```txt
<none>
```
# Return Value
char\* - the name of the data type of the TopicDescription.
# Detailed Description
This operation returns the registered name of the data type associated with the TopicDescription.
# 3.3.2 Class Topic
Topic is the most basic description of the data to be published and subscribed.
A Topic is identified by its name, which must be unique in the whole Domain. In addition (by virtue of extending TopicDescription) it fully identifies the type of data that can be communicated when publishing or subscribing to the Topic.
Topic is the only TopicDescription that can be used for publications and therefore a specialized DataWriter is associated to the Topic.
The interface description of this class is as follows:
```cpp
class Topic
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// inherited from class TopicDescription
//
// char*
// get_type_name
// (void);
// char*
// get_name
// (void);
// DomainParticipant_ptr
// get_participant
// (void);
//
// implemented API operations
//
ReturnCode_t
set_qos
(const TopicQos& qos);
```
```txt
ReturnCode_t
get_qos
(TopicQos& qos);
ReturnCode_t
set_listener
(TopicListener_ptr a_listener,
StatusMask mask);
TopicListener_ptr
get_listener
(void);
ReturnCode_t
get_inconsistent_topic_status
(InconsistentTopicStatus& a_status);
ReturnCode_t
get_all_data_disposed_topic_status
(AllDataDisposedTopicStatus& a_status);
ReturnCode_t dispose_all_data();
};
```
The next paragraphs describe the usage of all 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 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.2.2 get\_inconsistent\_topic\_status
# Scope
```makefile
DDS::Topic
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_inconsistent_topic_status
(InconsistentTopicStatus& a_status);
```
# Description
This operation obtains the InconsistentTopicStatus of the Topic.
# Parameters
inout InconsistentTopicStatus& a\_status - the contents of the InconsistentTopicStatus struct of the Topic will be copied into the location specified by a\_status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED o r RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the InconsistentTopicStatus of the Topic. The InconsistentTopicStatus can also be monitored using a TopicListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current InconsistentTopicStatus of this Topic has successfully been copied into the specified a\_status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Topic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.3 get\_all\_data\_disposed\_topic\_status
# Scope
DDS::Topic
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_all_data_disposed_topic_status
(AllDataDisposedTopicStatus& a_status);
```
# Description
This operation obtains the AllDataDisposedTopicStatus of the Topic.
# Parameters
inout AllDataDisposedTopicStatus& a\_status – the contents of the AllDataDisposedTopicStatus struct of the Topic will be copied into the location specified by a\_status.
# Return Value
ReturnCode\_t – Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the AllDataDisposedTopicStatus of the Topic. The A l lD a t a D i sp o s e d T o pi c S t a t us c a n a l s o b e m o n i t o r e d u s i n g a ExtTopicListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
RETCODE\_OK – the current AllDataDisposedTopicStatus of this Topic has successfully been copied into the specified status parameter.
RETCODE\_ERROR – an internal error has occurred.
RETCODE\_ALREADY\_DELETED – the Topic has already been deleted.
RETCODE\_OUT\_OF\_RESOURCES – the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.4 dispose\_all\_data
# Synopsis
```c
#include <ccpp_dds_dcps.h>
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
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_ALREADY\_DELETED, 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, dispose, on page 299.)
(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 po lic y. For B Y \_ S OU R C E \_ T I ME 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
• RETCODE\_OK - a request to dispose the topic has been sucessfully queued.
• RETCODE\_ERROR - and internal error has occured.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_ALREADY\_DELETED - the Topic has already been deleted.
• RETCODE\_NOT\_ENABLED - the Topic is not enabled.
# 3.3.2.5 get\_listener
# Scope
```makefile
DDS::Topic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
TopicListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a TopicListener.
# Parameters
```txt
<none>
```
# Return Value
TopicListener\_ptr - result is a pointer to the TopicListener attached to the Topic.
# Detailed Description
This operation allows access to a TopicListener attached to the Topic. When no TopicListener was attached to the Topic, the NULL pointer is returned.
# 3.3.2.6 get\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
char*
get_name
(void);
```
# 3.3.2.7 get\_participant (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
DomainParticipant_ptr
get_participant
(void);
```
# 3.3.2.8 get\_qos
# Scope
```makefile
DDS::Topic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(TopicQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a Topic.
# Parameters
inout TopicQos& qos - a reference to the destination TopicQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a Topic on which this operation is used. This TopicQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this Topic has successfully been copied into the specified TopicQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Topic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.9 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.3.2.10 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.3.2.11 get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
char*
get_type_name
(void);
```
# 3.3.2.12 set\_listener
# Scope
```makefile
DDS::Topic
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_listener
(TopicListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation attaches a TopicListener to the Topic.
# Parameters
in TopicListener\_ptr a\_listener - a pointer to the TopicListener instance, which will be attached to the Topic.
in StatusMask mask - a bit mask in which each bit enables the invocation of the TopicListener for a certain status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation attaches a TopicListener to the Topic. Only one TopicListener can be attached to each Topic. If a TopicListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# 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 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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the TopicListener:
• 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 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 which are applicable to the PublisherListener.
# Status Propagation
In case a communication status is not activated in the mask of the TopicListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a Topic specific behaviour when needed. In case the 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:
• RETCODE\_OK - the TopicListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_ALREADY\_DELETED - the Topic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.2.13 set\_qos
# Scope
```makefile
DDS::Topic
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_qos
(const TopicQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a Topic.
# Parameters
in const TopicQos& qos - the new set of QosPolicy settings for the Topic.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_IMMUTABLE\_POLICY or RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a Topic. 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 Topic, which can only be set before the Topic is enabled, the operation will fail and a 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 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new TopicQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid TopicQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the Topic 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 different value than set during enabling of the Topic
• 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.3 Class ContentFilteredTopic
ContentFilteredTopic is a specialization of TopicDescription that allows for content based subscriptions.
ContentFilteredTopic describes a more sophisticated subscription that indicates the Subscriber does not necessarily want to see all values of each instance published under the 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.
The interface description of this class is as follows:
```cpp
class ContentFilteredTopic
{
//
// inherited from class TopicDescription
//
// char*
// get_type_name
// (void);
// char*
// get_name
// (void);
// DomainParticipant_ptr
// get_participant
// (void);
//
// implemented API operations
//
char*
get_filter_expression
(void);
ReturnCode_t
get_expression_parameters
(StringSeq& expression_parameters);
ReturnCode_t
set_expression_parameters
(const StringSeq& expression_parameters);
Topic_ptr
get_related_topic
(void);
};
```
The next paragraphs describe the usage of all ContentFilteredTopic operations.
# 3.3.3.1 get\_expression\_parameters
# Scope
```autohotkey
DDS::ContentFilteredTopic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_expression_parameters
(StringSeq& expression_parameters);
```
# Description
This operation obtains the expression parameters associated with the ContentFilteredTopic.
# Parameters
inout StringSeq& expression\_parameters - a reference to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the expression parameters associated with the ContentFilteredTopic. That is, the parameters specified on the last successful call to set\_expression\_parameters, or if set\_expression\_parameters was never called, the parameters specified when the ContentFilteredTopic was created.
The resulting reference holds 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 ContentFilteredTopic.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of expression parameters applied to this ContentFilteredTopic has successfully been copied into the specified expression\_parameters parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the ContentFilteredTopic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.3.2 get\_filter\_expression
# Scope
DDS::ContentFilteredTopic
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_filter_expression
(void);
```
# Description
This operation returns the filter\_expression associated with the ContentFilteredTopic.
# Parameters
<none>
# Return Value
char\* - a handle to a string which holds the SQL filter expression.
# Detailed Description
This operation returns the filter\_expression associated with the ContentFilteredTopic. That is, the expression specified when the 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 get\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_name
(void);
```
# 3.3.3.4 get\_participant (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
DomainParticipant_ptr
get_participant
(void);
```
# 3.3.3.5 get\_related\_topic
# Scope
```autohotkey
DDS::ContentFilteredTopic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
Topic_ptr
get_related_topic
(void);
```
# Description
This operation returns the Topic associated with the ContentFilteredTopic.
# Parameters
```txt
<none>
```
# Return Value
Topic\_ptr - a pointer to the base topic on which the filtering will be applied.
# Detailed Description
This operation returns the Topic associated with the ContentFilteredTopic. That is, the Topic specified when the ContentFilteredTopic was created. This Topic is the base topic on which the filtering will be applied.
# 3.3.3.6 get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
char*
get_type_name
(void);
```
# 3.3.3.7 set\_expression\_parameters
# Scope
```autohotkey
DDS::ContentFilteredTopic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_expression_parameters
(const StringSeq& expression_parameters);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4 Class MultiTopic
MultiTopic is a specialization of TopicDescription that allows subscriptions to combine, filter and/or rearrange data coming from several Topics.
MultiTopic allows a more sophisticated subscription that can select and combine data received from multiple 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:
```cpp
class MultiTopic
{
//
// inherited from class TopicDescription
//
// char*
// get_type_name
// (void);
// char*
// get_name
// (void);
```
```c
// DomainParticipant_ptr
// get_participant
// (void);
//
// implemented API operations
//
char*
get Subscription_expression
(void);
ReturnCode_t
get_expression_parameters
(StringSeq& expression_parameters);
ReturnCode_t
set_expression_parameters
(const StringSeq& expression_parameters);
};
```
The next paragraphs describe the usage of all 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: MultiTopic operations have not been yet been implemented. Multitopic functionality is scheduled for a future release.
# 3.3.4.1 get\_expression\_parameters
# Scope
DDS::MultiTopic
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_expression_parameters
(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 MultiTopic.
# Parameters
inout StringSeq& expression\_parameters - a reference to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the expression parameters associated with the MultiTopic. T h a t i s , t h e p a r a m e t e r s s p e c i f i e d o n t h e l a s t s u c c e s s f u l c a l l t o set\_expression\_parameters, or if set\_expression\_parameters was never called, the parameters specified when the MultiTopic was created.
The resulting reference holds 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 MultiTopic.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of expression parameters applied to this MultiTopic has successfully been copied into the specified expression\_parameters parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the MultiTopic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.4.2 get\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_name
(void);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.3 get\_participant (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DomainParticipant_ptr
get_participant
(void);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.4 get\_subscription\_expression
# Scope
```txt
DDS::MultiTopic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
char*
get_subscription_expression
(void);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# Description
This operation returns the subscription expression associated with the MultiTopic.
# Parameters
```txt
<none>
```
# Return Value
char\* - result is a handle to a string which holds the SQL subscription expression.
# Detailed Description
This operation returns the subscription expression associated with the MultiTopic. That is, the expression specified when the 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 Topics. It is an SQL expression where the SELECT clause provides the fields to be kept, the FROM part provides the names of the Topics that are searched for those fields, and the WHERE clause gives the content filter. The 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 get\_type\_name (inherited)
This operation is inherited and therefore not described here. See the class TopicDescription for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_type_name
(void);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.3.4.6 set\_expression\_parameters
# Scope
```txt
DDS::MultiTopic
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_expression_parameters
(const 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 MultiTopic.
# Parameters
in const StringSeq& expression\_parameters - the handle to a sequence of strings with the parameters used in the SQL expression.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED or RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation changes the expression parameters associated with the 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 MultiTopic. This is the subscription expression specified when the MultiTopic was created.
# Return Code
When the operation returns:
• RETCODE\_OK - the new expression parameters are set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the number of parameters in expression\_parameters does not match the number of “%n” tokens in the expression for this MultiTopic or one of the parameters is an illegal parameter.
• RETCODE\_ALREADY\_DELETED - the MultiTopic has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.3.5 TopicListener interface
Since a Topic is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type TopicListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the TopicListener class. All 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.
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 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 Topic. The TopicListener is related to changes in communication status.
The interface description of this class is as follows:
```cpp
class TopicListener
{
//
// abstract external operations
//
void
on_inconsistent_topic
(Topic_ptr the_topic,
const InconsistentTopicStatus& status) = 0;
//
// implemented API operations
// <no operations>
//
};
```
The next paragraph describes the usage of the TopicListener operation. This abstract operation is fully described since it must be implemented by the application.
# 3.3.5.1 on\_inconsistent\_topic (abstract)
# Scope
```txt
DDS::TopicListener
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_inconsistent_topic
(Topic_ptr the_topic,
const InconsistentTopicStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the InconsistentTopicStatus changes.
# Parameters
in Topic\_ptr the\_topic - contain a pointer to the Topic on which the conflict occurred (this is an input to the application).
in const InconsistentTopicStatus& status - contain the 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 InconsistentTopicStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the r e l e v a n t T o p i c L i s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e InconsistentTopicStatus. The InconsistentTopicStatus will change when another Topic exists with the same topic\_name but different characteristics.
The Data Distribution Service will call the TopicListener operation with a parameter the\_topic, which will contain a reference to the Topic on which the confl ict oc curr ed and a par ame ter s t a t u s , w h i c h w i l l c o n t a i n t h e InconsistentTopicStatus struct.
# 3.3.6 ExtTopicListener interface
The ExtTopicListener interface is a subtype of 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:
```cpp
class ExtTopicListener : TopicListener
{
//
// abstract external operations
//
void
on_all_data_disposed(Topic_ptr the_topic) = 0;
//
// implemented API operations
// <no operations>
//
};
```
# 3.3.6.1 on\_all\_data\_disposed (abstract)
# Scope
DDS::ExtTopicListener
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_all_data_disposed(Topic_ptr the_topic) = 0;
```
# 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
in Topic\_ptr the\_topic - contains a pointer to the Topic which has been disposed.
# 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 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 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 dispose\_all\_data operations complete before this method returns.
# 3.3.7 Topic-Definition Type Specific Classes
This paragraph describes the generic TypeSupport class and the derived application type specific <type>TypeSupport classes which together implement the application Topic interface. For each application type, used as Topic data type, the pre-processor generates a <type>DataReader class from an IDL type description. The FooTypeSupport class that would be generated by the pre-processor for a fictional type Foo describes the <type>TypeSupport classes.
# 3.3.7.1 Class TypeSupport (abstract)
The Topic, MultiTopic or ContentFilteredTopic is bound to a data type described by the type name argument. Prior to creating a Topic, MultiTopic or ContentFilteredTopic, the data type must have been registered with the Data Distribution Service. This is done using the data type specific register\_type operation on a derived class of the 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:
```cpp
class TypeSupport
{
//
// abstract operations
//
// ReturnCode_t
// register_type
// (Domainparticipant_ptr domain, const char* type_name);
// char*
// get_type_name
// (void);
//
// implemented API operations
// <no operations>
//
};
```
The next paragraph list the 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 FooTypeSupport class (for the data type example Foo), which contains the data type specific implementation of this operation.
# 3.3.7.2 get\_type\_name (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <type>TypeSupport class. For further explanation see the description for the fictional data type Foo derived FooTypeSupport class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
char*
get_type_name
(void);
```
# 3.3.7.3 register\_type (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <type>TypeSupport class. For further explanation see the description for the fictional data type Foo derived FooTypeSupport class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
register_type
(Domainparticipant_ptr domain,
const char* type_name);
```
# 3.3.7.4 Class FooTypeSupport
The pre-processor generates from IDL type descriptions the application <type>TypeSupport classes. For each application data type that is used as Topic data type, a typed class <type>TypeSupport is derived from the TypeSupport class. In this paragraph, the class FooTypeSupport describes the operations of these derived <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 ccpp\_Space.h include file.
i General note: The name ccpp\_Space.h is derived from the IDL file Space.idl, that defines SPACE::Foo, for all relevant SPACE::FooDataWriter operations.
The Topic, MultiTopic or ContentFilteredTopic is bound to a data type described by the type\_name argument. Prior to creating a Topic, MultiTopic or ContentFilteredTopic, the data type must have been registered with the Data Distribution Service. This is done using the data type specific register\_type operation on the <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:
```cpp
class FooTypeSupport
{
//
// implemented API operations
//
ReturnCode_t
register_type
(DomainParticipant_ptr domain, const char* type_name);
char*
get_type_name
(void);
};
```
The next paragraph describes the usage of the FooTypeSupport operation.
# 3.3.7.5 get\_type\_name
# Scope
SPACE::FooTypeSupport
# Synopsis
```c
#include <cpp_Space.h>
char*
get_type_name
(void);
```
# Description
This operation returns the default name of the data type associated with the FooTypeSupport.
# Parameters
```txt
<none>
```
# Return Value
char\* - the name of the data type of the FooTypeSupport.
# Detailed Description
This operation returns the default name of the data type associated with the 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.6 register\_type
# Scope
SPACE::FooTypeSupport
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
register_type
(DomainParticipant_ptr domain,
const char* type_name);
```
# Description
This operation registers a new data type name to a DomainParticipant.
# Parameters
in Domainparticipant\_ptr domain - a pointer to a DomainParticipant object to which the new data type is registered.
in const char\* type\_name - a local alias of the new data type to be registered.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_OUT\_ OF\_RESOURCES or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation registers a new data type name to a 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 type\_name cannot be registered with two different <type>TypeSupport classes (that is, of a different data type) with the same DomainParticipant. When the operation is called on the same DomainParticipant with the same type\_name for a different <type>TypeSupport class, the operation returns RETCODE\_PRECONDITION\_NOT\_MET. However, it is possible to register the same <type>TypeSupport classes with the same DomainParticipant and the same or different type\_name multiple times. All registrations return RETCODE\_OK, but any subsequent registrations with the same type\_name are ignored.
# Return Code
When the operation returns:
• RETCODE\_OK - the FooTypeSupport class is registered with the new data type name to the DomainParticipant or the FooTypeSupport class was already registered
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - one or both of the parameters is invalid, the domain parameter is a NULL pointer, or the parameter type\_name has zero length.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - this type\_name is already registered with this DomainParticipant for a different <type>TypeSupport class.
# 3.4 Publication Module
Figure 18 DCPS Publication Module’s Class Model
This module contains the following classes:
• Publisher
• Publication type specific classes
• PublisherListener (interface)
• 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 <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) “Publication type specific classes” contains the following classes:
• DataWriter (abstract)
• FooDataWriter.
A Publisher is an object responsible for data distribution. It may publish data of different data types. A DataWriter acts as a typed accessor to a Publisher. The DataWriter is the object the application must use to communicate the existence and value of data-objects of a given data type to a Publisher. When data-object values have been communicated to the Publisher through the appropriate DataWriter, it is the Publisher’s responsibility to perform the distribution. The Publisher will do this according to its own PublisherQos, and the DataWriterQos attached to the corresponding DataWriter. A publication is defined by the association of a DataWriter to a Publisher. This association expresses the intent of the application to publish the data described by the DataWriter in the context provided by the Publisher.
# 3.4.1 Class Publisher
The Publisher acts on behalf of one or more DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DataWriter objects, it decides when it is appropriate to actually process the sample-update message. In making this decision, it considers the PublisherQos and the DataWriterQos.
The interface description of this class is as follows:
```cpp
class Publisher
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// implemented API operations
//
DataWriter_ptr
create_datawriter
(Topic_ptr a_topic,
const DataWriterQos& qos,
DataWriterListener_ptr a_listener,
StatusMask mask);
ReturnCode_t
delete_datawriter
```
```c
(DataWriter_ptr a_datawriter);
DataWriter_ptr
lookup_datawriter
(const char* topic_name);
ReturnCode_t
delete_contained_entities
(void);
ReturnCode_t
set_qos
(const PublisherQos& qos);
ReturnCode_t
get_qos
(PublisherQos& qos);
ReturnCode_t
set_listener
(PublisherListener_ptr a_listener, StatusMask mask);
PublisherListener_ptr
get_listener
(void);
ReturnCode_t
suspend_publications
(void);
ReturnCode_t
resume_publications
(void);
ReturnCode_t
begin_coherent_changes
(void);
ReturnCode_t
end_coherent_changes
(void);
ReturnCode_t
wait_for_acknowledgments
(const Duration_t& max_wait);
DomainParticipant_ptr
get_participant
(void);
ReturnCode_t
set_default_datawriter_qos
(const DataWriterQos& qos);
```
```txt
ReturnCode_t
get_default_datawriter_qos
(DataWriterQos& qos);
ReturnCode_t
copy_from_topic_qos
(DataWriterQos& a_datawriter_qos,
const TopicQos& a_topic_qos);
};
```
The next paragraphs describe the usage of all 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 begin\_coherent\_changes
# Scope
DDS::Publisher
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
begin_coherent_changes
(void);
```
# Description
This operation requests that the application will begin a ‘coherent set’ of modifications using DataWriter objects attached to this Publisher. The ‘coherent set’ will be completed by a matching call to end\_coherent\_changes.
# Parameters
<none>
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation requests that the application will begin a ‘coherent set’ of modifications using DataWriter objects attached to this Publisher. The ‘coherent set’ will be completed by a matching call to 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 Publisher has its coherent\_access attribute set to TRUE. If this is not the case, the Publisher wi ll not accept any coherent start requests and return 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 Publisher or one of its connected Subscribers may change, a late-joining 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 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:
• RETCODE\_OK - a new coherent change has successfully been started.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_PRECONDITION\_NOT\_MET - the Publisher is not able to handle coherent changes because its PresentationQos has not set coherent\_access to TRUE.
# 3.4.1.2 copy\_from\_topic\_qos
# Scope
DDS::Publisher
# Synopsis
#include <ccpp\_dds\_dcps.h>
```txt
ReturnCode_t
copy_from_topic_qos
(DataWriterQos& a_datawriter_qos,
const TopicQos& a_topic_qos);
```
# Description
This operation will copy policies in a\_topic\_qos to the corresponding policies in a\_datawriter\_qos.
# Parameters
inout DataWriterQos& a\_datawriter\_qos - the destination DataWriterQos struct to which the QosPolicy settings should be copied.
in const TopicQos& a\_topic\_qos - the source TopicQos struct, which should be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or 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 <Entity>Qos.
This is a “convenience” operation, useful in combination with the operations get\_default\_datawriter\_qos and Topic::get\_qos. The operation copy\_from\_topic\_qos can be used to merge the DataWriter default QosPolicy settings with the corresponding ones on the TopicQos. The resulting DataWriterQos can then be used to create a new DataWriter, or set its 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 DataWriterQos to the DataWriter.
# Return Code
When the operation returns:
• RETCODE\_OK - the QosPolicy settings are copied from the Topic to the DataWriter
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.3 create\_datawriter
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataWriter_ptr
create_datawriter
(Topic_ptr a_topic,
const DataWriterQos& qos,
DataWriterListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation creates a DataWriter with the desired DataWriterQos, for the desired Topic and attaches the optionally specified DataWriterListener to it.
# Parameters
in Topic\_ptr a\_topic - a pointer to the topic for which the DataWriter is created.
in const DataWriterQos& qos - the DataWriterQos for the new DataWriter. In case these settings are not self consistent, no DataWriter is created.
in DataWriterListener\_ptr a\_listener - a pointer to the DataWriterListener instance which will be attached to the new DataWriter. It is permitted to use NULL as the value of the listener: this behaves as a DataWriterListener whose operations perform no action.
# Return Value
DataWriter\_ptr - Return value is a pointer to the newly created DataWriter. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a DataWriter with the desired DataWriterQos, for the desired Topic and attaches the optionally specified DataWriterListener to it. The returned DataWriter is attached (and belongs) to the Publisher on which this operation is being called. To delete the DataWriter the operation delete\_datawriter or 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 DataWriter 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>DataWriter generated by calling the pre-processor. This data type specific class extends DataWriter and contains the operations to write data of data type <type>.
# QosPolicy
The possible application pattern to construct the DataWriterQos for the DataWriter is to:
• Retrieve the QosPolicy settings on the associated Topic by means of the get\_qos operation on the Topic
• Retrieve the default DataWriterQos by means of the get\_default\_datawriter\_qos operation on the Publisher
• Combine those two lists of QosPolicy settings and selectively modify QosPolicy settings as desired
• Use the resulting DataWriterQos to construct the DataWriter.
In case the specified QosPolicy settings are not consistent, no DataWriter is created and the NULL pointer is returned.
# Default QoS
The constant DATAWRITER\_QOS\_DEFAULT can be used as parameter qos to create a DataWriter with the default DataWriterQos as set in the Publisher. The effect of using DATAWRITER\_QOS\_DEFAULT is the same as calling the operation get\_default\_datawriter\_qos and using the resulting DataWriterQos to create the DataWriter.
The special DATAWRITER\_QOS\_USE\_TOPIC\_QOS can be used to create a DataWriter with a combination of the default DataWriterQos and the TopicQos. The effect of using DATAWRITER\_QOS\_USE\_TOPIC\_QOS is the same as calling the operation get\_default\_datawriter\_qos and retrieving the TopicQos (by means of the operation Topic::get\_qos) and then combining these two QosPolicy settings using the operation copy\_from\_topic\_qos, whereby any common policy that is set on the TopicQos “overrides” the corresponding policy on the default DataWriterQos. The resulting DataWriterQos is then applied to create the 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 communication status activated in the mask, the associated 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 DataWriterListener:
• OFFERED\_DEADLINE\_MISSED\_STATUS
• OFFERED\_INCOMPATIBLE\_QOS\_STATUS
• LIVELINESS\_LOST\_STATUS
• PUBLICATION\_MATCHED\_STATUS.
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.
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 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 which are applicable to the PublisherListener.
# Status Propagation
In case a communication status is not activated in the m a sk of the DataWriterListener, the PublisherListener of the containing Publisher is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the PublisherListener of the containing Publisher and a DataWriter specific behaviour when needed. In case the communication status is not activated in the mask of the PublisherListener as w e l l , t h e 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 DomainParticipantListener of the containing DomainParticipant. In case the 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 delete\_contained\_entities
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all the DataWriter objects that were created by means of one of the create\_datawriter operations on the Publisher.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes all the DataWriter objects that were created by means of one of the create\_datawriter operations on the Publisher. In other words, it deletes all contained DataWriter objects.
NOTE: The operation will return 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:
• RETCODE\_OK - the contained Entity objects are deleted and the application may delete the Publisher
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.4.1.5 delete\_datawriter
# Scope
DDS::Publisher
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_datawriter
(DataWriter_ptr a_datawriter);
```
# Description
This operation deletes a DataWriter that belongs to the Publisher.
# Parameters
in DataWriter\_ptr a\_datawriter - a pointer to the DataWriter, which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation deletes a DataWriter that belongs to the Publisher. When the operation is called on a different Publisher, as used when the DataWriter was c r e a t e d , 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 RETCODE\_PRECONDITION\_NOT\_MET. The deletion of the DataWriter will automatically unregister all instances. Depending on the settings of WriterDataLifecycleQosPolicy, the deletion of the DataWriter may also dispose of all instances.
# Return Code
When the operation returns:
• RETCODE\_OK - the DataWriter is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_datawriter is not a valid DataWriter\_ptr
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different Publisher, as used when the DataWriter was created.
# 3.4.1.6 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.4.1.7 end\_coherent\_changes
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
end_coherent_changes
(void);
```
# Description
This operation terminates the ‘coherent set’ initiated by the matching call to begin\_coherent\_changes.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation terminates the ‘coherent set’ initiated by the matching call to b e gi n \_ c o h e re n t \_ c h an g e s . I f t h e r e i s n o m a t c h i n g c a l l t o b e gi n \_ c o h e re n t \_ c h an g e s , t h e o p e r a t i o n w i l l r e t u r n t h e e r r o r PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the coherent change has successfully been closed.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_PRECONDITION\_NOT\_MET - there is no matching begin\_coherent\_ changes call that can be closed.
# 3.4.1.8 get\_default\_datawriter\_qos
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_datawriter_qos
(DataWriterQos& qos);
```
# Description
This operation gets the default DataWriterQos of the Publisher.
# Parameters
inout DataWriterQos& qos - a reference to the DataWriterQos struct (provided by the application) in which the default DataWriterQos for the DataWriter is written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation gets the default DataWriterQos of the Publisher (that is the struct with the QosPolicy settings) which is used for newly created DataWriter objects, in case the constant DATAWRITER\_QOS\_DEFAULT is used. The default DataWriterQos is only used when the constant is supplied as parameter qos to specify the DataWriterQos in the create\_datawriter operation. The application must provide the DataWriterQos struct in which the QosPolicy settings can be stored and pass the qos reference to the operation. The operation writes the default DataWriterQos to the struct referenced 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 set\_default\_datawriter\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 2 on page 38.
# Return Code
When the operation returns:
• RETCODE\_OK - the default DataWriter QosPolicy settings of this Publisher have successfully been copied into the specified DataWriterQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.9 get\_listener
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
PublisherListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a PublisherListener.
# Parameters
<none>
# Return Value
PublisherListener\_ptr - result is a pointer to the PublisherListener attached to the Publisher.
# Detailed Description
This operation allows access to a PublisherListener attached to the Publisher. When no PublisherListener was attached to the Publisher, the NULL pointer is returned.
# 3.4.1.10 get\_participant
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
DomainParticipant_ptr
get_participant
(void);
```
# Description
This operation returns the DomainParticipant associated with the Publisher or the NULL pointer.
# Parameters
```txt
<none>
```
# Return Value
DomainParticipant\_ptr - a pointer to the DomainParticipant associated with the Publisher or the NULL pointer.
# Detailed Description
This operation returns the DomainParticipant associated with the Publisher. Note that there is exactly one DomainParticipant associated with each Publisher. When the Publisher was already deleted (there is no associated DomainParticipant any more), the NULL pointer is returned.
# 3.4.1.11 get\_qos
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(PublisherQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a Publisher.
# Parameters
inout PublisherQos& qos - a reference to the destination PublisherQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a Publisher on which this operation is used. This PublisherQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this Publisher has successfully been copied into the specified PublisherQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.12 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.4.1.13 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.4.1.14 lookup\_datawriter
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DataWriter_ptr
lookup_datawriter
(const char* topic_name);
```
# Description
This operation returns a previously created DataWriter belonging to the Publisher which is attached to a Topic with the matching topic\_name.
# Parameters
in const char\* topic\_name - the name of the Topic, which is attached to the DataWriter to look for.
# Return Value
DataWriter\_ptr - Return value is a pointer to the DataWriter found. When no such DataWriter is found, the NULL pointer is returned.
# Detailed Description
This operation returns a previously created DataWriter belonging to the Publisher which is attached to a Topic with the matching topic\_name. When multiple 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 resume\_publications
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
resume_publications
(void);
```
# Description
This operation resumes a previously suspended publication.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, RETCODE_NOT_ENABLED or RETCODE_PRECONDITION_NOT_MET
```
# Detailed Description
If the Publisher is suspended, this operation will resume the publication of all DataWriter objects contained by this Publisher. All data held in the history buffer of the DataWriter's is actively published to the consumers. When the operation returns all DataWriter's have resumed the publication of suspended updates.
# Return Code
When the operation returns:
• RETCODE\_OK - the Publisher has been suspended
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the Publisher is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the Publisher is not suspended
# 3.4.1.16 set\_default\_datawriter\_qos
# Scope
```autohotkey
DDS::Publisher
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_default_datawriter_qos
(const DataWriterQos& qos);
```
# Description
This operation sets the default DataWriterQos of the Publisher.
# Parameters
in const DataWriterQos& qos - the DataWriterQos struct, which contains the new default DataWriterQos for the newly created DataWriters.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation sets the default DataWriterQos of the Publisher (that is the struct with the QosPolicy settings) which is used for newly created DataWriter objects, in case the constant DATAWRITER\_QOS\_DEFAULT is used. The default DataWriterQos is only used when the constant is supplied as parameter qos to specify the DataWriterQos in the create\_datawriter operation. The set\_default\_datawriter\_qos operation checks if the DataWriterQos is self c o n s i s t e n t . I f i t i s n o t , t h e o p e r a t i o n h a s n o e f f e c t a n d r e t u r n s RETCODE\_INCONSISTENT\_POLICY.
The values set by this operation are returned by get\_default\_datawriter\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default DataWriterQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataWriterQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted
• 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 set\_listener
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_listener
(PublisherListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation attaches a PublisherListener to the Publisher.
# Parameters
in PublisherListener\_ptr a\_listener - a pointer to the PublisherListener instance, which will be attached to the Publisher.
in StatusMask mask - a bit mask in which each bit enables the invocation of the PublisherListener for a certain status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a PublisherListener to the Publisher. Only one P u bl i s h e r Li s t e n e r can b e att ached to eac h P u b l i sh e r. I f a PublisherListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated PublisherListener
1. Short for No-Operation, an instruction that does nothing.
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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the PublisherListener:
• OFFERED\_DEADLINE\_MISSED\_STATUS (propagated)
• OFFERED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• LIVELINESS\_LOST\_STATUS (propagated)
• PUBLICATION\_MATCHED\_STATUS (propagated).
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return 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 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 which are applicable to the PublisherListener.
# 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 DataWriterListener of a contained DataWriter, the DataWriterListener on that contained DataWriter is invoked instead of the PublisherListener. This means, that a status change on a contained DataWriter only invokes the PublisherListener if the contained 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 PublisherListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a Publisher specific behaviour when needed. In case the 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:
• RETCODE\_OK - the PublisherListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.1.18 set\_qos
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const PublisherQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a Publisher.
# Parameters
in const PublisherQos& qos - the new set of QosPolicy settings for the Publisher.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, or RETCODE\_IMMUTABLE\_POLICY or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a 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 Publisher, which can only be set before the Publisher is enabled, the operation will fail and a 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 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 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 RETCODE\_PRECONDITION\_NOT\_MET error code.
# Return Code
When the operation returns:
• RETCODE\_OK - the new PublisherQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid PublisherQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the Publisher 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 different value than set during enabling of the Publisher.
• RETCODE\_PRECONDITION\_NOT\_MET - returned when insufficient access rights exist for the partition(s) listed in the QoS structure.
# 3.4.1.19 suspend\_publications
# Scope
DDS::Publisher
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
suspend_publications
(void);
```
# Description
This operation will suspend the dissemination of the publications by all contained DataWriter objects.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_NOT_ENABLED.
```
# Detailed Description
This operation suspends the publication of all DataWriter objects contained by this Publisher. The data written, disposed or unregistered by a DataWriter is stored in the history buffer of the 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 this operation have no effect. When the Publisher is deleted before resume\_publications is called, all suspended updates are discarded.
# Return Code
When the operation returns:
• RETCODE\_OK - the Publisher has been suspended
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the Publisher is not enabled.
# 3.4.1.20 wait\_for\_acknowledgments
# Scope
DDS::Publisher
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
wait_for_acknowledgments
(const 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 const Duration\_t& max\_wait - the maximum duration to block for the wait\_for\_acknowledgments, after which the application thread is unblocked. The special constant DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES, RETCODE\_NOT\_ENABLED or 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 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, whichever happens first. In the first case the operation will return RETCODE\_OK, in the latter it will return RETCODE\_TIMEOUT.
Be aware that in case the operation returns 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 will crash). In contrast, if a 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 one or more of the contained D a t a Wr i t e r s h a s i t s R e li a b i l i t yQ o s P o l ic y K i n d s e t t o RELIABLE\_RELIABILITY\_QOS. Otherwise the operation will return immediately with 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:
• RETCODE\_OK - the data of all contained DataWriters has been acknowledged by the local infrastructure.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Publisher has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the Publisher is not enabled.
• RETCODE\_TIMEOUT - not all data is acknowledged before max\_wait elapsed.
# 3.4.2 Publication Type Specific Classes
This paragraph describes the generic DataWriter class and the derived application type specific <type>DataWriter classes which together implement the application publication interface. For each application type, used as Topic data type, the pre-processor generates a <type>DataWriter class from an IDL type description. The FooDataWriter class that would be generated by the pre-processor for a fictional type Foo describes the <type>DataWriter classes.
# 3.4.2.1 Class DataWriter (abstract)
DataWriter allows the application to set the value of the sample to be published under a given Topic.
A DataWriter is attached to exactly one Publisher which acts as a factory for it.
A DataWriter is bound to exactly one Topic and therefore to exactly one data type. The Topic must exist prior to the DataWriter's creation.
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:
```cpp
class DataWriter
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// abstract operations (implemented in the data type specific
// DataWriter)
//
// InstanceHandle_t
// register_instance
// (const <data>& instance_data);
//
// InstanceHandle_t
// register_instance_w_timestamp
// (const <data>& instance_data,
// const Time_t& source_timestamp);
//
// ReturnCode_t
// unregister_instance
// (const <data>& instance_data,
// InstanceHandle_t handle);
//
// ReturnCode_t
// unregister_instance_w_timestamp
// (const <data>& instance_data,
// InstanceHandle_t handle,
```
```c
// const Time_t& source_timestamp);
//
// ReturnCode_t
// write
// (const <data>& instance_data,
// InstanceHandle_t handle);
//
// ReturnCode_t
// write_w_timestamp
// (const <data>& instance_data,
// InstanceHandle_t handle,
// const Time_t& source_timestamp);
//
// ReturnCode_t
// dispose
// (const <data>& instance_data,
// InstanceHandle_t instance_handle);
//
// ReturnCode_t
// dispose_w_timestamp
// (const <data>& instance_data,
// InstanceHandle_t instance_handle,
// const Time_t& source_timestamp);
//
// ReturnCode_t
// writedispose
// (const <data>& instance_data,
// InstanceHandle_t instance_handle);
//
// ReturnCode_t
// writedispose_w_timestamp
// (const <data>& instance_data,
// InstanceHandle_t instance_handle,
// const Time_t& source_timestamp);
//
// ReturnCode_t
// get_key_value
// (<data>& key_holder,
// InstanceHandle_t handle);
//
// InstanceHandle_t
// lookup_instance
// (const <data>& instance_data);
//
// implemented API operations
//
ReturnCode_t
set_qos
(const DataWriterQos& qos);
```
```c
ReturnCode_t
get_qos
(DataWriterQos& qos);
ReturnCode_t
set_listener
(DataWriterListener_ptr a_listener,
StatusMask mask);
DataWriterListener_ptr
get_listener
(void);
Topic_ptr
get_topic
(void);
Publisher_ptr
get_publisher
(void);
ReturnCode_t
wait_for_acknowledgments
(const Duration_t& max_wait);
ReturnCode_t
get_liveliness_lost_status
(LivelinessLostStatus& status);
ReturnCode_t
get_offered_deadline_missed_status
(OfferedDeadlineMissedStatus& status);
ReturnCode_t
get_offered_incompatible_qos_status
(OfferedIncompatibleQosStatus& status);
ReturnCode_t
get_publication_matched_status
(PublicationMatchedStatus& status);
ReturnCode_t
assert_liveliness
(void);
ReturnCode_t
get_matched_subscriptions
(InstanceHandleSeq& subscription_handles);
ReturnCode_t
```
```c
get_matched_subscription_data
(SubscriptionBuiltinTopicData& subscription_data,
InstanceHandle_t subscription_handle);
};
```
The next paragraphs describe the usage of all 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 assert\_liveliness
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
assert_liveliness
(void);
```
# Description
This operation asserts the liveliness for the DataWriter.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_NOT_ENABLED.
```
# Detailed Description
This operation will manually assert the liveliness for the DataWriter. This way, the Data Distribution Service is informed that the corresponding DataWriter is still alive. This operation is used in combination with the LivelinessQosPolicy s e t t o MANUAL\_BY\_PARTICIPANT\_LIVELINESS\_QOS o r MANUAL\_BY\_TOPIC\_LIVELINESS\_QOS. See Section 3.1.3.10, L i v e l i n e s s Q o s P o l i c y, o n p a g e 5 8 , f o r m o r e i n f o r m a t i o n o n LivelinessQosPolicy.
Writing data via the write operation of a DataWriter will assert the liveliness on the DataWriter itself and its containing DomainParticipant. Therefore, assert\_liveliness is only needed when not writing regularly.
The liveliness should be asserted by the application, depending on the LivelinessQosPolicy. Asserting the liveliness for this DataWriter can also be achieved by asserting the liveliness to the DomainParticipant.
# Return Code
When the operation returns:
• RETCODE\_OK - the liveliness of this DataWriter has successfully been asserted.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataWriter is not enabled.
# 3.4.2.3 dispose (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
dispose
(const <data>& instance_data,
InstanceHandle_t instance_handle);
```
# 3.4.2.4 dispose\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```txt
#include <ccpp_dds_dcps.h>
ReturnCode_t
dispose_w_timestamp
```
```txt
(const <data>& instance_data,
InstanceHandle_t instance_handle,
const Time_t& source_timestamp);
```
# 3.4.2.5 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.4.2.6 get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_key_value
(<data>& key_holder,
InstanceHandle_t handle);
```
# 3.4.2.7 get\_listener
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataWriterListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a DataWriterListener.
# Parameters
```txt
<none>
```
# Return Value
DataWriterListener\_ptr - result is a pointer to the DataWriterListener attached to the DataWriter.
# Detailed Description
This operation allows access to a DataWriterListener attached to the DataWriter. When no DataWriterListener was attached to the DataWriter, the NULL pointer is returned.
# 3.4.2.8 get\_liveliness\_lost\_status
# Scope
DDS::DataWriter
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_liveliness_lost_status
(LivelinessLostStatus& status);
```
# Description
This operation obtains the LivelinessLostStatus struct of the DataWriter.
# Parameters
inout LivelinessLostStatus& status - the contents of the LivelinessLostStatus struct of the DataWriter will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the LivelinessLostStatus struct of the DataWriter. This struct contains the information whether the liveliness (that the DataWriter has committed through its LivelinessQosPolicy) was respected.
This means that the status represents whether the DataWriter failed to actively signal its liveliness within the offered liveliness period. If the liveliness is lost, the DataReader objects will consider the DataWriter as no longer “alive”.
The L i v e li n e s s L os t 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 DataWriterListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current LivelinessLostStatus of this DataWriter has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.9 get\_matched\_subscription\_data
# Scope
DDS::DataWriter
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_matched_subscription_data
(SubscriptionBuiltinTopicData& subscription_data,
InstanceHandle_t subscription_handle);
```
# Description
This operation retrieves information on the specified subscription that is currently “associated” with the DataWriter.
# Parameters
inout SubscriptionBuiltinTopicData& subscription\_data - a reference to the sample in which the information about the specified subscription is to be stored.
in InstanceHandle\_t subscription\_handle - a handle to the subscription whose information needs to be retrieved.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves information on the specified subscription that is currently “associated” with the 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 ignore\_subscription operation on the DomainParticipant class.
The subscription\_handle must correspond to a subscription currently associated with the DataWriter, otherwise the operation will fail and return RETCODE\_BAD\_PARAMETER. The operation get\_matched\_subscriptions can be used to find the subscriptions that are currently matched with the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will return RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• RETCODE\_OK - the information on the specified subscription has successfully been retrieved.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataWriter is not enabled.
# 3.4.2.10 get\_matched\_subscriptions
# Scope
DDS::DataWriter
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_matched_subscriptions
(InstanceHandleSeq& subscription_handles);
```
# Description
This operation retrieves the list of subscriptions currently “associated” with the DataWriter.
# Parameters
inout InstanceHandleSeq& subscription\_handles - a sequence which is used to pass the list of all associated subscriptions.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves the list of subscriptions currently “associated” with the 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 ignore\_subscription operation on the DomainParticipant class.
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 get\_matched\_subscriptions operation or be released by invoking its destructor either implicitly or explicitly. 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 get\_matched\_subscription\_data operation or to the read\_instance operation on the built-in reader for the “DCPSSubscription” topic.
Be aware that since InstanceHandle\_t is an opaque datatype, it does not n e c e s s a r i l y m e a n t h a t t h e h a n d l e s o b t a i n e d f r o m t h e get\_matched\_subscriptions operation have the same value as the ones that appear in the instance\_handle field of the 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 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will return RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• RETCODE\_OK - the list of associated subscriptions has successfully been obtained.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataWriter is not enabled.
# 3.4.2.11 get\_offered\_deadline\_missed\_status
# Scope
DDS::DataWriter
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_offered_deadline_missed_status
(OfferedDeadlineMissedStatus& status);
```
# Description
This operation obtains the OfferedDeadlineMissedStatus struct of the DataWriter.
# Parameters
inout OfferedDeadlineMissedStatus& status - the contents of the OfferedDeadlineMissedStatus struct of the DataWriter will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the OfferedDeadlineMissedStatus struct of the DataWriter. This struct contains the information whether the deadline (that the DataWriter has committed through its DeadlineQosPolicy) was respected for each instance.
The OfferedDeadlineMissedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current LivelinessLostStatus of this DataWriter has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.12 get\_offered\_incompatible\_qos\_status
# Scope
DDS::DataWriter
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_offered_incompatible_qos_status
(OfferedIncompatibleQosStatus& status);
```
# Description
This operation obtains the OfferedIncompatibleQosStatus struct of the DataWriter.
# Parameters
inout OfferedIncompatibleQosStatus& status - the contents of the OfferedIncompatibleQosStatus struct of the DataWriter will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the OfferedIncompatibleQosStatus struct of the 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 DataReader object has been discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter.
The OfferedIncompatibleQosStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current OfferedIncompatibleQosStatus of this DataWriter has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.13 get\_publication\_matched\_status
# Scope
DDS::DataWriter
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_publication_matched_status
(PublicationMatchedStatus& status);
```
# Description
This operation obtains the PublicationMatchedStatus struct of the DataWriter.
# Parameters
inout PublicationMatchedStatus& status - the contents of the PublicationMatchedStatus struct of the DataWriter will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the PublicationMatchedStatus struct of the DataWriter. This struct contains the information 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 DataWriter with the same Topic and a compatible Qos, or that a previously discovered DataReader has ceased to be matched to the current 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 DataWriter or when either the DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the ignore\_subcription or ignore\_publication operations on the DomainParticipant.
The operation may fail if the infrastructure does not hold the information necessary to fill in the PublicationMatchedStatus. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return RETCODE\_UNSUPPORTED.
The PublicationMatchedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current PublicationMatchedStatus of this DataWriter has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” subscriptions.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.14 get\_publisher
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
Publisher_ptr
get_publisher
(void);
```
# Description
This operation returns the Publisher to which the DataWriter belongs.
# Parameters
```txt
<none>
```
# Return Value
Publiher\_ptr - Return value is a pointer to the Publisher to which the DataWriter belongs.
# Detailed Description
This operation returns the Publisher to which the DataWriter belongs, thus the Publisher that has created the DataWriter. If the DataWriter is already deleted, the NULL pointer is returned.
# 3.4.2.15 get\_qos
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DataWriterQos& qos);
```
# Description
This operation allows access to the existing list of QosPolicy settings for a DataWriter.
# Parameters
inout DataWriterQos& qos - a reference to the destination DataWriterQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing list of QosPolicy settings of a DataWriter on which this operation is used. This DataWriterQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this DataWriter has successfully been copied into the specified DataWriterQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.16 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.4.2.17 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.4.2.18 get\_topic
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
Topic_ptr
get_topic
(void);
```
# Description
This operation returns the Topic which is associated with the DataWriter.
# Parameters
```txt
<none>
```
# Return Value
Topic\_ptr - Return value is a pointer to the Topic which is associated with the DataWriter.
# Detailed Description
This operation returns the Topic which is associated with the DataWriter, thus the Topic with which the DataWriter is created. If the DataWriter is already deleted, the NULL pointer is returned.
# 3.4.2.19 lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
lookup_instance
```
```javascript
(const <data>& instance_data);
```
# 3.4.2.20 register\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
register_instance
(const <data>& instance_data);
```
# 3.4.2.21 register\_instance\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
InstanceHandle_t
register_instance_w_timestamp
(const <data>& instance_data,
const Time_t& source_timestamp);
```
# 3.4.2.22 set\_listener
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_listener
(DataWriterListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation attaches a DataWriterListener to the DataWriter.
# Parameters
in DataWriterListener\_ptr a\_listener - a pointer to the DataWriterListener instance, which will be attached to the DataWriter.
in StatusMask mask - a bit mask in which each bit enables the invocation of the DataWriterListener for a certain status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a DataWriterListener to the DataWriter. Only one DataWriterListener can be attached to each DataWriter. If a DataWriterListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated 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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DataWriterListener:
• OFFERED\_DEADLINE\_MISSED\_STATUS
• OFFERED\_INCOMPATIBLE\_QOS\_STATUS
• LIVELINESS\_LOST\_STATUS
• PUBLICATION\_MATCHED\_STATUS.
Be aware that the 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 the description for the
NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return 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 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 which are applicable to the PublisherListener.
# Status Propagation
In case a communication status is not activated in the m as k of th e DataWriterListener, the PublisherListener of the containing Publisher is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the PublisherListener of the containing Publisher and a DataWriter specific behaviour when needed. In case the communication status is not activated in the mask of the PublisherListener as w e l l , t h e 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 DomainParticipantListener of the containing DomainParticipant. In case the 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:
• RETCODE\_OK - the DataWriterListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.4.2.23 set\_qos
# Scope
DDS::DataWriter
# Synopsis
#include <ccpp\_dds\_dcps.h> ReturnCode\_t
```txt
set_qos
(const DataWriterQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DataWriter.
# Parameters
in const DataWriterQos& qos - new set of QosPolicy settings for the DataWriter.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALLREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_IMMUTABLE\_POLICY or RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a 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 DataWriter, which can only be set before the D a t a W r i t 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 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new default DataWriterQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataWriterQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted
• RETCODE\_IMMUTABLE\_POLICY - the parameter qos contains an immutable QosPolicy setting with a different value than set during enabling of the DataWriter.
• RETCODE\_INCONSISTENT\_POLICY - the parameter qos contains an inconsistent QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.
# 3.4.2.24 unregister\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
unregister_instance
(const <data>& instance_data,
InstanceHandle_t handle);
```
# 3.4.2.25 unregister\_instance\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
unregister_instance_w_timestamp
(const <data>& instance_data,
InstanceHandle_t handle,
const Time_t& source_timestamp);
```
# 3.4.2.26 wait\_for\_acknowledgments
# Scope
```autohotkey
DDS::DataWriter
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
wait_for_acknowledgments
(const Duration_t& max_wait);
```
# Description
This operation blocks the calling thread until either all data written by the DataWriter is acknowledged by the local infrastructure, or until the duration specified by max\_wait parameter elapses, whichever happens first.
# Parameters
in const Duration\_t& max\_wait - the maximum duration to block for the wait\_for\_acknowledgments, after which the application thread is unblocked. The special constant DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES, RETCODE\_NOT\_ENABLED or RETCODE\_TIMEOUT.
# Detailed Description
This operation blocks the calling thread until either all data written by the 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 wait\_for\_acknowledgments operation will block until the 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 opera tion will return R E TC O DE \_ OK , in th e latter it will return RETCODE\_TIMEOUT.
Be aware that in case the operation returns 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 will crash). In contrast, if the 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 DataWriter has its ReliabilityQosPolicyKind set to RELIABLE\_RELIABILITY\_QOS. Otherwise the operation will return immediately with 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:
• RETCODE\_OK - the data of the DataWriter has been acknowledged by the local infrastructure.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataWriter is not enabled.
• RETCODE\_TIMEOUT - not all data is acknowledged before max\_wait elapsed.
# 3.4.2.27 write (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
write
(const <data>& instance_data,
InstanceHandle_t handle);
```
# 3.4.2.28 write\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
write_w_timestamp
(const <data>& instance_data,
InstanceHandle_t handle,
const Time_t& source_timestamp);
```
# 3.4.2.29 writedispose (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
writedispose
(const <data>& instance_data,
InstanceHandle_t handle);
```
# 3.4.2.30 writedispose\_w\_timestamp (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataWriter class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
writedispose_w_timestamp
(const <data>& instance_data,
InstanceHandle_t handle,
const Time_t& source_timestamp);
```
# 3.4.2.31 Class FooDataWriter
The pre-processor generates from IDL type descriptions the application <type>DataWriter classes. For each application data type that is used as Topic data type, a typed class <type>DataWriter is derived from the DataWriter class. In this paragraph, the class FooDataWriter in the namespace SPACE describes the operations of these derived <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 ccpp\_Space.h include file.
i General note: The name ccpp\_Space.h is derived from the IDL file Space.idl, that defines SPACE::Foo, for all relevant SPACE::FooDataWriter operations.
A FooDataWriter is attached to exactly one Publisher which acts as a factory for it. The FooDataWriter is bound to exactly one Topic that has been registered to use a data type Foo. The Topic must exist prior to the FooDataWriter creation.
The interface description of this class is as follows:
```cpp
class FooDataWriter
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// inherited from class DataWriter
//
// ReturnCode_t
// set_qos
// (const DataWriterQos& qos);
// ReturnCode_t
// get_qos
// (DataWriterQos& qos);
// ReturnCode_t
// set_listener
// (DataWriterListener_ptr a_listener,
// StatusMask mask);
// DataWriterListener_ptr
// get_listener
// (void);
// Topic_ptr
// get_topic
// (void);
```
```c
// Publisher_ptr
// get_publisher
// (void);
// ReturnCode_t
// wait_for_acknowledgments
// (const Duration_t& max_wait);
// ReturnCode_t
// get_liveliness_lost_status
// (LivelinessLostStatus& status);
// ReturnCode_t
// get_offered_deadline_missed_status
// (OfferedDeadlineMissedStatus& status);
// ReturnCode_t
// get_offered_incompatible_qos_status
// (OfferedIncompatibleQosStatus& status);
// ReturnCode_t
// get_publication_matched_status
// (PublicationMatchedStatus& status);
// ReturnCode_t
// assert_liveliness
// (void);
// ReturnCode_t
// get_matched_subscriptions
// (InstanceHandleSeq& subscription_handles);
// ReturnCode_t
// get_matched_subscription_data
// (SubscriptionBuiltinTopicData& subscription_data,
// InstanceHandle_t subscription_handle);
//
// implemented API operations
//
InstanceHandle_t
register_instance
(const Foo& instance_data);
InstanceHandle_t
register_instance_w_timestamp
(const Foo& instance_data,
const Time_t& time_stamp);
ReturnCode_t
unregister_instance
(const Foo& instance_data,
InstanceHandle_t handle);
```
```txt
ReturnCode_t
unregister_instance_w_timestamp
(const Foo& instance_data,
InstanceHandle_t handle,
const Time_t& time_stamp);
ReturnCode_t
write
(const Foo& instance_data,
InstanceHandle_t handle);
ReturnCode_t
write_w_timestamp
(const Foo& instance_data,
InstanceHandle_t handle,
const Time_t& time_stamp);
ReturnCode_t
dispose
(const Foo& instance_data,
InstanceHandle_t instance_handle);
ReturnCode_t
dispose_w_timestamp
(const Foo& instance_data,
InstanceHandle_t instance_handle,
const Time_t& time_stamp);
ReturnCode_t
writedispose
(const Foo& instance_data,
InstanceHandle_t instance_handle);
ReturnCode_t
writedispose_w_timestamp
(const Foo& instance_data,
InstanceHandle_t instance_handle,
const Time_t& time_stamp);
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
InstanceHandle_t
lookup_instance
(const Foo& instance_data);
};
```
The next paragraphs describe the usage of all 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 assert\_liveliness (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
assert_liveliness
(void);
```
# 3.4.2.33 dispose
# Scope
```txt
SPACE::FooDataWriter
```
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
dispose
(const Foo& instance_data,
InstanceHandle_t instance_handle);
```
# Description
This operation requests the Data Distribution Service to mark the instance for deletion.
# Parameters
in const Foo& instance\_data - the actual instance to be disposed of.
in InstanceHandle\_t instance\_handle - the handle to the instance to be disposed of.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED RETCODE\_PRECONDITION\_NOT\_MET or 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 DataReader and, dependent on the QoSPolicy settings, also in the Transient and Persistent stores, will be marked for deletion by setting their InstanceStateKind to 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 DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.
# Effects on DataReaders
Actual deletion of the instance administration in a connected DataReader will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it.
- A DataWriter can register an instance explicitly by using one of the special operations register\_instance or register\_instance\_w\_timestamp.
- A DataWriter can register an instance implicitly by using the special constant HANDLE\_NIL in any of the other DataWriter operations.
- A DataWriter can unregister an instance explicitly by using one of the special operations unregister\_instance or unregister\_instance\_ w\_timestamp.
- A DataWriter will unregister all its contained instances implicitly when it is deleted.
- When a DataReader detects a loss of liveliness in one of its connected DataWriters, it will consider all instances registered by that 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 take operation, or one of its variants, on its DataReaders.
\- The DataReader can consume disposed samples implicitly when the autopurge\_disposed\_samples\_delay of the ReaderData LifecycleQosPolicy has expired.
The DataReader may also remove instances that haven’t been disposed first: this happens when the autopurge\_nowriter\_samples\_delay of the ReaderDataLifecycleQosPolicy has expired after the instance is considered u n r e g i s t e r e d b y a l l c o n n e c t e d D a t a W r i t e r s ( i . e . w h e n i t h a s a InstanceStateKind of NOT\_ALIVE\_NO\_WRITERS). See also Section 3.1.3.15, ReaderDataLifecycleQosPolicy, on page 71.
# 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 DataWriters that have previously registered it. (See above.)
• and the period of time specified by the service\_cleanup\_delay attribute in the DurabilityServiceQosPolicy on the Topic must have elapsed after the instance is considered unregistered by all connected DataWriters.
See also Section 3.1.3.4, DurabilityServiceQosPolicy, on page 49.
# Instance Handle
The HANDLE\_NIL handle value can be used for the 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 HANDLE\_NIL, it must correspond to the value that was returned by either the register\_instance operation or the register\_instance\_w\_timestamp operation, when the instance (identified by its key) was registered. If there is no correspondence, 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 DataReaders. Use the writedispose operation if the sample itself should be delivered together with the dispose request.
# Blocking
If the HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the dispose operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the ResourceLimitsQosPolicy, to be exceeded. Under these circumstances, the max\_blocking\_time attribute of the ReliabilityQosPolicy configures the maximum time the dispose operation may block (waiting for space to become available). If max\_blocking\_time elapses before the DataWriter is able to store the modification without exceeding the limits, the SPACE\_FooDataWriter\_dispose operation will fail and returns RETCODE\_TIMEOUT.
# Sample Validation
Vortex 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 dispose 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, 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, the operation will fail and return a 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:
• RETCODE\_OK - the Data Distribution Service is informed that the instance data must be disposed of
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - instance\_handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the instance\_handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy. This caused blocking of the dispose operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.34 dispose\_w\_timestamp
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
dispose_w_timestamp
(const Foo& instance_data,
InstanceHandle_t instance_handle,
const 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 const Foo& instance\_data - the actual instance to be disposed of.
in InstanceHandle\_t instance\_handle - the handle to the instance to be disposed of.
in Time\_t source\_timestamp - source\_timestamp is the timestamp which is provided for the DataReader.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, RETCODE_NOT_ENABLED RETCODE_PRECONDITION_NOT_MET or RETCODE_TIMEOUT.
```
# Detailed Description
This operation performs the same functions as dispose except that the application provides the value for the source\_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• RETCODE\_OK - the Data Distribution Service is informed that the instance data must be disposed of
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - instance\_handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the instance\_handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy. This caused blocking of the dispose\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.35 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
enable
(void);
```
# 3.4.2.36 get\_key\_value
# Scope
```txt
SPACE::FooDataWriter
```
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
```
# Description
This operation retrieves the key value of a specific instance.
# Parameters
inout Foo& key\_holder - a reference to the sample in which the key values are stored.
in InstanceHandle\_t handle - the handle to the instance from which to get the key value.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation retrieves the key value of the instance referenced to by instance\_handle. When the operation is called with a HANDLE\_NIL handle 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 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 RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the key\_holder instance contains the key values of the instance;
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - this instance is not registered.
# 3.4.2.37 get\_listener (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
DataWriterListener_ptr
get_listener
(void);
```
# 3.4.2.38 get\_liveliness\_lost\_status (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_liveliness_lost_status
(LivelinessLostStatus& status);
```
# 3.4.2.39 get\_matched\_subscription\_data (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_matched_subscription_data
(SubscriptionBuiltinTopicData& subscription_data,
InstanceHandle_t subscription_handle);
```
# 3.4.2.40 get\_matched\_subscriptions (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_matched_subscriptions
(InstanceHandleSeq& subscription_handles);
```
# 3.4.2.41 get\_offered\_deadline\_missed\_status (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_offered_deadline_missed_status
(OfferedDeadlineMissedStatus& status);
```
# 3.4.2.42 get\_offered\_incompatible\_qos\_status (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_offered_incompatible_qos_status
(OfferedIncompatibleQosStatus& status);
```
# 3.4.2.43 get\_publication\_matched\_status (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_publication_matched_status
(PublicationMatchedStatus& status);
```
# 3.4.2.44 get\_publisher (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
Publisher_ptr
get_publisher
(void);
```
# 3.4.2.45 get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_qos
(DataWriterQos& qos);
```
# 3.4.2.46 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```cpp
#include <cpp_Space.h>
StatusMask
get_status_changes
```
(void);
# 3.4.2.47 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.4.2.48 get\_topic (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
Topic_ptr
get_topic
(void);
```
# 3.4.2.49 lookup\_instance
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <ccpp_Space.h>
InstanceHandle_t
lookup_instance
(const Foo& instance_data);
```
# Description
This operation returns the value of the instance handle which corresponds to the instance\_data.
# Parameters
in const Foo& instance\_data - a reference to the instance for which the corresponding instance handle needs to be looked up.
# Return Value
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 time stamped variants) that operate on a specific instance. Note that DataWriter instance handles are local, and are not interchangeable with DataReader instance handles nor with instance handles of an other DataWriter.
This operation does not register the instance in question. If the instance has not been previously registered, if the 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 HANDLE\_NIL.
# Sample Validation
Vortex 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
```
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 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:
• 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 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 register\_instance
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
InstanceHandle_t
register_instance
(const Foo& instance_data);
```
# Description
This operation informs the Data Distribution Service that the application will be modifying a particular instance.
# Parameters
in const Foo& instance\_data - the instance, which the application writes to or disposes of.
# Return Value
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 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 write, write\_w\_timestamp, unregister\_instance, unregister\_instance\_w\_timestamp, dispose, dispose\_w\_timestamp, writedispose and 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 DataWriter operations. In case of an error, a HANDLE\_NIL handle value is returned.
The explicit use of this operation is optional as the application can directly call the write, write\_w\_timestamp, unregister\_instance, unregister\_instance\_w\_timestamp, dispose, dispose\_w\_timestamp, writedispose and writedispose\_w\_timestamp operations and specify a 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 DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Blocking
If the HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the register\_instance operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the 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 t yQ 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 register\_instance operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the register\_instance operation will fail and returns HANDLE\_NIL.
# Sample Validation
Vortex 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 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:
• 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 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 register\_instance\_w\_timestamp
# Scope
```txt
SPACE::FooDataWriter
```
# Synopsis
```c
#include <cpp_Space.h>
InstanceHandle_t
register_instance_w_timestamp
(const Foo& instance_data,
const 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 Foo instance\_data - the instance, which the application will write to or dispose of.
in const Time\_t& source\_timestamp - the timestamp used.
# Return Value
InstanceHandle\_t - Result value is the handle to the Instance, which must be used for writing and disposing. In case of an error, a HANDLE\_NIL handle value is returned.
# Detailed Description
This operation performs the same functions as register\_instance except that the application provides the value for the source\_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Multiple Calls
If this operation is called for an already registered instance, it just returns the already allocated instance handle. The source\_timestamp is ignored in that case.
# 3.4.2.52 set\_listener (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
set_listener
(DataWriterListener_ptr a_listener, StatusMask mask);
```
# 3.4.2.53 set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
set_qos
(const DataWriterQos& qos);
```
# 3.4.2.54 unregister\_instance
# Scope
```txt
SPACE::FooDataWriter
```
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
unregister_instance
(const Foo& instance_data,
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 const Foo& instance\_data - the instance to which the application was writing or disposing.
in InstanceHandle\_t handle - the handle to the instance, which has been used for writing and disposing.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or 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 register\_instance or register\_instance\_w\_timestamp. It should only be called on an instance that is currently registered. This operation should be called just once per instance, regardless of how many times 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 DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Effects
If, after unregistering, the application wants to modify (write or dispose) the instance, it has to register the instance again, or it has to use the special handle value HANDLE\_NIL.
This operation does not indicate that the instance should be deleted (that is the purpose of dispose). This operation just indicates that the DataWriter no longer has “anything to say” about the instance. If there is no other DataWriter that has registered the instance as well, then the InstanceStateKind in all connected DataReaders will be changed to NOT\_ALIVE\_NO\_WRITERS\_ INSTANCE\_STATE, p r o v i d e d t h i s I n s t a n ce S t a t e Ki n d w a s n o t a l r e a dy s e t t o NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE. In the last case the InstanceStateKind will not be effected by the unregister\_instance call, see also Figure 21, State Chart of the instance\_state for a Single Instance, on page 566.
This operation can affect the ownership of the data instance. If the 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, DataWriter.
The operation must be called only on registered instances. Otherwise the operation returns the error RETCODE\_PRECONDITION\_NOT\_MET.
# Instance Handle
The 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 HANDLE\_NIL, then it must correspond to the value returned by register\_instance or register\_instance\_w\_timestamp when the instance (identified by its key) was registered. If there is no correspondence, 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 DataReaders.
# Blocking
If the HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the unregister\_instance operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the 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 t yQ 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 unregister\_instance operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the unregister\_instance operation will fail and returns RETCODE\_TIMEOUT.
# Sample Validation
Vortex 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 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, 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, the operation will fail and return a 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:
• RETCODE\_OK - the Data Distribution Service is informed that the instance will not be modified any more
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the unregister\_instance operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.55 unregister\_instance\_w\_timestamp
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
unregister_instance_w_timestamp
(const Foo& instance_data,
InstanceHandle_t handle,
const 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 Foo instance\_data - the instance to which the application was writing or disposing.
in InstanceHandle\_t handle - the handle to the instance, which has been used for writing and disposing.
in const Time\_t& source\_timestamp - the timestamp used.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_TIMEOUT.
# Detailed Description
This operation performs the same functions as unregister\_instance except that the application provides the value for the source\_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• RETCODE\_OK - the Data Distribution Service is informed that the instance will not be modified any more
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the unregister\_instance\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.56 wait\_for\_acknowledgments (inherited)
This operation is inherited and therefore not described here. See the class DataWriter for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
wait_for_acknowledgments
(const Duration_t& max_wait);
```
# 3.4.2.57 write
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
write
(const Foo& instance_data,
InstanceHandle_t handle);
```
# Description
This operation modifies the value of a data instance.
# Parameters
in const Foo& instance\_data - the data to be written.
in InstanceHandle\_t handle - the handle to the instance as supplied by register\_instance.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or 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 DataReader objects. 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 DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.
Before writing data to an instance, the instance may be registered with the register\_instance or register\_instance\_w\_timestamp operation. The handle returned by one of the register\_instance operations can be supplied to the parameter handle of the write operation. However, it is also possible to supply the special 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 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 HANDLE\_NIL, it must correspond to the value returned by register\_instance or 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 HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the write operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the ResourceLimitsQosPolicy, is 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 write operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the write operation will fail and returns RETCODE\_TIMEOUT.
# Sample Validation
Vortex 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 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.
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:
• RETCODE\_OK - the value of a data instance is modified
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the write operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.58 write\_w\_timestamp
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
write_w_timestamp
(const Foo& instance_data,
InstanceHandle_t handle,
const 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 const Foo& instance\_data - the data to be written.
in InstanceHandle\_t handle - the handle to the instance as supplied by register\_instance.
in const Time\_t& source\_timestamp - the timestamp used.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_TIMEOUT.
# Detailed Description
This operation performs the same functions as write except that the application provides the value for the parameter source\_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• RETCODE\_OK - the value of a data instance is modified
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders.
This caused blocking of the write\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.59 writedispose
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
writedispose
(const Foo& instance_data,
InstanceHandle_t handle);
```
# Description
This operation modifies and disposes a data instance.
# Parameters
in const Foo& instance\_data - the data to be written and disposed.
in InstanceHandle\_t handle - the handle to the instance as supplied by register\_instance.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or 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 DataReader and, dependent on the QoSPolicy settings, also in the Transient and Persistent stores, will be modified and marked for deletion by setting their InstanceStateKind to 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 DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.
# Effects on DataReaders
Actual deletion of the instance administration in a connected DataReader will be postponed until the following conditions have been met:
• the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it.
- A DataWriter can register an instance explicitly by using one of the special operations register\_instance or register\_instance\_w\_timestamp.
- A DataWriter can register an instance implicitly by using the special constant HANDLE\_NIL in any of the other DataWriter operations.
- A DataWriter can unregister an instance explicitly by using one of the special operations unregister\_instance or unregister\_instance\_ w\_timestamp.
- A DataWriter will unregister all its contained instances implicitly when it is deleted.
- When a DataReader detects a loss of liveliness in one of its connected DataWriters, it will consider all instances registered by that 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 take operation, or one of its variants, on its DataReaders.
\- The DataReader can consume disposed samples implicitly when the autopurge\_disposed\_samples\_delay of the ReaderData LifecycleQosPolicy has expired.
The DataReader may also remove instances that haven’t been disposed first: this happens when the autopurge\_nowriter\_samples\_delay of the ReaderDataLifecycleQosPolicy has expired after the instance is considered u n r e g i s t e r e d b y a l l c o n n e c t e d D a t a W r i t e r s ( i . e . w h e n i t h a s a InstanceStateKind of NOT\_ALIVE\_NO\_WRITERS). See also Section 3.1.3.15, ReaderDataLifecycleQosPolicy, on page 71.
# 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 DataWriters that have previously registered it. (See above.)
• and the period of time specified by the service\_cleanup\_delay attribute in the DurabilityServiceQosPolicy on the Topic must have elapsed after the instance is considered unregistered by all connected DataWriters.
See also Section 3.1.3.4, DurabilityServiceQosPolicy, on page 49.
# Instance Handle
The 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 HANDLE\_NIL, it must correspond to the value that w a s r e t u r n e d b y e i t h e r t h e r e g i s t e r \_ i n s t a n c e o p e r a t i o n o r t h e register\_instance\_w\_timestamp operation, when the instance (identified by its key) was registered. If there is no correspondence, the result of the operation is unspecified.
The sample that is passed as instance\_data will actually be delivered to the connected DataReaders, but will immediately be marked for deletion.
# Blocking
If the HistoryQosPolicy is set to KEEP\_ALL\_HISTORY\_QOS, the writedispose operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the 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 ReliabilityQosPolicy configures the maximum time the writedispose operation may block (either waiting for space to become available or data to be acknowledged). If max\_blocking\_time elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the writedispose operation will fail and returns RETCODE\_TIMEOUT.
# Sample Validation
Vortex 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 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.
# 小
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:
• RETCODE\_OK - the Data Distribution Service has modified the instance and marked it for deletion.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the writedispose operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.2.60 writedispose\_w\_timestamp
# Scope
SPACE::FooDataWriter
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
writedispose_w_timestamp
(const Foo& instance_data,
InstanceHandle_t handle,
const 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
in const Foo& instance\_data - the data to be written and disposed.
in InstanceHandle\_t handle - the handle to the instance as supplied by register\_instance.
in const Time\_t& source\_timestamp - the timestamp used.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_TIMEOUT.
# Detailed Description
This operation performs the same functions as writedispose except that the application provides the value for the source\_timestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
# Return Code
When the operation returns:
• RETCODE\_OK - the Data Distribution Service has modified the instance and marked it for deletion.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle or instance\_data is not a valid sample.
• RETCODE\_ALREADY\_DELETED - the FooDataWriter has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataWriter is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - the handle has not been registered with this SPACE\_FooDataWriter.
• RETCODE\_TIMEOUT - either the current action overflowed the available resources as specified by the combination of the ReliabilityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgement by synchronous DataReaders. This caused blocking of the writedispose\_w\_timestamp operation, which could not be resolved before max\_blocking\_time of the ReliabilityQosPolicy elapsed.
# 3.4.3 PublisherListener Interface
Since a Publisher is an Entity, it has the ability to have a Listener associated w i t h i t . I n t h i s c a s e , t h e a s s o c i a t e d L i s t e n e r s h o u l d b e o f t y p e PublisherListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the PublisherListener class. All 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 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 PublisherListener is related to changes in communication status.
The interface description of this class is as follows:
```cpp
class PublisherListener {
//
// inherited from DataWriterListener
//
// void
// on_offered_deadline_missed
// (DataWriter_ptr writer,
// const OfferedDeadlineMissedStatus& status) = 0;
// void
// on_offered_incompatible_qos
// (DataWriter_ptr writer,
// const OfferedIncompatibleQosStatus& status) = 0;
// void
// on_liveliness_lost
// (DataWriter_ptr writer,
// const LivelinessLostStatus& status) = 0;
// void
// on_publication_matched
// (DataWriter_ptr writer,
// const PublicationMatchedStatus& status) = 0;
//
// implemented API operations
// <no operations>
//
};
```
The next paragraphs list all 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 on\_liveliness\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_lost
(DataWriter_ptr writer,
const LivelinessLostStatus& status) = 0;
```
# 3.4.3.2 on\_offered\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_deadline_missed
(DataWriter_ptr writer,
const OfferedDeadlineMissedStatus& status) = 0;
```
# 3.4.3.3 on\_offered\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_incompatible_qos
(DataWriter_ptr writer,
const OfferedIncompatibleQosStatus& status) = 0;
```
# 3.4.3.4 on\_publication\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataWriterListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_publication_matched
(DataWriter_ptr writer,
const PublicationMatchedStatus& status) = 0;
```
# 3.4.4 DataWriterListener Interface
Since a DataWriter is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DataWriterListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DataWriterListener class. All 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.
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 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 DataWriterListener is related to changes in communication status.
The interface description of this class is as follows:
```cpp
class DataWriterListener
{
// abstract external operations
void
on_offered_deadline_missed
(DataWriter_ptr writer,
const OfferedDeadlineMissedStatus& status) = 0;
void
on_offered_incompatible_qos
(DataWriter_ptr writer,
const OfferedIncompatibleQosStatus& status) = 0;
void
on_liveliness_lost
(DataWriter_ptr writer,
const LivelinessLostStatus& status) = 0;
void
on_publication_matched
(DataWriter_ptr writer,
const PublicationMatchedStatus& status) = 0;
// implemented API operations
// <no operations>
};
```
The next paragraphs describe the usage of all DataWriterListener operations. These abstract operations are fully described because they must be implemented by the application.
# 3.4.4.1 on\_liveliness\_lost (abstract)
# Scope
DDS::DataWriterListener
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_liveliness_lost
(DataWriter_ptr writer,
const LivelinessLostStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the LivelinessLostStatus changes.
# Parameters
in DataWriter\_ptr writer - contains a pointer to the DataWriter on which the LivelinessLostStatus has changed (this is an input to the application).
in const LivelinessLostStatus& status - contains the 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 LivelinessLostStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataWriterListener is installed and enabled for the liveliness lost status. The liveliness lost status will change when the liveliness that the DataWriter has committed through its LivelinessQosPolicy was not respected. In other words, the DataWriter failed to actively signal its liveliness within the offered liveliness period. As a result, the DataReader objects will consider the DataWriter as no longer “alive”.
The Data Distribution Service will call the DataWriterListener operation with a parameter writer, which will contain a reference to the DataWriter on which the confl ict oc curr ed and a par ame ter s t a t u s , w h i c h w i l l c o n t a i n t h e LivelinessLostStatus struct.
# 3.4.4.2 on\_offered\_deadline\_missed (abstract)
# Scope
```txt
DDS::DataWriterListener
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_deadline_missed
(DataWriter_ptr writer,
const OfferedDeadlineMissedStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the OfferedDeadlineMissedStatus changes.
# Parameters
in DataWriter\_ptr writer - contain a pointer to the DataWriter on which the OfferedDeadlineMissedStatus has changed (this is an input to the application).
in const OfferedDeadlineMissedStatus& status - contain the 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 OfferedDeadlineMissedStatus changes. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant DataWriterListener is installed and enabled for the offered deadline missed status. The offered deadline missed status will change when the deadline that the DataWriter has committed through its DeadlineQosPolicy was not respected for a specific instance.
The Data Distribution Service will call the DataWriterListener operation with a parameter writer, which will contain a reference to the DataWriter on which the confl ict oc curr ed and a par ame ter s t a t u s , w h i c h w i l l c o n t a i n t h e OfferedDeadlineMissedStatus struct.
# 3.4.4.3 on\_offered\_incompatible\_qos (abstract)
# Scope
```txt
DDS::DataWriterListener
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_offered_incompatible_qos
(DataWriter_ptr writer,
const OfferedIncompatibleQosStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the OFFERED\_INCOMPATIBLE\_QOS\_STATUS changes.
# Parameters
in DataWriter\_ptr writer - contain a pointer to the DataWriter on which the OFFERED\_INCOMPATIBLE\_QOS\_STATUS has changed (this is an input to the application).
in const OfferedIncompatibleQosStatus& status - contain the OfferedIncompatibleQosStatus struct (this is an input to the application).
# 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 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 DataWriterListener is installed and enabled for the OFFERED\_INCOMPATIBLE\_QOS\_STATUS. The incompatible Qos status will change when a DataReader object has been discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter.
The Data Distribution Service will call the DataWriterListener operation with a parameter writer, which will contain a reference to the DataWriter on which the confl ict oc curr ed and a par ame ter s t a t u s , w h i c h w i l l c o n t a i n t h e OfferedIncompatibleQosStatus struct.
# 3.4.4.4 on\_publication\_matched (abstract)
# Scope
DDS::DataWriterListener
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
void
on_publication_matched
(DataWriter_ptr writer,
const PublicationMatchedStatus& status) = 0;
```
# 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
in DataWriter\_ptr writer - contains a pointer to the DataWriter for which a match has been discovered (this is an input to the application provided by the Data Distribution Service).
in const PublicationMatchedStatus& status - contains the PublicationMatchedStatus struct (this is an input to the application provided by the Data Distribution Service).
# Return Value
<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 DataWriter has either been discovered, or that a previously discovered DataReader has ceased to be matched to the current 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 DataWriter or when either the DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the ignore\_subcription or ignore\_publication operations on the DomainParticipant.
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 a ta W r i t e r Li s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e PUBLICATION\_MATCHED\_STATUS.
The Data Distribution Service will provide a pointer to the DataWriter in the parameter writer and the PublicationMatchedStatus struct in the parameter status for use by the application.
# 3.5 Subscription Module
Figure 19 DCPS Subscription Module’s Class Model
This module contains the following classes:
• Subscriber
• Subscription type specific classes
• DataSample
• SampleInfo (struct)
• SubscriberListener (interface)
• DataReaderListener (interface)
• ReadCondition
• 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 <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) “Subscription type specific classes” contains the following classes:
• DataReader (abstract)
• FooDataReader
• DataReaderView (abstract)
• FooDataReaderView
A Subscriber is an object responsible for receiving published data and making it available (according to the SubscriberQos) to the application. It may receive and dispatch Topic with data of different specified data types. To access the received data, the application must use a typed DataReader attached to the Subscriber. Thus, a subscription is defined by the association of a DataReader with a Subscriber. This association expresses the intent of the application to subscribe to the data described by the DataReader in the context provided by the Subscriber.
# 3.5.1 Class Subscriber
A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions.
A Subscriber acts on behalf of one or more DataReader objects that are related to it. When it receives data (from the other parts of the system), it indicates to the application that data is available through its DataReaderListener and by enabling related Conditions. The application can access the list of concerned DataReader objects through the operation get\_datareaders and then access the data available through operations on the DataReader.
The interface description of this class is as follows:
```cpp
class Subscriber
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
```
```c
// implemented API operations
//
DataReader_ptr
create_datareader
(TopicDescription_ptr a_topic,
const DataReaderQos& qos,
DataReaderListener_ptr a_listener,
StatusMask mask);
ReturnCode_t
delete_datareader
(DataReader_ptr a_datareader);
ReturnCode_t
delete_contained_entities
(void);
DataReader_ptr
lookup_datareader
(const char* topic_name);
ReturnCode_t
get_datareaders
(DataReaderSeq& readers,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
notify_datareaders
(void);
ReturnCode_t
set_qos
(const SubscriberQos& qos);
ReturnCode_t
get_qos
(SubscriberQos& qos);
ReturnCode_t
set_listener
(SubscriberListener_ptr a_listener,
StatusMask mask);
SubscriberListener_ptr
get_listener
(void);
ReturnCode_t
begin_access
```
```txt
(void);
ReturnCode_t
end_access
(void);
DomainParticipant_ptr
get_participant
(void);
ReturnCode_t
set_default_datareader_qos
(const DataReaderQos& qos);
ReturnCode_t
get_default_datareader_qos
(DataReaderQos& qos);
ReturnCode_t
copy_from_topic_qos
(DataReaderQos& a_datareader_qos,
const TopicQos& a_topic_qos);
};
```
The next paragraphs describe the usage of all 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 begin\_access
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
begin_access
(void);
```
# 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 Subscriber. The access will be completed by a matching call to end\_access.
# Parameters
```txt
<none>
```
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR or 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 RETCODE\_ERROR. See Section 3.5.1.6, 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 ‘GROUP’. In the aforementioned case, the operation begin\_access must be called p r i o r t o c a l l i n g a n y o f t h e 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 , n a m e l y : get\_datareaders on the Subscriber and read, take, and all their variants on any DataReader. Otherwise the sample-accessing operations will return the error RETCODE\_PRECONDITION\_NOT\_MET. Once the application has finished accessing the data samples it must call 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:
• RETCODE\_OK - access to coherent/ordered data has successfully started.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
# 3.5.1.2 copy\_from\_topic\_qos
# Scope
DDS::Subscriber
# Synopsis
#include <ccpp\_dds\_dcps.h>
```txt
ReturnCode_t
copy_from_topic_qos
(DataReaderQos& a_datareader_qos,
const TopicQos& a_topic_qos);
```
# Description
This operation will copy the policies in a\_topic\_qos to the corresponding policies in a\_datareader\_qos.
# Parameters
inout DataReaderQos& a\_datareader\_qos - the destination DataReaderQos struct to which the QosPolicy settings will be copied.
in const TopicQos& a\_topic\_qos - the source TopicQos, which will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or 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 get\_default\_datawriter\_qos and Topic::get\_qos. The operation copy\_from\_topic\_qos can be used to merge the DataReader default QosPolicy settings with the corresponding ones on the Topic. The resulting DataReaderQos can then be used to create a new DataReader, or set its 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 DataReaderQos to the DataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - the QosPolicy settings have successfully been copied from the TopicQos to the DataReaderQos
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.3 create\_datareader
# Scope
```autohotkey
DDS::Subscriber
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DataReader_ptr
create_datareader
(TopicDescription_ptr a_topic,
const DataReaderQos& qos,
DataReaderListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation creates a DataReader with the desired QosPolicy settings, for the d e s i r e d T o p i c D e s c r i p t i o n a n d a t t a c h e s t h e o p t i o n a l l y s p e c i f i e d DataWriterListener to it.
# Parameters
in TopicDescription\_ptr a\_topic - a pointer to the TopicDescription for which the DataReader is created. This may be a Topic, MultiTopic or ContentFilteredTopic.
in const DataReaderQos& qos - the struct with the QosPolicy settings for the new DataReader, when these QosPolicy settings are not self consistent, no DataReader is created.
in DataReaderListener\_ptr a\_listener - a pointer to the DataReaderListener instance which will be attached to the new DataReader. It is permitted to use NULL as the value of the listener: this behaves as a DataWriterListener whose operations perform no action.
in StatusMask mask - a bit-mask in which each bit enables the invocation of the DataReaderListener for a certain status.
# Return Value
DataReader\_ptr - a pointer to the newly created DataReader. In case of an error, the NULL pointer is returned.
# Detailed Description
This operation creates a DataReader with the desired QosPolicy settings, for the d e s i r e d T o p i c D e s c r i p t i o n a n d a t t a c h e s t h e o p t i o n a l l y s p e c i f i e d DataReaderListener to it. The TopicDescription may be a Topic, MultiTopic or ContentFilteredTopic. The returned DataReader is attached (and belongs) to the Subscriber. To delete the DataReader the operation delete\_datareader or 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 DataReader returned by this operation is an object of a derived class, specific to the data type associated with the TopicDescription. For each application-defined data type <type> there is a class <type>DataReader generated by calling the pre-processor. This data type specific class extends DataReader and contains the operations to read data of data type <type>.
Because the DataReader may read a Topic, ContentFilteredTopic or MultiTopic, the DataReader is associated with the TopicDescription. The DataWriter can only write a Topic, not a ContentFilteredTopic or MultiTopic, because these two are constructed at the Subscriber side.
# QosPolicy
The common application pattern to construct the QosPolicy settings for the DataReader is to:
• Retrieve the QosPolicy settings on the associated TopicDescription by means of the get\_qos operation on the TopicDescription
• Retrieve the default DataReaderQos by means of the get\_default\_datareader\_qos operation on the Subscriber
• Combine those two QosPolicy settings and selectively modify policies as desired (copy\_from\_topic\_qos)
• Use the resulting QosPolicy settings to construct the DataReader.
• In case the specified QosPolicy settings are not self consistent, no DataReader is created and the NULL pointer is returned.
# Default QoS
The constant DATAREADER\_QOS\_DEFAULT can be used as parameter qos to create a DataReader with the default DataReaderQos as set in the Subscriber. The effect of using DATAREADER\_QOS\_DEFAULT is the same as calling the operation get\_default\_datareader\_qos and using the resulting DataReaderQos to create the DataReader.
The special DATAREADER\_QOS\_USE\_TOPIC\_QOS can be used to create a DataReader with a combination of the default DataReaderQos and the TopicQos. The effect of using DATAREADER\_QOS\_USE\_TOPIC\_QOS is the same as calling the operation get\_default\_datareader\_qos and retrieving the TopicQos (by means of the operation Topic::get\_qos) and then combining these two QosPolicy settings using the operation copy\_from\_topic\_qos, whereby any common policy that is set on the TopicQos “overrides” the corresponding policy on the default DataReaderQos. The resulting DataReaderQos is then applied to create the 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 communication status activated in the mask, the associated 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 DataReaderListener:
• REQUESTED\_DEADLINE\_MISSED\_STATUS
• REQUESTED\_INCOMPATIBLE\_QOS\_STATUS
• SAMPLE\_LOST\_STATUS
• SAMPLE\_REJECTED\_STATUS
• DATA\_AVAILABLE\_STATUS
• LIVELINESS\_CHANGED\_STATUS
• SUBSCRIPTION\_MATCHED\_STATUS.
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return NULL.
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 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 which are applicable to the PublisherListener.
# Status Propagation
In case a communication status is not activated in the m a sk of the DataReaderListener, the SubscriberListener of the containing Subscriber is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the SubscriberListener of the containing Subscriber and a DataReader specific behaviour when needed. In case the communication status is not activated in the mask of the SubscriberListener as well, the communication status will be propagated to the DomainParticipantListener of the containing DomainParticipant. In case the 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 delete\_contained\_entities
# Scope
DDS::Subscriber
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all the DataReader objects that were created by means of the create\_datareader operation on the Subscriber.
# Parameters
<none>
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation deletes all the DataReader objects that were created by means of the create\_datareader operation on the Subscriber. In other words, it deletes all contained DataReader objects. Prior to deleting each DataReader, this operation recursively calls the corresponding delete\_contained\_entities operation on each DataReader. In other words, all DataReader objects in the Subscriber are deleted, including the QueryCondition and ReadCondition objects contained by the DataReader.
NOTE: The operation will return 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 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:
• RETCODE\_OK - the contained Entity objects are deleted and the application may delete the Subscriber;
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.5.1.5 delete\_datareader
# Scope
DDS::Subscriber
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_datareader
(DataReader_ptr a_datareader);
```
# Description
This operation deletes a DataReader that belongs to the Subscriber.
# Parameters
in DataReader\_ptr a\_datareader - a pointer to the DataReader, which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation deletes a DataReader that belongs to the Subscriber. When the operation is called on a different Subscriber as used when the DataReader was c r e a t e d , 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 RETCODE\_PRECONDITION\_NOT\_MET. The deletion of the DataReader is not allowed if there are any ReadCondition or QueryCondition objects that are attached to the DataReader, or when the DataReader still contains unreturned l o a n s . I n t h o s e c a s e s t h e o p e r a t i o n a l s o r e t u r n s RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the DataReader is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_datareader is not a valid DataReader\_ptr
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different Subscriber as used when the DataReader was created, the DataReader contains one or more ReadCondition or QueryCondition objects or the DataReader still contains unreturned loans.
# 3.5.1.6 enable (inherited)
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# Description
This operation is inherited. See the Section 3.1.1, Class 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, begin\_access, and Section 3.5.1.7, 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 end\_access
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
end_access
(void);
```
# 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 Subscriber. This access must have been started by a matching call to begin\_access. Section 3.5.1.6, enable (inherited), contains additional information about coherent access.
# Parameters
```txt
<none>
```
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or 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.
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:
• RETCODE\_OK - access to coherent/ordered data has successfully started.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_PRECONDITION\_NOT\_MET - no matching call to begin\_access has been detected.
# 3.5.1.8 get\_datareaders
# Scope
DDS::Subscriber
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_datareaders
(DataReaderSeq& readers,
SampleStateMask sample_states,
ViewStateMask view_states,
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
inout 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 SampleStateMask sample\_states - a mask, which selects only those readers that have samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those readers that have samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those readers that have samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_ OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED or 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 RETCODE\_PRECONDITION\_NOT\_MET.
Depending on the setting of the PresentationQoSPolicy (see Section 3.1.3.14 on page 64), 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, PresentationQosPolicy, on page 64.
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:
• RETCODE\_OK - a list of DataReaders matching your description has successfully been composed.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the Subscriber is not enabled.
• 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 get\_default\_datareader\_qos
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_default_datareader_qos
(DataReaderQos& qos);
```
# Description
This operation gets the default QosPolicy settings of the DataReader.
# Parameters
inout DataReaderQos& qos - a reference to the DataReaderQos struct (provided by the application) in which the default QosPolicy settings for the DataReader are written.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation gets the default QosPolicy settings of the DataReader (that is the DataReaderQos) which is used for newly created DataReader objects, in case the constant DATAREADER\_QOS\_DEFAULT is used. The default DataReaderQos is only used when the constant is supplied as parameter qos to specify the DataReaderQos in the create\_datareader operation. The application must provide the DataReaderQos struct in which the QosPolicy settings can be stored and pass the qos reference to the operation. The operation writes the default QosPolicy settings to the struct referenced 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 set\_default\_datareader\_qos, or, if the call was never made, the default values as specified for each QosPolicy setting as defined in Table 2 on page 38.
# Return Code
When the operation returns:
• RETCODE\_OK - the default DataReader QosPolicy settings of this Subscriber have successfully been copied into the specified DataReaderQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.10 get\_listener
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
SubscriberListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a SubscriberListener.
# Parameters
```txt
<none>
```
# Return Value
SubscriberListener\_ptr - result is a pointer to the SubscriberListener attached to the Subscriber.
# Detailed Description
This operation allows access to a SubscriberListener attached to the Subscriber. When no SubscriberListener was attached to the Subscriber, the NULL pointer is returned.
# 3.5.1.11 get\_participant
# Scope
```autohotkey
DDS::Subscriber
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DomainParticipant_ptr
get_participant
(void);
```
# Description
This operation returns the DomainParticipant associated with the Subscriber or the NULL pointer.
# Parameters
```txt
<none>
```
# Return Value
DomainParticipant\_ptr - a pointer to the DomainParticipant associated with the Subscriber or the NULL pointer.
# Detailed Description
This operation returns the DomainParticipant associated with the Subscriber. Note that there is exactly one DomainParticipant associated with each Subscriber. When the Subscriber was already deleted (there is no associated DomainParticipant any more), the NULL pointer is returned.
# 3.5.1.12 get\_qos
# Scope
```autohotkey
DDS::Subscriber
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_qos
(SubscriberQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a Subscriber.
# Parameters
inout SubscriberQos& qos - a reference to the destination SubscriberQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a Subscriber on which this operation is used. This SubscriberQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoS policy values applied to this Subscriber has successfully been copied into the specified SubscriberQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.13 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.5.1.14 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.5.1.15 lookup\_datareader
# Scope
```autohotkey
DDS::Subscriber
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DataReader_ptr
lookup_datareader
(const char* topic_name);
```
# Description
This operation returns a previously created DataReader belonging to the Subscriber which is attached to a Topic with the matching topic\_name.
# Parameters
in const char\* topic\_name - the name of the Topic, which is attached to the DataReader to look for.
# Return Value
DataReader\_ptr - Return value is a reference to the DataReader found. When no such DataReader is found, the NULL pointer is returned.
# Detailed Description
This operation returns a previously created DataReader belonging to the Subscriber which is attached to a Topic with the matching topic\_name. When multiple 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 Subscriber, which returns the built-in DataReader objects for the built-in Topics.
# 3.5.1.16 notify\_datareaders
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
notify_datareaders
(void);
```
# Description
T h i s o p e ra ti o n in v o k e s t h e o n \_d a t a \_ a va i l a b l e op e r a t i on o n DataReaderListener objects which are attached to the contained DataReader entities having new, available data.
# Parameters
<none>
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED or RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation invokes the on\_data\_available operation on the DataReaderListener objects attached to contained DataReader entities that have received information, but which have not yet been processed by those DataReaders.
The notify\_datareaders operation ignores the bit mask value of individual DataReaderListener objects, even when the DATA\_AVAILABLE\_STATUS bit has not been set on a DataReader that has new, available data. The o n \_d a t a \_ a v ai l a b l e o p e r a t io n w il l s t i l l b e i n v o k e d , w h e n t h e DATA\_AVAILABLE\_STATUS bit has not been set on a DataReader, but will not propagate to the DomainParticipantListener.
When the DataReader has attached a NULL listener, the event will be consumed and will not propagate to the 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:
• RETCODE\_OK - all appropriate listeners have been invoked
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - there are insufficient Data Distribution Service resources to complete this operation
# 3.5.1.17 set\_default\_datareader\_qos
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_default_datareader_qos
(const DataReaderQos& qos);
```
# Description
This operation sets the default DataReaderQos of the DataReader.
# Parameters
in const DataReaderQos& qos - the DataReaderQos struct, which contains the new default QosPolicy settings for the newly created DataReaders.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER, RETCODE_UNSUPPORTED, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_INCONSISTENT_POLICY.
```
# Detailed Description
This operation sets the default DataReaderQos of the DataReader (that is the struct with the QosPolicy settings). This QosPolicy is used for newly created DataReader objects in case the constant DATAREADER\_QOS\_DEFAULT is used as parameter qos to specify the DataReaderQos in the create\_datareader operation. This operation checks if the DataReaderQos is self consistent. If it is not, the operation has no effect and returns RETCODE\_INCONSISTENT\_POLICY.
The values set by this operation are returned by get\_default\_datareader\_qos.
# Return Code
When the operation returns:
• RETCODE\_OK - the new default DataReaderQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataReaderQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• 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 set\_listener
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_listener
(SubscriberListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation attaches a SubscriberListener to the Subscriber.
# Parameters
in SubscriberListener\_ptr a\_listener - a pointer to the SubscriberListener instance, which will be attached to the Subscriber.
in StatusMask mask - a bit mask in which each bit enables the invocation of the SubscriberListener for a certain status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a SubscriberListener to the Subscriber. Only one SubscriberListener can be attached to each Subscriber. If a SubscriberListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated 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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the SubscriberListener:
• REQUESTED\_DEADLINE\_MISSED\_STATUS (propagated)
• REQUESTED\_INCOMPATIBLE\_QOS\_STATUS (propagated)
• SAMPLE\_LOST\_STATUS (propagated)
• SAMPLE\_REJECTED\_STATUS (propagated)
• DATA\_AVAILABLE\_STATUS (propagated)
• LIVELINESS\_CHANGED\_STATUS (propagated)
• SUBSCRIPTION\_MATCHED\_STATUS (propagated).
• DATA\_ON\_READERS\_STATUS.
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return 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 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 which are applicable to the PublisherListener.
# 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 DataReaderListener of a contained DataReader, the DataReaderListener on that contained DataReader is invoked instead of the SubscriberListener. This means that a status change on a contained DataReader only invokes the SubscriberListener if the contained 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 SubscriberListener, the DomainParticipantListener of the containing DomainParticipant is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the DomainParticipantListener of the containing DomainParticipant and a S u b s c r i b e r s p e c i f i c b e h a v i o u r w h e n n e e d e d . I n c a s e t h e 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 DATA\_ON\_READERS\_STATUS and 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 D i s t r i b u t i o n S e r v i c e w i l l f i r s t l o o k i n a n a t t a c h e d a n d a c t i v a t e d SubscriberListener or DomainParticipantListener (in that order) for the DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener or DomainParticipant Listener for the DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• RETCODE\_OK - the SubscriberListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• RETCODE\_ALREADY\_DELETED - the Subscriber has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.1.19 set\_qos
# Scope
DDS::Subscriber
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const SubscriberQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a Subscriber.
# Parameters
in const SubscriberQos& qos - new set of QosPolicy settings for the Subscriber.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_IMMUTABLE\_POLICY or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a Subscriber. 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 Subscriber, which can only be set before the Subscriber is enabled, the operation will fail and a 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 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 RETCODE\_PRECONDITION\_NOT\_MET error code.
# Return Code
When the operation returns:
• RETCODE\_OK - the new SubscriberQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid SubscriberQos. It contains a QosPolicy setting with an enum value that is outside its legal boundaries.
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the Subscriber 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 different value than set during enabling of the Subscriber.
• 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 <type>DataReader is generated (based on IDL) by calling the pre-processor. In case of data type Foo (this also applies to other types); “Subscription type specific classes” contains the following classes:
This paragraph describes the generic DataReader class and the derived application type specific <type>DataReader classes which together implement the application subscription interface. For each application type, used as Topic data type, the pre-processor generates a <type>DataReader class from an IDL type description. The FooDataReader class that would be generated by the pre-processor for a fictional type Foo describes the <type>DataReader classes.
# 3.5.2.1 Class DataReader (abstract)
A DataReader allows the application:
• to declare data it wishes to receive (i.e., make a subscription)
• to access data received by the associated Subscriber.
A DataReader refers to exactly one TopicDescription (either a Topic, a ContentFilteredTopic or a MultiTopic) that identifies the samples to be read. The DataReader may give access to several instances of the data type, which are distinguished from each other by their key.
DataReader 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::FooDataReader.
The interface description of this class is as follows:
```cpp
class DataReader
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// abstract operations (implemented in the data type
// specific DataReader)
```
```c
//
// ReturnCode_t
// read
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// take
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// read_w_condition
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// ReadCondition a_condition);
// ReturnCode_t
// take_w_condition
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// ReadCondition a_condition);
// ReturnCode_t
// read_next_sample
// (<data>& data_values,
// SampleInfo sample_info);
// ReturnCode_t
// take_next_sample
// (<data>& data_values,
// SampleInfo sample_info);
// ReturnCode_t
// read_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// take_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
```
```c
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// read_next_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// take_next_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// ReturnCode_t
// read_next_instance_w_condition
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// ReadCondition a_condition);
// ReturnCode_t
// take_next_instance_w_condition
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// ReadCondition a_condition);
// ReturnCode_t
// return_loan
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq);
// ReturnCode_t
// get_key_value
// (<data>& key_holder,
// InstanceHandle_t handle);
// InstanceHandle_t
// lookup_instance
// (const <data>& instance_data);
// implemented API operations
```
```c
//
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
QueryCondition_ptr
create_querycondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
ReturnCode_t
delete_readcondition
(ReadCondition_ptr a_condition);
ReturnCode_t
delete_contained_entities
(void);
ReturnCode_t
set_qos
(const DataReaderQos& qos);
ReturnCode_t
get_qos
(DataReaderQos& qos);
ReturnCode_t
set_listener
(DataReaderListener_ptr a_listener,
StatusMask mask);
DataReaderListener_ptr
get_listener
(void);
TopicDescription_ptr
get_topicdescription
(void);
Subscriber_ptr
get_subscriber
(void);
ReturnCode_t
get_sample_rejected_status
```
```txt
(SampleRejectedStatus& status);
ReturnCode_t
get_liveliness_changed_status
(LivelinessChangedStatus& status);
ReturnCode_t
get_requested_deadline_missed_status
(RequestedDeadlineMissedStatus& status);
ReturnCode_t
get_requested_incompatible_qos_status
(RequestedIncompatibleQosStatus& status);
ReturnCode_t
get_subscription_matched_status
(SubscriptionMatchedStatus& status);
ReturnCode_t
get_sample_lost_status
(SampleLostStatus& status);
ReturnCode_t
wait_for_historical_data
(const Duration_t& max_wait);
ReturnCode_t
get_matched_publications
(InstanceHandleSeq& publication_handles);
ReturnCode_t
get_matched_publication_data
(PublicationBuiltinTopicData& publication_data, InstanceHandle_t publication_handle);
DataReaderView_ptr
create_view
(DataReaderViewQos& qos);
ReturnCode_t
delete_view
(DataReaderView_ptr a_view);
ReturnCode_t
get_default_datareaderview_qos
(DataReaderViewQos& qos);
ReturnCode_t
set_default_datareaderview_qos
```
```txt
(DataReaderViewQos& qos);
};
```
The following paragraphs describe the usage of all 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 create\_querycondition
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
QueryCondition_ptr
create_querycondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
```
# Description
This operation creates a new QueryCondition for the DataReader.
# Parameters
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
in const char\* query\_expression - the query string, which must be a subset of the SQL query language.
in const StringSeq& query\_parameters - a sequence of strings which are the parameter 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 parameters in the query\_expression, the query\_parameters should at least contain n+1 = 9 values).
# Return Value
QueryCondition\_ptr - Result value is a pointer to the QueryCondition. When the operation fails, the NULL pointer is returned.
# Detailed Description
This operation creates a new QueryCondition for the DataReader. The returned QueryCondition is attached (and belongs) to the DataReader. When the operation fails, the NULL pointer is returned. To delete the QueryCondition the operation delete\_readcondition or delete\_contained\_entities must be used.
# State Masks
The result of the 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 READ\_SAMPLE\_STATE, NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states NEW\_VIEW\_STATE, NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states ALIVE\_INSTANCE\_STATE, NOT\_ALIVE\_DISPOSED\_ INSTANCE\_STATE, 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 parameters in the query\_expression, the query\_parameters should at least contain n+1 = 9 values).
# 3.5.2.3 create\_readcondition
# Scope
DDS::DataReader
# Synopsis
```txt
#include <ccpp_dds_dcps.h>
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation creates a new ReadCondition for the DataReader.
# Parameters
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReadCondition\_ptr - Result value is a pointer to the ReadCondition. When the operation fails, the NULL pointer is returned.
# Detailed Description
This operation creates a new ReadCondition for the DataReader. The returned ReadCondition is attached (and belongs) to the DataReader. When the operation fails, the NULL pointer is returned. To delete the ReadCondition the operation delete\_readcondition or delete\_contained\_entities must be used.
# State Masks
The result of the 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 READ\_SAMPLE\_STATE, NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states NEW\_VIEW\_STATE, NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states ALIVE\_INSTANCE\_STATE, NOT\_ALIVE\_DISPOSED\_ INSTANCE\_STATE, NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE or a combination of these.
# 3.5.2.4 create\_view
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataReaderView_ptr
create_view
(DataReaderViewQos& qos);
```
# Description
This operation creates a DataReaderView with the desired QosPolicy settings.
# Parameters
in const DataReaderViewQos& - the QosPolicy settings for the DataReaderView.
# Return Value
DataReaderView\_ptr - 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 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 delete\_contained\_entities
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all the Entity objects that were created by means of one of the “create\_” operations on the DataReader.
# Parameters
```txt
<none>
```
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes all the Entity objects that were created by means of one of the “create\_” operations on the DataReader. In other words, it deletes all QueryCondition and ReadCondition objects contained by the DataReader.
NOTE: The operation will return 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:
• RETCODE\_OK - the contained Entity objects are deleted and the application may delete the DataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - one or more of the contained entities are in a state where they cannot be deleted.
# 3.5.2.6 delete\_readcondition
# Scope
DDS::DataReader
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_readcondition
(ReadCondition_ptr a_condition);
```
# Description
This operation deletes a ReadCondition or QueryCondition which is attached to the DataReader.
# Parameters
in ReadCondition\_ptr a\_condition - a pointer to the ReadCondition or QueryCondition which is to be deleted.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation deletes a ReadCondition or QueryCondition which is attached to the DataReader. Since a QueryCondition is a specialized ReadCondition, the operation can also be used to delete a QueryCondition. A ReadCondition or QueryCondition cannot be deleted when it is not attached to this DataReader. When the operation is called on a ReadCondition or QueryCondition which w a s n o t a t t a c h e d t o t h i 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 RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the ReadCondition or QueryCondition is deleted
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid ReadCondition\_ptr
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_PRECONDITION\_NOT\_MET - the operation is called on a different DataReader, as used when the ReadCondition or QueryCondition was created.
# 3.5.2.7 delete\_view
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_view
(DataReaderView_ptr a_view);
```
# Description
This operation deletes a DataReaderView that belongs to the DataReader.
# Parameters
in DataReaderView\_ptr a\_view - a pointer to the DataReaderView which is to be deleted.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are:
RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER,
RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES,
RETCODE_PRECONDITION_NOT_MET.
```
# Detailed Description
This operation deletes the DataReaderView from the DataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - the DataReaderView is deleted.
• RETCODE\_ERROR - an internal error occurred.
• RETCODE\_BAD\_PARAMETER - the DataReaderView\_ptr parameter is invalid.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation.
• 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 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.5.2.9 get\_default\_datareaderview\_qos
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_default_datareaderview_qos
(DataReaderViewQos& qos);
```
# Description
This operation gets the default QosPolicy settings of the DataReaderView.
# Parameters
inout DataReaderViewQos qos - a reference to the DataReaderViewQos struct in which the default QosPolicy settings will be stored.
# Return Value
ReturnCode\_t - Possible return codes of the operation are:
```txt
RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES.
```
# Detailed Description
This operation gets the default QosPolicy settings of the DataReaderView, which are used for newly-created DataReaderView objects in case the constant DATAREADERVIEW\_QOS\_DEFAULT is used.
The values retrieved by this call match the values specified on the last successful call to set\_default\_datareaderview\_qos, or, if this call was never made, the default values as specified in Table 2 on page 38.
# Return Code
When the operation returns:
• RETCODE\_OK - the default DataReaderView QosPolicy settings of this DataReader have successfully been copied into the provided DataReaderViewQos parameter.
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation
# 3.5.2.10 get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_key_value
(<data>& key_holder,
InstanceHandle_t handle);
```
# 3.5.2.11 get\_listener
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataReaderListener_ptr
get_listener
(void);
```
# Description
This operation allows access to a DataReaderListener.
# Parameters
```txt
<none>
```
# Return Value
datareaderlistener\_ptr - result is a pointer to the DataReaderListener attached to the DataReader.
# Detailed Description
This operation allows access to a DataReaderListener attached to the DataReader. When no DataReaderListener was attached to the DataReader, the NULL pointer is returned.
# 3.5.2.12 get\_liveliness\_changed\_status
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_liveliness_changed_status
(LivelinessChangedStatus& status);
```
# Description
This operation obtains the LivelinessChangedStatus struct of the DataReader.
# Parameters
inout LivelinessChangedStatus& status - the contents of the LivelinessChangedStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This obtains returns the LivelinessChangedStatus struct of the DataReader. This struct contains the information whether the liveliness of one or more DataWriter objects that were writing instances read by the DataReader has changed. In other words, some DataWriter have become “alive” or “not alive”.
The Li ve li ne ss Ch an ge dS tat us can also be monitored u sing a DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current LivelinessChangedStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.13 get\_matched\_publication\_data
# Scope
DDS::DataReader
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_matched_publication_data
(PublicationBuiltinTopicData& publication_data,
InstanceHandle_t publication_handle);
```
# Description
This operation retrieves information on the specified publication that is currently “associated” with the DataReader.
# Parameters
inout PublicationBuiltinTopicData& publication\_data - a reference to the sample in which the information about the specified publication is to be stored.
in InstanceHandle\_t publication\_handle - a handle to the publication whose information needs to be retrieved.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves information on the specified publication that is currently “associated” with the 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 ignore\_publication operation on the DomainParticipant.
The publication\_handle must correspond to a publication currently associated with the Da ta Re ad er, oth erwise the operation will fail and return RETCODE\_BAD\_PARAMETER. The operation get\_matched\_publications can be used to find the publications that are currently matched with the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• RETCODE\_OK - the information on the specified publication has successfully been retrieved.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataReader is not enabled.
# 3.5.2.14 get\_matched\_publications
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_matched_publications
(InstanceHandleSeq& publication_handles);
```
# Description
This operation retrieves the list of publications currently "associated" with the DataReader.
# Parameters
inout InstanceHandleSeq& publication\_handles - a sequence which is used to pass the list of all associated publications.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES or RETCODE\_NOT\_ENABLED.
# Detailed Description
This operation retrieves the list of publications currently "associated" with the 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 ignore\_publication operation on the DomainParticipant.
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 get\_matched\_publications operation or be released by invoking its destructor either implicitly or explicitly. 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 get\_matched\_publication\_data operation or to the read\_instance operation on the built-in reader for the “DCPSPublication” topic.
Be aware that since InstanceHandle\_t is an opaque datatype, it does not n e c e s s a r i l y m e a n t h a t t h e h a n d l e s o b t a i n e d f r o m t h e get\_matched\_publications operation have the same value as the ones that appear in the instance\_handle field of the SampleInfo when retrieving the publication info through corresponding "DCPSPublications" 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 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return RETCODE\_UNSUPPORTED.
# Return Code
When the operation returns:
• RETCODE\_OK - the list of associated publications has successfully been obtained.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataReader is not enabled.
# 3.5.2.15 get\_property
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_property
(Property& a_property);
```
# Description
This function queries the value of a property set on a DataReader.
# Parameters
inout Property& a\_property - on entry, a\_property.name determines w h i c h p r o p e r t y t o q u e r y t h e v a l u e o f ; o n s u c c e s s f u l r e t u r n , a\_property.value is set to the current value of that property in the DataReader.
# Return Value
int - Possible return codes of the operation are:
```txt
RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, RETCODE_UNSUPPORTED
```
# Detailed Description
This operation looks up the property specified by a\_property.name in the DataReader, 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.
# Return Code
When the operation returns:
• RETCODE\_OK - a\_property.value has been set to the current value of the property.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_UNSUPPORTED - a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.5.2.16 get\_qos
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DataReaderQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DataReader.
# Parameters
inout DataReaderQos& qos - a reference to the destination DataReaderQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DataReader on which this operation is used. This DataReaderQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoSPolicy values applied to this DataReader has successfully been copied into the specified DataReaderQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.17 get\_requested\_deadline\_missed\_status
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_requested_deadline_missed_status
(RequestedDeadlineMissedStatus& status);
```
# Description
This operation obtains the RequestedDeadlineMissedStatus struct of the DataReader.
# Parameters
inout RequestedDeadlineMissedStatus& status - the contents of the RequestedDeadlineMissedStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the RequestedDeadlineMissedStatus struct of the DataReader. This struct contains the information whether the deadline that the DataReader was expecting through its DeadlineQosPolicy was not respected for a specific instance.
The RequestedDeadlineMissedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current RequestedDeadlineMissedStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.18 get\_requested\_incompatible\_qos\_status
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_requested_incompatible_qos_status
(RequestedIncompatibleQosStatus& status);
```
# Description
This operation obtains the RequestedIncompatibleQosStatus struct of the DataReader.
# Parameters
inout RequestedIncompatibleQosStatus& status - the contents of the RequestedIncompatibleQosStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the RequestedIncompatibleQosStatus struct of the 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 DataWriter and the DataReader. If the QosPolicy settings between DataWriter and DataReader are inconsistent, no communication between them is established. In addition the DataWriter will be informed via a REQUESTED\_INCOMPATIBLE\_QOS status c h a n g e a n d t h e D a t a R e a d e r w i l l b e i n f o r m e d v i a a n OFFERED\_INCOMPATIBLE\_QOS status change.
The RequestedIncompatibleQosStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current RequestedIncompatibleQosStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.19 get\_sample\_lost\_status
#
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_sample_lost_status
(SampleLostStatus& status);
```
# Description
This operation obtains the SampleLostStatus struct of the DataReader.
# Parameters
inout SampleLostStatus& status - the contents of the SampleLostStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the SampleLostStatus struct of the DataReader. This struct contains information whether samples have been lost. This only applies when the ReliabilityQosPolicy is set to RELIABLE. If the ReliabilityQosPolicy is set to BEST\_EFFORT the Data Distribution Service will not report the loss of samples.
The SampleLostStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current SampleLostStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.20 get\_sample\_rejected\_status
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_sample_rejected_status
(SampleRejectedStatus& status);
```
# Detailed Description
This operation obtains the SampleRejectedStatus struct of the DataReader.
# Parameters
inout SampleRejectedStatus& status - the contents of the SampleRejectedStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the SampleRejectedStatus struct of the DataReader. This struct contains the information whether a received sample has been rejected. S a m p l e s m a y b e r e j e c t e d b y t h e D a t a R e a d e r w h e n i t r u n s o u t o f 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 S a m p le R e j e c t ed 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 DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current SampleRejectedStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.21 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.5.2.22 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.5.2.23 get\_subscriber
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
Subscriber_ptr
get_subscriber
(void);
```
# Description
This operation returns the Subscriber to which the DataReader belongs.
# Parameters
```txt
<none>
```
# Return Value
Subscriber\_ptr - Return value is a pointer to the Subscriber to which the DataReader belongs.
# Detailed Description
This operation returns the Subscriber to which the DataReader belongs, thus the Subscriber that has created the DataReader. If the DataReader is already deleted, the NULL pointer is returned.
# 3.5.2.24 get\_subscription\_matched\_status
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
```
```txt
ReturnCode_t
get Subscription_matched_status
(SubscriptionMatchedStatus& status);
```
# Description
This operation obtains the SubscriptionMatchedStatus struct of the DataReader.
# Parameters
inout SubscriptionMatchedStatus& status - the contents of the SubscriptionMatchedStatus struct of the DataReader will be copied into the location specified by status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation obtains the SubscriptionMatchedStatus struct of the 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 DataReader with the same Topic and a compatible Qos, or that a previously discovered DataWriter has ceased to be matched to the current 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 DataReader or when either the DataReader or the DataWriter has chosen to put its matching counterpart on its ignore-list using the ignore\_publication or ignore\_subcription operations on the DomainParticipant.
The operation may fail if the infrastructure does not hold the information necessary to fill in the SubscriptionMatchedStatus. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return RETCODE\_UNSUPPORTED.
The SubscriptionMatchedStatus can also be monitored using a DataReaderListener or by using the associated StatusCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the current SubscriptionMatchedStatus of this DataReader has successfully been copied into the specified status parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_UNSUPPORTED - OpenSplice is configured not to maintain the information about “associated” publications.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.25 get\_topicdescription
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
TopicDescription_ptr
get_topicdescription
(void);
```
# Description
This operation returns the TopicDescription which is associated with the DataReader.
# Parameters
<none>
# Return Value
T o pi c D e s c ri p t i o n \_ pt r - R e t u r n v a l u e is a p o i n t e r to t h e TopicDescription which is associated with the DataReader.
# Detailed Description
This operation returns the TopicDescription which is associated with the DataReader, thus the TopicDescription with which the DataReader is created. If the DataReader is already deleted, the NULL pointer is returned.
# 3.5.2.26 lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
lookup_instance
(const <data>& instance_data);
```
# 3.5.2.27 read (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.28 read\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_instance
(<data>& data_values,
SampleInfoSeq& info_seq,
```
```txt
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.29 read\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_next_instance
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.30 read\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_next_instance_w_condition
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition a_condition);
```
# 3.5.2.31 read\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_sample
(<data>& data_value,
SampleInfo sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.32 read\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_w_condition
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition a_condition);
```
# 3.5.2.33 return\_loan (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
return_loan
(<data>& data_values,
SampleInfoSeq& info_seq);
```
# 3.5.2.34 set\_default\_datareaderview\_qos
# Synopsis
```c
#include <cpp_dds_dcps.h>
DDS::DataReader
set_default_datareaderview_qos
(DataReaderViewQos& qos);
```
# Description
This operation sets the default DataReaderViewQos of the DataReader.
# Parameters
in const DataReaderViewQos& qos - the DataReaderQos struct which contains the default QosPolicy settings for newly-created DataReaderView objects.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
# Return Code
When the operation returns:
• RETCODE\_OK - the new default DataReaderQos is set.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the DataReaderViewQos parameter is invalid.
• RETCODE\_OUT\_OF\_RESOURCES - the data distribution service ran out of resources to complete this operation.
# 3.5.2.35 set\_listener
# Scope
```txt
DDS::DataReader
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
set_listener
(DataReaderListener_ptr a_listener,
StatusMask mask);
```
# Description
This operation attaches a DataReaderListener to the DataReader.
# Parameters
in DataReaderListener\_ptr a\_listener - a pointer to the DataReaderListener instance, which will be attached to the DataReader. in StatusMask mask - a bit mask in which each bit enables the invocation of the DataReaderListener for a certain status.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation attaches a DataReaderListener to the DataReader. Only one DataReaderListener can be attached to each DataReader. If a DataReaderListener was already attached, the operation will replace it with the new one. When a\_listener is the NULL pointer, it represents a listener that is treated as a NOOP1 for all statuses activated in the bit mask.
# Communication Status
For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that communication status changes. For each communication status activated in the mask, the associated 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 NULL listener, which does not reset the communication statuses for which it is invoked.
The following statuses are applicable to the DataReaderListener:
• REQUESTED\_DEADLINE\_MISSED\_STATUS
• REQUESTED\_INCOMPATIBLE\_QOS\_STATUS
• SAMPLE\_LOST\_STATUS
• SAMPLE\_REJECTED\_STATUS
• DATA\_AVAILABLE\_STATUS
• LIVELINESS\_CHANGED\_STATUS
1. Short for No-Operation, an instruction that does nothing.
• SUBSCRIPTION\_MATCHED\_STATUS.
Be aware that the 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 the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will return 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 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 which are applicable to the PublisherListener.
# Status Propagation
I n c a s e a c o m m u n i c a t i o n s t a t u s i s n o t a c t i v a t e d i n t h e m a s k , t h e SubscriberListener of the DataReaderListener is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the SubscriberListener of the containing Subscriber and a DataReader specific behaviour when needed. In case the communication status is not activated in the mask of the SubscriberListener as well, the communication status will be propagated to the DomainParticipantListener of t he c on ta in i ng D o m a i n Pa r t i c i p an t . I n c a s e t h e 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 DATA\_ON\_READERS\_STATUS and 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 D i s t r i b u t i o n S e r v i c e w i l l f i r s t l o o k i n a n a t t a c h e d a n d a c t i v a t e d SubscriberListener or DomainParticipantListener (in that order) for the DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look in an attached and activated DataReaderListener, SubscriberListener or DomainParticipant Listener for the DATA\_AVAILABLE\_STATUS (in that order).
# Return Code
When the operation returns:
• RETCODE\_OK - the DataReaderListener is attached
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_UNSUPPORTED - a status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.2.36 set\_property
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_property
(const Property& a_property);
```
# Description
This function sets a property on a DataReader.
# Parameters
in Property a\_property - specifies the property (in a\_property.name) and its new value (in a\_property.value).
# Return Value
int - Possible return codes of the operation are:
```txt
RETCODE_OK, RETCODE_BAD_PARAMETER, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, 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:
parallelReadThreadCount
By default, the demarshalling of data into objects by a single read or take o p e r a t i o n h a p p e n s o n l y i n t h e c a l l i n g t h r e a d . T h e parallelReadThreadCount property can be used to control the number of parallel threads to be used for this demarshalling. When reading multiple samples takes a significant amount of time, increasing the number of threads on a multi-core machine can provide a significant benefit.
The value is interpreted as the number of parallel threads to use (i.e., the value is a string representing a natural integer in decimal notation, so for example the string ‘4’ will cause 4 threads to be used). The value ‘0’ is allowed and selects the default behaviour.
If the call was successful, successive read/take operations on that DataReader will use the specified number of threads for the demarshalling step of the respective operations until the value of this property is changed again.
# ignoreLoansOnDeletion
By default, the DataReader keeps history about open loans.
‘Open loans’ is memory given to the user by a take or a read action on a DataReader which is not returned with a call to return\_loan.
A DataReader can by default not be deleted if there are open loans; such an attempt will result in a RETCODE\_PRECONDITION\_NOT\_MET returncode.
To ignore open loans when it is necessary to delete the DataReader, set the property ignoreLoansOnDeletion on the DataReader to true. If this property is set the DataReader will ignore its open loans in the case of a delete action.
The value is interpreted as a boolean (i.e., it must be either ‘true’ or ‘false’).
false (default): The DataReader will check for open loans in case of a delete action and will return RETCODE\_PRECONDITION\_NOT\_MET if there are open loans.
true: The DataReader will ignore open loans and can be deleted.
# Return Code
When the operation returns:
• RETCODE\_OK - the property has been set.
• RETCODE\_BAD\_PARAMETER - an invalid value has been specified.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_UNSUPPORTED - a\_property.name specifies an undefined property or the operation is not supported in this version.
# 3.5.2.37 set\_qos
# Scope
DDS::DataReader
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const DataReaderQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DataReader.
# Parameters
in const DataReaderQos& qos - qos contains the new set of QosPolicy settings for the DataReader.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_UNSUPPORTED, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_IMMUTABLE\_POLICY or RETCODE\_INCONSISTENT\_POLICY.
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a 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 DataReader, which can only be set before the DataReader is enabled, the operation will fail and a 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new DataReaderQos is set
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataReaderQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries
• RETCODE\_UNSUPPORTED - one or more of the selected QosPolicy values are currently not supported by OpenSplice.
• RETCODE\_ALREADY\_DELETED - the DataReader 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 different value than set during enabling of the DataReader
• 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.38 take (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states)
```
# 3.5.2.39 take\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take_instance
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.40 take\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take_next_instance
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.41 take\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take_next_instance_w_condition
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
```
ReadCondition a\_condition);
# 3.5.2.42 take\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_sample
(<data>& data_value,
SampleInfo sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.43 take\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 derived FooDataReader class.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_w_condition
(<data>& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition a_condition);
```
# 3.5.2.44 wait\_for\_historical\_data
# Scope
DDS::DataReader
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
wait_for_historical_data
(const Duration_t& max_wait);
```
# Description
This operation will block the application thread until all “historical” data is received.
# Parameters
in const Duration\_t& max\_wait - the maximum duration to block for the wait\_for\_historical\_data, after which the application thread is unblocked. The special constant DURATION\_INFINITE can be used when the maximum waiting time does not need to be bounded.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_TIMEOUT or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation behaves differently for DataReader objects which have a non-VOLATILE\_DURABILITY\_QOS DurabilityQosPolicy and for DataReader objects which have a VOLATILE\_DURABILITY\_QOS DurabilityQosPolicy.
As soon as an application enables a non-VOLATILE\_DURABILITY\_QOS DataReader it will start receiving both “historical” data, i.e. the data that was written prior to the time the DataReader joined the domain, as well as any new data written by the DataWriter objects. There are situations where the application logic may require the application to wait until all “historical” data is received. This is the purpose of the wait\_for\_historical\_data operation.
As soon as an application enables a VOLATILE\_DURABILITY\_QOS DataReader it will not start receiving “historical” data but only new data written by the DataWriter objects. By calling wait\_for\_historical\_data the 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 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 RETCODE\_OK indicates that all the “historical” data was received a return value of RETCODE\_TIMEOUT indicates that max\_wait elapsed before all the data was received.
# Return Code
When the operation returns:
• RETCODE\_OK - the “historical” data is received
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the DataReader is not enabled.
• RETCODE\_TIMEOUT - not all data is received before max\_wait elapsed.
• 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.45 wait\_for\_historical\_data\_w\_condition
# Scope
```txt
DDS::DataReader
```
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
ReturnCode_t
wait_for_historical_data_w_condition
(const char* filter_expression,
const StringSeq& filter_parameters,
const Time_t& min_source_timestamp,
const Time_t& max_source_timestamp
const ResourceLimitsQosPolicy &resource_limits,
const 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 const char\* filter\_expression – the SQL expression (subset of SQL), which defines the filtering criteria (NULL when no SQL filtering is needed).
in const 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 e q u a l t o o r g r e a t e r t h a n t h e h i g h e s t r e f e r e n c e d % n t o k e n i n t h e 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 Time\_t& min\_source\_timestamp – Filter out all data published before this time. The special constant TIMESTAMP\_INVALID can be used when no minimum filter is needed. The value of min\_source\_timestamp.sec must be less than 0x7fffffff otherwise it will be recognized as TIMESTAMP\_INVALID\_SEC.
in const Time\_t& max\_source\_timestamp – Filter out all data published after this time. The special constant TIMESTAMP\_INVALID can be used when no maximum filter is needed. The value of max\_source\_timestamp.sec must be less than 0x7fffffff otherwise it will be recognized as TIMESTAMP\_INVALID\_SEC.
in const ResourceLimitsQosPolicy& resource\_limits – Specifies limits on the maximum amount of historical data that may be received.
in const Duration\_t& max\_wait – The maximum duration the application thread is blocked during this operation.
# Return Value
ReturnCode\_t – Possible return codes of the operation are:
RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_PRECONDITION\_NOT\_MET, RETCODE\_ALREADY\_DELETED, RETCODE\_NOT\_ENABLED, RETCODE\_TIMEOUT.
# Detailed Description
This operation is similar to the 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.44 on page 402.
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 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:
• RETCODE\_OK - the historical data is received.
• RETCODE\_ERROR - an internal error occurred.
• 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.
• RETCODE\_ALREADY\_DELETED - the DataReader is already deleted.
• RETCODE\_NOT\_ENABLED - the DataReader is not enabled.
• RETCODE\_TIMEOUT - not all data is received before max\_wait elapsed.
# 3.5.2.46 Class FooDataReader
The pre-processor generates from IDL type descriptions the application <type>DataReader classes. For each application data type that is used as Topic data type, a typed class <type>DataReader is derived from the DataReader class. In this paragraph, the class FooDataReader in the namespace SPACE describes the operations of these derived <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 ccpp\_Space.h include file.
General note: The name ccpp\_Space.h is derived from the IDL file Space.idl, that defines Foo, for all relevant FooDataWriter operations.
# State Masks
A FooDataReader refers to exactly one TopicDescription (either a Topic, a ContentFilteredTopic or a MultiTopic) that identifies the data to be read. Therefore it refers to exactly one data type. The Topic must exist prior to the FooDataReader creation. The FooDataReader may give access to several instances of the data type, which are distinguished from each other by their key. The FooDataReader is attached to exactly one Subscriber which acts as a factory for it.
The interface description of this class is as follows:
```cpp
class FooDataReader
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// inherited from class DataReader
//
// ReadCondition_ptr
// create_readcondition
// (SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
// QueryCondition_ptr
// create_querycondition
// (SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states,
// const char* query_expression,
// const StringSeq& query_parameters);
// ReturnCode_t
// delete_readcondition
// (ReadCondition_ptr a_condition);
```
```c
// ReturnCode_t
// delete_contained_entities
// (void);
// ReturnCode_t
// set_qos
// (const DataReaderQos& qos);
// ReturnCode_t
// get_qos
// (DataReaderQos& qos);
// ReturnCode_t
// set_listener
// (DataReaderListener_ptr a_listener,
// StatusMask mask);
// DataReaderListener_ptr
// get_listener
// (void);
// TopicDescription_ptr
// get_topicdescription
// (void);
// Subscriber_ptr
// get_subscriber
// (void);
// ReturnCode_t
// get_sample_rejected_status
// (SampleRejectedStatus& status);
// ReturnCode_t
// get_liveliness_changed_status
// (LivelinessChangedStatus& status);
// ReturnCode_t
// get_requested_deadline_missed_status
// (RequestedDeadlineMissedStatus& status);
// ReturnCode_t
// get_requested_incompatible_qos_status
// (RequestedIncompatibleQosStatus& status);
// ReturnCode_t
// get那个 Subscription matched_status
// (SubscriptionMatchedStatus& status);
// ReturnCode_t
```
```c
// get_sample_lost_status
// (SampleLostStatus& status);
// ReturnCode_t
// wait_for_historical_data
// (const Duration_t& max_wait);
// ReturnCode_t
// get_matched_publications
// (InstanceHandleSeq& publication_handles);
// ReturnCode_t
// get_matched_publication_data
// (PublicationBuiltinTopicData& publication_data,
// InstanceHandle_t publication_handle);
// implemented API operations
//
ReturnCode_t
read
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
read_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
ReturnCode_t
take_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
ReturnCode_t
data_value
(Foo& received_data,
SampleInfo sample_info);
```
```txt
ReturnCode_t
take_next_sample
(Foo& data_value,
SampleInfo sample_info);
ReturnCode_t
read_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
read_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
read_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
ReturnCode_t
take_next_instance_w_condition
(FooSeq& data_values,
```
```txt
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
ReturnCode_t
return_loan
(FooSeq& data_values,
SampleInfoSeq& info_seq);
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
InstanceHandle_t
lookup_instance
(const Foo& instance_data);
};
```
The next paragraphs describe the usage of all 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.47 create\_querycondition (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
QueryCondition_ptr
create_querycondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
```
# 3.5.2.48 create\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```txt
#include <cpp_Space.h>
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.2.49 delete\_contained\_entities (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
delete_contained_entities
(void);
```
# 3.5.2.50 delete\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
delete_readcondition
(ReadCondition_ptr a_condition);
```
# 3.5.2.51 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
enable
(void);
```
# 3.5.2.52 get\_key\_value
# Scope
```txt
SPACE::FooDataReader
```
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
```
# Description
This operation retrieves the key value of a specific instance.
# Parameters
inout Foo& key\_holder - a reference to the sample in which the key values are stored.
in InstanceHandle\_t handle - the handle to the instance from which to get the key value.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED or RETCODE\_PRECONDITION\_NOT\_MET.
# Detailed Description
This operation retrieves the key value of the instance referenced to by instance\_handle. When the operation is called with a HANDLE\_NIL handle 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 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 RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - the key\_holder instance contains the key values of the instance;
• RETCODE\_ERROR - an internal error has occurred
• RETCODE\_BAD\_PARAMETER - handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - this instance is not registered.
# 3.5.2.53 get\_listener (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
#include <ccpp\_Space.h>
```txt
DataReaderListener_ptr
get_listener
(void);
```
# 3.5.2.54 get\_liveliness\_changed\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_liveliness_changed_status
(LivelinessChangedStatus& status);
```
# 3.5.2.55 get\_matched\_publication\_data (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_matched_publication_data
(PublicationBuiltinTopicData& publication_data,
InstanceHandle_t publication_handle);
```
# 3.5.2.56 get\_matched\_publications (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_matched_publications
(InstanceHandleSeq& publication_handles);
```
# 3.5.2.57 get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_qos
(DataReaderQos& qos);
```
# 3.5.2.58 get\_requested\_deadline\_missed\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_requested_deadline_missed_status
(RequestedDeadlineMissedStatus& status);
```
# 3.5.2.59 get\_requested\_incompatible\_qos\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_requested_incompatible_qos_status
(RequestedIncompatibleQosStatus& status);
```
# 3.5.2.60 get\_sample\_lost\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_sample_lost_status
(SampleLostStatus& status);
```
# 3.5.2.61 get\_sample\_rejected\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
get_sample_rejected_status
(SampleRejectedStatus& status);
```
# 3.5.2.62 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```cpp
#include <cpp_Space.h>
StatusMask
get_status_changes
(void);
```
# 3.5.2.63 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.5.2.64 get\_subscriber (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```txt
#include <cpp_Space.h>
Subscriber_ptr
get_subscriber
(void);
```
# 3.5.2.65 get\_subscription\_matched\_status (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <ccpp_Space.h>
ReturnCode_t
get_subscription_matched_status
(SubscriptionMatchedStatus& status);
```
# 3.5.2.66 get\_topicdescription (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```txt
#include <cpp_Space.h>
TopicDescription_ptr
get_topicdescription
```
(void);
# 3.5.2.67 lookup\_instance
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <ccpp_Space.h>
InstanceHandle_t
lookup_instance
(const Foo& instance_data);
```
# Description
This operation returns the value of the instance handle which corresponds to the instance\_data.
# Parameters
in const Foo& instance\_data - the instance for which the corresponding instance handle needs to be looked up.
# Return Value
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 DataReader instance handles are local, and are not interchangeable with DataWriter instance handles nor with instance handles of an other DataReader. If the DataReader is already deleted, the handle value HANDLE\_NIL is returned.
# 3.5.2.68 read
# Scope
SPACE::FooDataReader
# Synopsis
```txt
#include <cpp_Space.h>
ReturnCode_t
read
(FooSeq& data_values,
SampleInfoSeq& info_seq,
```
```sql
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are: RETCODE_OK, RETCODE_ERROR, RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES, RETCODE_NOT_ENABLED, RETCODE_PRECONDITION_NOT_MET or RETCODE_NO_DATA.
```
# Detailed Description
This operation reads a sequence of Foo samples from the 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 FooDataReader has no samples that meet the constraints, the return value is RETCODE\_NO\_DATA.
# State Masks
The 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 READ\_SAMPLE\_STATE, NOT\_READ\_SAMPLE\_STATE or both
• view\_states is the mask, which selects only those samples with the desired view states NEW\_VIEW\_STATE, NOT\_NEW\_VIEW\_STATE or both
• instance\_states is the mask, which selects only those samples with the desired instance states ALIVE\_INSTANCE\_STATE, NOT\_ALIVE\_DISPOSED\_ INSTANCE\_STATE, 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 DestinationOrderQosPolicy of the Subscriber.
• When the DestinationOrderQosPolicy kind is 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 DestinationOrderQosPolicy kind is 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 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 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 read operation as specified by the following rules:
• The values of length, maximum, and release for the two sequences must be identical. Otherwise read returns 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 received\_data and info\_seq sequences are filled with elements that are “loaned” by the 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 return\_loan operation
• If the input maximum>0 and the input release == FALSE, the read operation will fail and returns 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 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 max\_samples==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 read operation will fail and returns 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 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 return\_loan operation to return the “loan” once it is no longer using the data in the sequence. Upon return from 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 read operation was called, or by accessing the “release” property. However, in many cases it may be simpler to always call 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 SampleInfo structures are of the same length and are in an one-to-one correspondence. Each SampleInfo structures provides information, such as the 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 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 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 DataReader will insert a dummy sample into the data\_values sequence to accompany the 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 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 NOT\_NEW\_VIEW\_STATE. It does not affect the instance\_state of the instance.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
\- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.69 read\_instance
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
read_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 a single instance from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the single instance, the samples belong to.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader. The behaviour is identical to 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 SampleInfo.instance\_handle in info\_seq will have the value of a\_handle. The 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:
• RETCODE\_OK - a sequence of data values is available
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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 ==HANDLE\_NIL.
- the handle has not been registered with this DataReader.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.70 read\_next\_instance
# Scope
```txt
SPACE::FooDataReader
```
# Synopsis
```c
#include <ccpp_Space.h>
ReturnCode_t
read_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader. The behaviour is similar to 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. T h e c o r r e s p o n d i n g 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 read\_next\_instance is ‘as if’ the DataReader invoked 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 HANDLE\_NIL is guaranteed to be ‘less than’ any valid instance\_handle. So the use of the parameter value a\_handle==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 read\_next\_instance is intended to be used in an application-driven iteration where the ap plication starts by passing a\_handle==HANDLE\_NIL, examines the samples returned, and then uses the instance\_handle returned in the SampleInfo as the value of a\_handle argument to the next call to read\_next\_instance. The iteration continues until read\_next\_instance returns the return value RETCODE\_NO\_DATA.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.71 read\_next\_instance\_w\_condition
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
read_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the FooDataReader, filtered by a ReadCondition or QueryCondition.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in ReadCondition\_ptr a\_condition - a pointer to a ReadCondition or QueryCondition which filters the data before it is returned by the read operation.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader, filtered by a ReadCondition or QueryCondition. The behaviour is identical to read\_next\_instance except for that the samples are filtered by a ReadCondition or QueryCondition. When using a ReadCondition, the result is the same as the read\_next\_instance operation with the same state parameters filled in as for the create\_readcondition. In this way, the application can avoid repeating the same parameters, specified when creating the ReadCondition. When using a QueryCondition, a content based filtering can be done. When either using a ReadCondition or QueryCondition, the condition must be created by this FooDataReader. Otherwise the operation will fail and returns RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid ReadCondition\_ptr or a\_handle is not a valid handle.
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.72 read\_next\_sample
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <ccpp_Space.h>
ReturnCode_t
read_next_sample
(Foo& data_value,
SampleInfo sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.73 read\_w\_condition
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
read_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReader, filtered by a ReadCondition or QueryCondition.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in ReadCondition\_ptr a\_condition - a pointer to a ReadCondition or QueryCondition which filters the data before it is returned by the read operation.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the FooDataReader, filtered by a ReadCondition or QueryCondition. The condition reference from both create\_readcondition or create\_querycondition may be used. The behaviour is identical to read except for that the samples are filtered by a ReadCondition or QueryCondition. When using a ReadCondition, the result is the same as the read operation with the same state parameters filled in as for the create\_readcondition. In this way, the application can avoid repeating the same parameters, specified when creating the ReadCondition. When using a QueryCondition, a content based filtering can be done. When either using a ReadCondition or QueryCondition, the condition must be created by this F o o D a t a R e a d e r. O t h e r w i s e t h e o p e r a t i o n w i l l f a i l a n d r e t u r n s RETCODE\_PRECONDITION\_NOT\_MET.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid ReadCondition\_ptr
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the ReadCondition or QueryCondition is not attached to this FooDataReader
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.74 return\_loan
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
return_loan
(FooSeq& data_values,
SampleInfoSeq& info_seq);
```
# Description
This operation indicates to the DataReader that the application is done accessing the sequence of data\_values and info\_seq.
# Parameters
inout FooSeq& data\_values - the sample data sequence which was loaned from the DataReader.
inout SampleInfoSeq& info\_seq - the SampleInfo structure sequence which was loaned from the DataReader.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES, RETCODE\_NOT\_ENABLED or RETCODE\_PRECONDITION\_ NOT\_MET.
# Detailed Description
This operation indicates to the DataReader that the application is done accessing the sequence of data\_values and info\_seq obtained by some earlier invocation of the operation read or take (or any of the similar operations) on the DataReader.
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 read or take. The data\_values and info\_seq must also have been obtained from the same DataReader to which they are returned. If either of these conditions is not met the operation will fail and returns RETCODE\_PRECONDITION\_NOT\_MET.
# Buffer Loan
The operation return\_loan allows implementations of the read and 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 read or take. However, as these buffers correspond to internal resources inside the DataReader, the application should not retain them indefinitely.
# Calling return\_loan
The use of the return\_loan operation is only necessary if the call to the operation read or 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 read or 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 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 return\_loan the pair of sequences has maximum=0.
# Return Code
When the operation returns:
• RETCODE\_OK - the DataReader is informed that the sequences will not be used any more
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• 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 FooDataReader.
# 3.5.2.75 set\_listener (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
set_listener
(DataReaderListener_ptr a_listener,
StatusMask mask);
```
# 3.5.2.76 set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
set_qos
(const DataReaderQos& qos);
```
# 3.5.2.77 take
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <ccpp_Space.h>
ReturnCode_t
take
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReader and by doing so, removes the data from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED, RETCODE\_OUT\_ OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_ NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the FooDataReader and by doing so, removes the data from the FooDataReader, so it can not be read or taken again. The behaviour is identical to read except for that the samples are removed from the FooDataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available and removed from the FooDataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.78 take\_instance
# Scope
```txt
SPACE::FooDataReader
```
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
take_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 a single instance from the FooDataReader and by doing so, removes the data from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the single instance, the samples belong to.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader and by doing so, removes the data from the FooDataReader, so it can not be read or taken again. The behaviour is identical to read\_instance except for that the samples are removed from the FooDataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available and removed from the FooDataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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 ==HANDLE\_NIL.
- the handle has not been registered with this DataReader.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.79 take\_next\_instance
# Scope
```txt
SPACE::FooDataReader
```
# Synopsis
```c
#include <ccpp_Space.h>
ReturnCode_t
take_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 FooDataReader and by doing so, removes the data from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in SampleStateMask sample\_states - a mask, which selects only those samples with the desired sample states.
in ViewStateMask view\_states - a mask, which selects only those samples with the desired view states.
in InstanceStateMask instance\_states - a mask, which selects only those samples with the desired instance states.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader and by doing so, removes the data from the FooDataReader, so i t c a n n o t 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 read\_next\_instance except for that the samples are removed from the FooDataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available and removed from the FooDataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.80 take\_next\_instance\_w\_condition
# Scope
SPACE::FooDataReader
# Synopsis
#include <ccpp\_Space.h>
```sql
ReturnCode_t
take_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the FooDataReader, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in InstanceHandle\_t a\_handle - the current single instance, the returned samples belong to the next single instance.
in ReadCondition\_ptr a\_condition - a pointer to a ReadCondition or QueryCondition which filters the data before it is returned by the read operation.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples of a single instance from the FooDataReader, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReader, so it can not be read o r t a k e n a g a i n . Th e b eh avio ur i s i d e n t i c a l t o read\_next\_instance\_w\_condition except for that the samples are removed from the FooDataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available and removed from the FooDataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid ReadCondition\_ptr or a\_handle is not a valid handle
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the ReadCondition or QueryCondition is not attached to this FooDataReader.
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.81 take\_next\_sample
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
take_next_sample
(Foo& data_value,
SampleInfo sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.2.82 take\_w\_condition
# Scope
SPACE::FooDataReader
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
take_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReader, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReader.
# Parameters
inout FooSeq& data\_values - the returned sample data sequence. data\_values is also used as an input to control the behaviour of this operation.
inout SampleInfoSeq& info\_seq - the returned SampleInfo structure sequence. info\_seq is also used as an input to control the behaviour of this operation.
in long max\_samples - the maximum number of samples that is returned.
in ReadCondition\_ptr a\_condition - a pointer to a ReadCondition or QueryCondition which filters the data before it is returned by the read operation.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY DELETED, RETCODE\_OUT\_OF\_RESOURCES, RETCODE\_NOT\_ENABLED, RETCODE\_PRECONDITION\_NOT\_MET or RETCODE\_NO\_DATA.
# Detailed Description
This operation reads a sequence of Foo samples from the FooDataReader, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReader, so it can not be read or taken again. The behaviour is identical to read\_w\_condition except for that the samples are removed from the FooDataReader.
# Return Code
When the operation returns:
• RETCODE\_OK - a sequence of data values is available and removed from the FooDataReader
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter a\_condition is not a valid ReadCondition\_ptr
• RETCODE\_ALREADY\_DELETED - the FooDataReader has already been deleted
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
• RETCODE\_NOT\_ENABLED - the FooDataReader is not enabled.
• RETCODE\_PRECONDITION\_NOT\_MET - one of the following is true:
- the ReadCondition or QueryCondition is not attached to this FooDataReader
- the max\_samples>maximum and max\_samples is not 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.
• RETCODE\_NO\_DATA - no samples that meet the constraints are available.
# 3.5.2.83 wait\_for\_historical\_data (inherited)
This operation is inherited and therefore not described here. See the class DataReader for further explanation.
# Synopsis
```c
#include <cpp_Space.h>
ReturnCode_t
wait_for_historical_data
(const Duration_t& max_wait);
```
# 3.5.2.84 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 <cpp_Space.h>
ReturnCode_t
wait_for_historical_data_w_condition
(const char* filter_expression,
const StringSeq& filter_parameters,
const Time_t& min_source_timestamp,
const Time_t& max_source_timestamp
```
const ResourceLimitsQosPolicy &resource\_limits,const Duration\_t &max\_wait)
# 3.5.3 Class DataSample
A DataSample represents an atom of data information (i.e. one value for an instance) as returned by the DataReader’s read/take operations. It consists of two parts: A SampleInfo and the Data itself. The Data part is the data as produced by a Publisher. The SampleInfo part contains additional information related to the data provided by the Data Distribution Service.
# 3.5.4 Struct SampleInfo
The struct 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 SampleInfo
{
SampleStateKind sample_state;
ViewStateKind view_state;
InstanceStateKind instance_state;
Time_t source_timestamp;
InstanceHandle_t instance_handle;
InstanceHandle_t publication_handle;
Long disposed_generation_count;
Long no_writers_generation_count;
Long sample_rank;
Long generation_rank;
Long absolute_generation_rank;
Boolean valid_data;
Time_t reception_timestamp;
};
```
The next paragraph describes the usage of the SampleInfo struct.
# 3.5.4.1 SampleInfo
# Scope
DDS
# Synopsis
```c
#include <cpp_dds_dcps.h>
struct SampleInfo
{
SampleStateKind sample_state;
ViewStateKind view_state;
InstanceStateKind instance_state;
Time_t source_timestamp;
```
```c
InstanceHandle_t instance_handle;
InstanceHandle_t publication_handle;
Long disposed_generation_count;
Long no_writers_generation_count;
Long sample_rank;
Long generation_rank;
Long absolute_generation_rank;
Boolean valid_data;
Time_t reception_timestamp;
};
```
# Description
The struct SampleInfo represents the additional information that accompanies the data in each sample that is read or taken.
# Attributes
SampleStateKind sample\_state - whether or not the corresponding data sample has already been read.
ViewStateKind view\_state - whether the DataReader has already seen samples of the most-current generation of the related instance.
InstanceStateKind instance\_state - whether the instance is alive, has no writers or is disposed of.
Time\_t source\_timestamp - the time provided by the DataWriter when the sample was written.
InstanceHandle\_t instance\_handle - the handle that identifies locally the corresponding instance.
InstanceHandle\_t publication\_handle - the handle that identifies locally t h e D a t a W r i t e r t h a t m o d i f i e d t h e i n s t a n c e . I n f a c t i t i s a n instance\_handle of the built-in DCPSPublication sample that describes this DataWriter. It can be used as a parameter to the DataReader operation get\_matched\_publication\_data to obtain this built-in DCPSPublication sample.
Long disposed\_generation\_count - the number of times the instance has become alive after it was disposed of explicitly by a DataWriter.
Long no\_writers\_generation\_count - the number of times the instance has become alive after it was disposed of because there were no DataWriter objects.
Long sample\_rank - the number of samples related to the same instance that are found in the collection returned by a read or take operation.
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.
Long absolute\_generation\_rank - the generation difference between the time the sample was received and the time the most recent sample was received.
Boolean valid\_data - whether the DataSample contains any meaningful data. If not, the sample is only used to communicate a change in the instance\_state of the instance.
Time\_t reception\_timestamp - the time provided by the DataReader when the sample was received.
# Detailed Description
The struct 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==ALIVE\_INSTANCE\_STATE) at the time the sample was received’. Note that the generation counters are initialized to zero when a DataReader first detects a never-seen-before instance.
Two types of generations are distinguished: disposed\_generation\_count and no\_writers\_generation\_count.
After a DataWriter disposes an instance, the disposed\_generation\_count for all DataReaders that already knew that instance will be incremented the next time the instance is written again.
If the DataReader detects that there are no live DataWriter entities, the instance\_state of the sample\_info will change from ALIVE\_INSTANCE\_STATE to NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE. The next time the instance is written, no\_writers\_generation\_count will be incremented.
# Sample Information
SampleInfo is the additional information that accompanies the data in each sample that is read or taken. It contains the following information:
• sample\_state (READ\_SAMPLE\_STATE or NOT\_READ\_SAMPLE\_STATE) indicates whether or not the corresponding data sample has already been read
• view\_state (NEW\_VIEW\_STATE, or NOT\_NEW\_VIEW\_STATE) indicates whether the DataReader has already seen samples of the most-current generation of the related instance
• instance\_state (ALIVE\_INSTANCE\_STATE, NOT\_ALIVE\_DISPOSED INSTANCE\_STATE, or NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE) indicates whether the instance is alive, has no writers or if it has been disposed of:
- ALIVE\_INSTANCE\_STATE if this instance is currently in existence
- NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE if this instance was disposed of by a DataWriter
- NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE none of the DataWriter objects currently “alive” (according to the LivelinessQosPolicy) are writing the instance.
• source\_timestamp indicates the time provided by the 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 get\_matched\_publication\_data operation on the DataReader or to the read\_instance operation on the built-in reader for the “DCPSPublication” topic.
Be aware that since 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 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 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 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 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 read or 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 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 DataReader when the sample was inserted.
NOTE: This is an OpenSplice-specific extension to the SampleInfo struct and is not part of the DDS Specification.
# 3.5.5 SubscriberListener Interface
Since a Subscriber is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type SubscriberListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the SubscriberListener class. All 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 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 SubscriberListener is related to changes in communication status.
The interface description of this class is as follows:
```cpp
class SubscriberListener
{
//
// inherited from class DataReaderListener
//
// void
// on_requested_deadline_missed
// (DataReader_ptr reader,
// const RequestedDeadlineMissedStatus& status) = 0;
// void
```
```c
// on_requested_incompatible_qos
// (DataReader_ptr reader,
// const RequestedIncompatibleQosStatus& status) = 0;
// void
// on_sample_rejected
// (DataReader_ptr reader,
// const SampleRejectedStatus& status) = 0;
// void
// on_liveliness_changed
// (DataReader_ptr reader,
// const LivelinessChangedStatus& status) = 0;
// void
// on_data_available
// (DataReader_ptr reader) = 0;
// void
// on_subscription_matched
// (DataReader_ptr reader,
// const SubscriptionMatchedStatus& status) = 0;
// void
// on_sample_lost
// (DataReader_ptr reader,
// const SampleLostStatus& status) = 0;
//
// abstract external operations
//
void
on_data_on_readers
(Subscriber_ptr subs) = 0;
//
// implemented API operations
// <no operations>
//
};
```
The next paragraphs list all 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 on\_data\_available (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
void
on_data_available
(DataReader_ptr reader) = 0;
```
# 3.5.5.2 on\_data\_on\_readers (abstract)
# Scope
```makefile
DDS::SubscriberListener
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_data_on_readers
(Subscriber_ptr subs) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when new data is available.
# Parameters
in Subscriber\_ptr subs - contain a pointer to the 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 Subscriber. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant S u bs c r i b e rL i s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e DATA\_ON\_READERS\_STATUS.
The Data Distribution Service will provide a reference to the Subscriber in the parameter subs for use by the application.
The statuses DATA\_ON\_READERS\_STATUS and DATA\_AVAILABLE\_STATUS will occur together. In case these status changes occur, the Data Distribution Service will l o o k f o r a n a t t a c h e d a n d a c t i v a t e d S u b s c r i be r L i s t en e r or DomainParticipantListener (in that order) for the
DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look for an attached and activated DataReaderListener, SubscriberListener o r DomainParticipantListener for the DATA\_AVAILABLE\_STATUS (in that order).
Note that if on\_data\_on\_readers is called, then the Data Distribution Service will not try to call on\_data\_available, however, the application can force a call to the callback function on\_data\_available of DataReaderListener objects that have data by means of the notify\_datareaders operation.
# 3.5.5.3 on\_liveliness\_changed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```txt
#include <cpp_dds_dcps.h>
void
on_liveliness_changed
(DataReader_ptr reader,
const LivelinessChangedStatus& status) = 0;
```
# 3.5.5.4 on\_requested\_deadline\_missed (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_deadline_missed
(DataReader_ptr reader,
const RequestedDeadlineMissedStatus& status) = 0;
```
# 3.5.5.5 on\_requested\_incompatible\_qos (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_incompatible_qos
(DataReader_ptr reader,
const RequestedIncompatibleQosStatus& status) = 0;
```
# 3.5.5.6 on\_sample\_lost (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on_sample_lost
(DataReader_ptr reader,
const SampleLostStatus& status) = 0;
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.5.7 on\_sample\_rejected (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_sample_rejected
(DataReader_ptr reader,
const SampleRejectedStatus& status) = 0;
```
# 3.5.5.8 on\_subscription\_matched (inherited, abstract)
This operation is inherited and therefore not described here. See the class DataReaderListener for further explanation.
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on Subscription_matched
(DataReader_ptr reader,
const SubscriptionMatchedStatus& status) = 0;
```
# 3.5.6 DataReaderListener Interface
Since a DataReader is an Entity, it has the ability to have a Listener associated with it. In this case, the associated Listener should be of type DataReaderListener. This interface must be implemented by the application. A user-defined class must be provided by the application which must extend from the DataReaderListener class. All 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 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 DataReaderListener is related to changes in communication status.
The interface description of this class is as follows:
```cpp
class DataReaderListener
{
//
// abstract external operations
//
void
on_requested_deadline_missed
(DataReader_ptr reader,
const RequestedDeadlineMissedStatus& status) = 0;
void
on_requested_incompatible_qos
(DataReader_ptr reader,
const RequestedIncompatibleQosStatus& status) = 0;
void
on_sample_rejected
(DataReader_ptr reader,
const SampleRejectedStatus& status) = 0;
void
on_liveliness_changed
(DataReader_ptr reader,
const LivelinessChangedStatus& status) = 0;
void
on_data_available
(DataReader_ptr reader) = 0;
void
on_subscription_matched
(DataReader_ptr reader,
const SubscriptionMatchedStatus& status) = 0;
void
on_sample_lost
(DataReader_ptr reader,
const SampleLostStatus& status) = 0;
}
```
```txt
// implemented API operations
// <no operations>
//
};
```
The next paragraphs describe the usage of all DataReaderListener operations. These abstract operations are fully described because they must be implemented by the application.
# 3.5.6.1 on\_data\_available (abstract)
# Scope
```txt
DDS::DataReaderListener
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
void
on_data_available
(DataReader_ptr reader) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when new data is available.
# Parameters
in DataReader\_ptr reader - contain a pointer to the 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 DataReader. The implementation may be left empty when this functionality is not needed. This operation will only be called when the relevant D a ta R e a d e rL i s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e DATA\_AVAILABLE\_STATUS.
The Data Distribution Service will provide a reference to the DataReader in the parameter reader for use by the application.
The statuses DATA\_ON\_READERS\_STATUS and DATA\_AVAILABLE\_STATUS will occur together. In case these status changes occur, the Data Distribution Service will l o o k f o r a n a t t a c h e d a n d a c t i v a t e d S u b s c r i be r L i s t en e r or D o ma i n P a r t ic i p a n t Li s t e n e r ( i n t h a t o rd e r ) fo r t h e DATA\_ON\_READERS\_STATUS. In case the DATA\_ON\_READERS\_STATUS can not be handled, the Data Distribution Service will look for an attached and activated DataReaderListener, SubscriberListener or
DomainParticipantListener for the DATA\_AVAILABLE\_STATUS (in that order).
Note that if on\_data\_on\_readers is called, then the Data Distribution Service will not try to call on\_data\_available, however, the application can force a call to the DataReader objects that have data by means of the notify\_datareaders operation.
# 3.5.6.2 on\_liveliness\_changed (abstract)
# Scope
DDS::DataReaderListener
# Synopsis
```txt
#include <cpp_dds_dcps.h>
void
on_liveliness_changed
(DataReader_ptr reader,
const LivelinessChangedStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the liveliness of one or more DataWriter objects that were writing instances read through this DataReader has changed.
# Parameters
in DataReader\_ptr reader - contain a pointer to the DataReader for which the liveliness of one or more DataWriter objects has changed (this is an input to the application provided by the Data Distribution Service).
in const LivelinessChangedStatus& status - contain the LivelinessChangedStatus struct (this is an input to the application 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 liveliness of one or more DataWriter objects that were writing instances read through this DataReader has changed. In other words, some 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 a ta R e a d e rL i s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e LIVELINESS\_CHANGED\_STATUS.
The Data Distribution Service will provide a reference to the DataReader in the parameter reader and the LivelinessChangedStatus struct for use by the application.
# 3.5.6.3 on\_requested\_deadline\_missed (abstract)
# Scope
```txt
DDS::DataReaderListener
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_deadline_missed
(DataReader_ptr reader,
const RequestedDeadlineMissedStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the deadline that the DataReader was expecting through its DeadlineQosPolicy was not respected.
# Parameters
in DataReader\_ptr reader - contain a pointer to the DataReader for which the deadline was missed (this is an input to the application provided by the Data Distribution Service).
in const RequestedDeadlineMissedStatus& status - contain the 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 DataReader was expecting through its 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 D a ta R e a d e r Li s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e REQUESTED\_DEADLINE\_MISSED\_STATUS.
The Data Distribution Service will provide a reference to the DataReader in the parameter reader and the RequestedDeadlineMissedStatus struct in the parameter status for use by the application.
# 3.5.6.4 on\_requested\_incompatible\_qos (abstract)
# Scope
DDS::DataReaderListener
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_requested_incompatible_qos
(DataReader_ptr reader,
const RequestedIncompatibleQosStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when the REQUESTED\_INCOMPATIBLE\_QOS\_STATUS changes.
# Parameters
in DataReader\_ptr reader - a pointer to the DataReader provided by the Data Distribution Service.
in const RequestedIncompatibleQosStatus& status - the RequestedIncompatibleQosStatus 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 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 DataReaderListener is installed and enabled for the REQUESTED\_INCOMPATIBLE\_QOS\_STATUS.
The Data Distribution Service will provide a reference to the DataReader in the parameter reader and the RequestedIncompatibleQosStatus 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 REQUESTED\_INCOMPATIBLE\_QOS\_STATUS in the mask in the call to DataReader::set\_listener. When the DataReaderListener on the DataReader is not enabled for the REQUESTED\_INCOMPATIBLE\_QOS\_STATUS, the status change will propagate to the SubscriberListener of the Subscriber ( i f e n a b l e d ) o r t o t h e D o m a in P a r t i c ip a n t L i st e n e r o f t h e DomainParticipant (if enabled).
# 3.5.6.5 on\_sample\_lost (abstract)
# Scope
DDS::DataReaderListener
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on_sample_lost
(DataReader_ptr reader,
const SampleLostStatus& status) = 0;
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.6.6 on\_sample\_rejected (abstract)
# Scope
DDS::DataReaderListener
# Synopsis
```c
#include <ccpp_dds_dcps.h>
void
on_sample_rejected
(DataReader_ptr reader,
const SampleRejectedStatus& status) = 0;
```
# Description
This operation must be implemented by the application and is called by the Data Distribution Service when a sample has been rejected.
# Parameters
in DataReader\_ptr reader - contains a pointer to the DataReader for which a sample has been rejected (this is an input to the application provided by the Data Distribution Service).
in const SampleRejectedStatus& status - contains the 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 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 DataReaderListener is installed and enabled for the SAMPLE\_REJECTED\_STATUS.
The Data Distribution Service will provide a reference to the DataReader in the parameter reader and the SampleRejectedStatus struct in the parameter status for use by the application.
# 3.5.6.7 on\_subscription\_matched (abstract)
# Scope
```txt
DDS::DataReaderListener
```
# Synopsis
```cpp
#include <ccpp_dds_dcps.h>
void
on Subscription_matched
(DataReader_ptr reader,
const SubscriptionMatchedStatus& status) = 0;
```
# 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
in DataReader\_ptr reader - contains a pointer to the 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
<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 DataReader has either been discovered, or that a previously discovered DataWriter has ceased to be matched to the current 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 DataReader or when either the DataReader or the DataWriter has chosen to put its matching counterpart on its ignore-list using the ignore\_publication or ignore\_subcription operations on the DomainParticipant.
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 a ta R e a d e rL i s t e n e r i s i n s t a l l e d a n d e n a b l e d f o r t h e SUBSCRIPTION\_MATCHED\_STATUS.
The Data Distribution Service will provide a pointer to the DataReader in the parameter reader and the SubscriptionMatchedStatus struct in the parameter status for use by the application.
# 3.5.7 Class ReadCondition
The DataReader objects can create a set of ReadCondition (and StatusCondition) objects which provide support (in conjunction with WaitSet objects) for an alternative communication style between the Data Distribution Service and the application (i.e., state-based rather than event-based).
ReadCondition objects allow an DataReader to specify the data samples it is interested in (by specifying the desired sample-states, view-states, and i n s t a nc e - s t a t es ) ; s e e t h e pa r a m e t er de f i n i t i o n s f o r D a t a R e a d e r ' s create\_readcondition operation. This allows the Data Distribution Service to trigger the condition only when suitable information is available. ReadCondition objects are to be used in conjunction with a WaitSet. More than one ReadCondition may be attached to the same DataReader.
The interface description of this class is as follows:
```cpp
class ReadCondition
{
//
// inherited from Condition
//
// Boolean
// get_trigger_value
// (void);
//
// implemented API operations
//
SampleStateMask
get_sample_state_mask
(void);
ViewStateMask
get_view_state_mask
(void);
InstanceStateMask
get_instance_state_mask
(void);
DataReader_ptr
get_datareader
(void);
};
```
The next paragraphs describe the usage of all 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 get\_datareader
# Scope
```autohotkey
DDS::ReadCondition
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataReader_ptr
get_datareader
(void);
```
# Description
This operation returns the DataReader associated with the ReadCondition.
# Parameters
```txt
<none>
```
# Return Value
DataReader\_ptr - Result value is a pointer to the DataReader.
# Detailed Description
This operation returns the DataReader associated with the ReadCondition. Note that there is exactly one DataReader associated with each ReadCondition (i.e. the DataReader that created the ReadCondition object).
# 3.5.7.2 get\_instance\_state\_mask
# Scope
```autohotkey
DDS::ReadCondition
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceStateMask
get_instance_state_mask
(void);
```
# Description
This operation returns the set of instance\_states that are taken into account to determine the trigger\_value of the ReadCondition.
# Parameters
```txt
<none>
```
# Return Value
InstanceStateMask - Result value are the instance\_states specified when the 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 ReadCondition.
The instance\_states returned are the instance\_states specified when the ReadCondition was created. instance\_states can be ALIVE\_INSTANCE\_STATE, NOT\_ALIVE\_DISPOSED\_INSTANCE\_STATE, NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE or a combination of these.
# 3.5.7.3 get\_sample\_state\_mask
# Scope
DDS::ReadCondition
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
SampleStateMask
get_sample_state_mask
(void);
```
# Description
This operation returns the set of sample\_states that are taken into account to determine the trigger\_value of the ReadCondition.
# Parameters
<none>
# Return Value
SampleStateMask - Result value are the sample\_states specified when the 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 ReadCondition.
The sample\_states returned are the sample\_states specified when the ReadCondition was created. sample\_states can be READ\_SAMPLE\_STATE, NOT\_READ\_SAMPLE\_STATE or both.
# 3.5.7.4 get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class Condition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
Boolean
get_trigger_value
(void);
```
# 3.5.7.5 get\_view\_state\_mask
# Scope
```autohotkey
DDS::ReadCondition
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ViewStateMask
get_view_state_mask
(void);
```
# Description
This operation returns the set of view\_states that are taken into account to determine the trigger\_value of the ReadCondition.
# Parameters
```txt
<none>
```
# Return Value
ViewStateMask - Result value are the view\_states specified when the 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 ReadCondition.
The view\_states returned are the view\_states specified when the ReadCondition was created. view\_states can be NEW\_VIEW\_STATE, NOT\_NEW\_VIEW\_STATE or both.
# 3.5.8 Class QueryCondition
QueryCondition objects are specialized ReadCondition objects that allow the application to specify a filter on the locally available data. The DataReader objects accept a set of QueryCondition objects for the DataReader and provide support (in conjunction with WaitSet objects) for an alternative communication style between the Data Distribution Service and the application (i.e., state-based rather than event-based).
# Query Function
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 DataReader's read/take operations. This allows the Data Distribution Service to trigger the condition only when suitable information is available. QueryCondition objects are to be used in conjunction with a WaitSet. More than one QueryCondition may be attached to the same DataReader.
The query (query\_expression) is similar to an SQL WHERE clause and can be parameterized by arguments that are dynamically changeable with the set\_query\_parameters operation.
The interface description of this class is as follows:
```cpp
class QueryCondition
{
//
// inherited from ReadCondition
//
// SampleStateMask
// get_sample_state_mask
// (void);
// ViewStateMask
// get_view_state_mask
// (void);
// InstanceStateMask
// get_instance_state_mask
// (void);
// DataReader_ptr
// get_datareader
// (void);
// Boolean
// get_trigger_value
// (void);
// implemented API operations
```
```c
//
char*
get_query_expression
(void);
ReturnCode_t
get_query_parameters
(StringSeq& query_parameters);
ReturnCode_t
set_query_parameters
(const StringSeq& query_parameters);
};
```
The next paragraphs describe the usage of all 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 get\_datareader (inherited)
This operation is inherited and therefore not described here. See the class ReadCondition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataReader_ptr
get_datareader
(void);
```
# 3.5.8.2 get\_instance\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class ReadCondition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceStateMask
get_instance_state_mask
(void);
```
# 3.5.8.3 get\_query\_parameters
# Scope
```txt
DDS::QueryCondition
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
```
```txt
ReturnCode_t
get_query_parameters
(StringSeq& query_parameters);
```
# Description
This operation obtains the query\_parameters associated with the QueryCondition.
# Parameters
inout StringSeq& query\_parameters - a reference to a sequence of strings that will be used to store the parameters used in the SQL expression.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_ OF\_RESOURCES.
# Detailed Description
This operation obtains the query\_parameters associated with the QueryCondition. That is, the parameters specified on the last successful call to set\_query\_parameters or, if set\_query\_parameters was never called, the arguments specified when the 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 QueryCondition.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of query parameters applied to this QueryCondition has successfully been copied into the specified query\_parameters parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the QueryCondition has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.8.4 get\_query\_expression
# Scope
DDS::QueryCondition
# Synopsis
```c
#include <ccpp_dds_dcps.h>
char*
get_query_expression
(void);
```
# Description
This operation returns the query expression associated with the QueryCondition.
# Parameters
```txt
<none>
```
# Return Value
char\* - Result value is a reference to the query expression associated with the QueryCondition.
# Detailed Description
This operation returns the query expression associated with the QueryCondition. That is, the expression specified when the QueryCondition was created. The operation will return NULL when there was an internal error or when the QueryCondition was already deleted. If there were no parameters, an empty sequence is returned.
# 3.5.8.5 get\_sample\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class ReadCondition for further explanation.
# Synopsis
```cpp
#include <cpp_dds_dcps.h>
SampleStateMask
get_sample_state_mask
(void);
```
# 3.5.8.6 get\_trigger\_value (inherited)
This operation is inherited and therefore not described here. See the class ReadCondition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
Boolean
get_trigger_value
(void);
```
# 3.5.8.7 get\_view\_state\_mask (inherited)
This operation is inherited and therefore not described here. See the class ReadCondition for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ViewStateMask
get_view_state_mask
(void);
```
# 3.5.8.8 set\_query\_parameters
# Scope
```txt
DDS::QueryCondition
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_query_parameters
(const StringSeq& parameters);
```
# Description
This operation changes the query parameters associated with the QueryCondition.
# Parameters
in const 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
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_BAD\_PARAMETER, RETCODE\_ALREADY\_ DELETED or 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 QueryCondition. The parameter query\_parameters is a sequence of strings which are the parameter 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 a n d % 8 a r e u s e d a s p a r a m e t e r i n t h e q u e r y \_ e x p r e s s i o n , t h e query\_parameters should at least contain n+1 = 9 values).
# Return Code
When the operation returns:
• RETCODE\_OK - the query parameters associated with the QueryCondition are changed.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the number of parameters in query\_parameters does not match the number of “%n” tokens in the expression for this QueryCondition or one of the parameters is an illegal parameter.
• RETCODE\_ALREADY\_DELETED - the QueryCondition has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.9 Class 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 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 DataReaderView belongs to exactly one DataReader.
• A DataReader can have zero to many DataReaderViews attached (all with their own key\_list definitions).
• The DataReaderView has the same interface as the DataReader, with its read and take variants, including w\_condition and next\_instance, next\_sample, etc.. It also supports ReadConditions and QueryConditions like a 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.
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:
```cpp
class DataReaderView
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// abstract operations (implemented in the data type specific
DataReaderView
//
// ReturnCode_t
// get_key_value
// (<data>& key_holder,
// InstanceHandle_t handle);
//
// InstanceHandle_t
// lookup_instance
// (const <data>& instance_data)
```
```c
//
// ReturnCode_t
// read
//
(<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// read_instance
//
(<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// read_next_instance
//
(<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// read_next_instance_w_condition
//
(<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// ReadCondition_ptr a_condition);
//
// ReturnCode_t
// read_next_sample
//
(<data>& data_values,
// SampleInfo& sample_info);
//
// ReturnCode_t
// read_w_condition
//
(<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// ReadCondition_ptr a_condition);
//
```
```c
// ReturnCode_t
// return_loan
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq);
//
// ReturnCode_t
// take
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// take_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// take_next_instance
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
// take_next_instance_w_condition
// (<data>Seq& data_values,
// SampleInfoSeq& info_seq,
// Long max_samples,
// InstanceHandle_t a_handle,
// ReadCondition_ptr a_condition);
//
// ReturnCode_t
// take_next_sample
// (<data>& data_values,
// SampleInfo& sample_info);
//
// ReturnCode_t
// take_w_condition
// (<data>Seq& data_values,
```
```c
// SampleInfoSeq& info_seq,
// Long max_samples,
// ReadCondition_ptr a_condition);
//
// implemented API operations
QueryCondition_ptr
create_querycondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
delete_contained_entities
(void);
ReturnCode_t
delete_readcondition
(ReadCondition_ptr a_condition);
DataReader_ptr
get_datareader
(void);
ReturnCode_t
get_qos
(DataReaderViewQos& qos);
ReturnCode_t
set_qos
(const DataReaderViewQos& qos);
```
The following 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 descriptions of these operations are 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, a full description is not given but the operation on the DataReader or its respective type specific class is referenced.
# 3.5.9.1 create\_querycondition
# Scope
DDS::DataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
QueryCondition_ptr
create_querycondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
```
# Description
This operation creates a new QueryCondition for the DataReaderView. For a full description please refer to Section 3.5.2.2, create\_querycondition, on page 368, which describes this operation in detail for the DataReader class.
# 3.5.9.2 create\_readcondition
# Scope
DDS::DataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
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, create\_readcondition, on page 369, which describes this operation in detail for the DataReader class.
# 3.5.9.3 delete\_contained\_entities
# Scope
```txt
DDS::DataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# Description
This operation deletes all the entitiesthat 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, delete\_contained\_entities, on page 371, which describes this operation in detail for the DataReader class.
# 3.5.9.4 delete\_readcondition
# Scope
```txt
DDS::DataReaderView
```
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_readcondition
(ReadCondition_ptr 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, delete\_contained\_entities, on page 371, which describes this operation in detail for the DataReader class.
# 3.5.9.5 enable (inherited)
This operation is inherited and therefore not described here. See Section 3.1.1, Class Entity (abstract), on page 26, for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.5.9.6 get\_datareader
# Scope
```txt
DDS::DataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
DataReader_ptr
get_datareader
(void);
```
# Description
Retrieves the DataReader to which this DataReaderView is attached.
# Parameters
```txt
<none>
```
# Return Value
DataReader\_ptr - A pointer to the DataReader.
# Detailed Description
This operation returns a pointer to the DataReader from which the DataReaderView was originally created. If the DataReader cannot be retrieved, NULL is returned.
# 3.5.9.7 get\_key\_value (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type Foo-derived FooDataReaderView class (see Section 3.5.10, Class FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_key_value
(<data>& key_holder,
InstanceHandle_t handle);
```
# 3.5.9.8 get\_qos
# Scope
```txt
DDS::DataReaderView
```
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DataReaderViewQos& qos);
```
# Description
This operation allows access to the existing set of QoS policies for a DataReaderView. For a full description please refer to Section 3.5.2.16, get\_qos, on page 382, which describes this operation in detail for the DataReader class.
# Parameters
inout DataReaderViewQos& qos - a reference to the destination DataReaderViewQos struct in which the QosPolicy settings will be copied.
# Return Value
ReturnCode\_t - Possible return codes of the operation are: RETCODE\_OK, RETCODE\_ERROR, RETCODE\_ALREADY\_DELETED or RETCODE\_OUT\_OF\_RESOURCES.
# Detailed Description
This operation allows access to the existing set of QoS policies of a DataReaderView on which this operation is used. This DataReaderViewQos is stored at the location pointed to by the qos parameter.
# Return Code
When the operation returns:
• RETCODE\_OK - the existing set of QoSPolicy values applied to this DataReaderView has successfully been copied into the specified DataReaderViewQos parameter.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_ALREADY\_DELETED - the DataReaderView has already been deleted.
• RETCODE\_OUT\_OF\_RESOURCES - the Data Distribution Service ran out of resources to complete this operation.
# 3.5.9.9 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See Section 3.1.1, Class Entity (abstract), on page 26, for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
```
```sql
StatusMask
get_status_changes
(void);
```
# 3.5.9.10 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See Section 3.1.1, Class Entity (abstract), on page 26, for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.5.9.11 lookup\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o - d e r i v e d F o oD a t a R e a de r V i e w c l a s s ( S e c t i o n 3 . 5 . 1 0 , C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
lookup_instance
(const <data>& instance_data)
```
# 3.5.9.12 read (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o - d e r i v e d F o oD a t a R e a de r V i e w c l a s s ( S e c t i o n 3 . 5 . 1 0 , C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
```
InstanceStateMask instance\_states);
# 3.5.9.13 read\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_instance
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.9.14 read\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_next_instance
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.9.15 read\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_instance_w_condition
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# 3.5.9.16 read\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_sample
(<data>& data_values,
SampleInfo& sample_info);
```
# 3.5.9.17 read\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
```
```txt
read_w_condition
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# 3.5.9.18 return\_loan (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type Foo derived FooDataReaderView class (Section 3.5.10, Class FooDataReaderView, on page 484).
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
return_loan
(<data>Seq& data_values,
SampleInfoSeq& info_seq);
```
# 3.5.9.19 set\_qos
# Scope
DDS::DataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const DataReaderViewQos& qos);
```
# Description
This operation replaces the existing set of QosPolicy settings for a DataReaderView.
# Parameters
in const DataReaderViewQos& qos - qos contains the new set of QosPolicy settings for the DataReader.
# Return Value
```txt
ReturnCode_t - Possible return codes of the operation are:
RETCODE_OK, RETCODE_ERROR, RETCODE_BAD_PARAMETER,
RETCODE_ALREADY_DELETED, RETCODE_OUT_OF_RESOURCES or
RETCODE_IMMUTABLE_POLICY.
```
# Detailed Description
This operation replaces the existing set of QosPolicy settings for a 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 DataReader, which can only be set before the DataReader is enabled, the operation will fail and a 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 RETCODE\_OK).
# Return Code
When the operation returns:
• RETCODE\_OK - the new DataReaderQos is set.
• RETCODE\_ERROR - an internal error has occurred.
• RETCODE\_BAD\_PARAMETER - the parameter qos is not a valid DataReaderQos. It contains a QosPolicy setting with an invalid Duration\_t value or an enum value that is outside its legal boundaries.
• RETCODE\_ALREADY\_DELETED - the DataReader 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 DataReaderView.
# 3.5.9.20 take (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take
(<data>Seq& data_values,
```
```sql
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.9.21 take\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_instance
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.9.22 take\_next\_instance (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_instance
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.9.23 take\_next\_instance\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_instance_w_condition
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# 3.5.9.24 take\_next\_sample (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_sample
(<data>& data_values,
SampleInfo& sample_info);
```
# 3.5.9.25 take\_w\_condition (abstract)
This abstract operation is defined as a generic operation, which is implemented by the <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 fictional data type F o o- d e r i ved F o o Da t a R e a d er V i e w class (Sec tion 3.5.10, C l a s s FooDataReaderView, on page 484).
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
```
```txt
take_w_condition
(<data>Seq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# 3.5.10 Class 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 <type>DataReaderView classes. For each application data type which is used as Topic data type, a typed class <type>DataReaderView is derived from the DataReaderView class. In this paragraph, the class FooDataReaderView in the n a m e s p a c e S P A C E d e s c r i b e s t h e o p e r a t i o n s o f t h e s e d e r i v e d <type>DataReaderView classes as an example for the fictional type Foo (defined in the module SPACE).
The interface description of this class is as follows:
```cpp
class FooDataReaderView
{
//
// inherited from class Entity
//
// StatusCondition_ptr
// get_statuscondition
// (void);
// StatusMask
// get_status_changes
// (void);
// ReturnCode_t
// enable
// (void);
//
// inherited from class DataReaderView
//
// QueryCondition_ptr
// create_querycondition
// (SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states,
// const char* query_expression,
// const StringSeq& query_parameters);
//
// ReadCondition_ptr
// create_readcondition
// (SampleStateMask sample_states,
// ViewStateMask view_states,
// InstanceStateMask instance_states);
//
// ReturnCode_t
```
```c
// delete_contained_entities
// (void);
//
// ReturnCode_t
// delete_readcondition
// (ReadCondition_ptr a_condition);
//
// DataReader_ptr
// get_datareader
// (void);
//
// ReturnCode_t
// get_qos
// (DataReaderViewQos& qos);
//
// ReturnCode_t
// set_qos
// (const DataReaderViewQos& qos);
//
//
// implemented API operations
//
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
InstanceHandle_t
lookup_instance
(const Foo& instance_data)
ReturnCode_t
read
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
read_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
```txt
ReturnCode_t
read_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
read_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
ReturnCode_t
read_next_sample
(Foo& data_values,
SampleInfo& sample_info);
ReturnCode_t
read_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
ReturnCode_t
return_loan
(FooSeq& data_values,
SampleInfoSeq& info_seq);
ReturnCode_t
take
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
```
```txt
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
ReturnCode_t
take_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
ReturnCode_t
take_next_sample
(Foo& data_values,
SampleInfo& sample_info);
ReturnCode_t
take_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
The following paragraphs describe the usage of all FooDataReaderView operations. The inherited operations are listed but not fully described because they are not implemented in this class. Full descriptions of these operations are given in the classes from which they are inherited.
# 3.5.10.1 create\_querycondition (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
QueryCondition_ptr
create_querycondition
```
```typescript
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states,
const char* query_expression,
const StringSeq& query_parameters);
```
# 3.5.10.2 create\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```txt
#include <ccpp_dds_dcps.h>
ReadCondition_ptr
create_readcondition
(SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# 3.5.10.3 delete\_contained\_entities
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
delete_contained_entities
(void);
```
# 3.5.10.4 delete\_readcondition (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
delete_readcondition
(ReadCondition_ptr a_condition);
```
# 3.5.10.5 enable (inherited)
This operation is inherited and therefore not described here. See the class Entity (Section 3.1.1, Class Entity (abstract), on page 26) for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
enable
(void);
```
# 3.5.10.6 get\_datareader (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
DataReader_ptr
get_datareader
(void);
```
# 3.5.10.7 get\_key\_value
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_key_value
(Foo& key_holder,
InstanceHandle_t handle);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.8 get\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
get_qos
(DataReaderViewQos& qos);
```
# 3.5.10.9 get\_status\_changes (inherited)
This operation is inherited and therefore not described here. See the class Entity for further explanation.
# Synopsis
```c
#include <ccpp_dds_dcps.h>
StatusMask
get_status_changes
(void);
```
# 3.5.10.10 get\_statuscondition (inherited)
This operation is inherited and therefore not described here. See the class Entity (Section 3.1.1, Class Entity (abstract), on page 26) for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
StatusCondition_ptr
get_statuscondition
(void);
```
# 3.5.10.11 lookup\_instance
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
InstanceHandle_t
lookup_instance
(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 Section 3.5.2.67, lookup\_instance, on page 417, which describes this operation in detail for the DataReader class. Note that instances in the FooDataReaderView are not defined by the keys of the TopicDescription but by the key list in the DataReaderView QosPolicy.
# 3.5.10.12 read
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read
```
```txt
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReaderView. For a full description please refer to Section 3.5.2.68, read, on page 417, which describes this operation in detail for the DataReader class.
# 3.5.10.13 read\_instance
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
read_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 a single instance from the FooDataReaderView. For a full description please refer to Section 3.5.2.69, read\_instance, on page 422, which describes this operation in detail for the DataReader class.
# 3.5.10.14 read\_next\_instance
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
```
```txt
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 FooDataReaderView. For a full description please refer to Section 3.5.2.70, read\_next\_instance, on page 424, which describes this operation in detail for the DataReader class.
# 3.5.10.15 read\_next\_instance\_w\_condition
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the FooDataReaderView, filtered by a ReadCondition or QueryCondition. For a full description please refer to Section 3.5.2.71, read\_next\_instance\_w\_condition, on page 426, which describes this operation in detail for the DataReader class.
# 3.5.10.16 read\_next\_sample
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```txt
#include <cpp_dds_dcps.h>
ReturnCode_t
read_next_sample
(Foo& data_values,
SampleInfo& sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.17 read\_w\_condition
# Scope
SPACE::FooDataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
read_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReaderView, filtered by a ReadCondition or QueryCondition. For a full description please refer to Section 3.5.2.73, read\_w\_condition, on page 428, which describes this operation in detail for the DataReader class.
# 3.5.10.18 return\_loan
# Scope
SPACE::FooDataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
return_loan
(FooSeq& data_values,
SampleInfoSeq& info_seq);
```
# Description
This operation indicates to the DataReaderView 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.74, return\_loan, on page 430, which describes this operation in detail for the DataReader class.
# 3.5.10.19 set\_qos (inherited)
This operation is inherited and therefore not described here. See the class DataReaderView (Section 3.5.9, Class DataReaderView (abstract), on page 468) for further explanation.
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
set_qos
(const DataReaderViewQos& qos);
```
# 3.5.10.20 take
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
take
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
SampleStateMask sample_states,
ViewStateMask view_states,
InstanceStateMask instance_states);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReaderView and by doing so, removes the data from the FooDataReaderView, but not from the FooDataReader that it belongs to. For a full description please refer to Section 3.5.2.77, take, on page 432, which describes this operation in detail for the DataReader class.
# 3.5.10.21 take\_instance
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 a single instance from the FooDataReaderView and by doing so, removes the data from the FooDataReaderView, but not from the FooDataReader that it belongs to. For a full description please refer to Section 3.5.2.78, take\_instance, on page 434, which describes this operation in detail for the DataReader class.
# 3.5.10.22 take\_next\_instance
# Scope
SPACE::FooDataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_instance
(FooSeq& data_values,
SampleInfoSeq& info_seq,
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 FooDataReaderView and by doing so, removes the data from the FooDataReaderView, but not from the FooDataReader that it belongs to. For a full description please refer to Section 3.5.2.79, take\_next\_instance, on page 436, which describes this operation in detail for the DataReader class.
# 3.5.10.23 take\_next\_instance\_w\_condition
# Scope
SPACE::FooDataReaderView
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_instance_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
InstanceHandle_t a_handle,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples of the next single instance from the FooDataReaderView, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReaderView, but not from the FooDataReader that it belongs to. For a full description please refer to Section 3.5.2.80, take\_next\_instance\_w\_condition, on page 437, which describes this operation in detail for the DataReader class.
# 3.5.10.24 take\_next\_sample
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_next_sample
(Foo& data_values,
SampleInfo& sample_info);
```
NOTE: This operation is not yet implemented. It is scheduled for a future release.
# 3.5.10.25 take\_w\_condition
# Scope
```txt
SPACE::FooDataReaderView
```
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
take_w_condition
(FooSeq& data_values,
SampleInfoSeq& info_seq,
Long max_samples,
ReadCondition_ptr a_condition);
```
# Description
This operation reads a sequence of Foo samples from the FooDataReaderView, filtered by a ReadCondition or QueryCondition and by doing so, removes the data from the FooDataReaderView, but not from the FooDataReader that it belongs to. For a full description please refer to Section 3.5.2.82, take\_w\_condition, on page 439, which describes this operation in detail for the DataReader 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 Vortex OpenSplice and has no factory. It is not associated with a DomainParticipant, so it can be be obtained by a normal allocation.
# 3.6.1 Class QosProvider
The QosProvider class provides access to the QoS settings that are specified in an XML file. The interface is as follows:
```cpp
class QosProvider
{
/* Constructor */
QosProvider (
const char *uri,
const char *profile);
/* API operations */
ReturnCode_t
get_participant_qos(
DomainParticipantQos &qos,
const char *id);
ReturnCode_t
get_topic_qos(
TopicQos &qos,
const char *id);
ReturnCode_t
get_subscriber_qos(
SubscriberQos &qos,
const char *id);
ReturnCode_t
get_datareader_qos(
DataReaderQos &qos,
const char *id);
ReturnCode_t
get_publisher_qos(
PublisherQos &qos,
const char *id);
ReturnCode_t
get_datawriter_qos(
DataWriterQos &qos,
const char *id);
}
```
# 3.6.1.1 QosProvider
# Synopsis
```c
#include <cpp_dds_dcps.h>
QosProvider(
const char *uri,
const char *profile);
```
# Description
Constructs a new 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 get\_\*\_qos(...) operations.
# Return Value
A QosProvider instance that is instantiated with all profiles and/or QoS’s loaded from the location specified by the provided uri.
Initialization of the 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).
When initialisation fails (for example, due to a parse error or when the resource identified by uri cannot be found), any subsequent operations on the QosProvider will return DDS::RETCODE\_PRECONDITION\_NOT\_MET.
# 3.6.1.2 get\_participant\_qos
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_participant_qos(
DomainParticipantQos &qos,
const char *id);
```
# Description
Resolves the DomainParticipantQos identified by the id from the uri the QosProvider \_this is associated with.
# Parameters
inout DomainParticipantQos & q o s - T h e d e s t i n a t i o n 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no DomainParticipantQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER If qos DOMAINPARTICIPANT\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 get\_topic\_qos
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_topic_qos(
TopicQos &qos,
const char *id);
```
# Description
Resolves the TopicQos identified by the id from the uri the QosProvider is associated with.
# Parameters
inout TopicQos & qos - The destination 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no TopicQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER - If qos == TOPIC\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 get\_subscriber\_qos
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_subscriber_qos(
SubscriberQos &qos,
const char *id);
```
# Description
Resolves the SubscriberQos identified by the id from the uri the QosProvider is associated with.
# Parameters
inout SubscriberQos & qos - The destination 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no SubscriberQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER - If qos == SUBSCRIBER\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 get\_datareader\_qos
# Synopsis
```c
#include <ccpp_dds_dcps.h>
ReturnCode_t
get_datareader_qos(
DataReaderQos &qos,
const char *id);
```
# Description
Resolves the DataReaderQos identified by the id from the uri the QosProvider is associated with.
# Parameters
inout DataReaderQos & qos - The destination 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no DataReaderQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER - If qos == DATAREADER\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 get\_publisher\_qos
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_publisher_qos(
PublisherQos &qos,
const char *id);
```
# Description
Resolves the PublisherQos identified by the id from the uri the QosProvider is associated with.
# Parameters
inout PublisherQos & qos - The destination 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no PublisherQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER - If qos == PUBLISHER\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 get\_datawriter\_qos
# Synopsis
```c
#include <cpp_dds_dcps.h>
ReturnCode_t
get_datawriter_qos(
DataWriterQos &qos,
const char *id);
```
# Description
Resolves the DataWriterQos identified by the id from the uri the QosProvider is associated with.
# Parameters
inout DataWriterQos & qos - The destination 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 QosProvider or a name that identifies a QoS within the uri associated with the 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 QosProvider instance. When id is NULL it is interpreted as a non-named QoS within the default QoS profile associated with the QosProvider.
# Return Value
The operation may return:
• DDS::RETCODE\_OK - If qos has been initialized successfully.
• DDS::RETCODE\_NO\_DATA - If no DataWriterQos that matches the provided id can be found within the uri associated with the QosProvider.
• DDS::RETCODE\_BAD\_PARAMETER - If qos == DATAWRITER\_QOS\_DEFAULT.
• DDS::RETCODE\_PRECONDITION\_NOT\_MET - If the 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 Entity is accompanied by an <Entity>Qos structure that implements the basic mechanism for an application to specify Quality of Service attributes. This structure consists of Entity specific QosPolicy attributes. QosPolicy attributes are structured types where each type specifies the information that controls an Entity related (configurable) attribute of the Data Distribution Service. A QosPolicy attribute struct is identified as <name>QosPolicy.
# Affected Entities
Each Entity can be configured with a set of QosPolicy settings. However, any Entity cannot support any QosPolicy. For instance, a DomainParticipant supports different QosPolicy settings than a Topic or a Publisher. The set of QosPolicy settings is implemented as a struct of QosPolicy structs, identified as <Entity>Qos. Each <Entity>Qos struct only contains those QosPolicy structs relevant to the specific Entity. The <Entity>Qos struct serves as the parameter to operations which require a Qos. <Entity>Qos struct is the API implementation of the QoS. Depending on the specific <Entity>Qos, it controls the behaviour of a Topic, DataWriter, DataReader, Publisher, Subscriber, DomainParticipant or DomainParticipantFactory1 .
# Basic Usage
The basic way to modify or set the <Entity>Qos is by using an get\_qos operation to get all QosPolicy settings from this Entity (that is the <Entity>Qos), modify several specific QosPolicy settings and put them back using an set\_qos operation to set all QosPolicy settings on this Entity (that is the <Entity>Qos). An example of these operations for the DataWriterQos are get\_default\_datawriter\_qos and set\_default\_datawriter\_qos, which take the DataWriterQos as a parameter.
The interface description of this struct is as follows:
```txt
// struct <name>QosPolicy
// see appendix
//
```
1. Note that the DomainParticipantFactory is a special kind of entity: it does not inherit from Entity, nor does it have a Listener or StatusCondition, but its behaviour can be controlled by its own set of QosPolicies.
```c
//
// struct <Entity>Qos
//
struct DomainParticipantFactoryQos
{ EntityFactoryQosPolicy entity_factory; };
struct DomainParticipantQos
{---------------------------------------------------------------------- user_data;
EntityFactoryQosPolicy entity_factory;
SchedulingQosPolicy watchdog_scheduling;
SchedulingQosPolicy listener_scheduling; };
struct TopicQos
{ TopicDataQosPolicy topic_data;
DurabilityQosPolicy durability;
DurabilityServiceQosPolicy durability_service;
DeadlineQosPolicy deadline;
LatencyBudgetQosPolicy latency_budget;
LivelinessQosPolicy liveliness;
ReliabilityQosPolicy reliability;
DestinationOrderQosPolicy destination_order;
HistoryQosPolicy history;
ResourceLimitsQosPolicy resource_limits;
TransportPriorityQosPolicy transport_priority;
LifespanQosPolicy lifespan;
OwnershipQosPolicy ownership; };
struct DataWriterQos
{ DurabilityQosPolicy durability;
DeadlineQosPolicy deadline;
LatencyBudgetQosPolicy latency_budget;
LivelinessQosPolicy liveliness;
ReliabilityQosPolicy reliability;
DestinationOrderQosPolicy destination_order;
HistoryQosPolicy history;
ResourceLimitsQosPolicy resource_limits;
TransportPriorityQosPolicy transport_priority;
LifespanQosPolicy lifespan;
UserDataQosPolicy user_data;
OwnershipQosPolicy ownership;
OwnershipStrengthQosPolicy ownership_strength;
WriterDataLifecycleQosPolicy writer_data_lifecycle;};
struct PublisherQos
{ PresentationQosPolicy presentation;
PartitionQosPolicy partition;
GroupDataQosPolicy group_data;
EntityFactoryQosPolicy entity_factory; };
struct DataReaderQos
{ DurabilityQosPolicy durability;
DeadlineQosPolicy deadline;
LatencyBudgetQosPolicy latency_budget;
LivelinessQosPolicy liveliness;
ReliabilityQosPolicy reliability;
```
```c
DestinationOrderQosPolicy destination_order;
HistoryQosPolicy history;
ResourceLimitsQosPolicy resource_limits;
UserDataQosPolicy user_data;
OwnershipQosPolicy ownership;
TimeBasedFilterQosPolicy time_based_filter;
ReaderDataLifecycleQosPolicy reader_data_lifetime;};
struct DataReaderViewQos
{ ViewKeyQosPolicy view_keys; }
struct SubscriberQos
{ PresentationQosPolicy presentation;
PartitionQosPolicy partition;
GroupDataQosPolicy group_data;
EntityFactoryQosPolicy entity_factory; };
//
// define <Entity>_QOS_DEFAULT
//
#define PARTICIPANT_QOS_DEFAULT
#define TOPIC_QOS_DEFAULT
#define DATAWRITER_QOS_DEFAULT
#define PUBLISHER_QOS_DEFAULT
#define DATAREADER_QOS_DEFAULT
#define SUBSCRIBER_QOS_DEFAULT
#define DATAWRITER_QOS_USE_TOPIC_QOS
#define DATAREADER_QOS_USE_TOPIC_QOS
//
// implemented API operations
// <no operations>
//
```
The next paragraphs describe the usage of each <Entity>Qos struct.
# DataReaderQos
# Scope
DDS
# Synopsis
```c
#include <ccpp_dds_dcps.h>
struct DataReaderQos
{ DurabilityQosPolicy durability;
DeadlineQosPolicy deadline;
LatencyBudgetQosPolicy latency_budget;
LivelinessQosPolicy liveliness;
ReliabilityQosPolicy reliability;
DestinationOrderQosPolicy destination_order;
HistoryQosPolicy history;
ResourceLimitsQosPolicy resource_limits;
```
```txt
UserDataQosPolicy user_data;
OwnershipQosPolicy ownership;
TimeBasedFilterQosPolicy time_based_filter;
ReaderDataLifecycleQosPolicy reader_data_lifecycle;
SubscriptionKeyQosPolicy subscription_keys;
ReaderLifespanQosPolicy reader_lifespan;
ShareQosPolicy share;};
```
# Description
This struct provides the basic mechanism for an application to specify Quality of Service attributes for a DataReader.
# Attributes
DurabilityQosPolicy durability - whether the data should be stored for late joining - deadline - the period within which a new sample is expected. See Section 3.1.3.3 on page 46 for more detailed information about these settings.
LatencyBudgetQosPolicy latency\_budget - used by the Data Distribution Service for optimization. See Section 3.1.3.8 on page 55 for more detailed information about these settings.
LivelinessQosPolicy liveliness - the way the liveliness of the DataReader is asserted to the Data Distribution Service. See Section 3.1.3.10 on page 58 for more detailed information about these settings.
ReliabilityQosPolicy reliability - the reliability of the data distribution. See Section 3.1.3.16 on page 74 for more detailed information about these settings.
DestinationOrderQosPolicy destination\_order - the order in which the DataReader timely orders the data. See Section 3.1.3.2 on page 44 for more detailed information about these settings.
HistoryQosPolicy history - how samples should be stored. See Section 3.1.3.7 on page 53 for more detailed information about these settings.
ResourceLimitsQosPolicy resource\_limits - the maximum amount of resources to be used. See Section 3.1.3.17 on page 76 for more detailed information about these settings.
UserDataQosPolicy user\_data - used to attach additional information to the DataReader. See Section 3.1.3.22 on page 82 for more detailed information about these settings.
OwnershipQosPolicy ownership - whether a DataWriter exclusively owns an instance. See Section 3.1.3.11 on page 60 for more detailed information about these settings.
TimeBasedFilterQosPolicy time\_based\_filter - the maximum data rate at which the DataReader will receive changes. See Section 3.1.3.19 on page 79 for more detailed information about these settings.
ReaderDataLifecycleQosPolicy reader\_data\_lifecycle - determines 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 NOT\_ALIVE\_NO\_WRITERS\_INSTANCE\_STATE o r 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 71 for more detailed information about these settings.
SubscriptionKeyQosPolicy subscription\_keys - Allows the DataReader to define its own set of keys on the data, different from the keys defined by the topic. See Section 3.1.3.24 on page 84 for more detailed information about these settings.
ReaderLifespanQosPolicy reader\_lifespan - Automatically remove samples from the DataReader after a specified timeout. See Section 3.1.3.25 on page 86 for more detailed information about these settings.
ShareQosPolicy share - Used to share a DataReader between multiple processes. See Section 3.1.3.26 on page 86 for more detailed information about these settings.
# Detailed Description
A QosPolicy can be set when the DataReader is created with the create\_datareader operation (or modified with the set\_qos operation). Both operations take the 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 set\_qos operation.
Some QosPolicy have “immutable” semantics meaning that they can only be specified either at DataReader creation time or prior to calling the enable operation on the DataReader.
The initial value of the default DataReaderQos in the Subscriber are given in the following table:
Table 16 QosPolicy Values
| Entity | Status Name | Description |
| Topic | INCONSISTENT_TOPIC_STATUS | Another Topic exists with the same name but with different characteristics. |
| ALL_DATA_DISPOSED_TOPIC_STATUS | All instances of the Topic have been disposed by the dispose_all_data operation on that topic. |
| Subscriber | DATA_ON_READERS_STATUS | New information is available. |
| DataReader | SAMPLE_REJECTED_STATUS | A (received) sample has been rejected. |
| LIVELINESS_CHANGED_STATUS | The liveliness of one or more DataWriter objects, that were writing instances read through the DataReader objects has changed. Some DataWriter object have become “alive” or “not alive”. |
| REQUESTED_DEADLINE_MISSED_STATUS | The deadline that the DataReader was expecting through its DeadlineQosPolicy was not respected for a specific instance. |
| REQUESTED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what is offered. |
| DATA_AVAILABLE_STATUS | New information is available. |
| SAMPLE_LOST_STATUS | A sample has been lost (never received). |
| SUBSCRIPTION_MATCH_STATUS | The DataReader has found a DataWriter that matches the Topic and has compatible QoS. |
| DataWriter | LIVELINESS_LOST_STATUS | The liveliness that the DataWriter has committed through its LivelinessQosPolicy was not respected; thus DataReader objects will consider the DataWriter as no longer “active”. |
| OFFERED_DEADLINE_MISSED_STATUS | The deadline that the DataWriter has committed through its DeadlineQosPolicy was not respected for a specific instance. |
| OFFERED_INCOMPATIBLE_QOS_STATUS | A QosPolicy setting was incompatible with what was requested. |
| PUBLICATION_MATCH_STATUS | The DataWriter has found DataReader that matches the 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 DATA\_ON\_READERS and 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 INCONSISTENT\_TOPIC status (which information is stored in the InconsistentTopicStatus struct), the application must call the operation get\_inconsistent\_topic\_status. A plain communication status can only be read from the 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 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 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, i.e. a listener with value NULL. Such a listener is treated as a NOOP1 for all statuses activated in its bit mask 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 RequestedDeadlineMissedStatus will become TRUE each time a new deadline 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 RequestedDeadlineMissedStatus). The value changes to FALSE when the 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 get\_requested\_deadline\_missed\_status operation on the proper Entity, or when the on\_requested\_deadline\_missed operation on the Listener attached to this 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:
```txt
- the DataWriter that owns it if its OwnershipQosPolicyKind = EXCLUSIVE_OWNERSHIP_QOS
- or by any DataWriter if its OwnershipQosPolicyKind = SHARED_OWNERSHIP_QOS.
```
• The loss of liveliness of the DataWriter of an instance for which there is no other DataWriter.
• The arrival of the notification that an instance has been unregistered by the only DataWriter that is known to be writing the instance.
Figure 25 Read Communication Status DataReader Statecraft
Figure 26 Subscriber Statecraft for a Read Communication Status
• The status flag of the 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 Subscriber.
- The on\_data\_available listener operation is called on any DataReader belonging to the Subscriber.
\- The read or take operation (or any of its variants) is called on any DataReader belonging to the Subscriber.
# Listeners
The Listeners provide for an event-based mechanism to asynchronous 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 Entity is also available in the Listener of the factory of the 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 Entity and enabled for this particular status. Statuses are enabled according the to the StatusKindMask parameter that was passed at creation time of the Entity, or that was passed to the set\_listener operation.
When an event occurs for a particular 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 Entity. For this factory, the same propagation rules apply. When even the 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 Entity only invokes the Listener of its factory if the Listener of the contained 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. However, since the event here is the arrival of data, both the DATA\_ON\_READERS and DATA\_AVAILABLE status are TRUE. The Data Distribution Service will first attempt to handle the DATA\_ON\_READERS status and try to activate the SubscriberListener. When this Listener is not activated for this status the event will propagate to the DomainParticipantListener. Only when the DATA\_ON\_READERS status can not be handled, the Data Distribution Service will attempt to handle the DATA\_AVAILABLE status and try to activate the 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 Conditions in conjunction with WaitSets provide for a state-based mechanism to synchronously inform the application of status changes. A Condition can be either a ReadCondition, QueryCondition, StatusCondition or GuardCondition. To create a Condition one of the following operations can be used:
• ReadCondition created by create\_readcondition
• QueryCondition created by create\_querycondition
• StatusCondition retrieved by get\_statuscondition on an Entity
• GuardCondition created by the C++ operation new
Note that the QueryCondition is a specialized ReadCondition. The GuardCondition is a different kind of Condition since it is not controlled by a status but directly by the application (when a GuardCondition is initially created, the trigger\_value is FALSE). The StatusCondition is present by default with each Entity, therefore, it does not have to be created.
Figure 28 DCPS WaitSets
A WaitSet may have one or several Conditions attached to it. An application thread may block execution (blocking may be limited by a timeout) by waiting on a WaitSet until the trigger\_value of one or more of the Conditions become TRUE. When a Condition, whose trigger\_value evaluates to TRUE, is attached to a WaitSet that is currently being waited on (using the wait operation), the WaitSet will unblock immediately.
This (state-based) mechanism is generally used as follows:
• The application creates a WaitSet.
• The application indicates which relevant information it wants to be notified of, by creating or retrieving Condition objects (StatusCondition, ReadCondition, QueryCondition or GuardCondition) and attach them to a WaitSet.
• It then waits on that WaitSet (using WaitSet::wait) until the trigger\_value of one or several Condition objects (in the WaitSet) become TRUE.
• When the thread is unblocked, the application uses the result of the wait (i.e., the list of Condition objects with trigger\_value==TRUE) to actually get the information:
- if the condition is a StatusCondition and the status changes refer to a plain communication status, by calling get\_status\_changes and then get\_<communication\_status> on the relevant Entity
- if the condition is a StatusCondition and the status changes refer to the read communication status:
DATA\_ON\_READERS, by calling get\_status\_changes and then get\_datareaders on the relevant Subscriber and then read/take on the returned DataReader objects
DATA\_AVAILABLE, by calling get\_status\_changes and then read/take on the relevant DataReader
\- if it is a ReadCondition or a QueryCondition, by calling directly read\_w\_condition/take\_w\_condition on the DataReader with the Condition as a parameter
Figure 29 DCPS Conditions
No extra information is passed from the Data Distribution Service to the application when a wait returns only the list of triggered Condition objects. Therefore, it is the application responsibility to investigate which Condition objects have triggered the WaitSet.
# Blocking Behaviour
The result of a wait operation depends on the state of the WaitSet, which in turn depends on whether at least one attached Condition has a trigger\_value of TRUE. If the wait operation is called on WaitSet with state BLOCKED it will block the calling thread. If wait is called on a WaitSet with state UNBLOCKED it will return immediately. In addition, when the WaitSet transitions from state BLOCKED to state UNBLOCKED it wakes up the thread (if any) that had called wait on it. Note that there can only be one thread waiting on a single WaitSet.
Figure 30 Blocking Behaviour of a Waitset State Chart
# StatusCondition Trigger State
The trigger\_value of a 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 StatusCondition to a particular communication status is controlled by the bit mask of enabled\_statuses set on the Condition by means of the set\_enabled\_statuses operation.
# ReadCondition and QueryCondition Trigger State
Similar to the StatusCondition, a ReadCondition also has a trigger\_value that determines whether the attached WaitSet is BLOCKED or UNBLOCKED. However, unlike the StatusCondition, the trigger\_value of the 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 ReadCondition. Additionally, for the 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 ReadCondition is dependent on the presence of samples on the associated DataReader implies that a single take operation can potentially change the trigger\_value of several ReadCondition or QueryCondition objects. For example, if all samples are taken, any ReadCondition or QueryCondition objects associated with the DataReader that had their trigger\_value==TRUE before will see the trigger\_value change to FALSE. Note that this does not guarantee that WaitSet objects, that had those Condition objects separately attached to, will not be woken up. Once we have trigger\_value==TRUE on a Condition it may wake up the WaitSet it was attached to, the condition transitions to trigger\_value==FALSE does not 'un-wake up' the WaitSet as 'un-wakening' is not possible. The consequence is that an application blocked on a WaitSet may return from the wait with a list of Condition objects some of which are no longer “active”. This is unavoidable if multiple threads are concurrently waiting on separate WaitSet objects and taking data associated with the same DataReader Entity. In other words, a wait may r e t u r n w i t h a l i s t o f C o n d i t i o n o b j e c t s w h i c h a l l h a v e a trigger\_value==FALSE. This only means that at some point one or more of the Condition objects have had a trigger\_value==TRUE but no longer do.
# GuardCondition Trigger State
The trigger\_value of a GuardCondition is completely controlled by the application via the operation set\_trigger\_value. This Condition can be used to implement an application defined wake-up of the blocked thread.
# Appendix
# G
# 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.
# 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 the C++ code has to be generated (in accordance with the OMG C++ Language Mapping Specification. The -S option indicates that this C-code should be StandAlone C++ code, in other words, it must not have any dependency on external ORB libraries. (It is also possible to use libraries from an existing ORB, so that your DDS application can also manage information coming from an external ORB. In that case you should use the CORBA-cohabitation mode, replacing the -S flag with a -C flag.). In this example, the pre-processor will generate the classes FooTypeSupport, FooDataWriter and FooDataReader which contain the type specific operations.
# 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. 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.
# 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, get\_matched\_publication\_data, on page 378.
Table 28 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, get\_matched\_subscription\_data, on page 278.
Table 29 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 built-in 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
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