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

Functions

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.

Parameters

  • entity – [in] Reader or Writer entity.

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

Returns

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

dds_instance_handle_t dds_instance_lookup(dds_entity_t entity, const void *data)

Deprecated:

Get enabled status on entity. Use dds_lookup_instance instead.

Parameters

  • entity – [in] Reader or Writer entity.

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

Returns

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 inst, void *data)

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

DOC_TODO: Check return codes for completeness

Parameters

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

  • inst – [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.

Returns

A dds_return_t indicating success or failure.