/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 COPYING 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. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* This file contains public declarations for the H5I (ID management) developer
* support routines.
*/
#ifndef H5Idevelop_H
#define H5Idevelop_H
/* Include package's public header */
#include "H5Ipublic.h" /* ID management */
/*****************/
/* Public Macros */
/*****************/
/*******************/
/* Public Typedefs */
/*******************/
/**
* The type of the realize_cb callback for H5Iregister_future
*/
//! <!-- [H5I_future_realize_func_t_snip] -->
typedef herr_t (*H5I_future_realize_func_t)(void *future_object, hid_t *actual_object_id);
//! <!-- [H5I_future_realize_func_t_snip] -->
/**
* The type of the discard_cb callback for H5Iregister_future
*/
//! <!-- [H5I_future_discard_func_t_snip] -->
typedef herr_t (*H5I_future_discard_func_t)(void *future_object);
//! <!-- [H5I_future_discard_func_t_snip] -->
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \ingroup H5I
*
* \brief Registers a "future" object under a type and returns an ID for it
*
* \param[in] type The identifier of the type of the new ID
* \param[in] object Pointer to "future" object for which a new ID is created
* \param[in] realize_cb Function pointer to realize a future object
* \param[in] discard_cb Function pointer to destroy a future object
*
* \return \hid_t{object}
*
* \details H5Iregister_future() creates and returns a new ID for a "future" object.
* Future objects are a special kind of object and represent a
* placeholder for an object that has not yet been created or opened.
* The \p realize_cb will be invoked by the HDF5 library to 'realize'
* the future object as an actual object. A call to H5Iobject_verify()
* will invoke the \p realize_cb callback and if it successfully
* returns, will return the actual object, not the future object.
*
* \details The \p type parameter is the identifier for the ID type to which
* this new future ID will belong. This identifier may have been created
* by a call to H5Iregister_type() or may be one of the HDF5 pre-defined
* ID classes (e.g. H5I_FILE, H5I_GROUP, H5I_DATASPACE, etc).
*
* \details The \p object parameter is a pointer to the memory which the new ID
* will be a reference to. This pointer will be stored by the library,
* but will not be returned to a call to H5Iobject_verify() until the
* \p realize_cb callback has returned the actual pointer for the object.
*
* A NULL value for \p object is allowed.
*
* \details The \p realize_cb parameter is a function pointer that will be
* invoked by the HDF5 library to convert a future object into an
* actual object. The \p realize_cb function may be invoked by
* H5Iobject_verify() to return the actual object for a user-defined
* ID class (i.e. an ID class registered with H5Iregister_type()) or
* internally by the HDF5 library in order to use or get information
* from an HDF5 pre-defined ID type. For example, the \p realize_cb
* for a future dataspace object will be called during the process
* of returning information from H5Sget_simple_extent_dims().
*
* Note that although the \p realize_cb routine returns
* an ID (as a parameter) for the actual object, the HDF5 library
* will swap the actual object in that ID for the future object in
* the future ID. This ensures that the ID value for the object
* doesn't change for the user when the object is realized.
*
* Note that the \p realize_cb callback could receive a NULL value
* for a future object pointer, if one was used when H5Iregister_future()
* was initially called. This is permitted as a means of allowing
* the \p realize_cb to act as a generator of new objects, without
* requiring creation of unnecessary future objects.
*
* It is an error to pass NULL for \p realize_cb.
*
* \details The \p discard_cb parameter is a function pointer that will be
* invoked by the HDF5 library to destroy a future object. This
* callback will always be invoked for _every_ future object, whether
* the \p realize_cb is invoked on it or not. It's possible that
* the \p discard_cb is invoked on a future object without the
* \p realize_cb being invoked, e.g. when a future ID is closed without
* requiring the future object to be realized into an actual one.
*
* Note that the \p discard_cb callback could receive a NULL value
* for a future object pointer, if one was used when H5Iregister_future()
* was initially called.
*
* It is an error to pass NULL for \p discard_cb.
*
* \note The H5Iregister_future() function is primarily targeted at VOL connector
* authors and is _not_ designed for general-purpose application use.
*
*/
H5_DLL hid_t H5Iregister_future(H5I_type_t type, const void *object, H5I_future_realize_func_t realize_cb,
H5I_future_discard_func_t discard_cb);
#ifdef __cplusplus
}
#endif
#endif /* H5Idevelop_H */