Last modified: 17 April 2012
Name: H5O_mcdt_search_cb_t
Signature:
  `typedef` H5O_mcdt_search_ret_t ( `*H5O_mcdt_search_cb_t` )( void *`op_data` )

Purpose:
  Provides the mechanism by which a user application may set an action for `H5Ocopy` to take after checking all suggested paths for a matching committed datatype but before starting the global search of the destination file.

Description:
  `H5O_mcdt_search_cb_t` is the callback function that `H5Ocopy` will invoke if the callback is set and when the merge committed datatype feature is enabled in the object copy property list (see `H5Pset_copy_object`).

  After searching the list of suggested committed datatype paths, `H5Ocopy` will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with `H5Pset_mcdt_search_cb` and the search process is described in `H5Padd_merge_committed_dtype_path`.

  Valid return values from this callback function are as follows (defined in the enumerated datatype `H5O_mcdt_search_ret_t` in `H5Opublic.h`):

  `H5O_MCDT_SEARCH_ERROR` |  | Aborts `H5Ocopy`.
  `H5O_MCDT_SEARCH_CONT` |  | Continues the global search of all committed datatypes in the destination file.
  `H5O_MCDT_SEARCH_STOP``` |  | Stops the search, but continues copying.

Warning:
  If the callback’s return value is `H5O_MCDT_SEARCH_ERROR`, `H5Ocopy` will abort and the destination file may be left in an inconsistent or corrupted state.

Parameters:

  void *`op_data` |  | IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to `H5Pset_mcdt_search_cb`.

Returns:
  Returns one of the `H5O_MCDT_SEARCH_*` values described above.

Failure Modes:
  `H5O_mcdt_search_cb_t` failure modes are dependent on the implementation of the callback function.

Example Usage:
  This example defines a callback function in the object copy property list to discontinue the global search if a matching committed datatype cannot be found among the suggested paths.

      /* The user-defined callback function */
      static H5O_mcdt_search_ret_t
      mcdt_search_cb(void *_udata)
      {
          H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

          return(action);
      }

      int main(void) {
          hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

          /* Enable the merging committed datatype feature. */
          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

          /* Add the path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

          /*
           * Set the callback function to discontinue the global search
           * if H5Ocopy cannot find a matching committed datatype from the
           * above suggested path.
           */
          action = H5O_MCDT_SEARCH_STOP;
          H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);

          /* Do the copy. */
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb`

  Copying Committed Datatypes with `H5Ocopy` |  | A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

History:

  Release | Change
  1.8.9 | C function type introduced in this release.