Internal functionality

All functionality in this section is considered internal. You should not build applications using these methods, since any function signature or datatype may change or be removed without warning.

group internal

Defines

DDS_MIN_PSEUDO_HANDLE ((dds_entity_t)0x7fff0000)

Pseudo Handle origin.

Some handles in CycloneDDS are ‘fake’, most importantly the builtin topic handles. These handles are derived from this constant.

DDS_CYCLONEDDS_HANDLE ((dds_entity_t)(DDS_MIN_PSEUDO_HANDLE + 256))

Special handle representing the entity corresponding to the CycloneDDS library itself.

DDS_KIND_MAX DDS_KIND_CYCLONEDDS

Max entity kind, used for loops.

DDS_LUNSET 0

Default initial value (nullptr) for listener functions.

Typedefs

typedef enum dds_entity_kind dds_entity_kind_t

DDS Entity Kind constants.

Warning

Unstable/Private API Used throughout the library to indicate what entity is what.

typedef uint64_t dds_instance_handle_t

Instance handles are uint64_t behind the scenes.

Warning

Private API

typedef enum dds_qos_policy_id dds_qos_policy_id_t

Qos Policy IDs

Used internally to mark the QoS policy type.

Enums

enum dds_entity_kind

DDS Entity Kind constants.

Warning

Unstable/Private API Used throughout the library to indicate what entity is what.

Values:

enumerator DDS_KIND_DONTCARE

Retrieving any entity

enumerator DDS_KIND_TOPIC

Topic entity

enumerator DDS_KIND_PARTICIPANT

Domain Participant entity

enumerator DDS_KIND_READER

Reader entity

enumerator DDS_KIND_WRITER

Writer entity

enumerator DDS_KIND_SUBSCRIBER

Subscriber entity

enumerator DDS_KIND_PUBLISHER

Publisher entity

enumerator DDS_KIND_COND_READ

ReadCondition entity

enumerator DDS_KIND_COND_QUERY

QueryCondition entity

enumerator DDS_KIND_COND_GUARD

GuardCondition entity

enumerator DDS_KIND_WAITSET

WaitSet entity

enumerator DDS_KIND_DOMAIN

Domain entity

enumerator DDS_KIND_CYCLONEDDS

CycloneDDS library entity

enum dds_qos_policy_id

Qos Policy IDs

Used internally to mark the QoS policy type.

Values:

enumerator DDS_INVALID_QOS_POLICY_ID

Invalid Policy

enumerator DDS_USERDATA_QOS_POLICY_ID

Userdata policy dds_qset_userdata()

enumerator DDS_DURABILITY_QOS_POLICY_ID

Durability policy dds_qset_durability()

enumerator DDS_PRESENTATION_QOS_POLICY_ID

Presentation policy dds_qset_presentation()

enumerator DDS_DEADLINE_QOS_POLICY_ID

Deadline policy dds_qset_deadline()

enumerator DDS_LATENCYBUDGET_QOS_POLICY_ID

LatencyBudget policy dds_qset_latency_budget()

enumerator DDS_OWNERSHIP_QOS_POLICY_ID

Ownership policy dds_qset_ownership()

enumerator DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID

OwnershipStrength policy dds_qset_ownership_strength()

enumerator DDS_LIVELINESS_QOS_POLICY_ID

Liveliness policy dds_qset_liveliness()

enumerator DDS_TIMEBASEDFILTER_QOS_POLICY_ID

TimeBasedFilter policy dds_qset_time_based_filter()

enumerator DDS_PARTITION_QOS_POLICY_ID

Partition policy dds_qset_partition()

enumerator DDS_RELIABILITY_QOS_POLICY_ID

Reliability policy dds_qset_reliability()

enumerator DDS_DESTINATIONORDER_QOS_POLICY_ID

DestinationOrder policy dds_qset_destination_order()

enumerator DDS_HISTORY_QOS_POLICY_ID

History policy dds_qset_history()

enumerator DDS_RESOURCELIMITS_QOS_POLICY_ID

ResourceLimits policy dds_qset_resource_limits()

enumerator DDS_ENTITYFACTORY_QOS_POLICY_ID

EntityFactory policy

enumerator DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID

WriterDataLifecycle policy dds_qset_writer_data_lifecycle()

enumerator DDS_READERDATALIFECYCLE_QOS_POLICY_ID

ReaderDataLifecycle policy dds_qset_reader_data_lifecycle()

enumerator DDS_TOPICDATA_QOS_POLICY_ID

Topicdata policy dds_qset_topicdata()

enumerator DDS_GROUPDATA_QOS_POLICY_ID

Groupdata policy dds_qset_groupdata()

enumerator DDS_TRANSPORTPRIORITY_QOS_POLICY_ID

TransportPriority policy dds_qset_transport_priority()

enumerator DDS_LIFESPAN_QOS_POLICY_ID

Livespan policy dds_qset_lifespan()

enumerator DDS_DURABILITYSERVICE_QOS_POLICY_ID

DurabilityService policy dds_qset_durability_service()

enumerator DDS_PROPERTY_QOS_POLICY_ID

Property policy dds_qset_property()

enumerator DDS_TYPE_CONSISTENCY_ENFORCEMENT_QOS_POLICY_ID

TypeConsistencyEnforcement policy dds_qset_type_consistency_enforcements()

enumerator DDS_DATA_REPRESENTATION_QOS_POLICY_ID

DataRepresentation policy dds_qset_data_representation()

Functions

void dds_cdrstream_desc_from_topic_desc(struct dds_cdrstream_desc *desc, const dds_topic_descriptor_t *topic_desc)

Gets a CDR stream serializer type descriptor from a topic descriptor.

Parameters
  • desc[out] Pointer to the target struct that can be filled with the CDR stream topic descriptor

  • topic_desc[in] The source topic descriptor

dds_entity_t dds_create_participant_guid(const dds_domainid_t domain, const dds_qos_t *qos, const dds_listener_t *listener, uint32_t flags, const dds_guid_t *guid)

Create a participant with the specified GUID.

See also

dds_create_participant for details

Parameters
  • domain[in] The domain in which to create the participant (can be DDS_DOMAIN_DEFAULT). DDS_DOMAIN_DEFAULT is for using the domain in the configuration.

  • qos[in] The QoS to set on the new participant (can be NULL).

  • listener[in] Any listener functions associated with the new participant (can be NULL).

  • flags[in] The flags to be used when creating the participant

  • guid[in] The GUID for the new participant

Returns

A valid participant handle or an error code.

dds_entity_t dds_create_writer_guid(dds_entity_t participant_or_publisher, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener, dds_guid_t *guid)

Create a writer with the specified GUID.

See also

dds_create_writer for details

Parameters
  • participant_or_publisher[in] The participant or publisher on which the writer is being created.

  • topic[in] The topic to write.

  • qos[in] The QoS to set on the new writer (can be NULL).

  • listener[in] Any listener functions associated with the new writer (can be NULL).

  • guid[in] The GUID for the new writer

Returns

A valid writer handle or an error code.

dds_entity_t dds_create_reader_guid(dds_entity_t participant_or_subscriber, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener, dds_guid_t *guid)

Create a reader with the specified GUID.

See also

dds_create_reader for details

Parameters
  • participant_or_subscriber[in] The participant or subscriber on which the reader is being created.

  • topic[in] The topic to read.

  • qos[in] The QoS to set on the new reader (can be NULL).

  • listener[in] Any listener functions associated with the new reader (can be NULL).

  • guid[in] The GUID for the new reader

Returns

A valid reader handle or an error code.

Testing

group testing

Functions

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.

This is a support function for testing and, other special uses and is subject to change.

Warning

Unstable API, for testing

Parameters
  • entity[in] A domain entity or an entity bound to a domain, such as a participant, reader or writer.

  • deaf[in] Whether to network stack should pretend to be deaf and ignore any incoming packets.

  • mute[in] 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.

  • reset_after[in] 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 values
  • 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.

Returns

A dds_return_t indicating success or failure.

Implementation

group implementation

Miscellaneous types and functions that are required to be public, since they are in the output of the IDL compiler, but are not intended for direct use.

Typedefs

typedef struct dds_sequence dds_sequence_t

Datastructure of a Sequence type Container for a sequence of bytes. The general model of this type is also used in IDL output, where the uint8_t * _buffer is replaced by the appropriate subtype of what is contained.

typedef struct dds_key_descriptor dds_key_descriptor_t

Key Descriptor Used to describe a named key field in a type with the offset from the start of a struct.

struct dds_sequence
#include <dds_public_impl.h>

Datastructure of a Sequence type Container for a sequence of bytes. The general model of this type is also used in IDL output, where the uint8_t * _buffer is replaced by the appropriate subtype of what is contained.

Public Members

uint32_t _maximum

Allocated space in _buffer

uint32_t _length

Used space in _buffer

uint8_t *_buffer

Sequence of bytes

bool _release

Whether a CycloneDDS _free method should free the contained buffer. if you put in your own allocated _buffer set this to false to avoid CycloneDDS calling free() on it.

struct dds_key_descriptor
#include <dds_public_impl.h>

Key Descriptor Used to describe a named key field in a type with the offset from the start of a struct.

Public Members

const char *m_name

name of keyfield

uint32_t m_offset

offset from pointer

uint32_t m_idx

m_idx’th key of type

Topic definition

group topic_definition

Topic definitions are output by the IDL compiler and have an implementation-private definition. The only thing exposed on the API is a pointer to the “dds_topic_descriptor_t” struct type.

Defines

DDS_DATA_REPRESENTATION_XCDR1 0

Data representation XCDR1 Type can be represented using XCDR1.

DDS_DATA_REPRESENTATION_XML 1

Data representation XML Type can be represented using XML.

DDS_DATA_REPRESENTATION_XCDR2 2

Data representation XCDR2 Type can be represented using XCDR2.

DDS_DATA_REPRESENTATION_FLAG_XCDR1 (1u << DDS_DATA_REPRESENTATION_XCDR1)

Data representation XCDR1 flag Type can be represented using XCDR1, preshifted.

DDS_DATA_REPRESENTATION_FLAG_XML (1u << DDS_DATA_REPRESENTATION_XML)

Data representation XML flag Type can be represented using XML, preshifted.

DDS_DATA_REPRESENTATION_FLAG_XCDR2 (1u << DDS_DATA_REPRESENTATION_XCDR2)

Data representation XCDR2 flag Type can be represented using XCDR2, preshifted.

DDS_DATA_REPRESENTATION_RESTRICT_DEFAULT (DDS_DATA_REPRESENTATION_FLAG_XCDR1 | DDS_DATA_REPRESENTATION_FLAG_XCDR2)

Default datarepresentation flag, XCDR1 and XCDR2 flags.

Typedefs

typedef struct dds_topic_descriptor dds_topic_descriptor_t

Topic Descriptor.

Warning

Unstable/Private API Contains all meta information about a type, usually produced by the IDL compiler Since this type is not intended for public consumption it can change without warning.

struct dds_type_meta_ser
#include <dds_public_impl.h>

Simple sized byte container to hold serialized type info Holds XTypes information (TypeInformation, TypeMapping) for a type.

Public Members

const unsigned char *data

data pointer

uint32_t sz

data size

struct dds_topic_descriptor
#include <dds_public_impl.h>

Topic Descriptor.

Warning

Unstable/Private API Contains all meta information about a type, usually produced by the IDL compiler Since this type is not intended for public consumption it can change without warning.

Public Members

const uint32_t m_size

Size of topic type

const uint32_t m_align

Alignment of topic type

const uint32_t m_flagset

Flags

const uint32_t m_nkeys

Number of keys (can be 0)

const char *m_typename

Type name

const dds_key_descriptor_t *m_keys

Key descriptors (NULL iff m_nkeys 0)

const uint32_t m_nops

Number of ops in m_ops

const uint32_t *m_ops

Marshalling meta data

const char *m_meta

XML topic description meta data

struct dds_type_meta_ser type_information

XCDR2 serialized TypeInformation, only present if flag DDS_TOPIC_XTYPES_METADATA is set

struct dds_type_meta_ser type_mapping

XCDR2 serialized TypeMapping: maps type-id to type object and minimal to complete type id, only present if flag DDS_TOPIC_XTYPES_METADATA is set

const uint32_t restrict_data_representation

restrictions on the data representations allowed for the top-level type for this topic, only present if flag DDS_TOPIC_RESTRICT_DATA_REPRESENTATION

Convenience log category definitions

group log_categories

These defines expand into numeric values that can be ORed together to specify messages of which categories must be passed to the respective sinks.

Every category other than DDS_LC_FATAL, DDS_LC_ERROR, DDS_LC_WARNING and DDS_LC_INFO automatically falls into the trace category.

Defines

DDS_LC_FATAL (1u)

Fatal error condition. Immediate abort on sink return.

DDS_LC_ERROR (2u)

Error condition.

DDS_LC_WARNING (4u)

Warning condition.

DDS_LC_INFO (8u)

Informational message.

DDS_LC_CONFIG (16u)

Debug/trace messages related to configuration settings.

DDS_LC_DISCOVERY (32u)

Debug/trace messages related to node discovery.

DDS_LC_DATA (64u)

Currently unused.

DDS_LC_TRACE (128u)

Debug/trace messages for which no specialized category exists (yet).

DDS_LC_RADMIN (256u)

Debug/trace messages related to receive administration.

DDS_LC_TIMING (512u)

Debug/trace messages related to timing.

DDS_LC_TRAFFIC (1024u)

Debug/trace messages related to send administration.

DDS_LC_TOPIC (2048u)

Currently unused.

DDS_LC_TCP (4096u)

Debug/trace messages related to TCP communication.

DDS_LC_PLIST (8192u)

Debug/trace messages related to parameter list processing.

DDS_LC_WHC (16384u)

Debug/trace messages related to the writer history cache.

DDS_LC_THROTTLE (32768u)

Debug/trace messages related to throttling.

DDS_LC_RHC (65536u)

Reader history cache.

DDS_LC_CONTENT (131072u)

Include content in traces.

DDS_LC_MALFORMED (262144u)

Output full dump of malformed messages as warnings

DDS_LC_SYSDEF (524288u)

Debug/trace messages related to sysdef parser.

DDS_LC_QOSPROV (1048576u)

Debug/trace messages related to qos provider.

DDS_LC_USER1 (1u << 29)

Reserved for user defined log categories (e.g. user application that uses Cyclone logger)

DDS_LC_USER2 (1u << 30)
DDS_LC_USER3 (1u << 31)
DDS_LC_USER (DDS_LC_USER1 | DDS_LC_USER2 | DDS_LC_USER3)
DDS_LC_ALL     (DDS_LC_FATAL | DDS_LC_ERROR | DDS_LC_WARNING | DDS_LC_INFO | \      DDS_LC_CONFIG | DDS_LC_DISCOVERY | DDS_LC_DATA | DDS_LC_TRACE | \      DDS_LC_TIMING | DDS_LC_TRAFFIC | DDS_LC_TCP | DDS_LC_THROTTLE | \      DDS_LC_CONTENT | DDS_LC_USER)

All common trace categories.