Eclipse Cyclone DDS C API Reference¶
-
struct
dds_allocator
¶
-
struct
dds_builtintopic_endpoint
¶ Public Members
-
dds_guid_t
key
¶
-
dds_guid_t
participant_key
¶
-
dds_instance_handle_t
participant_instance_handle
¶
-
char *
topic_name
¶
-
char *
type_name
¶
-
dds_guid_t
-
struct
dds_builtintopic_participant
¶
-
struct
dds_inconsistent_topic_status
¶ - #include <dds_public_status.h>
DCPS_Status_InconsistentTopic
-
struct
dds_key_descriptor
¶
-
struct
dds_liveliness_changed_status
¶ - #include <dds_public_status.h>
DCPS_Status_LivelinessChanged
-
struct
dds_liveliness_lost_status
¶ - #include <dds_public_status.h>
DCPS_Status_LivelinessLost
-
struct
dds_offered_deadline_missed_status
¶ - #include <dds_public_status.h>
DCPS_Status_OfferedDeadlineMissed
Public Members
-
uint32_t
total_count
¶
-
int32_t
total_count_change
¶
-
dds_instance_handle_t
last_instance_handle
¶
-
uint32_t
-
struct
dds_offered_incompatible_qos_status
¶ - #include <dds_public_status.h>
DCPS_Status_OfferedIncompatibleQoS
-
struct
dds_publication_matched_status
¶ - #include <dds_public_status.h>
DCPS_Status_PublicationMatched
-
struct
dds_requested_deadline_missed_status
¶ - #include <dds_public_status.h>
DCPS_Status_RequestedDeadlineMissed
Public Members
-
uint32_t
total_count
¶
-
int32_t
total_count_change
¶
-
dds_instance_handle_t
last_instance_handle
¶
-
uint32_t
-
struct
dds_requested_incompatible_qos_status
¶ - #include <dds_public_status.h>
DCPS_Status_RequestedIncompatibleQoS
-
struct
dds_rhc
¶
-
struct
dds_rhc_ops
¶ Public Members
-
struct ddsi_rhc_ops
rhc_ops
¶
-
dds_rhc_read_take_t
read
¶
-
dds_rhc_read_take_t
take
¶
-
dds_rhc_read_take_cdr_t
readcdr
¶
-
dds_rhc_read_take_cdr_t
takecdr
¶
-
dds_rhc_add_readcondition_t
add_readcondition
¶
-
dds_rhc_remove_readcondition_t
remove_readcondition
¶
-
dds_rhc_lock_samples_t
lock_samples
¶
-
dds_rhc_associate_t
associate
¶
-
struct ddsi_rhc_ops
-
struct
dds_sample_info
¶ - #include <dds.h>
Contains information about the associated data value
Public Members
-
dds_sample_state_t
sample_state
¶ Sample state
-
dds_view_state_t
view_state
¶ View state
-
dds_instance_state_t
instance_state
¶ Instance state
-
bool
valid_data
¶ Indicates whether there is a data associated with a sample
true, indicates the data is valid
false, indicates the data is invalid, no data to read
-
dds_time_t
source_timestamp
¶ timestamp of a data instance when it is written
-
dds_instance_handle_t
instance_handle
¶ handle to the data instance
-
dds_instance_handle_t
publication_handle
¶ handle to the publisher
-
uint32_t
disposed_generation_count
¶ count of instance state change from NOT_ALIVE_DISPOSED to ALIVE
-
uint32_t
no_writers_generation_count
¶ count of instance state change from NOT_ALIVE_NO_WRITERS to ALIVE
-
uint32_t
sample_rank
¶ indicates the number of samples of the same instance that follow the current one in the collection
-
uint32_t
generation_rank
¶ difference in generations between the sample and most recent sample of the same instance that appears in the returned collection
-
uint32_t
absolute_generation_rank
¶ difference in generations between the sample and most recent sample of the same instance when read/take was called
-
dds_sample_state_t
-
struct
dds_sample_lost_status
¶ - #include <dds_public_status.h>
DCPS_Status_SampleLost
-
struct
dds_sample_rejected_status
¶ - #include <dds_public_status.h>
DCPS_Status_SampleRejected
Public Members
-
uint32_t
total_count
¶
-
int32_t
total_count_change
¶
-
dds_sample_rejected_status_kind
last_reason
¶
-
dds_instance_handle_t
last_instance_handle
¶
-
uint32_t
-
struct
dds_sequence
¶
-
struct
dds_stat_keyvalue
¶ Public Members
-
const char *
name
¶ name, memory owned by library
-
enum dds_stat_kind
kind
¶ value type
-
uint32_t
u32
¶
-
uint64_t
u64
¶
-
uint64_t
lengthtime
¶
-
union dds_stat_keyvalue::[anonymous]
u
¶
-
const char *
-
struct
dds_statistics
¶ Public Members
-
dds_entity_t
entity
¶ handle of entity to which this set of values applies
-
uint64_t
opaque
¶ internal data
-
dds_time_t
time
¶ time stamp of latest call to
dds_refresh_statistics
-
size_t
count
¶ number of key-value pairs
-
struct dds_stat_keyvalue
kv
[]¶ data
-
dds_entity_t
-
struct
dds_subscription_matched_status
¶ - #include <dds_public_status.h>
DCPS_Status_SubscriptionMatched
-
struct
dds_topic_descriptor
¶
-
file
dds.h
- #include <stddef.h>#include <stdint.h>#include “dds/export.h”#include “dds/features.h”#include “dds/ddsrt/time.h”#include “dds/ddsrt/retcode.h”#include “dds/ddsrt/log.h”#include “dds/ddsc/dds_public_impl.h”#include “dds/ddsc/dds_public_alloc.h”#include “dds/ddsc/dds_public_qos.h”#include “dds/ddsc/dds_public_error.h”#include “dds/ddsc/dds_public_status.h”#include “dds/ddsc/dds_public_listener.h”
Eclipse Cyclone DDS C header.
Communication Status definitions
-
DDS_STATUS_ID_MAX
¶
-
DDS_INCONSISTENT_TOPIC_STATUS
¶ Another topic exists with the same name but with different characteristics.
-
DDS_OFFERED_DEADLINE_MISSED_STATUS
¶ The deadline that the writer has committed through its deadline QoS policy was not respected for a specific instance.
-
DDS_REQUESTED_DEADLINE_MISSED_STATUS
¶ The deadline that the reader was expecting through its deadline QoS policy was not respected for a specific instance.
-
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS
¶ A QoS policy setting was incompatible with what was requested.
-
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS
¶ A QoS policy setting was incompatible with what is offered.
-
DDS_SAMPLE_LOST_STATUS
¶ A sample has been lost (never received).
-
DDS_SAMPLE_REJECTED_STATUS
¶ A (received) sample has been rejected.
-
DDS_DATA_ON_READERS_STATUS
¶ New information is available.
-
DDS_DATA_AVAILABLE_STATUS
¶ New information is available.
-
DDS_LIVELINESS_LOST_STATUS
¶ The liveliness that the DDS_DataWriter has committed through its liveliness QoS policy was not respected; thus readers will consider the writer as no longer “alive”.
-
DDS_LIVELINESS_CHANGED_STATUS
¶ The liveliness of one or more writers, that were writing instances read through the readers has changed. Some writers have become “alive” or “not alive”.
-
DDS_PUBLICATION_MATCHED_STATUS
¶ The writer has found a reader that matches the topic and has a compatible QoS.
-
DDS_SUBSCRIPTION_MATCHED_STATUS
¶ The reader has found a writer that matches the topic and has a compatible QoS.
-
enum
dds_status_id
¶ Values:
-
enumerator
DDS_INCONSISTENT_TOPIC_STATUS_ID
¶
-
enumerator
DDS_OFFERED_DEADLINE_MISSED_STATUS_ID
¶
-
enumerator
DDS_REQUESTED_DEADLINE_MISSED_STATUS_ID
¶
-
enumerator
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS_ID
¶
-
enumerator
DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS_ID
¶
-
enumerator
DDS_SAMPLE_LOST_STATUS_ID
¶
-
enumerator
DDS_SAMPLE_REJECTED_STATUS_ID
¶
-
enumerator
DDS_DATA_ON_READERS_STATUS_ID
¶
-
enumerator
DDS_DATA_AVAILABLE_STATUS_ID
¶
-
enumerator
DDS_LIVELINESS_LOST_STATUS_ID
¶
-
enumerator
DDS_LIVELINESS_CHANGED_STATUS_ID
¶
-
enumerator
DDS_PUBLICATION_MATCHED_STATUS_ID
¶
-
enumerator
DDS_SUBSCRIPTION_MATCHED_STATUS_ID
¶
-
enumerator
-
typedef enum dds_status_id
dds_status_id_t
¶
Defines
-
DDS_MIN_PSEUDO_HANDLE
¶
-
DDS_BUILTIN_TOPIC_DCPSPARTICIPANT
¶
-
DDS_BUILTIN_TOPIC_DCPSTOPIC
¶
-
DDS_BUILTIN_TOPIC_DCPSPUBLICATION
¶
-
DDS_BUILTIN_TOPIC_DCPSSUBSCRIPTION
¶
-
DDS_CYCLONEDDS_HANDLE
¶ Special handle representing the entity corresponding to the CycloneDDS library itself
-
DDS_HAS_CREATE_TOPIC_GENERIC
¶
-
DDS_HAS_READCDR
¶
Typedefs
-
typedef int32_t
dds_entity_t
¶ Handle to an entity. A valid entity handle will always have a positive integer value. Should the value be negative, it is one of the DDS_RETCODE_* error codes.
-
typedef enum dds_sample_state
dds_sample_state_t
¶ Read state for a data value
-
typedef enum dds_view_state
dds_view_state_t
¶ View state of an instance relative to the samples
-
typedef enum dds_instance_state
dds_instance_state_t
¶ Defines the state of the instance
-
typedef struct dds_sample_info
dds_sample_info_t
¶ Contains information about the associated data value
-
typedef struct dds_builtintopic_guid
dds_builtintopic_guid_t
¶
-
typedef struct dds_builtintopic_guid
dds_guid_t
¶
-
typedef struct dds_builtintopic_participant
dds_builtintopic_participant_t
¶
-
typedef struct dds_builtintopic_endpoint
dds_builtintopic_endpoint_t
¶
-
typedef bool (*
dds_topic_filter_fn
)(const void *sample)¶ Topic filter function
-
typedef bool (*
dds_topic_filter_arg_fn
)(const void *sample, void *arg)¶
-
typedef bool (*
dds_querycondition_filter_fn
)(const void *sample)¶
-
typedef intptr_t
dds_attach_t
¶ Waitset attachment argument.
Every entity that is attached to the waitset can be accompanied by such an attachment argument. When the waitset wait is unblocked because of an entity that triggered, then the returning array will be populated with these attachment arguments that are related to the triggered entity.
Enums
-
enum
dds_sample_state
¶ Read state for a data value
Values:
-
enumerator
DDS_SST_READ
¶ DataReader has already accessed the sample by read
-
enumerator
DDS_SST_NOT_READ
¶ DataReader has not accessed the sample before
-
enumerator
-
enum
dds_view_state
¶ View state of an instance relative to the samples
Values:
-
enumerator
DDS_VST_NEW
¶ DataReader is accessing the sample for the first time when the instance is alive
-
enumerator
DDS_VST_OLD
¶ DataReader accessed the sample before
-
enumerator
-
enum
dds_instance_state
¶ Defines the state of the instance
Values:
-
enumerator
DDS_IST_ALIVE
¶ Samples received for the instance from the live data writers
-
enumerator
DDS_IST_NOT_ALIVE_DISPOSED
¶ Instance was explicitly disposed by the data writer
-
enumerator
DDS_IST_NOT_ALIVE_NO_WRITERS
¶ Instance has been declared as not alive by data reader as there are no live data writers writing that instance
-
enumerator
Functions
-
dds_return_t
dds_enable
(dds_entity_t entity)¶ Enable entity.
This operation enables the dds_entity_t. Created dds_entity_t objects can start in either an enabled or disabled state. This is controlled by the value of the entityfactory policy on the corresponding parent entity for the given 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 their 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 DDS_Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.
- Note
Delayed entity enabling is not supported yet (CHAM-96).
The default setting of DDS_EntityFactoryQosPolicy is such that, by default, entities are created in an enabled state so that it is not necessary to explicitly call dds_enable on newly-created entities.
The dds_enable operation produces the same results no matter how many times it is performed. Calling dds_enable on an already enabled DDS_Entity returns DDS_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 Status and the dds_get_status_changes operation (although the status of a disabled entity never changes). Other operations will return the error DDS_RETCODE_NOT_ENABLED.
Entities created with a parent that is disabled, are created disabled regardless of the setting of the entityfactory policy.
If the entityfactory policy has autoenable_created_entities set to TRUE, the dds_enable operation on the parent will automatically enable all child entities created with the parent.
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
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: The entity to enable.
- Return Value
DDS_RETCODE_OK
: The listeners of to the entity have been successfully been copied into the specified listener parameter.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The parent of the given Entity is not enabled.
-
dds_return_t
dds_delete
(dds_entity_t entity)¶ Delete given entity.
This operation will delete the given entity. It will also automatically delete all its children, childrens’ children, etc entities.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity to delete.
- Return Value
DDS_RETCODE_OK
: The entity and its children (recursive are deleted).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_get_publisher
(dds_entity_t writer)¶ Get entity publisher.
This operation returns the publisher to which the given entity belongs. For instance, it will return the Publisher that was used when creating a DataWriter (when that DataWriter was provided here).
- Return
A valid entity or an error code.
- Parameters
[in] writer
: Entity from which to get its publisher.
- Return Value
>0
: A valid publisher handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_get_subscriber
(dds_entity_t entity)¶ Get entity subscriber.
This operation returns the subscriber to which the given entity belongs. For instance, it will return the Subscriber that was used when creating a DataReader (when that DataReader was provided here).
- Return
A valid subscriber handle or an error code.
- Parameters
[in] entity
: Entity from which to get its subscriber.
- Return Value
>0
: A valid subscriber handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_get_datareader
(dds_entity_t condition)¶ Get entity datareader.
This operation returns the datareader to which the given entity belongs. For instance, it will return the DataReader that was used when creating a ReadCondition (when that ReadCondition was provided here).
- Return
A valid reader handle or an error code.
- Parameters
[in] condition
: Entity from which to get its datareader.
- Return Value
>0
: A valid reader handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_mask
(dds_entity_t condition, uint32_t *mask)¶ Get the mask of a condition.
This operation returns the mask that was used to create the given condition.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] condition
: Read or Query condition that has a mask.
- Return Value
DDS_RETCODE_OK
: Success (given mask is set).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The mask arg is NULL.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_instance_handle
(dds_entity_t entity, dds_instance_handle_t *ihdl)¶ Returns the instance handle that represents the entity.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity of which to get the instance handle.[out] ihdl
: Pointer to dds_instance_handle_t.
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_ERROR
: An internal error has occurred.
-
dds_return_t
dds_get_guid
(dds_entity_t entity, dds_guid_t *guid)¶ Returns the GUID that represents the entity in the network, and therefore only supports participants, readers and writers.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity of which to get the instance handle.[out] guid
: Where to store the GUID.
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ERROR
: An internal error has occurred.
-
dds_return_t
dds_read_status
(dds_entity_t entity, uint32_t *status, uint32_t mask)¶ Read the status set for the entity.
This operation reads the status(es) set for the entity based on the enabled status and mask set. It does not clear the read status(es).
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity on which the status has to be read.[out] status
: Returns the status set on the entity, based on the enabled status.[in] mask
: Filter the status condition to be read (can be NULL).
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_status
(dds_entity_t entity, uint32_t *status, uint32_t mask)¶ Read the status set for the entity.
This operation reads the status(es) set for the entity based on the enabled status and mask set. It clears the status set after reading.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity on which the status has to be read.[out] status
: Returns the status set on the entity, based on the enabled status.[in] mask
: Filter the status condition to be read (can be NULL).
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_status_changes
(dds_entity_t entity, uint32_t *status)¶ Get changed status(es)
This operation returns the status changes since they were last read.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity on which the statuses are read.[out] status
: Returns the current set of triggered statuses.
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_status_mask
(dds_entity_t entity, uint32_t *mask)¶ Get enabled status on entity.
This operation returns the status enabled on the entity
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity to get the status.[out] mask
: Mask of enabled statuses set on the entity.
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_enabled_status
(dds_entity_t entity, uint32_t *mask)¶
-
dds_return_t
dds_set_status_mask
(dds_entity_t entity, uint32_t mask)¶ Set status enabled on entity.
This operation enables the status(es) based on the mask set
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity to enable the status.[in] mask
: Status value that indicates the status to be enabled.
- Return Value
DDS_RETCODE_OK
: Success.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_set_enabled_status
(dds_entity_t entity, uint32_t mask)¶
-
dds_return_t
dds_get_qos
(dds_entity_t entity, dds_qos_t *qos)¶ Get entity QoS policies.
This operation allows access to the existing set of QoS policies for the entity.
- Return
A dds_return_t indicating success or failure. The QoS object will have at least all QoS relevant for the entity present and the corresponding dds_qget_… will return true.
- Parameters
[in] entity
: Entity on which to get qos.[out] qos
: Pointer to the qos structure that returns the set policies.
- Return Value
DDS_RETCODE_OK
: The existing set of QoS policy values applied to the entity has successfully been copied into the specified qos parameter.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The qos parameter is NULL.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_set_qos
(dds_entity_t entity, const dds_qos_t *qos)¶ Set entity QoS policies.
This operation replaces the existing set of Qos Policy settings for an entity. The parameter qos must contain the struct with the QosPolicy settings which is checked for self-consistency.
The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS_RETCODE_OK).
Not all policies are changeable when the entity is enabled.
- Note
Currently only Latency Budget and Ownership Strength are changeable QoS that can be set.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity from which to get qos.[in] qos
: Pointer to the qos structure that provides the policies.
- Return Value
DDS_RETCODE_OK
: The new QoS policies are set.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The qos parameter is NULL.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_IMMUTABLE_POLICY
: The entity is enabled and one or more of the policies of the QoS are immutable.DDS_RETCODE_INCONSISTENT_POLICY
: A few policies within the QoS are not consistent with each other.
-
dds_return_t
dds_get_listener
(dds_entity_t entity, dds_listener_t *listener)¶ Get entity listeners.
This operation allows access to the existing listeners attached to the entity.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity on which to get the listeners.[out] listener
: Pointer to the listener structure that returns the set of listener callbacks.
- Return Value
DDS_RETCODE_OK
: The listeners of to the entity have been successfully been copied into the specified listener parameter.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The listener parameter is NULL.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_set_listener
(dds_entity_t entity, const dds_listener_t *listener)¶ Set entity listeners.
This operation attaches a dds_listener_t to the dds_entity_t. Only one Listener can be attached to each Entity. If a Listener was already attached, this operation will replace it with the new one. In other words, all related callbacks are replaced (possibly with NULL).
When listener parameter is NULL, all listener callbacks that were possibly set on the Entity will be removed.
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 Listener callback 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.
- Note
Not all listener callbacks are related to all entities.
In case a related callback within the Listener is not set, the Listener of the Parent entity is called recursively, until a Listener with the appropriate callback set has been found and called. This allows the application to set (for instance) a default behaviour in the Listener of the containing Publisher and a DataWriter specific behaviour when needed. In case the callback is not set in the Publishers’ Listener either, the communication status will be propagated to the Listener of the DomainParticipant of the containing DomainParticipant. In case the callback is not set in the DomainParticipants’ Listener either, the Communication Status flag will be set, resulting in a possible WaitSet trigger.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity on which to get the listeners.[in] listener
: Pointer to the listener structure that contains the set of listener callbacks (maybe NULL).
- Return Value
DDS_RETCODE_OK
: The listeners of to the entity have been successfully been copied into the specified listener parameter.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_create_participant
(const dds_domainid_t domain, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new instance of a DDS participant in a domain.
If domain is set (not DDS_DOMAIN_DEFAULT) then it must match if the domain has also been configured or an error status will be returned. Currently only a single domain can be configured by providing configuration file. If no configuration file exists, the default domain is configured as 0.
- Return
A valid participant handle or an error code.
- Parameters
[in] domain
: The domain in which to create the participant (can be DDS_DOMAIN_DEFAULT). DDS_DOMAIN_DEFAULT is for using the domain in the configuration.[in] qos
: The QoS to set on the new participant (can be NULL).[in] listener
: Any listener functions associated with the new participant (can be NULL).
- Return Value
>0
: A valid participant handle.DDS_RETCODE_NOT_ALLOWED_BY_SECURITY
: An invalid DDS Security configuration was specified (whether that be missing or incorrect entries, expired certificates, or anything else related to the security settings and implementation).DDS_RETCODE_PRECONDITION_NOT_MET
: Some security properties specified in the QoS, but the Cyclone build does not include support for DDS Security.DDS_RETCODE_OUT_OF_RESOURCES
: Some resource limit (maximum participants, memory, handles, &c.) prevented creation of the participant.DDS_RETCODE_ERROR
: The “CYCLONEDDS_URI” environment variable lists non-existent or invalid configuration files, or contains invalid embedded configuration items; or an unspecified internal error has occurred.
-
dds_entity_t
dds_create_domain
(const dds_domainid_t domain, const char *config)¶ Creates a domain with a given configuration.
To explicitly create a domain based on a configuration passed as a string.
It will not be created if a domain with the given domain id already exists. This could have been created implicitly by a dds_create_participant().
Please be aware that the given domain_id always takes precedence over the configuration.
| domain_id | domain id in config | result +——–+——————+——- | n | any (or absent) | n, config is used | n | m == n | n, config is used | n | m != n | n, config is ignored: default
Config models: 1: <CycloneDDS> <Domain id=”X”>…</Domain> <Domain …/> </CycloneDDS> where … is all that can today be set in children of CycloneDDS with the exception of the id 2: <CycloneDDS> <Domain><Id>X</Id></Domain> … </CycloneDDS> legacy form, domain id must be the first element in the file with a value (if nothing has been set previously, it a warning is good enough)
Using NULL or “” as config will create a domain with default settings.
- Return
A valid entity handle or an error code.
- Parameters
[in] domain
: The domain to be created. DEFAULT_DOMAIN is not allowed.[in] config
: A configuration string containing file names and/or XML fragments representing the configuration.
- Return Value
DDS_RETCODE_BAD_PARAMETER
: Illegal value for domain id or the configfile parameter is NULL.DDS_RETCODE_PRECONDITION_NOT_MET
: The domain already existed and cannot be created again.DDS_RETCODE_ERROR
: An internal error has occurred.
-
dds_entity_t
dds_get_parent
(dds_entity_t entity)¶ Get entity parent.
This operation returns the parent to which the given entity belongs. For instance, it will return the Participant that was used when creating a Publisher (when that Publisher was provided here).
When a reader or a writer are created with a participant, then a subscriber or publisher are created implicitly. This function will return the implicit parent and not the used participant.
- Return
A valid entity handle or an error code.
- Parameters
[in] entity
: Entity from which to get its parent.
- Return Value
>0
: A valid entity handle.DDS_ENTITY_NIL
: Called with a participant.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_get_participant
(dds_entity_t entity)¶ Get entity participant.
This operation returns the participant to which the given entity belongs. For instance, it will return the Participant that was used when creating a Publisher that was used to create a DataWriter (when that DataWriter was provided here).
TODO: Link to generic dds entity relations documentation.
- Return
A valid entity or an error code.
- Parameters
[in] entity
: Entity from which to get its participant.
- Return Value
>0
: A valid participant handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_children
(dds_entity_t entity, dds_entity_t *children, size_t size)¶ Get entity children.
This operation returns the children that the entity contains. For instance, it will return all the Topics, Publishers and Subscribers of the Participant that was used to create those entities (when that Participant is provided here).
This functions takes a pre-allocated list to put the children in and will return the number of found children. It is possible that the given size of the list is not the same as the number of found children. If less children are found, then the last few entries in the list are untouched. When more children are found, then only ‘size’ number of entries are inserted into the list, but still complete count of the found children is returned. Which children are returned in the latter case is undefined.
When supplying NULL as list and 0 as size, you can use this to acquire the number of children without having to pre-allocate a list.
When a reader or a writer are created with a participant, then a subscriber or publisher are created implicitly. When used on the participant, this function will return the implicit subscriber and/or publisher and not the related reader/writer.
- Return
Number of children or an error code.
- Parameters
[in] entity
: Entity from which to get its children.[out] children
: Pre-allocated array to contain the found children.[in] size
: Size of the pre-allocated children’s list.
- Return Value
>=0
: Number of found children (can be larger than ‘size’).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The children parameter is NULL, while a size is provided.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_domainid
(dds_entity_t entity, dds_domainid_t *id)¶ Get the domain id to which this entity is attached.
When creating a participant entity, it is attached to a certain domain. All the children (like Publishers) and childrens’ children (like DataReaders), etc are also attached to that domain.
This function will return the original domain ID when called on any of the entities within that hierarchy. For entities not associated with a domain, the id is set to DDS_DOMAIN_DEFAULT.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity from which to get its children.[out] id
: Pointer to put the domain ID in.
- Return Value
DDS_RETCODE_OK
: Domain ID was returned.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The id parameter is NULL.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_lookup_participant
(dds_domainid_t domain_id, dds_entity_t *participants, size_t size)¶ Get participants of a domain.
This operation acquires the participants created on a domain and returns the number of found participants.
This function takes a domain id with the size of pre-allocated participant’s list in and will return the number of found participants. It is possible that the given size of the list is not the same as the number of found participants. If less participants are found, then the last few entries in an array stay untouched. If more participants are found and the array is too small, then the participants returned are undefined.
- Return
Number of participants found or and error code.
- Parameters
[in] domain_id
: The domain id.[out] participants
: The participant for domain.[in] size
: Size of the pre-allocated participant’s list.
- Return Value
>0
: Number of participants found.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The participant parameter is NULL, while a size is provided.
-
dds_entity_t
dds_create_topic
(dds_entity_t participant, const dds_topic_descriptor_t *descriptor, const char *name, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new topic with default type handling.
The type name for the topic is taken from the generated descriptor. Topic matching is done on a combination of topic name and type name. Each successful call to dds_create_topic creates a new topic entity sharing the same QoS settings with all other topics of the same name.
- Return
A valid, unique topic handle or an error code.
- Parameters
[in] participant
: Participant on which to create the topic.[in] descriptor
: An IDL generated topic descriptor.[in] name
: Name of the topic.[in] qos
: QoS to set on the new topic (can be NULL).[in] listener
: Any listener functions associated with the new topic (can be NULL).
- Return Value
>=0
: A valid unique topic handle.DDS_RETCODE_BAD_PARAMETER
: Either participant, descriptor, name or qos is invalid.DDS_RETCODE_BAD_PARAMETER
: Either participant, descriptor, name or qos is invalid.DDS_RETCODE_INCONSISTENT_POLICY
: QoS mismatch between qos and an existing topic’s QoS.DDS_RETCODE_PRECONDITION_NOT_MET
: Mismatch between type name in descriptor and pre-existing topic’s type name.
-
dds_entity_t
dds_create_topic_generic
(dds_entity_t participant, struct ddsi_sertopic **sertopic, const dds_qos_t *qos, const dds_listener_t *listener, const struct ddsi_plist *sedp_plist)¶ Creates a new topic with provided type handling.
The type name for the topic is taken from the provided “sertopic” object. Topic matching is done on a combination of topic name and type name. Each successful call to dds_create_topic creates a new topic entity sharing the same QoS settings with all other topics of the same name.
In case this function returns a valid handle, the ownership of the provided sertopic is handed over to Cyclone. On return, the caller gets in the sertopic parameter a pointer to the sertopic that is actually used by the topic. This can be the provided sertopic (if this sertopic was not yet known in the domain), or a sertopic thas was already known in the domain.
- Return
A valid, unique topic handle or an error code. Iff a valid handle, the domain takes ownership of provided serdata.
- Parameters
[in] participant
: Participant on which to create the topic.[inout] sertopic
: Internal description of the topic type (includes name). On return, the sertopic parameter is set to the actual sertopic that is used by the topic.[in] qos
: QoS to set on the new topic (can be NULL).[in] listener
: Any listener functions associated with the new topic (can be NULL).[in] sedp_plist
: Topic description to be published as part of discovery (if NULL, not published).
- Return Value
>=0
: A valid unique topic handle.DDS_RETCODE_BAD_PARAMETER
: Either participant, descriptor, name or qos is invalid.DDS_RETCODE_BAD_PARAMETER
: Either participant, descriptor, name or qos is invalid.DDS_RETCODE_INCONSISTENT_POLICY
: QoS mismatch between qos and an existing topic’s QoS.DDS_RETCODE_PRECONDITION_NOT_MET
: Mismatch between type name in sertopic and pre-existing topic’s type name.
-
dds_entity_t
dds_create_topic_arbitrary
(dds_entity_t participant, struct ddsi_sertopic *sertopic, const dds_qos_t *qos, const dds_listener_t *listener, const struct ddsi_plist *sedp_plist)¶
-
dds_entity_t
dds_find_topic
(dds_entity_t participant, const char *name)¶ Finds a named topic.
The returned topic should be released with dds_delete.
- Return
A valid topic handle or an error code.
- Parameters
[in] participant
: The participant on which to find the topic.[in] name
: The name of the topic to find.
- Return Value
>0
: A valid topic handle.DDS_RETCODE_BAD_PARAMETER
: Participant was invalid.DDS_RETCODE_PRECONDITION_NOT_MET
: No topic of this name existed yet in the participant
-
dds_return_t
dds_get_name
(dds_entity_t topic, char *name, size_t size)¶ Returns the name of a given topic.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] topic
: The topic.[out] name
: Buffer to write the topic name to.[in] size
: Number of bytes available in the buffer.
- Return Value
DDS_RETCODE_OK
: Success.
-
dds_return_t
dds_get_type_name
(dds_entity_t topic, char *name, size_t size)¶ Returns the type name of a given topic.
- Return
A dds_return_t indicating success or failure.
- Return
DDS_RETCODE_OK Success.
- Parameters
[in] topic
: The topic.[out] name
: Buffer to write the topic type name to.[in] size
: Number of bytes available in the buffer.
-
void
dds_set_topic_filter
(dds_entity_t topic, dds_topic_filter_fn filter)¶ Sets a filter on a topic. To be replaced by proper filtering on readers, no guarantee that this will be maintained for backwards compatibility.
Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.
- Parameters
[in] topic
: The topic on which the content filter is set.[in] filter
: The filter function used to filter topic samples.
-
void
dds_topic_set_filter
(dds_entity_t topic, dds_topic_filter_fn filter)¶
-
dds_return_t
dds_set_topic_filter_and_arg
(dds_entity_t topic, dds_topic_filter_arg_fn filter, void *arg)¶ Sets a filter and filter argument on a topic. To be replaced by proper filtering on readers, no guarantee that this will be maintained for backwards compatibility.
Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] topic
: The topic on which the content filter is set.[in] filter
: The filter function used to filter topic samples.[in] arg
: Argument for the filter function.
- Return Value
DDS_RETCODE_OK
: Filter set successfullyDDS_RETCODE_BAD_PARAMETER
: The topic handle is invalid
-
dds_topic_filter_fn
dds_get_topic_filter
(dds_entity_t topic)¶ Gets the filter for a topic. To be replaced by proper filtering on readers, no guarantee that this will be maintained for backwards compatibility.
- Return
The topic filter, or 0 when not set or set using dds_set_topic_filter_and_arg.
- Parameters
[in] topic
: The topic from which to get the filter.
-
dds_topic_filter_fn
dds_topic_get_filter
(dds_entity_t topic)¶
-
dds_return_t
dds_get_topic_filter_and_arg
(dds_entity_t topic, dds_topic_filter_arg_fn *fn, void **arg)¶ Gets the filter for a topic. To be replaced by proper filtering on readers, no guarantee that this will be maintained for backwards compatibility.
- Parameters
[in] topic
: The topic from which to get the filter.[out] fn
: The topic filter function (fn may be NULL).[out] arg
: Filter function argument (arg may be NULL).
- Return Value
DDS_RETCODE_OK
: Filter set successfullyDDS_RETCODE_PRECONDITION_NOT_MET
: Filter was set with dds_set_topic_filterDDS_RETCODE_BAD_PARAMETER
: The topic handle is invalid
-
dds_entity_t
dds_create_subscriber
(dds_entity_t participant, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new instance of a DDS subscriber.
- Return
A valid subscriber handle or an error code.
- Parameters
[in] participant
: The participant on which the subscriber is being created.[in] qos
: The QoS to set on the new subscriber (can be NULL).[in] listener
: Any listener functions associated with the new subscriber (can be NULL).
- Return Value
>0
: A valid subscriber handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the parameters is invalid.
-
dds_entity_t
dds_create_publisher
(dds_entity_t participant, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new instance of a DDS publisher.
- Return
A valid publisher handle or an error code.
- Parameters
[in] participant
: The participant to create a publisher for.[in] qos
: The QoS to set on the new publisher (can be NULL).[in] listener
: Any listener functions associated with the new publisher (can be NULL).
- Return Value
>0
: A valid publisher handle.DDS_RETCODE_ERROR
: An internal error has occurred.
-
dds_return_t
dds_suspend
(dds_entity_t publisher)¶ Suspends the publications of the Publisher.
This operation is a hint to the Service so it can optimize its performance by e.g., collecting modifications to DDS writers and then batching them. The Service is not required to use the hint.
Every invocation of this operation must be matched by a corresponding call to
- See
dds_resume indicating that the set of modifications has completed.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] publisher
: The publisher for which all publications will be suspended.
- Return Value
DDS_RETCODE_OK
: Publications suspended successfully.DDS_RETCODE_BAD_PARAMETER
: The pub parameter is not a valid publisher.DDS_RETCODE_UNSUPPORTED
: Operation is not supported.
-
dds_return_t
dds_resume
(dds_entity_t publisher)¶ Resumes the publications of the Publisher.
This operation is a hint to the Service to indicate that the application has completed changes initiated by a previous dds_suspend(). The Service is not required to use the hint.
The call to resume_publications must match a previous call to
- See
suspend_publications.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] publisher
: The publisher for which all publications will be resumed.
- Return Value
DDS_RETCODE_OK
: Publications resumed successfully.DDS_RETCODE_BAD_PARAMETER
: The pub parameter is not a valid publisher.DDS_RETCODE_PRECONDITION_NOT_MET
: No previous matching dds_suspend().DDS_RETCODE_UNSUPPORTED
: Operation is not supported.
-
dds_return_t
dds_wait_for_acks
(dds_entity_t publisher_or_writer, dds_duration_t timeout)¶ Waits at most for the duration timeout for acks for data in the publisher or writer.
This operation blocks the calling thread until either all data written by the publisher or writer is acknowledged by all matched reliable reader entities, or else the duration specified by the timeout parameter elapses, whichever happens first.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] publisher_or_writer
: Publisher or writer whose acknowledgments must be waited for[in] timeout
: How long to wait for acknowledgments before time out
- Return Value
DDS_RETCODE_OK
: All acknowledgments successfully received with the timeout.DDS_RETCODE_BAD_PARAMETER
: The publisher_or_writer is not a valid publisher or writer.DDS_RETCODE_TIMEOUT
: Timeout expired before all acknowledgments from reliable reader entities were received.DDS_RETCODE_UNSUPPORTED
: Operation is not supported.
-
dds_entity_t
dds_create_reader
(dds_entity_t participant_or_subscriber, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new instance of a DDS reader.
When a participant is used to create a reader, an implicit subscriber is created. This implicit subscriber will be deleted automatically when the created reader is deleted.
- Return
A valid reader handle or an error code.
- Parameters
[in] participant_or_subscriber
: The participant or subscriber on which the reader is being created.[in] topic
: The topic to read.[in] qos
: The QoS to set on the new reader (can be NULL).[in] listener
: Any listener functions associated with the new reader (can be NULL).
- Return Value
>0
: A valid reader handle.DDS_RETCODE_ERROR
: An internal error occurred.
-
dds_entity_t
dds_create_reader_rhc
(dds_entity_t participant_or_subscriber, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener, struct dds_rhc *rhc)¶ Creates a new instance of a DDS reader with a custom history cache.
When a participant is used to create a reader, an implicit subscriber is created. This implicit subscriber will be deleted automatically when the created reader is deleted.
- Return
A valid reader handle or an error code.
- Parameters
[in] participant_or_subscriber
: The participant or subscriber on which the reader is being created.[in] topic
: The topic to read.[in] qos
: The QoS to set on the new reader (can be NULL).[in] listener
: Any listener functions associated with the new reader (can be NULL).[in] rhc
: Reader history cache to use, reader becomes the owner
- Return Value
>0
: A valid reader handle.DDS_RETCODE_ERROR
: An internal error occurred.
-
dds_return_t
dds_reader_wait_for_historical_data
(dds_entity_t reader, dds_duration_t max_wait)¶ Wait until reader receives all historic data.
The operation blocks the calling thread until either all “historical” data is received, or else the duration specified by the max_wait parameter elapses, whichever happens first. A return value of 0 indicates that all the “historical” data was received; a return value of TIMEOUT indicates that max_wait elapsed before all the data was received.
- Return
a status, 0 on success, TIMEOUT on timeout or a negative value to indicate error.
- Parameters
[in] reader
: The reader on which to wait for historical data.[in] max_wait
: How long to wait for historical data before time out.
-
dds_entity_t
dds_create_writer
(dds_entity_t participant_or_publisher, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener)¶ Creates a new instance of a DDS writer.
When a participant is used to create a writer, an implicit publisher is created. This implicit publisher will be deleted automatically when the created writer is deleted.
- Return
A valid writer handle or an error code.
- Return
>0 A valid writer handle.
- Return
DDS_RETCODE_ERROR An internal error occurred.
- Parameters
[in] participant_or_publisher
: The participant or publisher on which the writer is being created.[in] topic
: The topic to write.[in] qos
: The QoS to set on the new writer (can be NULL).[in] listener
: Any listener functions associated with the new writer (can be NULL).
-
dds_return_t
dds_register_instance
(dds_entity_t writer, dds_instance_handle_t *handle, const void *data)¶ Registers an instance.
This operation registers an instance with a key value to the data writer and returns an instance handle that could be used for successive write & dispose operations. When the handle is not allocated, the function will return an error and the handle will be un-touched.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to which instance has be associated.[out] handle
: The instance handle.[in] data
: The instance with the key value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_return_t
dds_unregister_instance
(dds_entity_t writer, const void *data)¶ Unregisters an instance.
This operation reverses the action of register instance, removes all information regarding the instance and unregisters an instance with a key value from the data writer.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to which instance is associated.[in] data
: The instance with the key value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_return_t
dds_unregister_instance_ih
(dds_entity_t writer, dds_instance_handle_t handle)¶ Unregisters an instance.
This operation unregisters the instance which is identified by the key fields of the given typed instance handle.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to which instance is associated.[in] handle
: The instance handle.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_return_t
dds_unregister_instance_ts
(dds_entity_t writer, const void *data, dds_time_t timestamp)¶ Unregisters an instance.
This operation reverses the action of register instance, removes all information regarding the instance and unregisters an instance with a key value from the data writer. It also provides a value for the timestamp explicitly.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to which instance is associated.[in] data
: The instance with the key value.[in] timestamp
: The timestamp used at registration.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_return_t
dds_unregister_instance_ih_ts
(dds_entity_t writer, dds_instance_handle_t handle, dds_time_t timestamp)¶ Unregisters an instance.
This operation unregisters an instance with a key value from the handle. Instance can be identified from instance handle. If an unregistered key ID is passed as an instance data, an error is logged and not flagged as return value.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to which instance is associated.[in] handle
: The instance handle.[in] timestamp
: The timestamp used at registration.
- Return Value
DDS_RETCODE_OK
: The operation was successfulDDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not validDDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object
-
dds_return_t
dds_writedispose
(dds_entity_t writer, const void *data)¶ This operation modifies and disposes a data instance.
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 reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the dds_writedispose operation on the writer may block if the modification would cause data to be lost because one of the limits, specified in the resource_limits QoS policy, to be exceeded. In case the synchronous attribute value of the reliability Qos policy is set to true for communicating writers and readers then the writer will wait until all synchronous readers have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the reliability QoS policy configures the maximum time the dds_writedispose operation may block. If max_blocking_time elapses before the writer is able to store the modification without exceeding the limits and all expected acknowledgements are received, the dds_writedispose operation will fail and returns DDS_RETCODE_TIMEOUT.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] data
: The data to be written and disposed.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletion.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_TIMEOUT
: Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.
-
dds_return_t
dds_writedispose_ts
(dds_entity_t writer, const void *data, dds_time_t timestamp)¶ This operation modifies and disposes a data instance with a specific timestamp.
This operation performs the same functions as dds_writedispose except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] data
: The data to be written and disposed.[in] timestamp
: The timestamp used as source timestamp.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletion.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_TIMEOUT
: Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.
-
dds_return_t
dds_dispose
(dds_entity_t writer, const void *data)¶ This operation disposes an instance, identified by the data sample.
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 reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the dds_writedispose operation on the writer may block if the modification would cause data to be lost because one of the limits, specified in the resource_limits QoS policy, to be exceeded. In case the synchronous attribute value of the reliability Qos policy is set to true for communicating writers and readers then the writer will wait until all synchronous readers have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the reliability QoS policy configures the maximum time the dds_writedispose operation may block. If max_blocking_time elapses before the writer is able to store the modification without exceeding the limits and all expected acknowledgements are received, the dds_writedispose operation will fail and returns DDS_RETCODE_TIMEOUT.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] data
: The data sample that identifies the instance to be disposed.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletion.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_TIMEOUT
: Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.
-
dds_return_t
dds_dispose_ts
(dds_entity_t writer, const void *data, dds_time_t timestamp)¶ This operation disposes an instance with a specific timestamp, identified by the data sample.
This operation performs the same functions as dds_dispose except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] data
: The data sample that identifies the instance to be disposed.[in] timestamp
: The timestamp used as source timestamp.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletionDDS_RETCODE_ERROR
: An internal error has occurredDDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalidDDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate objectDDS_RETCODE_ALREADY_DELETED
: The entity has already been deletedDDS_RETCODE_TIMEOUT
: Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgment by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.
-
dds_return_t
dds_dispose_ih
(dds_entity_t writer, dds_instance_handle_t handle)¶ This operation disposes an instance, identified by the instance handle.
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 reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.
The given instance handle must correspond to the value that was returned by either the dds_register_instance operation, dds_register_instance_ts or dds_lookup_instance. If there is no correspondence, then the result of the operation is unspecified.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] handle
: The handle to identify an instance.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletion.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalidDDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate objectDDS_RETCODE_ALREADY_DELETED
: The entity has already been deletedDDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this writer
-
dds_return_t
dds_dispose_ih_ts
(dds_entity_t writer, dds_instance_handle_t handle, dds_time_t timestamp)¶ This operation disposes an instance with a specific timestamp, identified by the instance handle.
This operation performs the same functions as dds_dispose_ih except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer to dispose the data instance from.[in] handle
: The handle to identify an instance.[in] timestamp
: The timestamp used as source timestamp.
- Return Value
DDS_RETCODE_OK
: The sample is written and the instance is marked for deletion.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: At least one of the arguments is invalid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this writer.
-
dds_return_t
dds_write
(dds_entity_t writer, const void *data)¶ Write the value of a data instance.
With this API, the value of the source timestamp is automatically made available to the data reader by the service.
- Return
dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer entity.[in] data
: Value to be written.
-
void
dds_write_flush
(dds_entity_t writer)¶
-
dds_return_t
dds_writecdr
(dds_entity_t writer, struct ddsi_serdata *serdata)¶ Write a serialized value of a data instance.
This call causes the writer to write the serialized value that is provided in the serdata argument.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer entity.[in] serdata
: Serialized value to be written.
- Return Value
DDS_RETCODE_OK
: The writer successfully wrote the serialized value.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_TIMEOUT
: The writer failed to write the serialized value reliably within the specified max_blocking_time.
-
dds_return_t
dds_write_ts
(dds_entity_t writer, const void *data, dds_time_t timestamp)¶ Write the value of a data instance along with the source timestamp passed.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] writer
: The writer entity.[in] data
: Value to be written.[in] timestamp
: Source timestamp.
-
dds_entity_t
dds_create_readcondition
(dds_entity_t reader, uint32_t mask)¶ Creates a readcondition associated to the given reader.
The readcondition allows specifying which samples are of interest in a data reader’s history, by means of a mask. The mask is or’d with the flags that are dds_sample_state_t, dds_view_state_t and dds_instance_state_t.
Based on the mask value set, the readcondition gets triggered when data is available on the reader.
Waitsets allow waiting for an event on some of any set of entities. This means that the readcondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask.
- Note
The parent reader and every of its associated conditions (whether they are readconditions or queryconditions) share the same resources. This means that one of these entities reads or takes data, the states of the data will change for other entities automatically. For instance, if one reads a sample, then the sample state will become ‘read’ for all associated reader/conditions. Or if one takes a sample, then it’s not available to any other associated reader/condition.
- Return
A valid condition handle or an error code.
- Parameters
[in] reader
: Reader to associate the condition to.[in] mask
: Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).
- Return Value
>0
: A valid condition handleDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_create_querycondition
(dds_entity_t reader, uint32_t mask, dds_querycondition_filter_fn filter)¶ Creates a queryondition associated to the given reader.
The queryondition allows specifying which samples are of interest in a data reader’s history, by means of a mask and a filter. The mask is or’d with the flags that are dds_sample_state_t, dds_view_state_t and dds_instance_state_t.
Based on the mask value set and data that matches the filter, the querycondition gets triggered when data is available on the reader.
Waitsets allow waiting for an event on some of any set of entities. This means that the querycondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask and filter.
- Note
The parent reader and every of its associated conditions (whether they are readconditions or queryconditions) share the same resources. This means that one of these entities reads or takes data, the states of the data will change for other entities automatically. For instance, if one reads a sample, then the sample state will become ‘read’ for all associated reader/conditions. Or if one takes a sample, then it’s not available to any other associated reader/condition.
- Return
A valid condition handle or an error code
- Parameters
[in] reader
: Reader to associate the condition to.[in] mask
: Interest (dds_sample_state_t|dds_view_state_t|dds_instance_state_t).[in] filter
: Callback that the application can use to filter specific samples.
- Return Value
>=0
: A valid condition handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_create_guardcondition
(dds_entity_t participant)¶ Creates a guardcondition.
Waitsets allow waiting for an event on some of any set of entities. This means that the guardcondition can be used to wake up a waitset when data is in the reader history with states that matches the given mask.
- Return
A valid condition handle or an error code.
- Return Value
>0
: A valid condition handleDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_set_guardcondition
(dds_entity_t guardcond, bool triggered)¶ Sets the trigger status of a guardcondition.
- Return Value
DDS_RETCODE_OK
: Operation successfulDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_guardcondition
(dds_entity_t guardcond, bool *triggered)¶ Reads the trigger status of a guardcondition.
- Return Value
DDS_RETCODE_OK
: Operation successfulDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_guardcondition
(dds_entity_t guardcond, bool *triggered)¶ Reads and resets the trigger status of a guardcondition.
- Return Value
DDS_RETCODE_OK
: Operation successfulDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_create_waitset
(dds_entity_t participant)¶ Create a waitset and allocate the resources required.
A WaitSet object allows an application to wait until one or more of the conditions of the attached entities evaluates to TRUE or until the timeout expires.
- Return
A valid waitset handle or an error code.
- Parameters
[in] participant
: Domain participant which the WaitSet contains.
- Return Value
>=0
: A valid waitset handle.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_waitset_get_entities
(dds_entity_t waitset, dds_entity_t *entities, size_t size)¶ Acquire previously attached entities.
This functions takes a pre-allocated list to put the entities in and will return the number of found entities. It is possible that the given size of the list is not the same as the number of found entities. If less entities are found, then the last few entries in the list are untouched. When more entities are found, then only ‘size’ number of entries are inserted into the list, but still the complete count of the found entities is returned. Which entities are returned in the latter case is undefined.
- Return
A dds_return_t with the number of children or an error code.
- Parameters
[in] waitset
: Waitset from which to get its attached entities.[out] entities
: Pre-allocated array to contain the found entities.[in] size
: Size of the pre-allocated entities’ list.
- Return Value
>=0
: Number of children found (can be larger than ‘size’).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The entities parameter is NULL, while a size is provided.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.
-
dds_return_t
dds_waitset_attach
(dds_entity_t waitset, dds_entity_t entity, dds_attach_t x)¶ This operation attaches an Entity to the WaitSet.
This operation attaches an Entity to the WaitSet. The dds_waitset_wait() will block when none of the attached entities are triggered. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:
Reader/Writer/Publisher/Subscriber/Topic/Participant
These are triggered when their status changed.
WaitSet
Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).
ReadCondition/QueryCondition
Triggered when data is available on the related Reader that matches the Condition.
Multiple entities can be attached to a single waitset. A particular entity can be attached to multiple waitsets. However, a particular entity can not be attached to a particular waitset multiple times.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] waitset
: The waitset to attach the given entity to.[in] entity
: The entity to attach.[in] x
: Blob that will be supplied when the waitset wait is triggerd by the given entity.
- Return Value
DDS_RETCODE_OK
: Entity attached.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The given waitset or entity are not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The entity was already attached.
-
dds_return_t
dds_waitset_detach
(dds_entity_t waitset, dds_entity_t entity)¶ This operation detaches an Entity to the WaitSet.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] waitset
: The waitset to detach the given entity from.[in] entity
: The entity to detach.
- Return Value
DDS_RETCODE_OK
: Entity detached.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The given waitset or entity are not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The entity is not attached.
-
dds_return_t
dds_waitset_set_trigger
(dds_entity_t waitset, bool trigger)¶ Sets the trigger_value associated with a waitset.
When the waitset is attached to itself and the trigger value is set to ‘true’, then the waitset will wake up just like with an other status change of the attached entities.
This can be used to forcefully wake up a waitset, for instance when the application wants to shut down. So, when the trigger value is true, the waitset will wake up or not wait at all.
The trigger value will remain true until the application sets it false again deliberately.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] waitset
: The waitset to set the trigger value on.[in] trigger
: The trigger value to set.
- Return Value
DDS_RETCODE_OK
: Trigger value set.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The given waitset is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.
-
dds_return_t
dds_waitset_wait
(dds_entity_t waitset, dds_attach_t *xs, size_t nxs, dds_duration_t reltimeout)¶ This operation allows an application thread to wait for the a status change or other trigger on (one of) the entities that are attached to the WaitSet.
The “dds_waitset_wait” operation blocks until the some of the attached entities have triggered or “reltimeout” has elapsed. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:
Reader/Writer/Publisher/Subscriber/Topic/Participant
These are triggered when their status changed.
WaitSet
Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).
ReadCondition/QueryCondition
Triggered when data is available on the related Reader that matches the Condition.
This functions takes a pre-allocated list to put the “xs” blobs in (that were provided during the attach of the related entities) and will return the number of triggered entities. It is possible that the given size of the list is not the same as the number of triggered entities. If less entities were triggered, then the last few entries in the list are untouched. When more entities are triggered, then only ‘size’ number of entries are inserted into the list, but still the complete count of the triggered entities is returned. Which “xs” blobs are returned in the latter case is undefined.
In case of a time out, the return value is 0.
Deleting the waitset while the application is blocked results in an error code (i.e. < 0) returned by “wait”.
Multiple threads may block on a single waitset at the same time; the calls are entirely independent.
An empty waitset never triggers (i.e., dds_waitset_wait on an empty waitset is essentially equivalent to a sleep).
The “dds_waitset_wait_until” operation is the same as the “dds_waitset_wait” except that it takes an absolute timeout.
- Return
A dds_return_t with the number of entities triggered or an error code
- Parameters
[in] waitset
: The waitset to set the trigger value on.[out] xs
: Pre-allocated list to store the ‘blobs’ that were provided during the attach of the triggered entities.[in] nxs
: The size of the pre-allocated blobs list.[in] reltimeout
: Relative timeout
- Return Value
>0
: Number of entities triggered.0
: Time out (no entities were triggered).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The given waitset is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.
-
dds_return_t
dds_waitset_wait_until
(dds_entity_t waitset, dds_attach_t *xs, size_t nxs, dds_time_t abstimeout)¶ This operation allows an application thread to wait for the a status change or other trigger on (one of) the entities that are attached to the WaitSet.
The “dds_waitset_wait” operation blocks until the some of the attached entities have triggered or “abstimeout” has been reached. ‘Triggered’ (dds_triggered()) doesn’t mean the same for every entity:
Reader/Writer/Publisher/Subscriber/Topic/Participant
These are triggered when their status changed.
WaitSet
Triggered when trigger value was set to true by the application. It stays triggered until application sets the trigger value to false (dds_waitset_set_trigger()). This can be used to wake up an waitset for different reasons (f.i. termination) than the ‘normal’ status change (like new data).
ReadCondition/QueryCondition
Triggered when data is available on the related Reader that matches the Condition.
This functions takes a pre-allocated list to put the “xs” blobs in (that were provided during the attach of the related entities) and will return the number of triggered entities. It is possible that the given size of the list is not the same as the number of triggered entities. If less entities were triggered, then the last few entries in the list are untouched. When more entities are triggered, then only ‘size’ number of entries are inserted into the list, but still the complete count of the triggered entities is returned. Which “xs” blobs are returned in the latter case is undefined.
In case of a time out, the return value is 0.
Deleting the waitset while the application is blocked results in an error code (i.e. < 0) returned by “wait”.
Multiple threads may block on a single waitset at the same time; the calls are entirely independent.
An empty waitset never triggers (i.e., dds_waitset_wait on an empty waitset is essentially equivalent to a sleep).
The “dds_waitset_wait” operation is the same as the “dds_waitset_wait_until” except that it takes an relative timeout.
The “dds_waitset_wait” operation is the same as the “dds_wait” except that it takes an absolute timeout.
- Return
A dds_return_t with the number of entities triggered or an error code.
- Parameters
[in] waitset
: The waitset to set the trigger value on.[out] xs
: Pre-allocated list to store the ‘blobs’ that were provided during the attach of the triggered entities.[in] nxs
: The size of the pre-allocated blobs list.[in] abstimeout
: Absolute timeout
- Return Value
>0
: Number of entities triggered.0
: Time out (no entities were triggered).DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The given waitset is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The waitset has already been deleted.
-
dds_return_t
dds_read
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)¶ Access and read the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition.
Return value provides information about number of samples read, which will be <= maxs. Based on the count, the buffer will contain data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the Data. Data values once read will remain in the buffer with the sample_state set to READ and view_state set to NOT_NEW.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs)¶ Access and read loaned samples of data reader, readcondition or querycondition.
After dds_read_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory.
- Return
A dds_return_t with the number of samples read or an error code
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL)[out] si
: Pointer to an array of dds_sample_info_t returned for each data value[in] maxs
: Maximum number of samples to read
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_mask
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, uint32_t mask)¶ Read the collection of data values and sample info from the data reader, readcondition or querycondition based on mask.
When using a readcondition or querycondition, their masks are or’d with the given mask.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_mask_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, uint32_t mask)¶ Access and read loaned samples of data reader, readcondition or querycondition based on mask.
When using a readcondition or querycondition, their masks are or’d with the given mask.
After dds_read_mask_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_instance
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle)¶ Access and read the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition, coped by the provided instance handle.
This operation implements the same functionality as dds_read, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_read_instance_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle)¶ Access and read loaned samples of data reader, readcondition or querycondition, scoped by the provided instance handle.
This operation implements the same functionality as dds_read_wl, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_read_instance_mask
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶ Read the collection of data values and sample info from the data reader, readcondition or querycondition based on mask and scoped by the provided instance handle.
This operation implements the same functionality as dds_read_mask, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_read_instance_mask_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶ Access and read loaned samples of data reader, readcondition or querycondition based on mask, scoped by the provided instance handle.
This operation implements the same functionality as dds_read_mask_wl, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_take
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)¶ Access the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition.
Data value once read is removed from the Data Reader cannot to ‘read’ or ‘taken’ again. Return value provides information about number of samples read, which will be <= maxs. Based on the count, the buffer will contain data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the Data.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs)¶ Access loaned samples of data reader, readcondition or querycondition.
After dds_take_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_mask
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, uint32_t mask)¶ Take the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition based on mask.
When using a readcondition or querycondition, their masks are or’d with the given mask.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_mask_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, uint32_t mask)¶ Access loaned samples of data reader, readcondition or querycondition based on mask.
When using a readcondition or querycondition, their masks are or’d with the given mask.
After dds_take_mask_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_readcdr
(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, uint32_t mask)¶ Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition.
This call accesses the serialized data from the data reader, readcondition or querycondition and makes it available to the application. The serialized data is made available through ddsi_serdata structures. Returned samples are marked as READ.
Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.[in] maxs
: Maximum number of samples to read.[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The precondition for this operation is not met.
-
dds_return_t
dds_takecdr
(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, uint32_t mask)¶ Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition.
This call accesses the serialized data from the data reader, readcondition or querycondition and makes it available to the application. The serialized data is made available through ddsi_serdata structures. Once read the data is removed from the reader and cannot be ‘read’ or ‘taken’ again.
Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.[in] maxs
: Maximum number of samples to read.[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The precondition for this operation is not met.
-
dds_return_t
dds_take_instance
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle)¶ Access the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition but scoped by the given instance handle.
This operation mplements the same functionality as dds_take, except that only data scoped to the provided instance handle is taken.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_take_instance_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle)¶ Access loaned samples of data reader, readcondition or querycondition, scoped by the given instance handle.
This operation implements the same functionality as dds_take_wl, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_take_instance_mask
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶ Take the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition based on mask and scoped by the given instance handle.
This operation implements the same functionality as dds_take_mask, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples read or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] bufsz
: The size of buffer provided.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=0
: Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_take_instance_mask_wl
(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶ Access loaned samples of data reader, readcondition or querycondition based on mask and scoped by the given intance handle.
This operation implements the same functionality as dds_take_mask_wl, except that only data scoped to the provided instance handle is read.
- Return
A dds_return_t with the number of samples or an error code.
- Parameters
[in] reader_or_condition
: Reader, readcondition or querycondition entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: Pointer to an array of dds_sample_info_t returned for each data value.[in] maxs
: Maximum number of samples to read.[in] handle
: Instance handle related to the samples to read.[in] mask
: Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.
- Return Value
>=
: 0 Number of samples read.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate objectDDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.DDS_RETCODE_PRECONDITION_NOT_MET
: The instance handle has not been registered with this reader.
-
dds_return_t
dds_take_next
(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶ Read, copy and remove the status set for the entity.
This operation copies the next, non-previously accessed data value and corresponding sample info and removes from the data reader. As an entity, only reader is accepted.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] reader
: The reader entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: The pointer to dds_sample_info_t returned for a data value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_take_next_wl
(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶ Read, copy and remove the status set for the entity.
This operation copies the next, non-previously accessed data value and corresponding sample info and removes from the data reader. As an entity, only reader is accepted.
After dds_take_next_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] reader
: The reader entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: The pointer to dds_sample_info_t returned for a data value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_next
(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶ Read and copy the status set for the entity.
This operation copies the next, non-previously accessed data value and corresponding sample info. As an entity, only reader is accepted.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] reader
: The reader entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: The pointer to dds_sample_info_t returned for a data value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_read_next_wl
(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶ Read and copy the status set for the loaned sample.
This operation copies the next, non-previously accessed data value and corresponding loaned sample info. As an entity, only reader is accepted.
After dds_read_next_wl function is being called and the data has been handled, dds_return_loan function must be called to possibly free memory.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] reader
: The reader entity.[out] buf
: An array of pointers to samples into which data is read (pointers can be NULL).[out] si
: The pointer to dds_sample_info_t returned for a data value.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_return_loan
(dds_entity_t reader_or_condition, void **buf, int32_t bufsz)¶ Return loaned samples to data-reader or condition associated with a data-reader.
Used to release sample buffers returned by a read/take operation. When the application provides an empty buffer, memory is allocated and managed by DDS. By calling dds_return_loan, the memory is released so that the buffer can be reused during a successive read/take operation. When a condition is provided, the reader to which the condition belongs is looked up.
- Return
A dds_return_t indicating success or failure
- Parameters
[in] reader_or_condition
: Reader or condition that belongs to a reader.[in] buf
: An array of (pointers to) samples.[in] bufsz
: The number of (pointers to) samples stored in buf.
-
dds_instance_handle_t
dds_lookup_instance
(dds_entity_t entity, const void *data)¶ This operation takes a sample and returns an instance handle to be used for subsequent operations.
- Return
instance handle or DDS_HANDLE_NIL if instance could not be found from key.
- Parameters
[in] entity
: Reader or Writer entity.[in] data
: Sample with a key fields set.
-
dds_instance_handle_t
dds_instance_lookup
(dds_entity_t entity, const void *data)¶
-
dds_return_t
dds_instance_get_key
(dds_entity_t entity, dds_instance_handle_t inst, void *data)¶ This operation takes an instance handle and return a key-value corresponding to it.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Reader, writer, readcondition or querycondition entity.[in] inst
: Instance handle.[out] data
: pointer to an instance, to which the key ID corresponding to the instance handle will be returned, the sample in the instance should be ignored.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: One of the parameters was invalid or the topic does not exist.DDS_RETCODE_ERROR
: An internal error has occurred.
-
dds_return_t
dds_begin_coherent
(dds_entity_t entity)¶ Begin coherent publishing or begin accessing a coherent set in a subscriber.
Invoking on a Writer or Reader behaves as if dds_begin_coherent was invoked on its parent Publisher or Subscriber respectively.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: The entity that is prepared for coherent access.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: The provided entity is invalid or not supported.
-
dds_return_t
dds_end_coherent
(dds_entity_t entity)¶ End coherent publishing or end accessing a coherent set in a subscriber.
Invoking on a Writer or Reader behaves as if dds_end_coherent was invoked on its parent Publisher or Subscriber respectively.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: The entity on which coherent access is finished.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The provided entity is invalid or not supported.
-
dds_return_t
dds_notify_readers
(dds_entity_t subscriber)¶ Trigger DATA_AVAILABLE event on contained readers.
The DATA_AVAILABLE event is broadcast to all readers owned by this subscriber that currently have new data available. Any on_data_available listener callbacks attached to respective readers are invoked.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] subscriber
: A valid subscriber handle.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The provided subscriber is invalid.
-
dds_return_t
dds_triggered
(dds_entity_t entity)¶ Checks whether the entity has one of its enabled statuses triggered.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: Entity for which to check for triggered status.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_entity_t
dds_get_topic
(dds_entity_t entity)¶ Get the topic.
This operation returns a topic (handle) when the function call is done with reader, writer, read condition or query condition. For instance, it will return the topic when it is used for creating the reader or writer. For the conditions, it returns the topic that is used for creating the reader which was used to create the condition.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: The entity.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_matched_subscriptions
(dds_entity_t writer, dds_instance_handle_t *rds, size_t nrds)¶ Get instance handles of the data readers matching a writer.
This operation fills the provided array with the instance handles of the data readers that match the writer. On successful output, the number of entries of “rds” set is the minimum of the return value and the value of “nrds”.
- Return
A dds_return_t indicating the number of matched readers or failure. The return value may be larger than nrds if there are more matching readers than the array can hold.
- Parameters
[in] writer
: The writer.[in] rds
: The array to be filled.[in] nrds
: The size of the rds array, at most the first nrds entries will be filled. rds = NULL and nrds = 0 is a valid way of determining the number of matched readers, but inefficient compared to relying on the matched publication status.
- Return Value
>=0
: The number of matching readers.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not valid or rds = NULL and nrds > 0.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_builtintopic_endpoint_t *
dds_get_matched_subscription_data
(dds_entity_t writer, dds_instance_handle_t ih)¶ Get a description of a reader matched with the provided writer.
This operation looks up the reader instance handle in the set of readers matched with the specified writer, returning a freshly allocated sample of the DCPSSubscription built-in topic if found, and NULL if not. The caller is responsible for freeing the memory allocated.
This operation is similar to performing a read of the given instance handle on a reader of the DCPSSubscription built-in topic, but this operation additionally filters on whether the reader is matched by the provided writer.
- Return
A newly allocated sample containing the information on the reader, or a NULL pointer for any kind of failure.
- Parameters
[in] writer
: The writer.[in] ih
: The instance handle of a reader.
- Return Value
!=
: NULL The requested dataNULL
: The writer is not valid or ih is not an instance handle of a matched reader.
-
dds_return_t
dds_get_matched_publications
(dds_entity_t reader, dds_instance_handle_t *wrs, size_t nwrs)¶ Get instance handles of the data writers matching a reader.
This operation fills the provided array with the instance handles of the data writers that match the reader. On successful output, the number of entries of “wrs” set is the minimum of the return value and the value of “nwrs”.
- Return
A dds_return_t indicating the number of matched writers or failure. The return value may be larger than nwrs if there are more matching writers than the array can hold.
- Parameters
[in] reader
: The reader.[in] wrs
: The array to be filled.[in] nwrs
: The size of the wrs array, at most the first nwrs entries will be filled. wrs = NULL and wrds = 0 is a valid way of determining the number of matched readers, but inefficient compared to relying on the matched publication status.
- Return Value
>=0
: The number of matching writers.DDS_RETCODE_BAD_PARAMETER
: The entity parameter is not valid or wrs = NULL and nwrs > 0.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_builtintopic_endpoint_t *
dds_get_matched_publication_data
(dds_entity_t reader, dds_instance_handle_t ih)¶ Get a description of a writer matched with the provided reader.
This operation looks up the writer instance handle in the set of writers matched with the specified reader, returning a freshly allocated sample of the DCPSPublication built-in topic if found, and NULL if not. The caller is responsible for freeing the memory allocated.
This operation is similar to performing a read of the given instance handle on a reader of the DCPSPublication built-in topic, but this operation additionally filters on whether the writer is matched by the provided reader.
- Return
A newly allocated sample containing the information on the writer, or a NULL pointer for any kind of failure.
- Parameters
[in] reader
: The reader.[in] ih
: The instance handle of a writer.
- Return Value
!=
: NULL The requested dataNULL
: The reader is not valid or ih is not an instance handle of a matched writer.
-
dds_return_t
dds_assert_liveliness
(dds_entity_t entity)¶ This operation manually asserts the liveliness of a writer or domain participant.
This operation manually asserts the liveliness of a writer or domain participant. This is used in combination with the Liveliness QoS policy to indicate that the entity remains active. This operation need only be used if the liveliness kind in the QoS is either DDS_LIVELINESS_MANUAL_BY_PARTICIPANT or DDS_LIVELINESS_MANUAL_BY_TOPIC.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: A domain participant or writer
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
dds_return_t
dds_domain_set_deafmute
(dds_entity_t entity, bool deaf, bool mute, dds_duration_t reset_after)¶ This operation allows making the domain’s network stack temporarily deaf and/or mute. It is a support function for testing and, other special uses and is subject to change.
- Return
A dds_return_t indicating success or failure.
- Parameters
[in] entity
: A domain entity or an entity bound to a domain, such as a participant, reader or writer.[in] deaf
: Whether to network stack should pretend to be deaf and ignore any incoming packets.[in] mute
: Whether to network stack should pretend to be mute and discard any outgoing packets where it normally would. pass them to the operating system kernel for transmission.[in] reset_after
: Any value less than INFINITY will cause it to set deaf = mute = false after reset_after ns have passed. This is done by an event scheduled for the appropriate time and otherwise forgotten. These events are not affected by subsequent calls to this function.
- Return Value
DDS_RETCODE_OK
: The operation was successful.DDS_BAD_PARAMETER
: The entity parameter is not a valid parameter.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.
-
-
file
dds.h
- #include “dds/dds.h”
-
file
dds_internal_api.h
WARNING This file is only needed for the work around for https://github.com/eclipse-cyclonedds/cyclonedds/issues/74 Do not include this file in an application! Once issue #74 is solved this header file should be removed.
Defines
-
DDS_READ_WITHOUT_LOCK
¶
Functions
-
uint32_t
dds_reader_lock_samples
(dds_entity_t entity)¶
-
-
file
dds_public_alloc.h
- #include <stddef.h>#include “dds/export.h”
DDS C Allocation API.
This header file defines the public API of allocation convenience functions in the Eclipse Cyclone DDS C language binding.
Typedefs
-
typedef struct dds_allocator
dds_allocator_t
¶
-
typedef void *(*
dds_alloc_fn_t
)(size_t)¶
-
typedef void *(*
dds_realloc_fn_t
)(void*, size_t)¶
-
typedef void (*
dds_free_fn_t
)(void*)¶
Enums
Functions
-
void *
dds_alloc
(size_t size)¶
-
void *
dds_realloc
(void *ptr, size_t size)¶
-
void *
dds_realloc_zero
(void *ptr, size_t size)¶
-
void
dds_free
(void *ptr)¶
-
char *
dds_string_alloc
(size_t size)¶
-
char *
dds_string_dup
(const char *str)¶
-
void
dds_string_free
(char *str)¶
-
void
dds_sample_free
(void *sample, const struct dds_topic_descriptor *desc, dds_free_op_t op)¶
-
typedef struct dds_allocator
-
file
dds_public_error.h
- #include “dds/export.h”#include “dds/ddsrt/log.h”#include “dds/ddsrt/retcode.h”
DDS C Error API.
This header file defines the public API of error values and convenience functions in the CycloneDDS C language binding.
-
file
dds_public_impl.h
- #include <stdint.h>#include <stdbool.h>#include “dds/export.h”#include “dds/ddsc/dds_public_alloc.h”
DDS C Implementation API.
This header file defines the public API for all kinds of things in the Eclipse Cyclone DDS C language binding.
Defines
-
DDS_TOPIC_NO_OPTIMIZE
¶
-
DDS_TOPIC_FIXED_KEY
¶
-
DDS_TOPIC_CONTAINS_UNION
¶
-
DDS_READ_SAMPLE_STATE
¶
-
DDS_NOT_READ_SAMPLE_STATE
¶
-
DDS_ANY_SAMPLE_STATE
¶
-
DDS_NEW_VIEW_STATE
¶
-
DDS_NOT_NEW_VIEW_STATE
¶
-
DDS_ANY_VIEW_STATE
¶
-
DDS_ALIVE_INSTANCE_STATE
¶
-
DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE
¶
-
DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE
¶
-
DDS_ANY_INSTANCE_STATE
¶
-
DDS_ANY_STATE
¶
-
DDS_DOMAIN_DEFAULT
¶
-
DDS_HANDLE_NIL
¶
-
DDS_ENTITY_NIL
¶
-
DDS_KIND_MAX
¶
-
DDS_OP_TYPE_BOO
¶
-
DDS_OP_SUBTYPE_BOO
¶
-
DDS_OP_FLAG_KEY
¶
-
DDS_OP_FLAG_DEF
¶
-
DDS_OP_FLAG_FP
¶
-
DDS_OP_FLAG_SGN
¶
Typedefs
-
typedef struct dds_sequence
dds_sequence_t
¶
-
typedef struct dds_key_descriptor
dds_key_descriptor_t
¶
-
typedef struct dds_topic_descriptor
dds_topic_descriptor_t
¶
-
typedef enum dds_entity_kind
dds_entity_kind_t
¶
-
typedef uint64_t
dds_instance_handle_t
¶
-
typedef uint32_t
dds_domainid_t
¶
Enums
-
enum
dds_entity_kind
¶ Values:
-
enumerator
DDS_KIND_DONTCARE
¶
-
enumerator
DDS_KIND_TOPIC
¶
-
enumerator
DDS_KIND_PARTICIPANT
¶
-
enumerator
DDS_KIND_READER
¶
-
enumerator
DDS_KIND_WRITER
¶
-
enumerator
DDS_KIND_SUBSCRIBER
¶
-
enumerator
DDS_KIND_PUBLISHER
¶
-
enumerator
DDS_KIND_COND_READ
¶
-
enumerator
DDS_KIND_COND_QUERY
¶
-
enumerator
DDS_KIND_COND_GUARD
¶
-
enumerator
DDS_KIND_WAITSET
¶
-
enumerator
DDS_KIND_DOMAIN
¶
-
enumerator
DDS_KIND_CYCLONEDDS
¶
-
enumerator
-
enum
dds_stream_opcode
¶ Values:
-
enumerator
DDS_OP_RTS
¶
-
enumerator
DDS_OP_ADR
¶
-
enumerator
DDS_OP_JSR
¶
-
enumerator
DDS_OP_JEQ
¶
-
enumerator
-
enum
dds_stream_typecode
¶ Values:
-
enumerator
DDS_OP_VAL_1BY
¶
-
enumerator
DDS_OP_VAL_2BY
¶
-
enumerator
DDS_OP_VAL_4BY
¶
-
enumerator
DDS_OP_VAL_8BY
¶
-
enumerator
DDS_OP_VAL_STR
¶
-
enumerator
DDS_OP_VAL_BST
¶
-
enumerator
DDS_OP_VAL_SEQ
¶
-
enumerator
DDS_OP_VAL_ARR
¶
-
enumerator
DDS_OP_VAL_UNI
¶
-
enumerator
DDS_OP_VAL_STU
¶
-
enumerator
-
enum
dds_stream_typecode_primary
¶ Values:
-
enumerator
DDS_OP_TYPE_1BY
¶
-
enumerator
DDS_OP_TYPE_2BY
¶
-
enumerator
DDS_OP_TYPE_4BY
¶
-
enumerator
DDS_OP_TYPE_8BY
¶
-
enumerator
DDS_OP_TYPE_STR
¶
-
enumerator
DDS_OP_TYPE_BST
¶
-
enumerator
DDS_OP_TYPE_SEQ
¶
-
enumerator
DDS_OP_TYPE_ARR
¶
-
enumerator
DDS_OP_TYPE_UNI
¶
-
enumerator
DDS_OP_TYPE_STU
¶
-
enumerator
-
enum
dds_stream_typecode_subtype
¶ Values:
-
enumerator
DDS_OP_SUBTYPE_1BY
¶
-
enumerator
DDS_OP_SUBTYPE_2BY
¶
-
enumerator
DDS_OP_SUBTYPE_4BY
¶
-
enumerator
DDS_OP_SUBTYPE_8BY
¶
-
enumerator
DDS_OP_SUBTYPE_STR
¶
-
enumerator
DDS_OP_SUBTYPE_BST
¶
-
enumerator
DDS_OP_SUBTYPE_SEQ
¶
-
enumerator
DDS_OP_SUBTYPE_ARR
¶
-
enumerator
DDS_OP_SUBTYPE_UNI
¶
-
enumerator
DDS_OP_SUBTYPE_STU
¶
-
enumerator
Functions
-
void
dds_write_set_batch
(bool enable)¶ Description : Enable or disable write batching. Overrides default configuration setting for write batching (Internal/WriteBatch).
Arguments :
enable Enables or disables write batching for all writers.
-
-
file
dds_public_listener.h
- #include “dds/export.h”#include “dds/ddsc/dds_public_impl.h”#include “dds/ddsc/dds_public_status.h”
DDS C Listener API.
This header file defines the public API of listeners in the Eclipse Cyclone DDS C language binding.
Defines
-
DDS_LUNSET
¶
Typedefs
-
typedef void (*
dds_on_inconsistent_topic_fn
)(dds_entity_t topic, const dds_inconsistent_topic_status_t status, void *arg)¶
-
typedef void (*
dds_on_liveliness_lost_fn
)(dds_entity_t writer, const dds_liveliness_lost_status_t status, void *arg)¶
-
typedef void (*
dds_on_offered_deadline_missed_fn
)(dds_entity_t writer, const dds_offered_deadline_missed_status_t status, void *arg)¶
-
typedef void (*
dds_on_offered_incompatible_qos_fn
)(dds_entity_t writer, const dds_offered_incompatible_qos_status_t status, void *arg)¶
-
typedef void (*
dds_on_data_on_readers_fn
)(dds_entity_t subscriber, void *arg)¶
-
typedef void (*
dds_on_sample_lost_fn
)(dds_entity_t reader, const dds_sample_lost_status_t status, void *arg)¶
-
typedef void (*
dds_on_data_available_fn
)(dds_entity_t reader, void *arg)¶
-
typedef void (*
dds_on_sample_rejected_fn
)(dds_entity_t reader, const dds_sample_rejected_status_t status, void *arg)¶
-
typedef void (*
dds_on_liveliness_changed_fn
)(dds_entity_t reader, const dds_liveliness_changed_status_t status, void *arg)¶
-
typedef void (*
dds_on_requested_deadline_missed_fn
)(dds_entity_t reader, const dds_requested_deadline_missed_status_t status, void *arg)¶
-
typedef void (*
dds_on_requested_incompatible_qos_fn
)(dds_entity_t reader, const dds_requested_incompatible_qos_status_t status, void *arg)¶
-
typedef void (*
dds_on_publication_matched_fn
)(dds_entity_t writer, const dds_publication_matched_status_t status, void *arg)¶
-
typedef void (*
dds_on_subscription_matched_fn
)(dds_entity_t reader, const dds_subscription_matched_status_t status, void *arg)¶
-
typedef struct dds_listener
dds_listener_t
¶
Functions
-
dds_listener_t *
dds_create_listener
(void *arg)¶ Allocate memory and initializes to default values (::DDS_LUNSET) of a listener.
- Return
Returns a pointer to the allocated memory for dds_listener_t structure.
- Parameters
[in] arg
: optional pointer that will be passed on to the listener callbacks
-
dds_listener_t *
dds_listener_create
(void *arg)¶
-
void
dds_delete_listener
(dds_listener_t *listener)¶ Delete the memory allocated to listener structure.
- Parameters
[in] listener
: pointer to the listener struct to delete
-
void
dds_listener_delete
(dds_listener_t *listener)¶
-
void
dds_reset_listener
(dds_listener_t *listener)¶ Reset the listener structure contents to ::DDS_LUNSET.
- Parameters
[inout] listener
: pointer to the listener struct to reset
-
void
dds_listener_reset
(dds_listener_t *listener)¶
-
void
dds_copy_listener
(dds_listener_t *dst, const dds_listener_t *src)¶ Copy the listener callbacks from source to destination.
- Parameters
[inout] dst
: The pointer to the destination listener structure, where the content is to copied[in] src
: The pointer to the source listener structure to be copied
-
void
dds_listener_copy
(dds_listener_t *dst, const dds_listener_t *src)¶
-
void
dds_merge_listener
(dds_listener_t *dst, const dds_listener_t *src)¶ Copy the listener callbacks from source to destination, unless already set.
Any listener callbacks already set in
dst
(including NULL) are skipped, only those set to DDS_LUNSET are copied fromsrc
.- Parameters
[inout] dst
: The pointer to the destination listener structure, where the content is merged[in] src
: The pointer to the source listener structure to be copied
-
void
dds_listener_merge
(dds_listener_t *dst, const dds_listener_t *src)¶
-
void
dds_lset_inconsistent_topic
(dds_listener_t *listener, dds_on_inconsistent_topic_fn callback)¶ Set the inconsistent_topic callback in the listener structure.
- Parameters
listener
: The pointer to the listener structure, where the callback will be setcallback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_liveliness_lost
(dds_listener_t *listener, dds_on_liveliness_lost_fn callback)¶ Set the liveliness_lost callback in the listener structure.
- Parameters
[out] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_offered_deadline_missed
(dds_listener_t *listener, dds_on_offered_deadline_missed_fn callback)¶ Set the offered_deadline_missed callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_offered_incompatible_qos
(dds_listener_t *listener, dds_on_offered_incompatible_qos_fn callback)¶ Set the offered_incompatible_qos callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_data_on_readers
(dds_listener_t *listener, dds_on_data_on_readers_fn callback)¶ Set the data_on_readers callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_sample_lost
(dds_listener_t *listener, dds_on_sample_lost_fn callback)¶ Set the sample_lost callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_data_available
(dds_listener_t *listener, dds_on_data_available_fn callback)¶ Set the data_available callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_sample_rejected
(dds_listener_t *listener, dds_on_sample_rejected_fn callback)¶ Set the sample_rejected callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_liveliness_changed
(dds_listener_t *listener, dds_on_liveliness_changed_fn callback)¶ Set the liveliness_changed callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_requested_deadline_missed
(dds_listener_t *listener, dds_on_requested_deadline_missed_fn callback)¶ Set the requested_deadline_missed callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_requested_incompatible_qos
(dds_listener_t *listener, dds_on_requested_incompatible_qos_fn callback)¶ Set the requested_incompatible_qos callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_publication_matched
(dds_listener_t *listener, dds_on_publication_matched_fn callback)¶ Set the publication_matched callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lset_subscription_matched
(dds_listener_t *listener, dds_on_subscription_matched_fn callback)¶ Set the subscription_matched callback in the listener structure.
- Parameters
[inout] listener
: The pointer to the listener structure, where the callback will be set[in] callback
: The callback to set in the listener, can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_inconsistent_topic
(const dds_listener_t *listener, dds_on_inconsistent_topic_fn *callback)¶ Get the inconsistent_topic callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_liveliness_lost
(const dds_listener_t *listener, dds_on_liveliness_lost_fn *callback)¶ Get the liveliness_lost callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_offered_deadline_missed
(const dds_listener_t *listener, dds_on_offered_deadline_missed_fn *callback)¶ Get the offered_deadline_missed callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_offered_incompatible_qos
(const dds_listener_t *listener, dds_on_offered_incompatible_qos_fn *callback)¶ Get the offered_incompatible_qos callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_data_on_readers
(const dds_listener_t *listener, dds_on_data_on_readers_fn *callback)¶ Get the data_on_readers callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_sample_lost
(const dds_listener_t *listener, dds_on_sample_lost_fn *callback)¶ Get the sample_lost callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_data_available
(const dds_listener_t *listener, dds_on_data_available_fn *callback)¶ Get the data_available callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_sample_rejected
(const dds_listener_t *listener, dds_on_sample_rejected_fn *callback)¶ Get the sample_rejected callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_liveliness_changed
(const dds_listener_t *listener, dds_on_liveliness_changed_fn *callback)¶ Get the liveliness_changed callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_requested_deadline_missed
(const dds_listener_t *listener, dds_on_requested_deadline_missed_fn *callback)¶ Get the requested_deadline_missed callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_requested_incompatible_qos
(const dds_listener_t *listener, dds_on_requested_incompatible_qos_fn *callback)¶ Get the requested_incompatible_qos callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_publication_matched
(const dds_listener_t *listener, dds_on_publication_matched_fn *callback)¶ Get the publication_matched callback from the listener structure.
- Parameters
[in] listener
: The pointer to the listener structure, where the callback will be retrieved from[inout] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer
-
void
dds_lget_subscription_matched
(const dds_listener_t *listener, dds_on_subscription_matched_fn *callback)¶ Get the subscription_matched callback from the listener structure.
- Parameters
[in] callback
: Pointer where the retrieved callback can be stored; can be NULL, ::DDS_LUNSET or a valid callback pointer[inout] listener
: The pointer to the listener structure, where the callback will be retrieved from
-
-
file
dds_public_qos.h
- #include “dds/export.h”#include “dds/ddsc/dds_public_qosdefs.h”
DDS C QoS API.
This header file defines the public API of QoS and Policies in the Eclipse Cyclone DDS C language binding.
Defines
-
DDS_HAS_PROPERTY_LIST_QOS
¶
Functions
-
dds_qos_t *
dds_create_qos
(void)¶ Allocate memory and initialize default QoS-policies.
- Return
- Pointer to the initialized dds_qos_t structure, NULL if unsuccessful.
-
void
dds_delete_qos
(dds_qos_t *qos)¶ Delete memory allocated to QoS-policies structure.
- Parameters
[in] qos
: - Pointer to dds_qos_t structure
-
void
dds_reset_qos
(dds_qos_t *qos)¶ Reset a QoS-policies structure to default values.
- Parameters
[inout] qos
: - Pointer to the dds_qos_t structure
-
dds_return_t
dds_copy_qos
(dds_qos_t *dst, const dds_qos_t *src)¶ Copy all QoS-policies from one structure to another.
- Return
- Return-code indicating success or failure
- Parameters
[inout] dst
: - Pointer to the destination dds_qos_t structure[in] src
: - Pointer to the source dds_qos_t structure
-
void
dds_merge_qos
(dds_qos_t *dst, const dds_qos_t *src)¶ Copy all QoS-policies from one structure to another, unless already set.
Policies are copied from src to dst, unless src already has the policy set to a non-default value.
- Parameters
[inout] dst
: - Pointer to the destination qos structure[in] src
: - Pointer to the source qos structure
-
bool
dds_qos_equal
(const dds_qos_t *a, const dds_qos_t *b)¶ Copy all QoS-policies from one structure to another, unless already set.
Policies are copied from src to dst, unless src already has the policy set to a non-default value.
- Parameters
[inout] a
: - Pointer to the destination qos structure[in] b
: - Pointer to the source qos structure
-
void
dds_qset_userdata
(dds_qos_t *qos, const void *value, size_t sz)¶ Set the userdata of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the userdata[in] value
: - Pointer to the userdata[in] sz
: - Size of userdata stored in value
-
void
dds_qset_topicdata
(dds_qos_t *qos, const void *value, size_t sz)¶ Set the topicdata of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the topicdata[in] value
: - Pointer to the topicdata[in] sz
: - Size of the topicdata stored in value
-
void
dds_qset_groupdata
(dds_qos_t *qos, const void *value, size_t sz)¶ Set the groupdata of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the groupdata[in] value
: - Pointer to the group data[in] sz
: - Size of groupdata stored in value
-
void
dds_qset_durability
(dds_qos_t *qos, dds_durability_kind_t kind)¶ Set the durability policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] kind
: - Durability kind value DCPS_QoS_Durability
-
void
dds_qset_history
(dds_qos_t *qos, dds_history_kind_t kind, int32_t depth)¶ Set the history policy of a qos structure.
Note that depth is only relevant for keep last. If you want limited history for keep all, use dds_qset_resource_limits().
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] kind
: - History kind value DCPS_QoS_History[in] depth
: - History depth value DCPS_QoS_History
-
void
dds_qset_resource_limits
(dds_qos_t *qos, int32_t max_samples, int32_t max_instances, int32_t max_samples_per_instance)¶ Set the resource limits policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] max_samples
: - Number of samples resource-limit value[in] max_instances
: - Number of instances resource-limit value[in] max_samples_per_instance
: - Number of samples per instance resource-limit value
-
void
dds_qset_presentation
(dds_qos_t *qos, dds_presentation_access_scope_kind_t access_scope, bool coherent_access, bool ordered_access)¶ Set the presentation policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] access_scope
: - Access-scope kind[in] coherent_access
: - Coherent access enable value[in] ordered_access
: - Ordered access enable value
-
void
dds_qset_lifespan
(dds_qos_t *qos, dds_duration_t lifespan)¶ Set the lifespan policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] lifespan
: - Lifespan duration (expiration time relative to source timestamp of a sample)
-
void
dds_qset_deadline
(dds_qos_t *qos, dds_duration_t deadline)¶ Set the deadline policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] deadline
: - Deadline duration
-
void
dds_qset_latency_budget
(dds_qos_t *qos, dds_duration_t duration)¶ Set the latency-budget policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] duration
: - Latency budget duration
-
void
dds_qset_ownership
(dds_qos_t *qos, dds_ownership_kind_t kind)¶ Set the ownership policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] kind
: - Ownership kind
-
void
dds_qset_ownership_strength
(dds_qos_t *qos, int32_t value)¶ Set the ownership strength policy of a qos structure.
param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy param[in] value - Ownership strength value
-
void
dds_qset_liveliness
(dds_qos_t *qos, dds_liveliness_kind_t kind, dds_duration_t lease_duration)¶ Set the liveliness policy of a qos structure.
param[in,out] qos - Pointer to a dds_qos_t structure that will store the policy param[in] kind - Liveliness kind param[in[ lease_duration - Lease duration
-
void
dds_qset_time_based_filter
(dds_qos_t *qos, dds_duration_t minimum_separation)¶ Set the time-based filter policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] minimum_separation
: - Minimum duration between sample delivery for an instance
-
void
dds_qset_partition
(dds_qos_t *qos, uint32_t n, const char **ps)¶ Set the partition policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] n
: - Number of partitions stored in ps[in] ps
: - Pointer to string(s) storing partition name(s)
-
void
dds_qset_partition1
(dds_qos_t *qos, const char *name)¶ Convenience function to set the partition policy of a qos structure to a single name. Name may be a null pointer.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] name
: - Pointer to the name
-
void
dds_qset_reliability
(dds_qos_t *qos, dds_reliability_kind_t kind, dds_duration_t max_blocking_time)¶ Set the reliability policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] kind
: - Reliability kind[in] max_blocking_time
: - Max blocking duration applied when kind is reliable. This is how long the writer will block when its history is full.
-
void
dds_qset_transport_priority
(dds_qos_t *qos, int32_t value)¶ Set the transport-priority policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] value
: - Priority value
-
void
dds_qset_destination_order
(dds_qos_t *qos, dds_destination_order_kind_t kind)¶ Set the destination-order policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] kind
: - Destination-order kind
-
void
dds_qset_writer_data_lifecycle
(dds_qos_t *qos, bool autodispose)¶ Set the writer data-lifecycle policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] autodispose
: - Automatic disposal of unregistered instances
-
void
dds_qset_reader_data_lifecycle
(dds_qos_t *qos, dds_duration_t autopurge_nowriter_samples_delay, dds_duration_t autopurge_disposed_samples_delay)¶ Set the reader data-lifecycle policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] autopurge_nowriter_samples_delay
: - Delay for purging of samples from instances in a no-writers state[in] autopurge_disposed_samples_delay
: - Delay for purging of samples from disposed instances
-
void
dds_qset_durability_service
(dds_qos_t *qos, dds_duration_t service_cleanup_delay, dds_history_kind_t history_kind, int32_t history_depth, int32_t max_samples, int32_t max_instances, int32_t max_samples_per_instance)¶ Set the durability-service policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] service_cleanup_delay
: - Delay for purging of abandoned instances from the durability service[in] history_kind
: - History policy kind applied by the durability service[in] history_depth
: - History policy depth applied by the durability service[in] max_samples
: - Number of samples resource-limit policy applied by the durability service[in] max_instances
: - Number of instances resource-limit policy applied by the durability service[in] max_samples_per_instance
: - Number of samples per instance resource-limit policy applied by the durability service
-
void
dds_qset_ignorelocal
(dds_qos_t *qos, dds_ignorelocal_kind_t ignore)¶ Set the ignore-local policy of a qos structure.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the policy[in] ignore
: - True if readers and writers owned by the same participant should be ignored
-
void
dds_qset_prop
(dds_qos_t *qos, const char *name, const char *value)¶ Stores a property with the provided name and string value in a qos structure.
In the case a property with the provided name already exists in the qos structure, the value for this entry is overwritten with the provided string value. If more than one property with the provided name exists, only the value of the first of these properties is updated.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the property[in] name
: - Pointer to name of the property[in] value
: - Pointer to a (null-terminated) string that will be stored
-
void
dds_qunset_prop
(dds_qos_t *qos, const char *name)¶ Removes the property with the provided name from a qos structure.
In case more than one property exists with this name, only the first property is removed.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains the property[in] name
: - Pointer to name of the property
-
void
dds_qset_bprop
(dds_qos_t *qos, const char *name, const void *value, const size_t sz)¶ Stores the provided binary data as a property in a qos structure.
In the case a property with the provided name already exists in the qos structure, the value for this entry is overwritten with the provided data. If more than one property with the provided name exists, only the value of the first of these properties is updated.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that will store the property[in] name
: - Pointer to name of the property[in] value
: - Pointer to data to be stored in the property[in] sz
: - Size of the data
-
void
dds_qunset_bprop
(dds_qos_t *qos, const char *name)¶ Removes the binary property with the provided name from a qos structure.
In case more than one binary property exists with this name, only the first binary property is removed.
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains the binary property[in] name
: - Pointer to name of the property
-
bool
dds_qget_userdata
(const dds_qos_t *qos, void **value, size_t *sz)¶ Get the userdata from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] value
: - Pointer that will store the userdata. If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0[inout] sz
: - Pointer that will store the size of userdata
-
bool
dds_qget_topicdata
(const dds_qos_t *qos, void **value, size_t *sz)¶ Get the topicdata from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] value
: - Pointer that will store the topicdata. If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0[inout] sz
: - Pointer that will store the size of topicdata
-
bool
dds_qget_groupdata
(const dds_qos_t *qos, void **value, size_t *sz)¶ Get the groupdata from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] value
: - Pointer that will store the groupdata. If sz = 0, then a null pointer, else it is a pointer to an allocated buffer of sz+1 bytes where the last byte is always 0[inout] sz
: - Pointer that will store the size of groupdata
-
bool
dds_qget_durability
(const dds_qos_t *qos, dds_durability_kind_t *kind)¶ Get the durability policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the durability kind
-
bool
dds_qget_history
(const dds_qos_t *qos, dds_history_kind_t *kind, int32_t *depth)¶ Get the history policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the history kind (optional)[inout] depth
: - Pointer that will store the history depth (optional)
-
bool
dds_qget_resource_limits
(const dds_qos_t *qos, int32_t *max_samples, int32_t *max_instances, int32_t *max_samples_per_instance)¶ Get the resource-limits policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] max_samples
: - Pointer that will store the number of samples resource-limit (optional)[inout] max_instances
: - Pointer that will store the number of instances resource-limit (optional)[inout] max_samples_per_instance
: - Pointer that will store the number of samples per instance resource-limit (optional)
-
bool
dds_qget_presentation
(const dds_qos_t *qos, dds_presentation_access_scope_kind_t *access_scope, bool *coherent_access, bool *ordered_access)¶ Get the presentation policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] access_scope
: - Pointer that will store access scope kind (optional)[inout] coherent_access
: - Pointer that will store coherent access enable value (optional)[inout] ordered_access
: - Pointer that will store orderede access enable value (optional)
-
bool
dds_qget_lifespan
(const dds_qos_t *qos, dds_duration_t *lifespan)¶ Get the lifespan policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] lifespan
: - Pointer that will store lifespan duration
-
bool
dds_qget_deadline
(const dds_qos_t *qos, dds_duration_t *deadline)¶ Get the deadline policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] deadline
: - Pointer that will store deadline duration
-
bool
dds_qget_latency_budget
(const dds_qos_t *qos, dds_duration_t *duration)¶ Get the latency-budget policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] duration
: - Pointer that will store latency-budget duration
-
bool
dds_qget_ownership
(const dds_qos_t *qos, dds_ownership_kind_t *kind)¶ Get the ownership policy from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the ownership kind
-
bool
dds_qget_ownership_strength
(const dds_qos_t *qos, int32_t *value)¶ Get the ownership strength qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] value
: - Pointer that will store the ownership strength value
-
bool
dds_qget_liveliness
(const dds_qos_t *qos, dds_liveliness_kind_t *kind, dds_duration_t *lease_duration)¶ Get the liveliness qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the liveliness kind (optional)[inout] lease_duration
: - Pointer that will store the liveliness lease duration (optional)
-
bool
dds_qget_time_based_filter
(const dds_qos_t *qos, dds_duration_t *minimum_separation)¶ Get the time-based filter qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] minimum_separation
: - Pointer that will store the minimum separation duration (optional)
-
bool
dds_qget_partition
(const dds_qos_t *qos, uint32_t *n, char ***ps)¶ Get the partition qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] n
: - Pointer that will store the number of partitions (optional)[inout] ps
: - Pointer that will store the string(s) containing partition name(s) (optional)
-
bool
dds_qget_reliability
(const dds_qos_t *qos, dds_reliability_kind_t *kind, dds_duration_t *max_blocking_time)¶ Get the reliability qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the reliability kind (optional)[inout] max_blocking_time
: - Pointer that will store the max blocking time for reliable reliability (optional)
-
bool
dds_qget_transport_priority
(const dds_qos_t *qos, int32_t *value)¶ Get the transport priority qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] value
: - Pointer that will store the transport priority value
-
bool
dds_qget_destination_order
(const dds_qos_t *qos, dds_destination_order_kind_t *kind)¶ Get the destination-order qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] kind
: - Pointer that will store the destination-order kind
-
bool
dds_qget_writer_data_lifecycle
(const dds_qos_t *qos, bool *autodispose)¶ Get the writer data-lifecycle qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] autodispose
: - Pointer that will store the autodispose unregistered instances enable value
-
bool
dds_qget_reader_data_lifecycle
(const dds_qos_t *qos, dds_duration_t *autopurge_nowriter_samples_delay, dds_duration_t *autopurge_disposed_samples_delay)¶ Get the reader data-lifecycle qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] autopurge_nowriter_samples_delay
: - Pointer that will store the delay for auto-purging samples from instances in a no-writer state (optional)[inout] autopurge_disposed_samples_delay
: - Pointer that will store the delay for auto-purging of disposed instances (optional)
-
bool
dds_qget_durability_service
(const dds_qos_t *qos, dds_duration_t *service_cleanup_delay, dds_history_kind_t *history_kind, int32_t *history_depth, int32_t *max_samples, int32_t *max_instances, int32_t *max_samples_per_instance)¶ Get the durability-service qos policy values.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] service_cleanup_delay
: - Pointer that will store the delay for purging of abandoned instances from the durability service (optional)[inout] history_kind
: - Pointer that will store history policy kind applied by the durability service (optional)[inout] history_depth
: - Pointer that will store history policy depth applied by the durability service (optional)[inout] max_samples
: - Pointer that will store number of samples resource-limit policy applied by the durability service (optional)[inout] max_instances
: - Pointer that will store number of instances resource-limit policy applied by the durability service (optional)[inout] max_samples_per_instance
: - Pointer that will store number of samples per instance resource-limit policy applied by the durability service (optional)
-
bool
dds_qget_ignorelocal
(const dds_qos_t *qos, dds_ignorelocal_kind_t *ignore)¶ Get the ignore-local qos policy.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[in] qos
: - Pointer to a dds_qos_t structure storing the policy[inout] ignore
: - Pointer that will store whether to ignore readers/writers owned by the same participant (optional)
-
bool
dds_qget_propnames
(const dds_qos_t *qos, uint32_t *n, char ***names)¶ Gets the names of the properties from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains properties[inout] n
: - Pointer to number of property names that are returned (optional)[inout] names
: - Pointer that will store the string(s) containing property name(s) (optional). This function will allocate the memory for the list of names and for the strings containing the names; the caller gets ownership of the allocated memory
-
bool
dds_qget_prop
(const dds_qos_t *qos, const char *name, char **value)¶ Get the value of the property with the provided name from a qos structure.
In case more than one property exists with this name, the value for the first property with this name will be returned.
- Return
- false iff any of the arguments is invalid, the qos is not present in the qos object or there was no property found with the provided name
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains the property[in] name
: - Pointer to name of the property[inout] value
: - Pointer to a string that will store the value of the property. The memory for storing the string value will be allocated by this function and the caller gets ownership of the allocated memory
-
bool
dds_qget_bpropnames
(const dds_qos_t *qos, uint32_t *n, char ***names)¶ Gets the names of the binary properties from a qos structure.
- Return
- false iff any of the arguments is invalid or the qos is not present in the qos object
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains binary properties[inout] n
: - Pointer to number of binary property names that are returned (optional)[inout] names
: - Pointer that will store the string(s) containing binary property name(s) (optional). This function will allocate the memory for the list of names and for the strings containing the names; the caller gets ownership of the allocated memory
-
bool
dds_qget_bprop
(const dds_qos_t *qos, const char *name, void **value, size_t *sz)¶ Get the value of the binary property with the provided name from a qos structure.
In case more than one binary property exists with this name, the value for the first binary property with this name will be returned.
- Return
- false iff any of the arguments is invalid, the qos is not present in the qos object or there was no binary property found with the provided name
- Parameters
[inout] qos
: - Pointer to a dds_qos_t structure that contains the property[in] name
: - Pointer to name of the binary property[inout] value
: - Pointer to a buffer that will store the value of the property. If sz = 0 then a NULL pointer. The memory for storing the value will be allocated by this function and the caller gets ownership of the allocated memory[inout] sz
: - Pointer that will store the size of the returned buffer.
-
-
file
dds_public_qosdefs.h
DDS C QoS API.
This header file defines the public API of QoS and Policies in the Eclipse Cyclone DDS C language binding.
Defines
-
DDS_LENGTH_UNLIMITED
¶
Typedefs
-
typedef enum dds_qos_policy_id
dds_qos_policy_id_t
¶ QoS identifiers
-
typedef struct dds_qos
dds_qos_t
¶ QoS structure
-
typedef enum dds_durability_kind
dds_durability_kind_t
¶ Durability QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_history_kind
dds_history_kind_t
¶ History QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_ownership_kind
dds_ownership_kind_t
¶ Ownership QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_liveliness_kind
dds_liveliness_kind_t
¶ Liveliness QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_reliability_kind
dds_reliability_kind_t
¶ Reliability QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_destination_order_kind
dds_destination_order_kind_t
¶ DestinationOrder QoS: Applies to Topic, DataReader, DataWriter
-
typedef enum dds_presentation_access_scope_kind
dds_presentation_access_scope_kind_t
¶ Presentation QoS: Applies to Publisher, Subscriber
-
typedef enum dds_ignorelocal_kind
dds_ignorelocal_kind_t
¶ Ignore-local QoS: Applies to DataReader, DataWriter
Enums
-
enum
dds_qos_policy_id
¶ QoS identifiers
Values:
-
enumerator
DDS_INVALID_QOS_POLICY_ID
¶
-
enumerator
DDS_USERDATA_QOS_POLICY_ID
¶
-
enumerator
DDS_DURABILITY_QOS_POLICY_ID
¶
-
enumerator
DDS_PRESENTATION_QOS_POLICY_ID
¶
-
enumerator
DDS_DEADLINE_QOS_POLICY_ID
¶
-
enumerator
DDS_LATENCYBUDGET_QOS_POLICY_ID
¶
-
enumerator
DDS_OWNERSHIP_QOS_POLICY_ID
¶
-
enumerator
DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID
¶
-
enumerator
DDS_LIVELINESS_QOS_POLICY_ID
¶
-
enumerator
DDS_TIMEBASEDFILTER_QOS_POLICY_ID
¶
-
enumerator
DDS_PARTITION_QOS_POLICY_ID
¶
-
enumerator
DDS_RELIABILITY_QOS_POLICY_ID
¶
-
enumerator
DDS_DESTINATIONORDER_QOS_POLICY_ID
¶
-
enumerator
DDS_HISTORY_QOS_POLICY_ID
¶
-
enumerator
DDS_RESOURCELIMITS_QOS_POLICY_ID
¶
-
enumerator
DDS_ENTITYFACTORY_QOS_POLICY_ID
¶
-
enumerator
DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID
¶
-
enumerator
DDS_READERDATALIFECYCLE_QOS_POLICY_ID
¶
-
enumerator
DDS_TOPICDATA_QOS_POLICY_ID
¶
-
enumerator
DDS_GROUPDATA_QOS_POLICY_ID
¶
-
enumerator
DDS_TRANSPORTPRIORITY_QOS_POLICY_ID
¶
-
enumerator
DDS_LIFESPAN_QOS_POLICY_ID
¶
-
enumerator
DDS_DURABILITYSERVICE_QOS_POLICY_ID
¶
-
enumerator
DDS_PROPERTY_QOS_POLICY_ID
¶
-
enumerator
-
enum
dds_durability_kind
¶ Durability QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_DURABILITY_VOLATILE
¶
-
enumerator
DDS_DURABILITY_TRANSIENT_LOCAL
¶
-
enumerator
DDS_DURABILITY_TRANSIENT
¶
-
enumerator
DDS_DURABILITY_PERSISTENT
¶
-
enumerator
-
enum
dds_history_kind
¶ History QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_HISTORY_KEEP_LAST
¶
-
enumerator
DDS_HISTORY_KEEP_ALL
¶
-
enumerator
-
enum
dds_ownership_kind
¶ Ownership QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_OWNERSHIP_SHARED
¶
-
enumerator
DDS_OWNERSHIP_EXCLUSIVE
¶
-
enumerator
-
enum
dds_liveliness_kind
¶ Liveliness QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_LIVELINESS_AUTOMATIC
¶
-
enumerator
DDS_LIVELINESS_MANUAL_BY_PARTICIPANT
¶
-
enumerator
DDS_LIVELINESS_MANUAL_BY_TOPIC
¶
-
enumerator
-
enum
dds_reliability_kind
¶ Reliability QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_RELIABILITY_BEST_EFFORT
¶
-
enumerator
DDS_RELIABILITY_RELIABLE
¶
-
enumerator
-
enum
dds_destination_order_kind
¶ DestinationOrder QoS: Applies to Topic, DataReader, DataWriter
Values:
-
enumerator
DDS_DESTINATIONORDER_BY_RECEPTION_TIMESTAMP
¶
-
enumerator
DDS_DESTINATIONORDER_BY_SOURCE_TIMESTAMP
¶
-
enumerator
-
-
file
dds_public_status.h
- #include “dds/export.h”
DDS C Communication Status API.
This header file defines the public API of the Communication Status in the Eclipse Cyclone DDS C language binding.
Typedefs
-
typedef struct dds_offered_deadline_missed_status
dds_offered_deadline_missed_status_t
¶ DCPS_Status_OfferedDeadlineMissed
-
typedef struct dds_offered_incompatible_qos_status
dds_offered_incompatible_qos_status_t
¶ DCPS_Status_OfferedIncompatibleQoS
-
typedef struct dds_publication_matched_status
dds_publication_matched_status_t
¶ DCPS_Status_PublicationMatched
-
typedef struct dds_liveliness_lost_status
dds_liveliness_lost_status_t
¶ DCPS_Status_LivelinessLost
-
typedef struct dds_subscription_matched_status
dds_subscription_matched_status_t
¶ DCPS_Status_SubscriptionMatched
-
typedef struct dds_sample_rejected_status
dds_sample_rejected_status_t
¶ DCPS_Status_SampleRejected
-
typedef struct dds_liveliness_changed_status
dds_liveliness_changed_status_t
¶ DCPS_Status_LivelinessChanged
-
typedef struct dds_requested_deadline_missed_status
dds_requested_deadline_missed_status_t
¶ DCPS_Status_RequestedDeadlineMissed
-
typedef struct dds_requested_incompatible_qos_status
dds_requested_incompatible_qos_status_t
¶ DCPS_Status_RequestedIncompatibleQoS
-
typedef struct dds_sample_lost_status
dds_sample_lost_status_t
¶ DCPS_Status_SampleLost
-
typedef struct dds_inconsistent_topic_status
dds_inconsistent_topic_status_t
¶ DCPS_Status_InconsistentTopic
Enums
Functions
-
dds_return_t
dds_get_inconsistent_topic_status
(dds_entity_t topic, dds_inconsistent_topic_status_t *status)¶ Get INCONSISTENT_TOPIC status.
This operation gets the status value corresponding to INCONSISTENT_TOPIC and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] topic
: The entity to get the status[out] status
: The pointer to DCPS_Status_InconsistentTopic to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_publication_matched_status
(dds_entity_t writer, dds_publication_matched_status_t *status)¶ Get PUBLICATION_MATCHED status.
This operation gets the status value corresponding to PUBLICATION_MATCHED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] writer
: The entity to get the status[out] status
: The pointer to DCPS_Status_PublicationMatched to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_liveliness_lost_status
(dds_entity_t writer, dds_liveliness_lost_status_t *status)¶ Get LIVELINESS_LOST status.
This operation gets the status value corresponding to LIVELINESS_LOST and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] writer
: The entity to get the status[out] status
: The pointer to DCPS_Status_LivelinessLost to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_offered_deadline_missed_status
(dds_entity_t writer, dds_offered_deadline_missed_status_t *status)¶ Get OFFERED_DEADLINE_MISSED status.
This operation gets the status value corresponding to OFFERED_DEADLINE_MISSED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] writer
: The entity to get the status[out] status
: The pointer to DCPS_Status_OfferedDeadlineMissed to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_offered_incompatible_qos_status
(dds_entity_t writer, dds_offered_incompatible_qos_status_t *status)¶ Get OFFERED_INCOMPATIBLE_QOS status.
This operation gets the status value corresponding to OFFERED_INCOMPATIBLE_QOS and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] writer
: The writer entity to get the status[out] status
: The pointer to DCPS_Status_OfferedIncompatibleQoS to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_subscription_matched_status
(dds_entity_t reader, dds_subscription_matched_status_t *status)¶ Get SUBSCRIPTION_MATCHED status.
This operation gets the status value corresponding to SUBSCRIPTION_MATCHED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] reader
: The reader entity to get the status[out] status
: The pointer to DCPS_Status_SubscriptionMatched to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_liveliness_changed_status
(dds_entity_t reader, dds_liveliness_changed_status_t *status)¶ Get LIVELINESS_CHANGED status.
This operation gets the status value corresponding to LIVELINESS_CHANGED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] reader
: The entity to get the status[out] status
: The pointer to DCPS_Status_LivelinessChanged to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_sample_rejected_status
(dds_entity_t reader, dds_sample_rejected_status_t *status)¶ Get SAMPLE_REJECTED status.
This operation gets the status value corresponding to SAMPLE_REJECTED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
0 - Success
- Return
<0 - Failure
- Parameters
[in] reader
: The entity to get the status[out] status
: The pointer to DCPS_Status_SampleRejected to get the status
- Return Value
DDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_sample_lost_status
(dds_entity_t reader, dds_sample_lost_status_t *status)¶ Get SAMPLE_LOST status.
This operation gets the status value corresponding to SAMPLE_LOST and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
A dds_return_t indicating success or failure
- Parameters
[in] reader
: The entity to get the status[out] status
: The pointer to DCPS_Status_SampleLost to get the status
- Return Value
DDS_RETCODE_OK
: SuccessDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_requested_deadline_missed_status
(dds_entity_t reader, dds_requested_deadline_missed_status_t *status)¶ Get REQUESTED_DEADLINE_MISSED status.
This operation gets the status value corresponding to REQUESTED_DEADLINE_MISSED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
A dds_return_t indicating success or failure
- Parameters
[in] reader
: The entity to get the status[out] status
: The pointer to DCPS_Status_RequestedDeadlineMissed to get the status
- Return Value
DDS_RETCODE_OK
: SuccessDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
dds_return_t
dds_get_requested_incompatible_qos_status
(dds_entity_t reader, dds_requested_incompatible_qos_status_t *status)¶ Get REQUESTED_INCOMPATIBLE_QOS status.
This operation gets the status value corresponding to REQUESTED_INCOMPATIBLE_QOS and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.
- Return
A dds_return_t indicating success or failure
- Parameters
[in] reader
: The entity to get the status[out] status
: The pointer to DCPS_Status_RequestedIncompatibleQoS to get the status
- Return Value
DDS_RETCODE_OK
: SuccessDDS_RETCODE_ERROR
: An internal error has occurred.DDS_RETCODE_BAD_PARAMETER
: One of the given arguments is not valid.DDS_RETCODE_ILLEGAL_OPERATION
: The operation is invoked on an inappropriate object.DDS_RETCODE_ALREADY_DELETED
: The entity has already been deleted.
-
typedef struct dds_offered_deadline_missed_status
-
file
dds_rhc.h
- #include “dds/ddsrt/static_assert.h”#include “dds/ddsi/ddsi_rhc.h”
Defines
-
NO_STATE_MASK_SET
¶
Typedefs
-
typedef dds_return_t (*
dds_rhc_associate_t
)(struct dds_rhc *rhc, struct dds_reader *reader, const struct ddsi_sertopic *topic, struct ddsi_tkmap *tkmap)¶
-
typedef int32_t (*
dds_rhc_read_take_t
)(struct dds_rhc *rhc, bool lock, void **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t mask, dds_instance_handle_t handle, struct dds_readcond *cond)¶
-
typedef int32_t (*
dds_rhc_read_take_cdr_t
)(struct dds_rhc *rhc, bool lock, struct ddsi_serdata **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t sample_states, uint32_t view_states, uint32_t instance_states, dds_instance_handle_t handle)¶
Functions
-
dds_return_t
dds_rhc_associate
(struct dds_rhc *rhc, struct dds_reader *reader, const struct ddsi_sertopic *topic, struct ddsi_tkmap *tkmap)¶
-
bool
dds_rhc_store
(struct dds_rhc *rhc, const struct ddsi_writer_info *wrinfo, struct ddsi_serdata *sample, struct ddsi_tkmap_instance *tk)¶
-
int32_t
dds_rhc_read
(struct dds_rhc *rhc, bool lock, void **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t mask, dds_instance_handle_t handle, struct dds_readcond *cond)¶
-
int32_t
dds_rhc_take
(struct dds_rhc *rhc, bool lock, void **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t mask, dds_instance_handle_t handle, struct dds_readcond *cond)¶
-
int32_t
dds_rhc_readcdr
(struct dds_rhc *rhc, bool lock, struct ddsi_serdata **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t sample_states, uint32_t view_states, uint32_t instance_states, dds_instance_handle_t handle)¶
-
int32_t
dds_rhc_takecdr
(struct dds_rhc *rhc, bool lock, struct ddsi_serdata **values, dds_sample_info_t *info_seq, uint32_t max_samples, uint32_t sample_states, uint32_t view_states, uint32_t instance_states, dds_instance_handle_t handle)¶
-
void
dds_reader_data_available_cb
(struct dds_reader *rd)¶
-
-
file
dds_statistics.h
- #include “dds/dds.h”#include “dds/ddsrt/attributes.h”#include “dds/export.h”
Enums
Functions
-
struct dds_statistics *
dds_create_statistics
(dds_entity_t entity)¶ Allocate a new statistics object for entity.
This allocates and populates a newly allocated
struct dds_statistics
for the specified entity.- Return
a newly allocated and populated statistics structure or NULL if entity is invalid or doesn’t support any statistics.
- Parameters
[in] entity
: the handle of the entity
-
dds_return_t
dds_refresh_statistics
(struct dds_statistics *stat)¶ Update a previously created statistics structure with current values.
Only the time stamp and the values (and “opaque”) may change. The set of keys and the types of the values do not change.
- Return
success or an error indication
- Parameters
[inout] stat
: statistics structure to update the values of
- Return Value
DDS_RETCODE_OK
: the data was successfully updatedDDS_RETCODE_BAD_PARAMETER
: stats is a null pointer or the referenced entity no longer existsDDS_RETCODE_PRECONDITION_NOT_MET
: library was deinitialized
-
void
dds_delete_statistics
(struct dds_statistics *stat)¶ Free a previously created statistics object.
This frees the statistics object. Passing a null pointer is a no-op. The operation succeeds also if the referenced entity no longer exists.
- Parameters
[in] stat
: statistics object to free
-
const struct dds_stat_keyvalue * dds_lookup_statistic (const struct dds_statistics *stat, const char *name) ddsrt_nonnull((2))
Lookup a specific value by name.
This looks up the specified name in the list of keys in
stat
and returns the address of the key-value pair if present, a null pointer if not. Ifstat
is a null pointer, it returns a null pointer.- Return
The address of the key-value pair inside
stat
, or NULL ifstat
is NULL orname
does not match a key in `stat.- Parameters
[in] stat
: statistics object to lookup a name in (or NULL)[in] name
: name to look for
-
struct dds_statistics *
-
dir
ddsc/include/dds
-
dir
ddsc
-
dir
ddsc/include/ddsc
-
dir
ddsc/include/dds/ddsc
-
dir
ddsc/include