Builtin Topic Support¶

group builtintopic_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¶: Pseudo dds_topic_t for the builtin topic DcpsParticipant. Samples from this topic are dds_builtintopic_participant structs.

DDS_BUILTIN_TOPIC_DCPSTOPIC¶: 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¶: Pseudo dds_topic_t for the builtin topic DcpsPublication. Samples from this topic are dds_builtintopic_endpoint structs.

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

group builtintopic

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.

dds_return_t dds_builtintopic_get_endpoint_type_info(dds_builtintopic_endpoint_t *builtintopic_endpoint, const dds_typeinfo_t **type_info)¶

Gets the type information from endpoint information that was retrieved by dds_get_matched_subscription_data or dds_get_matched_publication_data.

Parameters

builtintopic_endpoint – [in] The builtintopic endpoint struct
type_info – [out] Type information that will be allocated by this function in case of success.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – One or more parameters are invalid

Returns

A dds_return_t indicating success or 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.