# Topics

group (Topic)

  Defines

  DDS_HAS_CREATE_TOPIC_SERTYPE 1

    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 1

    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 filters)

  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