# 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_READ_WITHOUT_LOCK (0xFFFFFFED)

    Constant to use with dds_read() or dds_take() when using dds_reader_lock_samples().

  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

  uint32_t dds_reader_lock_samples(dds_entity_t reader)

    Returns number of samples in read cache and locks the reader cache, to make sure that the samples content doesn’t change.

    Because the cache is locked, you should be able to read/take without having to lock first. This is done by passing the DDS_READ_WITHOUT_LOCK value to the read/take call as maxs. Then the read/take will not lock but still unlock.

    CycloneDDS doesn’t support a read/take that just returns all available samples issue #74. As a work around to support LENGTH_UNLIMITED in C++. dds_reader_lock_samples() and DDS_READ_WITHOUT_LOCK are needed.

    Parameters:

      - reader – [in] Reader to lock the cache of.

    Returns:

      the number of samples in the reader cache.

group (Testing tools)

  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.

group (Public Implementation Details)

  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

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

    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