# Instance Handles

group (Instance Handles)

  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.