Instance Handles

group instance_handle

Instance handle <=> key value mapping. Functions exactly as read w.r.t. treatment of data parameter. On output, only key values set.

T x = { ... };
T y;
dds_instance_handle_t ih;
ih = dds_lookup_instance (e, &x);
dds_instance_get_key (e, ih, &y);


dds_instance_handle_t dds_lookup_instance(dds_entity_t entity, const void *data)

This operation takes a sample and returns an instance handle to be used for subsequent operations.

  • entity[in] Reader or Writer entity.

  • data[in] Sample with a key fields set.


instance handle or DDS_HANDLE_NIL if instance could not be found from key.

dds_return_t dds_instance_get_key(dds_entity_t entity, dds_instance_handle_t ih, void *data)

This operation takes an instance handle and return a key-value corresponding to it.

DOC_TODO: Check return codes for completeness

  • entity[in] Reader, writer, readcondition or querycondition entity.

  • ih[in] Instance handle.

  • data[out] pointer to an instance, to which the key ID corresponding to the instance handle will be returned, the sample in the instance should be ignored.

Return values
  • DDS_RETCODE_OK – The operation was successful.

  • DDS_RETCODE_BAD_PARAMETER – One of the parameters was invalid or the topic does not exist.

  • DDS_RETCODE_ERROR – An internal error has occurred.


A dds_return_t indicating success or failure.