/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

 * Copyright by The HDF Group.                                               *

 * All rights reserved.                                                      *

 *                                                                           *

 * This file is part of HDF5.  The full HDF5 copyright notice, including     *

 * terms governing use, modification, and redistribution, is contained in    *

 * the LICENSE file, which can be found at the root of the source code       *

 * distribution tree, or in https://www.hdfgroup.org/licenses.               *

 * If you do not have access to either file, you may request a copy from     *

 * help@hdfgroup.org.                                                        *

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*

 * Purpose:     The Virtual Object Layer as described in documentation.

 *              The purpose is to provide an abstraction on how to access the

 *              underlying HDF5 container, whether in a local file with

 *              a specific file format, or remotely on other machines, etc...

 */

/****************/

/* Module Setup */

/****************/

#include "H5VLmodule.h" /* This source code file is part of the H5VL module */

/***********/

/* Headers */

/***********/

#include "H5private.h"   /* Generic Functions                                */

#include "H5Eprivate.h"  /* Error handling                                   */

#include "H5ESprivate.h" /* Event Sets                                       */

#include "H5Fprivate.h"  /* File access                                      */

#include "H5Iprivate.h"  /* IDs                                              */

#include "H5MMprivate.h" /* Memory management                                */

#include "H5Pprivate.h"  /* Property lists                                   */

#include "H5PLprivate.h" /* Plugins                                          */

#include "H5Tprivate.h"  /* Datatypes                                        */

#include "H5VLpkg.h"     /* Virtual Object Layer                             */

/****************/

/* Local Macros */

/****************/

/******************/

/* Local Typedefs */

/******************/

/* Structure used when trying to find a

 * VOL connector to open a given file with.

 */

typedef struct H5VL_file_open_find_connector_t {

    const char         *filename;

    const H5VL_class_t *cls;

    hid_t               fapl_id;

} H5VL_file_open_find_connector_t;

/* Typedef for common callback form of registered optional operations */

typedef herr_t (*H5VL_reg_opt_oper_t)(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                      hid_t dxpl_id, void **req);

/********************/

/* Package Typedefs */

/********************/

/********************/

/* Local Prototypes */

/********************/

/* Helper routines */

static herr_t H5VL__common_optional_op(hid_t id, H5I_type_t id_type, H5VL_reg_opt_oper_t reg_opt_op,

                                       H5VL_optional_args_t *args, hid_t dxpl_id, void **req,

                                       H5VL_object_t **_vol_obj_ptr);

/* VOL connector callback equivalents */

static void  *H5VL__attr_create(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id,

                                hid_t dxpl_id, void **req);

static void  *H5VL__attr_open(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                              const char *name, hid_t aapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__attr_read(void *obj, const H5VL_class_t *cls, hid_t mem_type_id, void *buf, hid_t dxpl_id,

                              void **req);

static herr_t H5VL__attr_write(void *obj, const H5VL_class_t *cls, hid_t mem_type_id, const void *buf,

                               hid_t dxpl_id, void **req);

static herr_t H5VL__attr_get(void *obj, const H5VL_class_t *cls, H5VL_attr_get_args_t *args, hid_t dxpl_id,

                             void **req);

static herr_t H5VL__attr_specific(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                  H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__attr_optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                  hid_t dxpl_id, void **req);

static herr_t H5VL__attr_close(void *obj, const H5VL_class_t *cls, hid_t dxpl_id, void **req);

static void  *H5VL__dataset_create(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                   const char *name, hid_t lcpl_id, hid_t type_id, hid_t space_id,

                                   hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, void **req);

static void  *H5VL__dataset_open(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                 const char *name, hid_t dapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__dataset_read(size_t count, void *obj[], const H5VL_class_t *cls, hid_t mem_type_id[],

                                 hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id, void *buf[],

                                 void **req);

static herr_t H5VL__dataset_write(size_t count, void *obj[], const H5VL_class_t *cls, hid_t mem_type_id[],

                                  hid_t mem_space_id[], hid_t file_space_id[], hid_t dxpl_id,

                                  const void *buf[], void **req);

static herr_t H5VL__dataset_get(void *obj, const H5VL_class_t *cls, H5VL_dataset_get_args_t *args,

                                hid_t dxpl_id, void **req);

static herr_t H5VL__dataset_specific(void *obj, const H5VL_class_t *cls, H5VL_dataset_specific_args_t *args,

                                     hid_t dxpl_id, void **req);

static herr_t H5VL__dataset_optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                     hid_t dxpl_id, void **req);

static herr_t H5VL__dataset_close(void *obj, const H5VL_class_t *cls, hid_t dxpl_id, void **req);

static void  *H5VL__datatype_commit(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                    const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id,

                                    hid_t tapl_id, hid_t dxpl_id, void **req);

static void  *H5VL__datatype_open(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                  const char *name, hid_t tapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__datatype_get(void *obj, const H5VL_class_t *cls, H5VL_datatype_get_args_t *args,

                                 hid_t dxpl_id, void **req);

static herr_t H5VL__datatype_specific(void *obj, const H5VL_class_t *cls, H5VL_datatype_specific_args_t *args,

                                      hid_t dxpl_id, void **req);

static herr_t H5VL__datatype_optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                      hid_t dxpl_id, void **req);

static herr_t H5VL__datatype_close(void *obj, const H5VL_class_t *cls, hid_t dxpl_id, void **req);

static void  *H5VL__file_create(const H5VL_class_t *cls, const char *name, unsigned flags, hid_t fcpl_id,

                                hid_t fapl_id, hid_t dxpl_id, void **req);

static void  *H5VL__file_open(const H5VL_class_t *cls, const char *name, unsigned flags, hid_t fapl_id,

                              hid_t dxpl_id, void **req);

static herr_t H5VL__file_open_find_connector_cb(H5PL_type_t plugin_type, const void *plugin_info,

                                                void *op_data);

static herr_t H5VL__file_get(void *obj, const H5VL_class_t *cls, H5VL_file_get_args_t *args, hid_t dxpl_id,

                             void **req);

static herr_t H5VL__file_specific(void *obj, const H5VL_class_t *cls, H5VL_file_specific_args_t *args,

                                  hid_t dxpl_id, void **req);

static herr_t H5VL__file_optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                  hid_t dxpl_id, void **req);

static herr_t H5VL__file_close(void *obj, const H5VL_class_t *cls, hid_t dxpl_id, void **req);

static void  *H5VL__group_create(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                 const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id,

                                 void **req);

static void  *H5VL__group_open(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                               const char *name, hid_t gapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__group_get(void *obj, const H5VL_class_t *cls, H5VL_group_get_args_t *args, hid_t dxpl_id,

                              void **req);

static herr_t H5VL__group_specific(void *obj, const H5VL_class_t *cls, H5VL_group_specific_args_t *args,

                                   hid_t dxpl_id, void **req);

static herr_t H5VL__group_optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args,

                                   hid_t dxpl_id, void **req);

static herr_t H5VL__group_close(void *obj, const H5VL_class_t *cls, hid_t dxpl_id, void **req);

static herr_t H5VL__link_create(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params,

                                const H5VL_class_t *cls, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id,

                                void **req);

static herr_t H5VL__link_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj,

                              const H5VL_loc_params_t *loc_params2, const H5VL_class_t *cls, hid_t lcpl_id,

                              hid_t lapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__link_move(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj,

                              const H5VL_loc_params_t *loc_params2, const H5VL_class_t *cls, hid_t lcpl_id,

                              hid_t lapl_id, hid_t dxpl_id, void **req);

static herr_t H5VL__link_get(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                             H5VL_link_get_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__link_specific(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                  H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__link_optional(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                  H5VL_optional_args_t *args, hid_t dxpl_id, void **req);

static void  *H5VL__object_open(void *obj, const H5VL_loc_params_t *params, const H5VL_class_t *cls,

                                H5I_type_t *opened_type, hid_t dxpl_id, void **req);

static herr_t H5VL__object_copy(void *src_obj, const H5VL_loc_params_t *src_loc_params, const char *src_name,

                                void *dst_obj, const H5VL_loc_params_t *dst_loc_params, const char *dst_name,

                                const H5VL_class_t *cls, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id,

                                void **req);

static herr_t H5VL__object_get(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                               H5VL_object_get_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__object_specific(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                    H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__object_optional(void *obj, const H5VL_loc_params_t *loc_params, const H5VL_class_t *cls,

                                    H5VL_optional_args_t *args, hid_t dxpl_id, void **req);

static herr_t H5VL__introspect_get_conn_cls(void *obj, const H5VL_class_t *cls, H5VL_get_conn_lvl_t lvl,

                                            const H5VL_class_t **conn_cls);

static herr_t H5VL__introspect_opt_query(void *obj, const H5VL_class_t *cls, H5VL_subclass_t subcls,

                                         int opt_type, uint64_t *flags);

static herr_t H5VL__request_wait(void *req, const H5VL_class_t *cls, uint64_t timeout,

                                 H5VL_request_status_t *status);

static herr_t H5VL__request_notify(void *req, const H5VL_class_t *cls, H5VL_request_notify_t cb, void *ctx);

static herr_t H5VL__request_cancel(void *req, const H5VL_class_t *cls, H5VL_request_status_t *status);

static herr_t H5VL__request_specific(void *req, const H5VL_class_t *cls, H5VL_request_specific_args_t *args);

static herr_t H5VL__request_optional(void *req, const H5VL_class_t *cls, H5VL_optional_args_t *args);

static herr_t H5VL__request_free(void *req, const H5VL_class_t *cls);

static herr_t H5VL__blob_put(void *obj, const H5VL_class_t *cls, const void *buf, size_t size, void *blob_id,

                             void *ctx);

static herr_t H5VL__blob_get(void *obj, const H5VL_class_t *cls, const void *blob_id, void *buf, size_t size,

                             void *ctx);

static herr_t H5VL__blob_specific(void *obj, const H5VL_class_t *cls, void *blob_id,

                                  H5VL_blob_specific_args_t *args);

static herr_t H5VL__blob_optional(void *obj, const H5VL_class_t *cls, void *blob_id,

                                  H5VL_optional_args_t *args);

static herr_t H5VL__token_cmp(void *obj, const H5VL_class_t *cls, const H5O_token_t *token1,

                              const H5O_token_t *token2, int *cmp_value);

static herr_t H5VL__token_to_str(void *obj, H5I_type_t obj_type, const H5VL_class_t *cls,

                                 const H5O_token_t *token, char **token_str);

static herr_t H5VL__token_from_str(void *obj, H5I_type_t obj_type, const H5VL_class_t *cls,

                                   const char *token_str, H5O_token_t *token);

static herr_t H5VL__optional(void *obj, const H5VL_class_t *cls, H5VL_optional_args_t *args, hid_t dxpl_id,

                             void **req);

/*********************/

/* Package Variables */

/*********************/

/*****************************/

/* Library Private Variables */

/*****************************/

/*******************/

/* Local Variables */

/*******************/

/*-------------------------------------------------------------------------

 * Function:    H5VLinitialize

 *

 * Purpose:     Calls the connector-specific callback to initialize the connector.

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VLinitialize(hid_t connector_id, hid_t vipl_id)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Invoke class' callback, if there is one */

    if (connector->cls->initialize) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(FAIL)

            {

                ret_value = connector->cls->initialize(vipl_id);

            }

        H5_AFTER_USER_CB(FAIL)

        if (ret_value < 0)

            HGOTO_ERROR(H5E_VOL, H5E_CANTCLOSEOBJ, FAIL, "VOL connector did not initialize");

    }

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* end H5VLinitialize() */

/*-------------------------------------------------------------------------

 * Function:    H5VLterminate

 *

 * Purpose:     Calls the connector-specific callback to terminate the connector.

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VLterminate(hid_t connector_id)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Invoke class' callback, if there is one */

    if (connector->cls->terminate) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(FAIL)

            {

                ret_value = connector->cls->terminate();

            }

        H5_AFTER_USER_CB(FAIL)

        if (ret_value < 0)

            HGOTO_ERROR(H5E_VOL, H5E_CANTCLOSEOBJ, FAIL, "VOL connector did not terminate cleanly");

    }

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* end H5VLterminate() */

/*---------------------------------------------------------------------------

 * Function:    H5VLget_cap_flags

 *

 * Purpose:     Retrieves the capability flag for a connector

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLget_cap_flags(hid_t connector_id, uint64_t *cap_flags /*out*/)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Retrieve capability flags */

    if (cap_flags)

        *cap_flags = connector->cls->cap_flags;

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLget_cap_flags */

/*---------------------------------------------------------------------------

 * Function:    H5VLget_value

 *

 * Purpose:     Retrieves the 'value' for a connector

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLget_value(hid_t connector_id, H5VL_class_value_t *value /*out*/)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Retrieve connector value */

    if (value)

        *value = connector->cls->value;

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLget_value */

/*-------------------------------------------------------------------------

 * Function:    H5VL__common_optional_op

 *

 * Purpose:     Performs an optional connector-specific operation on an object

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

static herr_t

H5VL__common_optional_op(hid_t id, H5I_type_t id_type, H5VL_reg_opt_oper_t reg_opt_op,

                         H5VL_optional_args_t *args, hid_t dxpl_id, void **req, H5VL_object_t **_vol_obj_ptr)

{

    H5VL_object_t  *tmp_vol_obj = NULL;                                         /* Object for id */

    H5VL_object_t **vol_obj_ptr = (_vol_obj_ptr ? _vol_obj_ptr : &tmp_vol_obj); /* Ptr to object ptr for id */

    bool            vol_wrapper_set = false;   /* Whether the VOL object wrapping context was set up */

    herr_t          ret_value       = SUCCEED; /* Return value */

    FUNC_ENTER_PACKAGE

    /* Check ID type & get VOL object */

    if (NULL == (*vol_obj_ptr = (H5VL_object_t *)H5I_object_verify(id, id_type)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "invalid identifier");

    /* Set wrapper info in API context */

    if (H5VL_set_vol_wrapper(*vol_obj_ptr) < 0)

        HGOTO_ERROR(H5E_VOL, H5E_CANTSET, FAIL, "can't set VOL wrapper info");

    vol_wrapper_set = true;

    /* Call the corresponding internal VOL routine */

    /* (Must return value from callback, for iterators) */

    if ((ret_value =

             (*reg_opt_op)((*vol_obj_ptr)->data, (*vol_obj_ptr)->connector->cls, args, dxpl_id, req)) < 0)

        HERROR(H5E_VOL, H5E_CANTOPERATE, "unable to execute optional callback");

done:

    /* Reset object wrapping info in API context */

    if (vol_wrapper_set && H5VL_reset_vol_wrapper() < 0)

        HDONE_ERROR(H5E_VOL, H5E_CANTRESET, FAIL, "can't reset VOL wrapper info");

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL__common_optional_op() */

/*-------------------------------------------------------------------------

 * Function:    H5VL_copy_connector_info

 *

 * Purpose:     Copy the VOL info for a connector

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VL_copy_connector_info(const H5VL_connector_t *connector, void **dst_info, const void *src_info)

{

    void  *new_connector_info = NULL;    /* Copy of connector info */

    herr_t ret_value          = SUCCEED; /* Return value */

    FUNC_ENTER_NOAPI(FAIL)

    /* Sanity checks */

    assert(connector);

    /* Check for actual source info */

    if (src_info) {

        /* Allow the connector to copy or do it ourselves */

        if (connector->cls->info_cls.copy) {

            /* Prepare & restore library for user callback */

            H5_BEFORE_USER_CB(FAIL)

                {

                    new_connector_info = (connector->cls->info_cls.copy)(src_info);

                }

            H5_AFTER_USER_CB(FAIL)

            if (NULL == new_connector_info)

                HGOTO_ERROR(H5E_VOL, H5E_CANTCOPY, FAIL, "connector info copy callback failed");

        } /* end if */

        else if (connector->cls->info_cls.size > 0) {

            if (NULL == (new_connector_info = H5MM_malloc(connector->cls->info_cls.size)))

                HGOTO_ERROR(H5E_VOL, H5E_CANTALLOC, FAIL, "connector info allocation failed");

            H5MM_memcpy(new_connector_info, src_info, connector->cls->info_cls.size);

        } /* end else-if */

        else

            HGOTO_ERROR(H5E_VOL, H5E_UNSUPPORTED, FAIL, "no way to copy connector info");

    } /* end if */

    /* Set the connector info for the copy */

    *dst_info = new_connector_info;

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL_copy_connector_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLcopy_connector_info

 *

 * Purpose:     Copies a VOL connector's info object

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLcopy_connector_info(hid_t connector_id, void **dst_vol_info, void *src_vol_info)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args and get VOL connector */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Copy the VOL connector's info object */

    if (H5VL_copy_connector_info(connector, dst_vol_info, src_vol_info) < 0)

        HGOTO_ERROR(H5E_VOL, H5E_CANTCOPY, FAIL, "unable to copy VOL connector info object");

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLcopy_connector_info() */

/*-------------------------------------------------------------------------

 * Function:    H5VL_cmp_connector_info

 *

 * Purpose:     Compare VOL info for a connector.  Sets *cmp_value to

 *              positive if INFO1 is greater than INFO2, negative if

 *              INFO2 is greater than INFO1 and zero if INFO1 and

 *              INFO2 are equal.

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VL_cmp_connector_info(const H5VL_connector_t *connector, int *cmp_value, const void *info1,

                        const void *info2)

{

    herr_t ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_NOAPI(FAIL)

    /* Sanity checks */

    assert(connector);

    assert(cmp_value);

    /* Take care of cases where one or both pointers is NULL */

    if (info1 == NULL && info2 != NULL) {

        *cmp_value = -1;

        HGOTO_DONE(SUCCEED);

    } /* end if */

    if (info1 != NULL && info2 == NULL) {

        *cmp_value = 1;

        HGOTO_DONE(SUCCEED);

    } /* end if */

    if (info1 == NULL && info2 == NULL) {

        *cmp_value = 0;

        HGOTO_DONE(SUCCEED);

    } /* end if */

    /* Use the class's info comparison routine to compare the info objects,

     * if there is a callback, otherwise just compare the info objects as

     * memory buffers

     */

    if (connector->cls->info_cls.cmp) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(FAIL)

            {

                ret_value = (connector->cls->info_cls.cmp)(cmp_value, info1, info2);

            }

        H5_AFTER_USER_CB(FAIL)

        if (ret_value < 0)

            HGOTO_ERROR(H5E_VOL, H5E_CANTCOMPARE, FAIL, "can't compare connector info");

    } /* end if */

    else {

        assert(connector->cls->info_cls.size > 0);

        *cmp_value = memcmp(info1, info2, connector->cls->info_cls.size);

    } /* end else */

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL_cmp_connector_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLcmp_connector_info

 *

 * Purpose:     Compares two connector info objects

 *

 * Note:  Both info objects must be from the same VOL connector class

 *

 * Return:      Success:    Non-negative, with *cmp set to positive if

 *          info1 is greater than info2, negative if info2

 *          is greater than info1 and zero if info1 and info2

 *          are equal.

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLcmp_connector_info(int *cmp, hid_t connector_id, const void *info1, const void *info2)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API(FAIL)

    /* Check args and get VOL connector */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Compare the two VOL connector info objects */

    if (cmp)

        H5VL_cmp_connector_info(connector, cmp, info1, info2);

done:

    FUNC_LEAVE_API(ret_value)

} /* H5VLcmp_connector_info() */

/*-------------------------------------------------------------------------

 * Function:    H5VL_free_connector_info

 *

 * Purpose:     Free VOL info for a connector

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VL_free_connector_info(const H5VL_connector_t *connector, const void *info)

{

    herr_t ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_NOAPI(FAIL)

    /* Sanity check */

    assert(connector);

    /* Only free info object, if it's non-NULL */

    if (info) {

        /* Allow the connector to free info or do it ourselves */

        if (connector->cls->info_cls.free) {

            /* Prepare & restore library for user callback */

            H5_BEFORE_USER_CB(FAIL)

                {

                    /* Cast through uintptr_t to de-const memory */

                    ret_value = (connector->cls->info_cls.free)((void *)(uintptr_t)info);

                }

            H5_AFTER_USER_CB(FAIL)

            if (ret_value < 0)

                HGOTO_ERROR(H5E_VOL, H5E_CANTRELEASE, FAIL, "connector info free request failed");

        }

        else

            H5MM_xfree_const(info);

    }

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL_free_connector_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLfree_connector_info

 *

 * Purpose:     Free VOL connector info object

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLfree_connector_info(hid_t connector_id, void *info)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args and get VOL connector */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Free the VOL connector info object */

    if (H5VL_free_connector_info(connector, info) < 0)

        HGOTO_ERROR(H5E_VOL, H5E_CANTRELEASE, FAIL, "unable to release VOL connector info object");

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLfree_connector_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLconnector_info_to_str

 *

 * Purpose:     Serialize a connector's info into a string

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLconnector_info_to_str(const void *info, hid_t connector_id, char **str)

{

    herr_t ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Only serialize info object, if it's non-NULL */

    if (info) {

        H5VL_connector_t *connector; /* VOL connector */

        /* Check args and get connector pointer */

        if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

            HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

        /* Allow the connector to serialize info */

        if (connector->cls->info_cls.to_str) {

            /* Prepare & restore library for user callback */

            H5_BEFORE_USER_CB(FAIL)

                {

                    ret_value = (connector->cls->info_cls.to_str)(info, str);

                }

            H5_AFTER_USER_CB(FAIL)

            if (ret_value < 0)

                HGOTO_ERROR(H5E_VOL, H5E_CANTSERIALIZE, FAIL, "can't serialize connector info");

        } /* end if */

        else

            *str = NULL;

    } /* end if */

    else

        *str = NULL;

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLconnector_info_to_str() */

/*-------------------------------------------------------------------------

 * Function:    H5VL__connector_str_to_info

 *

 * Purpose:     Deserializes a string into a connector's info object

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *-------------------------------------------------------------------------

 */

herr_t

H5VL__connector_str_to_info(const char *str, H5VL_connector_t *connector, void **info)

{

    herr_t ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_PACKAGE

    /* Only deserialize string, if it's non-NULL */

    if (str) {

        /* Allow the connector to deserialize info */

        if (connector->cls->info_cls.from_str) {

            /* Prepare & restore library for user callback */

            H5_BEFORE_USER_CB(FAIL)

                {

                    ret_value = (connector->cls->info_cls.from_str)(str, info);

                }

            H5_AFTER_USER_CB(FAIL)

            if (ret_value < 0)

                HGOTO_ERROR(H5E_VOL, H5E_CANTUNSERIALIZE, FAIL, "can't deserialize connector info");

        } /* end if */

        else

            *info = NULL;

    } /* end if */

    else

        *info = NULL;

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL__connector_str_to_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLconnector_str_to_info

 *

 * Purpose:     Deserialize a string into a connector's info

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info /*out*/)

{

    H5VL_connector_t *connector = NULL;

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args and get VOL connector */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Call internal routine */

    if (H5VL__connector_str_to_info(str, connector, info) < 0)

        HGOTO_ERROR(H5E_VOL, H5E_CANTDECODE, FAIL, "can't deserialize connector info");

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLconnector_str_to_info() */

/*---------------------------------------------------------------------------

 * Function:    H5VLget_object

 *

 * Purpose:     Retrieves an underlying object.

 *

 * Return:      Success:    Non-NULL

 *              Failure:    NULL

 *

 *---------------------------------------------------------------------------

 */

void *

H5VLget_object(void *obj, hid_t connector_id)

{

    H5VL_connector_t *connector;        /* VOL connector */

    void             *ret_value = NULL; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args */

    if (NULL == obj)

        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "invalid object");

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, NULL, "not a VOL connector ID");

    /* Check for 'get_object' callback in connector */

    if (connector->cls->wrap_cls.get_object) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(NULL)

            {

                ret_value = (connector->cls->wrap_cls.get_object)(obj);

            }

        H5_AFTER_USER_CB(NULL)

    }

    else

        ret_value = obj;

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLget_object */

/*---------------------------------------------------------------------------

 * Function:    H5VLget_wrap_ctx

 *

 * Purpose:     Get a VOL connector's object wrapping context. The output

 *              wrap context is stored in memory allocated by the VOL callback

 *              under *wrap_ctx and must be freed by the caller through

 *              H5VLfree_wrap_ctx().

 *

 * Return:      Success:    Non-negative

 *              Failure:    Negative

 *

 *---------------------------------------------------------------------------

 */

herr_t

H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx /*out*/)

{

    H5VL_connector_t *connector;           /* VOL connector */

    herr_t            ret_value = SUCCEED; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args and get connector pointer */

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, FAIL, "not a VOL connector ID");

    /* Allow the connector to wrap */

    if (connector->cls->wrap_cls.get_wrap_ctx) {

        /* Sanity check */

        assert(connector->cls->wrap_cls.free_wrap_ctx);

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(FAIL)

            {

                /* Invoke connector's callback */

                ret_value = (connector->cls->wrap_cls.get_wrap_ctx)(obj, wrap_ctx);

            }

        H5_AFTER_USER_CB(FAIL)

        if (ret_value < 0)

            HGOTO_ERROR(H5E_VOL, H5E_CANTGET, FAIL, "connector wrap context callback failed");

    } /* end if */

    else

        *wrap_ctx = NULL;

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLget_wrap_ctx() */

/*-------------------------------------------------------------------------

 * Function:    H5VL_wrap_object

 *

 * Purpose:     Wrap an object with connector

 *

 * Return:      Success:    Non-NULL

 *              Failure:    NULL

 *

 *-------------------------------------------------------------------------

 */

void *

H5VL_wrap_object(const H5VL_class_t *cls, void *wrap_ctx, void *obj, H5I_type_t obj_type)

{

    void *ret_value = NULL; /* Return value */

    FUNC_ENTER_NOAPI(NULL)

    /* Sanity checks */

    assert(cls);

    assert(obj);

    /* Only wrap object if there's a wrap context */

    if (wrap_ctx) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(NULL)

            {

                /* Ask the connector to wrap the object */

                ret_value = (cls->wrap_cls.wrap_object)(obj, obj_type, wrap_ctx);

            }

        H5_AFTER_USER_CB(NULL)

        if (NULL == ret_value)

            HGOTO_ERROR(H5E_VOL, H5E_CANTGET, NULL, "can't wrap object");

    } /* end if */

    else

        ret_value = obj;

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL_wrap_object() */

/*---------------------------------------------------------------------------

 * Function:    H5VLwrap_object

 *

 * Purpose:     Asks a connector to wrap an underlying object.

 *

 * Return:      Success:    Non-NULL

 *              Failure:    NULL

 *

 *---------------------------------------------------------------------------

 */

void *

H5VLwrap_object(void *obj, H5I_type_t obj_type, hid_t connector_id, void *wrap_ctx)

{

    H5VL_connector_t *connector;        /* VOL connector */

    void             *ret_value = NULL; /* Return value */

    FUNC_ENTER_API_NOINIT

    /* Check args and get connector pointer */

    if (NULL == obj)

        HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "invalid object");

    if (NULL == (connector = H5I_object_verify(connector_id, H5I_VOL)))

        HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, NULL, "not a VOL connector ID");

    /* Wrap the object */

    if (NULL == (ret_value = H5VL_wrap_object(connector->cls, wrap_ctx, obj, obj_type)))

        HGOTO_ERROR(H5E_VOL, H5E_CANTGET, NULL, "unable to wrap object");

done:

    FUNC_LEAVE_API_NOINIT(ret_value)

} /* H5VLwrap_object */

/*-------------------------------------------------------------------------

 * Function:    H5VL_unwrap_object

 *

 * Purpose:     Unwrap an object from connector

 *

 * Return:      Success:    Non-NULL

 *              Failure:    NULL

 *

 *-------------------------------------------------------------------------

 */

void *

H5VL_unwrap_object(const H5VL_class_t *cls, void *obj)

{

    void *ret_value = NULL; /* Return value */

    FUNC_ENTER_NOAPI(NULL)

    /* Sanity checks */

    assert(cls);

    assert(obj);

    /* Only unwrap object if there's an unwrap callback */

    if (cls->wrap_cls.wrap_object) {

        /* Prepare & restore library for user callback */

        H5_BEFORE_USER_CB(NULL)

            {

                /* Ask the connector to unwrap the object */

                ret_value = (cls->wrap_cls.unwrap_object)(obj);

            }

        H5_AFTER_USER_CB(NULL)

        if (NULL == ret_value)

            HGOTO_ERROR(H5E_VOL, H5E_CANTGET, NULL, "can't unwrap object");

    } /* end if */

    else

        ret_value = obj;

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5VL_unwrap_object() */

/*---------------------------------------------------------------------------

 * Function:    H5VLunwrap_object

 *

 * Purpose:     Unwrap an object from connector

 *

 * Return:      Success:    Non-NULL

 *              Failure:    NULL

 *

 *---------------------------------------------------------------------------

 */

void *

H5VLunwrap_object(void *obj, hid_t connector_id)

{

    H5VL_connector_t *connector;        /* VOL connector */

    void             *ret_value = NULL; /* Return value */