Eclipse Cyclone DDS C API Reference

struct dds_allocator

Public Members

void *(*malloc)(size_t size)
void *(*realloc)(void *ptr, size_t size)
void (*free)(void *ptr)
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_qos_t *qos
struct dds_builtintopic_guid

Public Members

uint8_t v[16]
struct dds_builtintopic_participant

Public Members

dds_guid_t key
dds_qos_t *qos
struct dds_inconsistent_topic_status
#include <dds_public_status.h>

DCPS_Status_InconsistentTopic

Public Members

uint32_t total_count
int32_t total_count_change
struct dds_key_descriptor

Public Members

const char *m_name
uint32_t m_index
struct dds_liveliness_changed_status
#include <dds_public_status.h>

DCPS_Status_LivelinessChanged

Public Members

uint32_t alive_count
uint32_t not_alive_count
int32_t alive_count_change
int32_t not_alive_count_change
dds_instance_handle_t last_publication_handle
struct dds_liveliness_lost_status
#include <dds_public_status.h>

DCPS_Status_LivelinessLost

Public Members

uint32_t total_count
int32_t total_count_change
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
struct dds_offered_incompatible_qos_status
#include <dds_public_status.h>

DCPS_Status_OfferedIncompatibleQoS

Public Members

uint32_t total_count
int32_t total_count_change
uint32_t last_policy_id
struct dds_publication_matched_status
#include <dds_public_status.h>

DCPS_Status_PublicationMatched

Public Members

uint32_t total_count
int32_t total_count_change
uint32_t current_count
int32_t current_count_change
dds_instance_handle_t last_subscription_handle
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
struct dds_requested_incompatible_qos_status
#include <dds_public_status.h>

DCPS_Status_RequestedIncompatibleQoS

Public Members

uint32_t total_count
int32_t total_count_change
uint32_t last_policy_id
struct dds_rhc

Public Members

const struct dds_rhc_ops *ops
struct ddsi_rhc rhc
union dds_rhc::[anonymous] common
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 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

struct dds_sample_lost_status
#include <dds_public_status.h>

DCPS_Status_SampleLost

Public Members

uint32_t total_count
int32_t total_count_change
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
struct dds_sequence

Public Members

uint32_t _maximum
uint32_t _length
uint8_t *_buffer
bool _release
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
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

struct dds_subscription_matched_status
#include <dds_public_status.h>

DCPS_Status_SubscriptionMatched

Public Members

uint32_t total_count
int32_t total_count_change
uint32_t current_count
int32_t current_count_change
dds_instance_handle_t last_publication_handle
struct dds_topic_descriptor

Public Members

const uint32_t m_size
const uint32_t m_align
const uint32_t m_flagset
const uint32_t m_nkeys
const char *m_typename
const dds_key_descriptor_t *m_keys
const uint32_t m_nops
const uint32_t *m_ops
const char *m_meta
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
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

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

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

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 successfully

  • DDS_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 successfully

  • DDS_RETCODE_PRECONDITION_NOT_MET: Filter was set with dds_set_topic_filter

  • DDS_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 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_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 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 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 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_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 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_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 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_set_guardcondition(dds_entity_t guardcond, bool triggered)

Sets the trigger status of a guardcondition.

Return Value
  • DDS_RETCODE_OK: Operation successful

  • 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_read_guardcondition(dds_entity_t guardcond, bool *triggered)

Reads the trigger status of a guardcondition.

Return Value
  • DDS_RETCODE_OK: Operation successful

  • 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_take_guardcondition(dds_entity_t guardcond, bool *triggered)

Reads and resets the trigger status of a guardcondition.

Return Value
  • DDS_RETCODE_OK: Operation successful

  • 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_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 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_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 data

  • NULL: 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 data

  • NULL: 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.

Defines

DDS_FREE_KEY_BIT
DDS_FREE_CONTENTS_BIT
DDS_FREE_ALL_BIT

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

enum dds_free_op_t

Values:

enumerator DDS_FREE_ALL
enumerator DDS_FREE_CONTENTS
enumerator DDS_FREE_KEY

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)
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.

Defines

DDS_ERR_NR_MASK
DDS_ERR_LINE_MASK
DDS_ERR_FILE_ID_MASK
dds_err_nr(e)

Macro to extract error number

dds_err_line(e)

Macro to extract line number

dds_err_file_id(e)

Macro to extract file identifier

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
enum dds_stream_opcode

Values:

enumerator DDS_OP_RTS
enumerator DDS_OP_ADR
enumerator DDS_OP_JSR
enumerator DDS_OP_JEQ
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
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
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

Functions

void dds_write_set_batch(bool enable)

Description : Enable or disable write batching. Overrides default configuration setting for write batching (Internal/WriteBatch).

Arguments :

  1. 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 from src.

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 set

  • callback: 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.

dds_qos_t *dds_qos_create(void)
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_qos_delete(dds_qos_t *qos)
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

void dds_qos_reset(dds_qos_t *qos)
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

dds_return_t dds_qos_copy(dds_qos_t *dst, const dds_qos_t *src)
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

void dds_qos_merge(dds_qos_t *dst, const dds_qos_t *src)
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
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
enum dds_history_kind

History QoS: Applies to Topic, DataReader, DataWriter

Values:

enumerator DDS_HISTORY_KEEP_LAST
enumerator DDS_HISTORY_KEEP_ALL
enum dds_ownership_kind

Ownership QoS: Applies to Topic, DataReader, DataWriter

Values:

enumerator DDS_OWNERSHIP_SHARED
enumerator DDS_OWNERSHIP_EXCLUSIVE
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
enum dds_reliability_kind

Reliability QoS: Applies to Topic, DataReader, DataWriter

Values:

enumerator DDS_RELIABILITY_BEST_EFFORT
enumerator DDS_RELIABILITY_RELIABLE
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
enum dds_presentation_access_scope_kind

Presentation QoS: Applies to Publisher, Subscriber

Values:

enumerator DDS_PRESENTATION_INSTANCE
enumerator DDS_PRESENTATION_TOPIC
enumerator DDS_PRESENTATION_GROUP
enum dds_ignorelocal_kind

Ignore-local QoS: Applies to DataReader, DataWriter

Values:

enumerator DDS_IGNORELOCAL_NONE
enumerator DDS_IGNORELOCAL_PARTICIPANT
enumerator DDS_IGNORELOCAL_PROCESS
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

enum dds_sample_rejected_status_kind

dds_sample_rejected_status_kind

Values:

enumerator DDS_NOT_REJECTED
enumerator DDS_REJECTED_BY_INSTANCES_LIMIT
enumerator DDS_REJECTED_BY_SAMPLES_LIMIT
enumerator DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT

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: Success

  • 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_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: Success

  • 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_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: Success

  • 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.

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)
typedef bool (*dds_rhc_add_readcondition_t)(struct dds_rhc *rhc, struct dds_readcond *cond)
typedef void (*dds_rhc_remove_readcondition_t)(struct dds_rhc *rhc, struct dds_readcond *cond)
typedef uint32_t (*dds_rhc_lock_samples_t)(struct dds_rhc *rhc)

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)
void dds_rhc_unregister_wr(struct dds_rhc *rhc, const struct ddsi_writer_info *wrinfo)
void dds_rhc_relinquish_ownership(struct dds_rhc *rhc, const uint64_t wr_iid)
void dds_rhc_set_qos(struct dds_rhc *rhc, const struct dds_qos *qos)
void dds_rhc_free(struct dds_rhc *rhc)
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)
bool dds_rhc_add_readcondition(struct dds_rhc *rhc, struct dds_readcond *cond)
void dds_rhc_remove_readcondition(struct dds_rhc *rhc, struct dds_readcond *cond)
uint32_t dds_rhc_lock_samples(struct dds_rhc *rhc)
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

enum dds_stat_kind

Values:

enumerator DDS_STAT_KIND_UINT32

value is a 32-bit unsigned integer

enumerator DDS_STAT_KIND_UINT64

value is a 64-bit unsigned integer

enumerator DDS_STAT_KIND_LENGTHTIME

value is integral(length(t) dt)

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 updated

  • DDS_RETCODE_BAD_PARAMETER: stats is a null pointer or the referenced entity no longer exists

  • DDS_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. If stat is a null pointer, it returns a null pointer.

Return

The address of the key-value pair inside stat, or NULL if stat is NULL or name 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

dir ddsc/include/dds
dir ddsc
dir ddsc/include/ddsc
dir ddsc/include/dds/ddsc
dir ddsc/include