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.

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.