# Builtin Topic Support

group (Constants)

  Convenience constants for referring to builtin topics These constants can be used in place of an actual dds_topic_t, when creating readers or writers for builtin-topics.

  Defines

  DDS_BUILTIN_TOPIC_DCPSPARTICIPANT ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 1))

    Pseudo dds_topic_t for the builtin topic DcpsParticipant. Samples from this topic are dds_builtintopic_participant structs.

  DDS_BUILTIN_TOPIC_DCPSTOPIC ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 2))

    Pseudo dds_topic_t for the builtin topic DcpsTopic. Samples from this topic are dds_builtintopic_topic structs. Note that this only works if you have specified ENABLE_TOPIC_DISCOVERY in your cmake build.

  DDS_BUILTIN_TOPIC_DCPSPUBLICATION ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 3))

    Pseudo dds_topic_t for the builtin topic DcpsPublication. Samples from this topic are dds_builtintopic_endpoint structs.

  DDS_BUILTIN_TOPIC_DCPSSUBSCRIPTION ((dds_entity_t) (DDS_MIN_PSEUDO_HANDLE + 4))

    Pseudo dds_topic_t for the builtin topic DcpsSubscription. Samples from this topic are dds_builtintopic_endpoint structs.

group (Builtin Topic Support)

  Typedefs

  typedef struct dds_builtintopic_guid dds_builtintopic_guid_t

    Structure of a GUID in any builtin topic sample.

  typedef struct dds_builtintopic_guid dds_guid_t

    Structure of a GUID in any builtin topic sample.

    dds_builtintopic_guid_t is a bit of a weird name for what everyone just calls a GUID, so let us try and switch to using the more logical one.

  typedef struct dds_builtintopic_participant dds_builtintopic_participant_t

    Sample structure of the Builtin topic DcpsParticipant.

  typedef struct dds_builtintopic_topic_key dds_builtintopic_topic_key_t

    Structure of a key in the Builtin topic DcpsTopic.

  typedef struct dds_builtintopic_topic dds_builtintopic_topic_t

    Sample structure of the Builtin topic DcpsTopic.

  typedef struct dds_builtintopic_endpoint dds_builtintopic_endpoint_t

    Sample structure of the Builtin topic DcpsPublication and DcpsSubscription.

  typedef enum dds_typeid_kind dds_typeid_kind_t

    Type identifier kind for getting endpoint type identifier.

  Enums

  enum dds_typeid_kind

    Type identifier kind for getting endpoint type identifier.

    Values:

    enumerator DDS_TYPEID_MINIMAL

      XTypes Minimal Type ID

    enumerator DDS_TYPEID_COMPLETE

      XTypes Complete Type ID

  Functions

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

    Parameters:

      - writer – [in] The writer.

      - rds – [in] The array to be filled.

      - nrds – [in] 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 values:

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

    Returns:

      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.

  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, e.g. using dds_builtintopic_free_endpoint.

    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.

    Parameters:

      - writer – [in] The writer.

      - ih – [in] The instance handle of a reader.

    Return values:

      - != – NULL The requested data

      - NULL – The writer is not valid or ih is not an instance handle of a matched reader.

    Returns:

      A newly allocated sample containing the information on the reader, or a NULL pointer for any kind of failure.

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

    Parameters:

      - reader – [in] The reader.

      - wrs – [in] The array to be filled.

      - nwrs – [in] 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 values:

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

    Returns:

      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.

  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, e.g. using dds_builtintopic_free_endpoint.

    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.

    Parameters:

      - reader – [in] The reader.

      - ih – [in] The instance handle of a writer.

    Return values:

      - != – NULL The requested data

      - NULL – The reader is not valid or ih is not an instance handle of a matched writer.

    Returns:

      A newly allocated sample containing the information on the writer, or a NULL pointer for any kind of failure.

  void dds_builtintopic_free_endpoint(dds_builtintopic_endpoint_t *builtintopic_endpoint)

    Free the endpoint information that was retrieved by dds_get_matched_subscription_data or dds_get_matched_publication_data.

    This operation deallocates the memory of the fields in a dds_builtintopic_endpoint_t struct and deallocates the struct itself.

    Parameters:

      - builtintopic_endpoint – [in] The builtintopic endpoint struct

  void dds_builtintopic_free_topic(dds_builtintopic_topic_t *builtintopic_topic)

    Free the provided topic information.

    This operation deallocates the memory of the fields in a dds_builtintopic_topic_t struct and deallocates the struct itself.

    Parameters:

      - builtintopic_topic – [in] The builtintopic topic struct

  void dds_builtintopic_free_participant(dds_builtintopic_participant_t *builtintopic_participant)

    Free the provided participant information.

    This operation deallocates the memory of the fields in a dds_builtintopic_participant_t struct and deallocates the struct itself.

    Parameters:

      - builtintopic_participant – [in] The builtintopic participant struct

  struct dds_builtintopic_guid
    #include <dds.h>

    Structure of a GUID in any builtin topic sample.

    Public Members

    uint8_t v[16]

      16-byte unique identifier

  struct dds_builtintopic_participant
    #include <dds.h>

    Sample structure of the Builtin topic DcpsParticipant.

    Public Members

    dds_guid_t key

      The GUID that uniquely identifies the participant on the network

    dds_qos_t *qos

      The QoS of the participant

  struct dds_builtintopic_topic_key
    #include <dds.h>

    Structure of a key in the Builtin topic DcpsTopic.

    Public Members

    unsigned char d[16]

      16-byte unique identifier

  struct dds_builtintopic_topic
    #include <dds.h>

    Sample structure of the Builtin topic DcpsTopic.

    Public Members

    dds_builtintopic_topic_key_t key

      The GUID that uniquely identifies the topic on the network

    char *topic_name

      The name of the topic, potentially unicode.

    char *type_name

      The name of the type, potentially unicode.

    dds_qos_t *qos

      The QoS of the topic

  struct dds_builtintopic_endpoint
    #include <dds.h>

    Sample structure of the Builtin topic DcpsPublication and DcpsSubscription.

    Public Members

    dds_guid_t key

      The GUID that uniquely identifies the endpoint on the network

    dds_guid_t participant_key

      The GUID of the participant this endpoint belongs to.

    dds_instance_handle_t participant_instance_handle

      The instance handle the participant assigned to this enpoint.

    char *topic_name

      The name of the topic, potentially unicode.

    char *type_name

      The name of the type, potentially unicode.

    dds_qos_t *qos

      The QoS of the endpoint

group (XTypes)

  CycloneDDS supports XTypes, but most of that functionality outside the new IDL constructs happens behind the scenes. However, some API functionality is added that allows inspecting types at runtime. Using it in C is not very ergonomic, but dynamic languages like Python can make good use of it.

  Functions

  dds_return_t dds_get_typeobj(dds_entity_t entity, const dds_typeid_t *type_id, dds_duration_t timeout, dds_typeobj_t **type_obj)

    This function resolves the type for the provided type identifier, which can e.g. be retrieved from endpoint or topic discovery data.

    Parameters:

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

      - type_id – [in] Type identifier

      - timeout – [in] Timeout for waiting for requested type information to be available

      - type_obj – [out] The type information, untouched if type is not resolved

    Return values:

      - DDS_RETCODE_OK – The operation was successful.

      - DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter, type_id or type name is not provided, or the sertype out parameter is NULL

      - DDS_RETCODE_NOT_FOUND – A type with the provided type_id and type_name was not found

      - DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

      - DDS_RETCODE_UNSUPPORTED – Cyclone DDS built without type discovery (cf. DDS_HAS_TYPE_DISCOVERY)

    Returns:

      A dds_return_t indicating success or failure.

  dds_return_t dds_free_typeobj(dds_typeobj_t *type_obj)

    Free the type object that was retrieved using dds_get_typeobj.

    Parameters:

      - type_obj – [in] The type object

    Return values:

      - DDS_RETCODE_OK – The operation was successful.

      - DDS_RETCODE_BAD_PARAMETER – The type_obj parameter is NULL

      - DDS_RETCODE_UNSUPPORTED – Cyclone DDS built without type discovery (cf. DDS_HAS_TYPE_DISCOVERY)

    Returns:

      A dds_return_t indicating success or failure.

  dds_return_t dds_get_typeinfo(dds_entity_t entity, dds_typeinfo_t **type_info)

    This function gets the type information from the provided topic, reader or writer.

    Parameters:

      - entity – [in] A topic/reader/writer entity

      - type_info – [out] The type information, untouched if returncode indicates failure

    Return values:

      - DDS_RETCODE_OK – The operation was successful.

      - DDS_RETCODE_BAD_PARAMETER – The type_info parameter is null

      - DDS_RETCODE_NOT_FOUND – The entity does not have type information set

      - DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

      - DDS_RETCODE_UNSUPPORTED – Cyclone DDS built without type discovery (cf. DDS_HAS_TYPE_DISCOVERY)

    Returns:

      A dds_return_t indicating success or failure.

  dds_return_t dds_free_typeinfo(dds_typeinfo_t *type_info)

    Free the type information that was retrieved using dds_get_typeinfo.

    Parameters:

      - type_info – [in] The type information

    Return values:

      - DDS_RETCODE_OK – The operation was successful.

      - DDS_RETCODE_BAD_PARAMETER – The type_info parameter is NULL

      - DDS_RETCODE_UNSUPPORTED – Cyclone DDS built without type discovery (cf. DDS_HAS_TYPE_DISCOVERY)

    Returns:

      A dds_return_t indicating success or failure.