Topics¶

group topic

Defines

DDS_HAS_CREATE_TOPIC_SERTYPE¶

Indicates that the library defines the dds_create_topic_sertype function.

Introduced to help with the change from sertopic to sertype. If you are using a modern CycloneDDS version you will not need this.

DDS_HAS_CREATE_TOPIC_GENERIC¶

Indicates that the library defines the dds_create_topic_generic function.

Introduced to help with the change from sertopic to sertype. You should probably move to using sertype instead of sertopic and ignore this.

Typedefs

typedef enum dds_find_scope dds_find_scope_t¶: Scope for dds_find_topic()

Enums

enum dds_find_scope¶

Scope for dds_find_topic()

Values:

enumerator DDS_FIND_SCOPE_GLOBAL¶: locate the topic anywhere CycloneDDS knows about

enumerator DDS_FIND_SCOPE_LOCAL_DOMAIN¶: locate the topic locally within domain boundaries

enumerator DDS_FIND_SCOPE_PARTICIPANT¶: locate the topic within the current participant

Functions

dds_entity_t dds_create_topic(dds_entity_t participant, const dds_topic_descriptor_t *descriptor, const char *name, const dds_qos_t *qos, const dds_listener_t *listener)¶

Creates a new topic with default type handling.

The type name for the topic is taken from the generated descriptor. Topic matching is done on a combination of topic name and type name. Each successful call to dds_create_topic creates a new topic entity sharing the same QoS settings with all other topics of the same name.

Parameters

participant – [in] Participant on which to create the topic.
descriptor – [in] An IDL generated topic descriptor.
name – [in] Name of the topic.
qos – [in] QoS to set on the new topic (can be NULL).
listener – [in] Any listener functions associated with the new topic (can be NULL).

Return values

>=0 – A valid unique topic handle.
DDS_RETCODE_BAD_PARAMETER – Either participant, descriptor, name or qos is invalid.
DDS_RETCODE_INCONSISTENT_POLICY – QoS mismatch between qos and an existing topic’s QoS.
DDS_RETCODE_PRECONDITION_NOT_MET – Mismatch between type name in descriptor and pre-existing topic’s type name.

Returns

A valid, unique topic handle or an error code.

dds_entity_t dds_create_topic_sertype(dds_entity_t participant, const char *name, struct ddsi_sertype **sertype, const dds_qos_t *qos, const dds_listener_t *listener, const struct ddsi_plist *sedp_plist)¶

Creates a new topic with provided type handling.

The name for the type is taken from the provided “sertype” object. Type matching is done on a combination of topic name and type name. Each successful call to dds_create_topic creates a new topic entity sharing the same QoS settings with all other topics of the same name.

In case this function returns a valid handle, the ownership of the provided sertype is handed over to Cyclone. On return, the caller gets in the sertype parameter a pointer to the sertype that is actually used by the topic. This can be the provided sertype (if this sertype was not yet known in the domain), or a sertype thas was already known in the domain.

Parameters

participant – [in] Participant on which to create the topic.
name – [in] Topic name
sertype – [inout] Internal description of the type . On return, the sertype parameter is set to the actual sertype that is used by the topic.
qos – [in] QoS to set on the new topic (can be NULL).
listener – [in] Any listener functions associated with the new topic (can be NULL).
sedp_plist – [in] Topic description to be published as part of discovery (if NULL, not published).

Return values

>=0 – A valid unique topic handle.
DDS_RETCODE_BAD_PARAMETER – Either participant, descriptor, name or qos is invalid.
DDS_RETCODE_INCONSISTENT_POLICY – QoS mismatch between qos and an existing topic’s QoS.
DDS_RETCODE_PRECONDITION_NOT_MET – Mismatch between type name in sertype and pre-existing topic’s type name.

Returns

A valid, unique topic handle or an error code. Iff a valid handle, the domain takes ownership of provided serdata.

dds_entity_t dds_create_topic_generic(dds_entity_t participant, struct ddsi_sertopic **sertopic, const dds_qos_t *qos, const dds_listener_t *listener, const struct ddsi_plist *sedp_plist)¶

Creates a new topic with provided type handling.

DOC_TODO: this description does not make any sense, this is for the legacy sertopic? deprecate?

The name for the type is taken from the provided “sertype” object. Type matching is done on a combination of topic name and type name. Each successful call to dds_create_topic creates a new topic entity sharing the same QoS settings with all other topics of the same name.

In case this function returns a valid handle, the ownership of the provided sertype is handed over to Cyclone. On return, the caller gets in the sertype parameter a pointer to the sertype that is actually used by the topic. This can be the provided sertype (if this sertype was not yet known in the domain), or a sertype thas was already known in the domain.

Parameters

participant – [in] Participant on which to create the topic.
sertopic – [inout] Legacy internal description of the type. On return, the sertype parameter is set to the actual sertype that is used by the topic.
qos – [in] QoS to set on the new topic (can be NULL).
listener – [in] Any listener functions associated with the new topic (can be NULL).
sedp_plist – [in] Topic description to be published as part of discovery (if NULL, not published).

Return values

>=0 – A valid unique topic handle.
DDS_RETCODE_BAD_PARAMETER – Either participant, descriptor, name or qos is invalid.
DDS_RETCODE_INCONSISTENT_POLICY – QoS mismatch between qos and an existing topic’s QoS.
DDS_RETCODE_PRECONDITION_NOT_MET – Mismatch between type name in sertype and pre-existing topic’s type name.

Returns

A valid, unique topic handle or an error code. Iff a valid handle, the domain takes ownership of provided serdata.

dds_entity_t dds_find_topic(dds_find_scope_t scope, dds_entity_t participant, const char *name, const dds_typeinfo_t *type_info, dds_duration_t timeout)¶

Finds a locally created or discovered remote topic by topic name and type information.

Finds a locally created topic or a discovered remote topic based on the topic name and type. In case the topic is not found, this function will wait for the topic to become available until the provided time out.

When using the scope DDS_FIND_SCOPE_LOCAL_DOMAIN, there will be no requests sent over the network for resolving the type in case it is unresolved. This also applies to dependent types: in case a dependency of the provided type is unresolved, no requests will be sent for resolving the type when using LOCAL_DOMAIN scope.

In case the scope is DDS_FIND_SCOPE_GLOBAL, for unresolved types (or dependencies) a type lookup request will be sent.

In case no type information is provided and multiple (discovered) topics exist with the provided name, an arbitrary topic with that name will be returned. In this scenario, it would be better to read DCPSTopic data and use that to get the required topic meta-data.

The returned topic should be released with dds_delete.

Parameters

scope – [in] The scope used to find the topic. In case topic discovery is not enabled in the build, SCOPE_GLOBAL cannot be used.
participant – [in] The handle of the participant the found topic will be created in
name – [in] The name of the topic to find.
type_info – [in] The type information of the topic to find. Optional, and should not be provided in case topic discovery is not enabled in the build.
timeout – [in] The timeout for waiting for the topic to become available

Return values

>0 – A valid topic handle.
0 – No topic of this name exists
DDS_RETCODE_BAD_PARAMETER – Participant or type information was invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type could not be found.

Returns

A valid topic handle or an error code.

dds_return_t dds_create_topic_descriptor(dds_find_scope_t scope, dds_entity_t participant, const dds_typeinfo_t *type_info, dds_duration_t timeout, dds_topic_descriptor_t **descriptor)¶

Creates topic descriptor for the provided type_info.

Parameters

scope – [in] The scope used to find the type: DDS_FIND_SCOPE_LOCAL_DOMAIN or DDS_FIND_SCOPE_GLOBAL. In case DDS_FIND_SCOPE_GLOBAL is used, a type lookup request will be sent to other nodes.
participant – [in] The handle of the participant.
type_info – [in] The type (dds_typeinfo_t) of the topic to find.
timeout – [in] The timeout for waiting for the type to become available
descriptor – [out] - Pointer to a dds_topic_descriptor_t pointer that will be allocated and populated. To free allocated memory for this descriptor, use dds_delete_topic_descriptor.

Return values

DDS_RETCODE_OK – The topic descriptor has been succesfully created.
DDS_RETCODE_BAD_PARAMETER – Type_info or descriptor parameter not provided, invalid entity (not a participant) or scope invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The participant or the type_id was not found.
DDS_RETCODE_TIMEOUT – Type was not resolved within the provided timeout
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_delete_topic_descriptor(dds_topic_descriptor_t *descriptor)¶

Delete memory allocated to the provided topic descriptor.

Parameters

descriptor – [in] - Pointer to a dds_topic_descriptor_t

Return values

DDS_RETCODE_OK – The topic descriptor has been succesfully deleted.
DDS_RETCODE_BAD_PARAMETER – No descriptor provided
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_name(dds_entity_t topic, char *name, size_t size)¶

Returns the name of a given topic.

Parameters

topic – [in] The topic.
name – [out] Buffer to write the topic name to.
size – [in] Number of bytes available in the buffer.

Returns

A dds_return_t indicating success or failure.

Returns

Actual length of topic name (name is truncated if return value >= size) or error

dds_return_t dds_get_type_name(dds_entity_t topic, char *name, size_t size)¶

Returns the type name of a given topic.

Parameters

topic – [in] The topic.
name – [out] Buffer to write the topic type name to.
size – [in] Number of bytes available in the buffer.

Returns

A dds_return_t indicating success or failure.

Returns

Actual length of type name (name is truncated if return value >= size) or error

group topic_filter

Topic filter functions.

Sampleinfo is all zero when filtering in a write call (i.e., writer created using a filtered topic, which one perhaps shouldn’t be doing), otherwise it has as much filled in correctly as is possible given the context and the rest fixed:

sample_state DDS_SST_NOT_READ;
publication_handle set to writer’s instance handle
source_timestamp set to source timestamp of sample
ranks 0
valid_data true
instance_handle set to instance handle of existing instance if the sample matches an existing instance, otherwise to what the instance handle will be if it passes the filter
view_state set to instance view state if sample being filtered matches an existing instance, NEW if not
instance_state set to instance state if sample being filtered matches an existing instance, NEW if not
generation counts set to instance’s generation counts if the sample matches an existing instance instance, 0 if not

Warning

part of the Unstable API: no guarantee that any of this will be maintained for backwards compatibility.

Typedefs

typedef bool (*dds_topic_filter_sample_fn)(const void *sample)¶

Topic filter function that only needs to look at the sample.

Warning

Unstable API

typedef bool (*dds_topic_filter_sample_arg_fn)(const void *sample, void *arg)¶

Topic filter function that only needs to look at the sample and a custom argument.

Warning

Unstable API

typedef bool (*dds_topic_filter_sampleinfo_arg_fn)(const dds_sample_info_t *sampleinfo, void *arg)¶

Topic filter function that only needs to look at the sampleinfo and a custom argument.

Warning

Unstable API

typedef bool (*dds_topic_filter_sample_sampleinfo_arg_fn)(const void *sample, const dds_sample_info_t *sampleinfo, void *arg)¶

Topic filter function that needs to look at the sample, the sampleinfo and a custom argument.

Warning

Unstable API

typedef dds_topic_filter_sample_fn dds_topic_filter_fn¶

See dds_topic_filter_sample_fn.

Warning

Unstable API

typedef dds_topic_filter_sample_arg_fn dds_topic_filter_arg_fn¶

See dds_topic_filter_sample_arg_fn.

Warning

Unstable API

Enums

enum dds_topic_filter_mode¶

Topic filter mode;.

Warning

Unstable API

Values:

enumerator DDS_TOPIC_FILTER_NONE¶: Can be used to reset topic filter

enumerator DDS_TOPIC_FILTER_SAMPLE¶: Use with dds_topic_filter_sample_fn

enumerator DDS_TOPIC_FILTER_SAMPLE_ARG¶: Use with dds_topic_filter_sample_arg_fn

enumerator DDS_TOPIC_FILTER_SAMPLEINFO_ARG¶: Use with dds_topic_filter_sampleinfo_arg_fn

enumerator DDS_TOPIC_FILTER_SAMPLE_SAMPLEINFO_ARG¶: Use with dds_topic_filter_sample_sampleinfo_arg_fn

Functions

void dds_set_topic_filter(dds_entity_t topic, dds_topic_filter_fn filter)¶

Sets a filter on a topic. To be replaced by proper filtering on readers,.

Deprecated:: use dds_set_topic_filter_and_arg or dds_set_topic_filter_extended instead

Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.

Warning

Unstable API

Parameters

topic – [in] The topic on which the content filter is set.
filter – [in] The filter function used to filter topic samples.

void dds_topic_set_filter(dds_entity_t topic, dds_topic_filter_fn filter)¶

Sets a filter on a topic. To be replaced by proper filtering on readers,.

Deprecated:: use dds_set_topic_filter_and_arg or dds_set_topic_filter_extended instead

Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.

Warning

Unstable API

Parameters

topic – [in] The topic on which the content filter is set.
filter – [in] The filter function used to filter topic samples.

dds_return_t dds_set_topic_filter_and_arg(dds_entity_t topic, dds_topic_filter_arg_fn filter, void *arg)¶

Sets a filter and filter argument on a topic.

Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.

Warning

Unstable API To be replaced by proper filtering on readers.

Parameters

topic – [in] The topic on which the content filter is set.
filter – [in] The filter function used to filter topic samples.
arg – [in] Argument for the filter function.

Return values

DDS_RETCODE_OK – Filter set successfully
DDS_RETCODE_BAD_PARAMETER – The topic handle is invalid

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_set_topic_filter_extended(dds_entity_t topic, const struct dds_topic_filter *filter)¶

Sets a filter and filter argument on a topic.

Not thread-safe with respect to data being read/written using readers/writers using this topic. Be sure to create a topic entity specific to the reader you want to filter, then set the filter function, and only then create the reader. And don’t change it unless you know there are no concurrent writes.

Warning

Unstable API To be replaced by proper filtering on readers.

Parameters

topic – [in] The topic on which the content filter is set.
filter – [in] The filter specification.

Return values

DDS_RETCODE_OK – Filter set successfully
DDS_RETCODE_BAD_PARAMETER – The topic handle is invalid

Returns

A dds_return_t indicating success or failure.

dds_topic_filter_fn dds_get_topic_filter(dds_entity_t topic)¶

Gets the filter for a topic.

Deprecated:: Use dds_get_topic_filter_and_arg() or dds_get_topic_filter_extended() instead.

To be replaced by proper filtering on readers.

Warning

Unstable API

Parameters

topic – [in] The topic from which to get the filter.

Returns

The topic filter, or 0 when of type other than “sample”.

dds_topic_filter_fn dds_topic_get_filter(dds_entity_t topic)¶

Gets the filter for a topic.

Deprecated:: Use dds_get_topic_filter_and_arg() or dds_get_topic_filter_extended() instead.

To be replaced by proper filtering on readers.

Warning

Unstable API

Parameters

topic – [in] The topic from which to get the filter.

Returns

The topic filter, or 0 when of type other than “sample”.

dds_return_t dds_get_topic_filter_and_arg(dds_entity_t topic, dds_topic_filter_arg_fn *fn, void **arg)¶

Gets the filter for a topic.

To be replaced by proper filtering on readers

Warning

Unstable API

Parameters

topic – [in] The topic from which to get the filter.
fn – [out] The topic filter function (fn may be NULL).
arg – [out] Filter function argument (arg may be NULL).

Return values

DDS_RETCODE_OK – Filter set successfully
DDS_RETCODE_PRECONDITION_NOT_MET – Filter is not of “none” or “sample_arg”
DDS_RETCODE_BAD_PARAMETER – The topic handle is invalid

dds_return_t dds_get_topic_filter_extended(dds_entity_t topic, struct dds_topic_filter *filter)¶

Gets the filter for a topic.

To be replaced by proper filtering on readers

Warning

Unstable API

Parameters

topic – [in] The topic from which to get the filter.
filter – [out] The topic filter specification.

Return values

DDS_RETCODE_OK – Filter set successfully
DDS_RETCODE_BAD_PARAMETER – The topic handle is invalid

union dds_topic_filter_function_union¶

#include <dds.h>

Union of all filter function types;.

Warning

Unstable API

Public Members

dds_topic_filter_sample_fn sample¶: Use with mode dds_topic_filter_mode::DDS_TOPIC_FILTER_SAMPLE

dds_topic_filter_sample_arg_fn sample_arg¶: Use with mode dds_topic_filter_mode::DDS_TOPIC_FILTER_SAMPLE_ARG

dds_topic_filter_sampleinfo_arg_fn sampleinfo_arg¶: Use with mode dds_topic_filter_mode::DDS_TOPIC_FILTER_SAMPLEINFO_ARG

dds_topic_filter_sample_sampleinfo_arg_fn sample_sampleinfo_arg¶: Use with mode dds_topic_filter_mode::DDS_TOPIC_FILTER_SAMPLE_SAMPLEINFO_ARG

struct dds_topic_filter¶

#include <dds.h>

Full topic filter container;.

Warning

Unstable API

Public Members

enum dds_topic_filter_mode mode¶: Provide a mode

union dds_topic_filter_function_union f¶: Provide a filter function

void *arg¶: Provide an argument, can be NULL