source/include/H5VLpublic.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * This file contains public declarations for the H5VL (VOL) module.
0015  */
0016
0017 #ifndef H5VLpublic_H
0018 #define H5VLpublic_H
0019
0020 #include "H5public.h"  /* Generic Functions                        */
0021 #include "H5Ipublic.h" /* Identifiers                              */
0022
0023 /*****************/
0024 /* Public Macros */
0025 /*****************/
0026
0027 /**
0028  * \ingroup H5VLDEF
0029  * \brief Version number of VOL class struct & callbacks
0030  *
0031  * \details Each VOL connector must set the 'version' field in the H5VL_class_t
0032  *          struct to the version of the H5VL_class_t struct that the connector
0033  *          implements.  The HDF5 library will reject connectors with
0034  *          incompatible structs.
0035  */
0036 #define H5VL_VERSION 3
0037
0038 /* VOL connector identifier values
0039  * These are H5VL_class_value_t values, NOT hid_t values!
0040  */
0041 /**
0042  * \ingroup H5VLDEF
0043  * Invalid ID for VOL connector ID
0044  */
0045 #define H5_VOL_INVALID (-1)
0046 /**
0047  * \ingroup H5VLDEF
0048  * Native HDF5 file format VOL connector
0049  */
0050 #define H5_VOL_NATIVE 0
0051 /**
0052  * \ingroup H5VLDEF
0053  * VOL connector IDs below this value are reserved for library use
0054  */
0055 #define H5_VOL_RESERVED 256
0056 /**
0057  * \ingroup H5VLDEF
0058  * Maximum VOL connector ID
0059  */
0060 #define H5_VOL_MAX 65535
0061
0062 /*
0063  * Capability flags for VOL connectors
0064  */
0065 #define H5VL_CAP_FLAG_NONE          0x0000000000000000 /**< No special connector capabilities */
0066 #define H5VL_CAP_FLAG_THREADSAFE    0x0000000000000001 /**< Connector is threadsafe */
0067 #define H5VL_CAP_FLAG_ASYNC         0x0000000000000002 /**< Connector performs operations asynchronously*/
0068 #define H5VL_CAP_FLAG_NATIVE_FILES  0x0000000000000004 /**< Connector produces native file format */
0069 #define H5VL_CAP_FLAG_ATTR_BASIC    0x0000000000000008 /**< H5A create/delete/exists/open/close/read/write */
0070 #define H5VL_CAP_FLAG_ATTR_MORE     0x0000000000000010 /**< All other H5A API calls */
0071 #define H5VL_CAP_FLAG_DATASET_BASIC 0x0000000000000020 /**< H5D create/open/close/read/write */
0072 #define H5VL_CAP_FLAG_DATASET_MORE  0x0000000000000040 /**< All other H5D API calls */
0073 #define H5VL_CAP_FLAG_FILE_BASIC    0x0000000000000080 /**< H5F create/open/close/read/write */
0074 #define H5VL_CAP_FLAG_FILE_MORE     0x0000000000000100 /**< All other H5F API calls */
0075 #define H5VL_CAP_FLAG_GROUP_BASIC   0x0000000000000200 /**< H5G create/open/close */
0076 #define H5VL_CAP_FLAG_GROUP_MORE    0x0000000000000400 /**< All other H5G API calls*/
0077 #define H5VL_CAP_FLAG_LINK_BASIC    0x0000000000000800 /**< H5L exists/delete */
0078 #define H5VL_CAP_FLAG_LINK_MORE     0x0000000000001000 /**< All other H5L API calls */
0079 #define H5VL_CAP_FLAG_MAP_BASIC                                                                              \
0080     0x0000000000002000 /**< H5M create/open/close/get*type/get_count/put/get/exists/delete */
0081 #define H5VL_CAP_FLAG_MAP_MORE         0x0000000000004000 /**< All other H5M API calls */
0082 #define H5VL_CAP_FLAG_OBJECT_BASIC     0x0000000000008000 /**< H5O open/close/exists */
0083 #define H5VL_CAP_FLAG_OBJECT_MORE      0x0000000000010000 /**< All other H5O API calls */
0084 #define H5VL_CAP_FLAG_REF_BASIC        0x0000000000020000 /**< H5Rdestroy */
0085 #define H5VL_CAP_FLAG_REF_MORE         0x0000000000040000 /**< All other H5R API calls */
0086 #define H5VL_CAP_FLAG_OBJ_REF          0x0000000000080000 /**< Connector supports object references */
0087 #define H5VL_CAP_FLAG_REG_REF          0x0000000000100000 /**< Connector supports regional references */
0088 #define H5VL_CAP_FLAG_ATTR_REF         0x0000000000200000 /**< Connector supports attribute references */
0089 #define H5VL_CAP_FLAG_STORED_DATATYPES 0x0000000000400000 /**< Connector supports stored datatypes */
0090 #define H5VL_CAP_FLAG_CREATION_ORDER   0x0000000000800000 /**< Connector tracks creation order */
0091 #define H5VL_CAP_FLAG_ITERATE          0x0000000001000000 /**< Connector supports iteration functions */
0092 #define H5VL_CAP_FLAG_STORAGE_SIZE     0x0000000002000000 /**< Connector can return a meaningful storage size */
0093 #define H5VL_CAP_FLAG_BY_IDX           0x0000000004000000 /**< "by index" API calls are supported */
0094 #define H5VL_CAP_FLAG_GET_PLIST                                                                              \
0095     0x0000000008000000 /**< Connector can return the property lists used to create an object */
0096 #define H5VL_CAP_FLAG_FLUSH_REFRESH  0x0000000010000000 /**< flush/refresh calls are supported */
0097 #define H5VL_CAP_FLAG_EXTERNAL_LINKS 0x0000000020000000 /**< External links are supported */
0098 #define H5VL_CAP_FLAG_HARD_LINKS     0x0000000040000000 /**< Hard links are supported */
0099 #define H5VL_CAP_FLAG_SOFT_LINKS     0x0000000080000000 /**< Soft links are supported */
0100 #define H5VL_CAP_FLAG_UD_LINKS       0x0000000100000000 /**< User-defined links are supported */
0101 #define H5VL_CAP_FLAG_TRACK_TIMES    0x0000000200000000 /**< Connector tracks creation, etc. times */
0102 #define H5VL_CAP_FLAG_MOUNT          0x0000000400000000 /**< H5Fmount/unmount supported */
0103 #define H5VL_CAP_FLAG_FILTERS        0x0000000800000000 /**< Connector implements a filter pipeline */
0104 #define H5VL_CAP_FLAG_FILL_VALUES    0x0000001000000000 /**< Connector allows fill values to be set */
0105
0106 /**
0107  * \ingroup H5VLDEF
0108  *
0109  * Flags to return from H5VLquery_optional API and 'opt_query' callbacks
0110  *
0111  * \details Operations which access multiple objects' data or metadata in a
0112  *          container should be registered as file-level optional operations.
0113  *          (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so
0114  *          a VOL connector that implemented it should register it as an optional
0115  *          file operation, and pass-through VOL connectors that are stacked above
0116  *          the connector that registered it should assume that dataset elements
0117  *          for _any_ dataset in the file could be written to)
0118  */
0119 #define H5VL_OPT_QUERY_SUPPORTED       0x0001 /**< VOL connector supports this operation */
0120 #define H5VL_OPT_QUERY_READ_DATA       0x0002 /**< Operation reads data for object */
0121 #define H5VL_OPT_QUERY_WRITE_DATA      0x0004 /**< Operation writes data for object */
0122 #define H5VL_OPT_QUERY_QUERY_METADATA  0x0008 /**< Operation reads metadata for object */
0123 #define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /**< Operation modifies metadata for object */
0124 #define H5VL_OPT_QUERY_COLLECTIVE                                                                            \
0125     0x0020 /**< Operation is collective (operations without this flag are assumed to be independent) */
0126 #define H5VL_OPT_QUERY_NO_ASYNC  0x0040 /**< Operation may NOT be executed asynchronously */
0127 #define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /**< Operation involves multiple objects */
0128
0129 /*******************/
0130 /* Public Typedefs */
0131 /*******************/
0132
0133 /**
0134  * \ingroup H5VLDEF
0135  *
0136  * \brief VOL connector identifiers.
0137  *
0138  * \details Values 0 through 255 are for connectors defined by the HDF5
0139  *          library. Values 256 through 511 are available for testing new
0140  *          connectors. Subsequent values should be obtained from the HDF5
0141  *          development team at mailto:help@hdfgroup.org.
0142  */
0143 //! <!-- [H5VL_class_value_t_snip] -->
0144 typedef int H5VL_class_value_t;
0145 //! <!-- [H5VL_class_value_t_snip] -->
0146
0147 /**
0148  * \ingroup H5VLDEF
0149  * \details Enum type for each VOL subclass
0150  *          (Used for various queries, etc)
0151  */
0152 typedef enum H5VL_subclass_t {
0153     H5VL_SUBCLS_NONE,     /**< Operations outside of a subclass */
0154     H5VL_SUBCLS_INFO,     /**< 'Info' subclass */
0155     H5VL_SUBCLS_WRAP,     /**< 'Wrap' subclass */
0156     H5VL_SUBCLS_ATTR,     /**< 'Attribute' subclass */
0157     H5VL_SUBCLS_DATASET,  /**< 'Dataset' subclass */
0158     H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */
0159     H5VL_SUBCLS_FILE,     /**< 'File' subclass */
0160     H5VL_SUBCLS_GROUP,    /**< 'Group' subclass */
0161     H5VL_SUBCLS_LINK,     /**< 'Link' subclass */
0162     H5VL_SUBCLS_OBJECT,   /**< 'Object' subclass */
0163     H5VL_SUBCLS_REQUEST,  /**< 'Request' subclass */
0164     H5VL_SUBCLS_BLOB,     /**< 'Blob' subclass */
0165     H5VL_SUBCLS_TOKEN     /**< 'Token' subclass */
0166                           /* NOTE: if more operations are added, the
0167                            * H5VL_opt_vals_g[] array size should be updated.
0168                            */
0169 } H5VL_subclass_t;
0170
0171 /********************/
0172 /* Public Variables */
0173 /********************/
0174
0175 /*********************/
0176 /* Public Prototypes */
0177 /*********************/
0178
0179 #ifdef __cplusplus
0180 extern "C" {
0181 #endif
0182
0183 /**
0184  * \ingroup H5VL
0185  * \brief Registers a new VOL connector by name
0186  *
0187  * \param[in] connector_name Connector name
0188  * \vipl_id
0189  * \return \hid_t{VOL connector}
0190  *
0191  * \details H5VLregister_connector_by_name() registers a new VOL connector with
0192  *          the name \p connector_name as a member of the virtual object layer
0193  *          class. This VOL connector identifier is good until the library is
0194  *          closed or the connector is unregistered.
0195  *
0196  *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
0197  *          initialization property list of class #H5P_VOL_INITIALIZE created
0198  *          with H5Pcreate(). When created, this property list contains no
0199  *          library properties. If a VOL connector author decides that
0200  *          initialization-specific data are needed, they can be added to the
0201  *          empty list and retrieved by the connector in the VOL connector's
0202  *          initialize callback. Use of the VOL initialization property list is
0203  *          uncommon, as most VOL-specific properties are added to the file
0204  *          access property list via the connector's API calls which set the
0205  *          VOL connector for the file open/create. For more information, see
0206  *          \ref_vol_doc.
0207  *
0208  * \since 1.12.0
0209  *
0210  */
0211 H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id);
0212 /**
0213  * \ingroup H5VL
0214  * \brief Registers a new VOL connector by value
0215  *
0216  * \param[in] connector_value Connector value
0217  * \vipl_id
0218  * \return \hid_t{VOL connector}
0219  *
0220  * \details H5VLregister_connector_by_value() registers a new VOL connector
0221  *          with value connector_value as a member of the virtual object layer
0222  *          class. This VOL connector identifier is good until the library is
0223  *          closed or the connector is unregistered.
0224  *
0225  *          \p connector_value has a type of H5VL_class_value_t, which is
0226  *          defined in H5VLpublic.h as follows:
0227  *          \snippet this H5VL_class_value_t_snip
0228  *
0229  *          Valid VOL connector identifiers can have values from 0 through 255
0230  *          for connectors defined by the HDF5 library. Values 256 through 511
0231  *          are available for testing new connectors. Subsequent values should
0232  *          be obtained by contacting the The HDF Help Desk.
0233  *
0234  *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
0235  *          initialization property list of class #H5P_VOL_INITIALIZE created
0236  *          with H5Pcreate(). When created, this property list contains no
0237  *          library properties. If a VOL connector author decides that
0238  *          initialization-specific data are needed, they can be added to the
0239  *          empty list and retrieved by the connector in the VOL connector's
0240  *          initialize callback. Use of the VOL initialization property list is
0241  *          uncommon, as most VOL-specific properties are added to the file
0242  *          access property list via the connector's API calls which set the
0243  *          VOL connector for the file open/create. For more information, see
0244  *          the \ref_vol_doc.
0245  *
0246  * \since 1.12.0
0247  *
0248  */
0249 H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id);
0250 /**
0251  * \ingroup H5VL
0252  * \brief Tests whether a VOL class has been registered under a certain name
0253  *
0254  * \param[in] name Alleged name of connector
0255  * \return \htri_t
0256  *
0257  * \details H5VLis_connector_registered_by_name() tests whether a VOL class has
0258  *          been registered or not, according to the supplied connector name
0259  *          \p name.
0260  *
0261  * \since 1.12.0
0262  */
0263 H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name);
0264 /**
0265  * \ingroup H5VL
0266  * \brief Tests whether a VOL class has been registered for a given value
0267  *
0268  * \param[in] connector_value Connector value
0269  * \return \htri_t
0270  *
0271  * \details H5VLis_connector_registered_by_value() tests whether a VOL class
0272  *          has been registered, according to the supplied connector value \p
0273  *          connector_value.
0274  *
0275  *          \p connector_value has a type of H5VL_class_value_t, which is
0276  *          defined in H5VLpublic.h as follows:
0277  *          \snippet this H5VL_class_value_t_snip
0278  *
0279  *          Valid VOL connector identifiers can have values from 0 through 255
0280  *          for connectors defined by the HDF5 library. Values 256 through 511
0281  *          are available for testing new connectors. Subsequent values should
0282  *          be obtained by contacting the The HDF Help Desk.
0283  *
0284  * \since 1.12.0
0285  */
0286 H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value);
0287 /**
0288  * \ingroup H5VL
0289  * \brief Retrieves the VOL connector identifier for a given object identifier
0290  *
0291  * \obj_id
0292  * \return \hid_t{VOL connector}
0293  *
0294  * \details H5VLget_connector_id() retrieves the registered VOL connector
0295  *          identifier for the specified object identifier \p obj_id. The VOL
0296  *          connector identifier must be closed with H5VLclose() when no longer
0297  *          in use.
0298  *
0299  * \since 1.12.0
0300  */
0301 H5_DLL hid_t H5VLget_connector_id(hid_t obj_id);
0302 /**
0303  * \ingroup H5VL
0304  * \brief Retrieves the identifier for a registered VOL connector name
0305  *
0306  * \param[in] name Connector name
0307  * \return \hid_t{VOL connector}
0308  *
0309  * \details H5VLget_connector_id_by_name() retrieves the identifier for a
0310  *          registered VOL connector with the name \p name. The identifier must
0311  *          be closed with H5VLclose() when no longer in use.
0312  *
0313  * \since 1.12.0
0314  */
0315 H5_DLL hid_t H5VLget_connector_id_by_name(const char *name);
0316 /**
0317  * \ingroup H5VL
0318  * \brief Retrieves the identifier for a registered VOL connector value
0319  *
0320  * \param[in] connector_value Connector value
0321  * \return \hid_t{VOL connector}
0322  *
0323  * \details H5VLget_connector_id_by_value() retrieves the identifier for a
0324  *          registered VOL connector with the value \p connector_value. The
0325  *          identifier will need to be closed by H5VLclose().
0326  *
0327  *          \p connector_value has a type of H5VL_class_value_t, which is
0328  *          defined in H5VLpublic.h as follows:
0329  *          \snippet this H5VL_class_value_t_snip
0330  *
0331  *          Valid VOL connector identifiers can have values from 0 through 255
0332  *          for connectors defined by the HDF5 library. Values 256 through 511
0333  *          are available for testing new connectors. Subsequent values should
0334  *          be obtained by contacting the The HDF Help Desk.
0335  *
0336  * \since 1.12.0
0337  */
0338 H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value);
0339 /**
0340  * \ingroup H5VL
0341  * \brief Retrieves a connector name for a VOL
0342  *
0343  * \obj_id{id} or file identifier
0344  * \param[out] name Connector name
0345  * \param[in] size Maximum length of the name to retrieve
0346  * \return Returns the length of the connector name on success, and a negative value on failure.
0347  *
0348  * \details H5VLget_connector_name() retrieves up to \p size elements of the
0349  *          VOL name \p name associated with the object or file identifier \p
0350  *          id.
0351  *
0352  *          Passing in a NULL pointer for size will return the size of the
0353  *          connector name. This can be used to determine the size of the
0354  *          buffer to allocate for the name.
0355  *
0356  * \since 1.12.0
0357  */
0358 H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size);
0359 /**
0360  * \ingroup H5VL
0361  * \brief Closes a VOL connector identifier
0362  *
0363  * \param[in] connector_id Connector identifier
0364  * \return \herr_t
0365  *
0366  * \details H5VLclose() closes a VOL connector identifier. This does not affect
0367  *          the file access property lists which have been defined to use this
0368  *          VOL connector or files which are already opened under this
0369  *          connector.
0370  *
0371  * \since 1.12.0
0372  */
0373 H5_DLL herr_t H5VLclose(hid_t connector_id);
0374 /**
0375  * \ingroup H5VL
0376  * \brief Removes a VOL connector identifier from the library
0377  *
0378  * \param[in] connector_id Connector identifier
0379  * \return \herr_t
0380  *
0381  * \details H5VLunregister_connector() removes a VOL connector identifier from
0382  *          the library. This does not affect the file access property lists
0383  *          which have been defined to use the VOL connector or any files which
0384  *          are already opened with this connector.
0385  *
0386  * \attention H5VLunregister_connector() will fail if attempting to unregister
0387  *            the native VOL connector.
0388  *
0389  * \since 1.12.0
0390  */
0391 H5_DLL herr_t H5VLunregister_connector(hid_t connector_id);
0392 /**
0393  * \ingroup H5VL
0394  * \brief Determine if a VOL connector supports a particular
0395  *        optional callback operation.
0396  *
0397  * \obj_id
0398  * \param[in] subcls VOL subclass
0399  * \param[in] opt_type Option type
0400  * \param[out] flags Operation flags
0401  * \return \herr_t
0402  *
0403  * \since 1.12.1
0404  */
0405 H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags);
0406 /**
0407  * \ingroup H5VL
0408  * \brief Determines whether an object ID represents a native
0409  *        VOL connector object.
0410  *
0411  * \obj_id
0412  * \param[out] is_native Boolean determining whether object is a native VOL connector object
0413  * \return \herr_t
0414  *
0415  * \since 1.12.2
0416  */
0417 H5_DLL herr_t H5VLobject_is_native(hid_t obj_id, hbool_t *is_native);
0418
0419 #ifdef __cplusplus
0420 }
0421 #endif
0422
0423 #endif /* H5VLpublic_H */