/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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://support.hdfgroup.org/ftp/HDF5/releases. *
* 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 H5VL (VOL) module.
*/
#ifndef _H5VLpublic_H
#define _H5VLpublic_H
/* Public headers needed by this file */
#include "H5public.h" /* Generic Functions */
#include "H5Ipublic.h" /* IDs */
/*****************/
/* Public Macros */
/*****************/
/* VOL connector identifier values
* These are H5VL_class_value_t values, NOT hid_t values!
*/
/**
* \ingroup H5VLDEF
* Invalid ID for VOL connector ID
*/
#define H5_VOL_INVALID (-1)
/**
* \ingroup H5VLDEF
* Native HDF5 file format VOL connector
*/
#define H5_VOL_NATIVE 0
/**
* \ingroup H5VLDEF
* VOL connector IDs below this value are reserved for library use
*/
#define H5_VOL_RESERVED 256
/**
* \ingroup H5VLDEF
* Maximum VOL connector ID
*/
#define H5_VOL_MAX 65535
/*******************/
/* Public Typedefs */
/*******************/
/**
* \ingroup H5VLDEF
*
* \brief VOL connector identifiers.
*
* \details Values 0 through 255 are for connectors defined by the HDF5
* library. Values 256 through 511 are available for testing new
* connectors. Subsequent values should be obtained from the HDF5
* development team at mailto:help@hdfgroup.org.
*/
//! [H5VL_class_value_t_snip]
typedef int H5VL_class_value_t;
//! [H5VL_class_value_t_snip]
/**
* \ingroup H5VLDEF
* \details Enum type for each VOL subclass
* (Used for various queries, etc)
*/
typedef enum H5VL_subclass_t {
H5VL_SUBCLS_NONE, /**< Operations outside of a subclass */
H5VL_SUBCLS_INFO, /**< 'Info' subclass */
H5VL_SUBCLS_WRAP, /**< 'Wrap' subclass */
H5VL_SUBCLS_ATTR, /**< 'Attribute' subclass */
H5VL_SUBCLS_DATASET, /**< 'Dataset' subclass */
H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */
H5VL_SUBCLS_FILE, /**< 'File' subclass */
H5VL_SUBCLS_GROUP, /**< 'Group' subclass */
H5VL_SUBCLS_LINK, /**< 'Link' subclass */
H5VL_SUBCLS_OBJECT, /**< 'Object' subclass */
H5VL_SUBCLS_REQUEST, /**< 'Request' subclass */
H5VL_SUBCLS_BLOB, /**< 'Blob' subclass */
H5VL_SUBCLS_TOKEN /**< 'Token' subclass */
} H5VL_subclass_t;
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \ingroup H5VL
* \brief Registers a new VOL connector by name
*
* \param[in] connector_name Connector name
* \vipl_id
* \return \hid_t{VOL connector}
*
* \details H5VLregister_connector_by_name() registers a new VOL connector with
* the name \p connector_name as a member of the virtual object layer
* class. This VOL connector identifier is good until the library is
* closed or the connector is unregistered.
*
* \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
* initialization property list of class #H5P_VOL_INITIALIZE created
* with H5Pcreate(). When created, this property list contains no
* library properties. If a VOL connector author decides that
* initialization-specific data are needed, they can be added to the
* empty list and retrieved by the connector in the VOL connector's
* initialize callback. Use of the VOL initialization property list is
* uncommon, as most VOL-specific properties are added to the file
* access property list via the connector's API calls which set the
* VOL connector for the file open/create. For more information, see
* the VOL documentation.
*
* \todo Fix the reference to VOL documentation.
*
* \since 1.12.0
*/
H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id);
/**
* \ingroup H5VL
* \brief Registers a new VOL connector by value
*
* \param[in] connector_value Connector value
* \vipl_id
* \return \hid_t{VOL connector}
*
* \details H5VLregister_connector_by_value() registers a new VOL connector
* with value connector_value as a member of the virtual object layer
* class. This VOL connector identifier is good until the library is
* closed or the connector is unregistered.
*
* \p connector_value has a type of H5VL_class_value_t, which is
* defined in H5VLpublic.h as follows:
* \snippet this H5VL_class_value_t_snip
*
* Valid VOL connector identifiers can have values from 0 through 255
* for connectors defined by the HDF5 library. Values 256 through 511
* are available for testing new connectors. Subsequent values should
* be obtained by contacting the The HDF Help Desk.
*
* \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
* initialization property list of class #H5P_VOL_INITIALIZE created
* with H5Pcreate(). When created, this property list contains no
* library properties. If a VOL connector author decides that
* initialization-specific data are needed, they can be added to the
* empty list and retrieved by the connector in the VOL connector's
* initialize callback. Use of the VOL initialization property list is
* uncommon, as most VOL-specific properties are added to the file
* access property list via the connector's API calls which set the
* VOL connector for the file open/create. For more information, see
* the VOL documentation.
*
* \todo Fix the reference to VOL documentation.
*
* \since 1.12.0
*/
H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id);
/**
* \ingroup H5VL
* \brief Tests whether a VOL class has been registered under a certain name
*
* \param[in] name Alleged name of connector
* \return \htri_t
*
* \details H5VLis_connector_registered_by_name() tests whether a VOL class has
* been registered or not, according to the supplied connector name
* \p name.
*
* \since 1.12.0
*/
H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name);
/**
* \ingroup H5VL
* \brief Tests whether a VOL class has been registered for a given value
*
* \param[in] connector_value Connector value
* \return \htri_t
*
* \details H5VLis_connector_registered_by_value() tests whether a VOL class
* has been registered, according to the supplied connector value \p
* connector_value.
*
* \p connector_value has a type of H5VL_class_value_t, which is
* defined in H5VLpublic.h as follows:
* \snippet this H5VL_class_value_t_snip
*
* Valid VOL connector identifiers can have values from 0 through 255
* for connectors defined by the HDF5 library. Values 256 through 511
* are available for testing new connectors. Subsequent values should
* be obtained by contacting the The HDF Help Desk.
*
* \since 1.12.0
*/
H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value);
/**
* \ingroup H5VL
* \brief Retrieves the VOL connector identifier for a given object identifier
*
* \obj_id
* \return \hid_t{VOL connector}
*
* \details H5VLget_connector_id() retrieves the registered VOL connector
* identifier for the specified object identifier \p obj_id. The VOL
* connector identifier must be closed with H5VLclose() when no longer
* in use.
*
* \since 1.12.0
*/
H5_DLL hid_t H5VLget_connector_id(hid_t obj_id);
/**
* \ingroup H5VL
* \brief Retrieves the identifier for a registered VOL connector name
*
* \param[in] name Connector name
* \return \hid_t{VOL connector}
*
* \details H5VLget_connector_id_by_name() retrieves the identifier for a
* registered VOL connector with the name \p name. The identifier must
* be closed with H5VLclose() when no longer in use.
*
* \since 1.12.0
*/
H5_DLL hid_t H5VLget_connector_id_by_name(const char *name);
/**
* \ingroup H5VL
* \brief Retrieves the identifier for a registered VOL connector value
*
* \param[in] connector_value Connector value
* \return \hid_t{VOL connector}
*
* \details H5VLget_connector_id_by_value() retrieves the identifier for a
* registered VOL connector with the value \p connector_value. The
* identifier will need to be closed by H5VLclose().
*
* \p connector_value has a type of H5VL_class_value_t, which is
* defined in H5VLpublic.h as follows:
* \snippet this H5VL_class_value_t_snip
*
* Valid VOL connector identifiers can have values from 0 through 255
* for connectors defined by the HDF5 library. Values 256 through 511
* are available for testing new connectors. Subsequent values should
* be obtained by contacting the The HDF Help Desk.
*
* \since 1.12.0
*/
H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value);
/**
* \ingroup H5VL
* \brief Retrieves a connector name for a VOL
*
* \obj_id{id} or file identifier
* \param[out] name Connector name
* \param[in] size Maximum length of the name to retrieve
* \return Returns the length of the connector name on success, and a negative value on failure.
*
* \details H5VLget_connector_name() retrieves up to \p size elements of the
* VOL name \p name associated with the object or file identifier \p
* id.
*
* Passing in a NULL pointer for size will return the size of the
* connector name. This can be used to determine the size of the
* buffer to allocate for the name.
*
* \since 1.12.0
*/
H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size);
/**
* \ingroup H5VL
* \brief Closes a VOL connector identifier
*
* \param[in] connector_id Connector identifier
* \return \herr_t
*
* \details H5VLclose() closes a VOL connector identifier. This does not affect
* the file access property lists which have been defined to use this
* VOL connector or files which are already opened under this
* connector.
*
* \since 1.12.0
*/
H5_DLL herr_t H5VLclose(hid_t connector_id);
/**
* \ingroup H5VL
* \brief Removes a VOL connector identifier from the library
*
* \param[in] connector_id Connector identifier
* \return \herr_t
*
* \details H5VLunregister_connector() removes a VOL connector identifier from
* the library. This does not affect the file access property lists
* which have been defined to use the VOL connector or any files which
* are already opened with this connector.
*
* \attention H5VLunregister_connector() will fail if attempting to unregister
* the native VOL connector.
*
* \since 1.12.0
*/
H5_DLL herr_t H5VLunregister_connector(hid_t connector_id);
/**
* \ingroup H5VL
* \brief Determine if a VOL connector supports a particular
* optional callback operation.
*
* \obj_id
* \param[in] subcls VOL subclass
* \param[in] opt_type Option type
* \param[out] supported Flag
* \return \herr_t
*
* \since 1.12.0
*/
H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported);
#ifdef __cplusplus
}
#endif
/* Semi-public headers mainly for VOL connector authors */
#include "H5VLconnector.h" /* VOL connector author routines */
#include "H5VLconnector_passthru.h" /* Pass-through VOL connector author routines */
#include "H5VLnative.h" /* Native VOL connector macros, for VOL connector authors */
#endif /* _H5VLpublic_H */