source/include/H5VLconnector_passthru.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 authoring VOL connectors
0015  * which act as "passthrough" connectors that forward their API calls to
0016  * an underlying connector.
0017  *
0018  * An example of this might be a logging connector, which creates log messages
0019  * and then passes the call on to an underlying VOL connector.
0020  *
0021  * The functionality required to implement such a connector is specialized
0022  * and non-trivial so it has been split into this header in an effort to keep
0023  * the H5VLconnector.h header easier to understand.
0024  */
0025
0026 #ifndef H5VLconnector_passthru_H
0027 #define H5VLconnector_passthru_H
0028
0029 /* Public headers needed by this file */
0030 #include "H5public.h"   /* Generic Functions                    */
0031 #include "H5Ipublic.h"  /* IDs                                  */
0032 #include "H5VLpublic.h" /* Virtual Object Layer                 */
0033
0034 /* Semi-public headers mainly for VOL connector authors */
0035 #include "H5VLconnector.h"
0036
0037 /*****************/
0038 /* Public Macros */
0039 /*****************/
0040
0041 /*******************/
0042 /* Public Typedefs */
0043 /*******************/
0044
0045 /********************/
0046 /* Public Variables */
0047 /********************/
0048
0049 /*********************/
0050 /* Public Prototypes */
0051 /*********************/
0052
0053 #ifdef __cplusplus
0054 extern "C" {
0055 #endif
0056
0057 /* Helper routines for VOL connector authors */
0058 H5_DLL herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connector_id2);
0059 /**
0060  * \ingroup H5VL
0061  *
0062  * \brief Wrap an internal object with a "wrap context" and register an
0063  *        hid_t for the resulting object.
0064  *
0065  * \param[in] obj  VOL object.
0066  * \param[in] type VOL-managed object class. Allowable values are:
0067  *                 - #H5I_FILE
0068  *                 - #H5I_GROUP
0069  *                 - #H5I_DATATYPE
0070  *                 - #H5I_DATASET
0071  *                 - #H5I_MAP
0072  *                 - #H5I_ATTR
0073  *
0074  * \return \hid_t{VOL connector}
0075  *
0076  * \note This routine is mainly targeted toward wrapping objects for
0077  *       iteration routine callbacks (i.e. the callbacks from H5Aiterate*,
0078  *       H5Literate* / H5Lvisit*, and H5Ovisit* ). Using it in an application
0079  *       will return an error indicating the API context isn't available or
0080  *       can't be retrieved.
0081  *
0082  */
0083 H5_DLL hid_t  H5VLwrap_register(void *obj, H5I_type_t type);
0084 H5_DLL herr_t H5VLretrieve_lib_state(void **state);
0085 H5_DLL herr_t H5VLstart_lib_state(void);
0086 H5_DLL herr_t H5VLrestore_lib_state(const void *state);
0087 H5_DLL herr_t H5VLfinish_lib_state(void);
0088 H5_DLL herr_t H5VLfree_lib_state(void *state);
0089
0090 /* Pass-through callbacks */
0091 H5_DLL void  *H5VLget_object(void *obj, hid_t connector_id);
0092 H5_DLL herr_t H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx);
0093 H5_DLL void  *H5VLwrap_object(void *obj, H5I_type_t obj_type, hid_t connector_id, void *wrap_ctx);
0094 H5_DLL void  *H5VLunwrap_object(void *obj, hid_t connector_id);
0095 H5_DLL herr_t H5VLfree_wrap_ctx(void *wrap_ctx, hid_t connector_id);
0096
0097 /* Public wrappers for generic callbacks */
0098 H5_DLL herr_t H5VLinitialize(hid_t connector_id, hid_t vipl_id);
0099 H5_DLL herr_t H5VLterminate(hid_t connector_id);
0100 H5_DLL herr_t H5VLget_cap_flags(hid_t connector_id, uint64_t *cap_flags);
0101 H5_DLL herr_t H5VLget_value(hid_t connector_id, H5VL_class_value_t *conn_value);
0102
0103 /* Public wrappers for info fields and callbacks */
0104 H5_DLL herr_t H5VLcopy_connector_info(hid_t connector_id, void **dst_vol_info, void *src_vol_info);
0105 H5_DLL herr_t H5VLcmp_connector_info(int *cmp, hid_t connector_id, const void *info1, const void *info2);
0106 H5_DLL herr_t H5VLfree_connector_info(hid_t connector_id, void *vol_info);
0107 H5_DLL herr_t H5VLconnector_info_to_str(const void *info, hid_t connector_id, char **str);
0108 H5_DLL herr_t H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info);
0109
0110 /* Public wrappers for attribute callbacks */
0111 H5_DLL void  *H5VLattr_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0112                               const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
0113                               hid_t aapl_id, hid_t dxpl_id, void **req);
0114 H5_DLL void  *H5VLattr_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0115                             const char *name, hid_t aapl_id, hid_t dxpl_id, void **req);
0116 H5_DLL herr_t H5VLattr_read(void *attr, hid_t connector_id, hid_t dtype_id, void *buf, hid_t dxpl_id,
0117                             void **req);
0118 H5_DLL herr_t H5VLattr_write(void *attr, hid_t connector_id, hid_t dtype_id, const void *buf, hid_t dxpl_id,
0119                              void **req);
0120 H5_DLL herr_t H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_args_t *args, hid_t dxpl_id,
0121                            void **req);
0122 H5_DLL herr_t H5VLattr_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0123                                 H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req);
0124 H5_DLL herr_t H5VLattr_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0125                                 void **req);
0126 H5_DLL herr_t H5VLattr_close(void *attr, hid_t connector_id, hid_t dxpl_id, void **req);
0127
0128 /* Public wrappers for dataset callbacks */
0129 H5_DLL void  *H5VLdataset_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0130                                  const char *name, hid_t lcpl_id, hid_t type_id, hid_t space_id, hid_t dcpl_id,
0131                                  hid_t dapl_id, hid_t dxpl_id, void **req);
0132 H5_DLL void  *H5VLdataset_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0133                                const char *name, hid_t dapl_id, hid_t dxpl_id, void **req);
0134 H5_DLL herr_t H5VLdataset_read(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[],
0135                                hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id, void *buf[],
0136                                void **req);
0137 H5_DLL herr_t H5VLdataset_write(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[],
0138                                 hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id,
0139                                 const void *buf[], void **req);
0140 H5_DLL herr_t H5VLdataset_get(void *dset, hid_t connector_id, H5VL_dataset_get_args_t *args, hid_t dxpl_id,
0141                               void **req);
0142 H5_DLL herr_t H5VLdataset_specific(void *obj, hid_t connector_id, H5VL_dataset_specific_args_t *args,
0143                                    hid_t dxpl_id, void **req);
0144 H5_DLL herr_t H5VLdataset_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0145                                    void **req);
0146 H5_DLL herr_t H5VLdataset_close(void *dset, hid_t connector_id, hid_t dxpl_id, void **req);
0147
0148 /* Public wrappers for named datatype callbacks */
0149 H5_DLL void  *H5VLdatatype_commit(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0150                                   const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id,
0151                                   hid_t dxpl_id, void **req);
0152 H5_DLL void  *H5VLdatatype_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0153                                 const char *name, hid_t tapl_id, hid_t dxpl_id, void **req);
0154 H5_DLL herr_t H5VLdatatype_get(void *dt, hid_t connector_id, H5VL_datatype_get_args_t *args, hid_t dxpl_id,
0155                                void **req);
0156 H5_DLL herr_t H5VLdatatype_specific(void *obj, hid_t connector_id, H5VL_datatype_specific_args_t *args,
0157                                     hid_t dxpl_id, void **req);
0158 H5_DLL herr_t H5VLdatatype_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0159                                     void **req);
0160 H5_DLL herr_t H5VLdatatype_close(void *dt, hid_t connector_id, hid_t dxpl_id, void **req);
0161
0162 /* Public wrappers for file callbacks */
0163 H5_DLL void  *H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id,
0164                               void **req);
0165 H5_DLL void  *H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req);
0166 H5_DLL herr_t H5VLfile_get(void *file, hid_t connector_id, H5VL_file_get_args_t *args, hid_t dxpl_id,
0167                            void **req);
0168 H5_DLL herr_t H5VLfile_specific(void *obj, hid_t connector_id, H5VL_file_specific_args_t *args, hid_t dxpl_id,
0169                                 void **req);
0170 H5_DLL herr_t H5VLfile_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0171                                 void **req);
0172 H5_DLL herr_t H5VLfile_close(void *file, hid_t connector_id, hid_t dxpl_id, void **req);
0173
0174 /* Public wrappers for group callbacks */
0175 H5_DLL void  *H5VLgroup_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0176                                const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id,
0177                                void **req);
0178 H5_DLL void  *H5VLgroup_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0179                              const char *name, hid_t gapl_id, hid_t dxpl_id, void **req);
0180 H5_DLL herr_t H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_args_t *args, hid_t dxpl_id,
0181                             void **req);
0182 H5_DLL herr_t H5VLgroup_specific(void *obj, hid_t connector_id, H5VL_group_specific_args_t *args,
0183                                  hid_t dxpl_id, void **req);
0184 H5_DLL herr_t H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0185                                  void **req);
0186 H5_DLL herr_t H5VLgroup_close(void *grp, hid_t connector_id, hid_t dxpl_id, void **req);
0187
0188 /* Public wrappers for link callbacks */
0189 H5_DLL herr_t H5VLlink_create(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params,
0190                               hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req);
0191 H5_DLL herr_t H5VLlink_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj,
0192                             const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id,
0193                             hid_t lapl_id, hid_t dxpl_id, void **req);
0194 H5_DLL herr_t H5VLlink_move(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj,
0195                             const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id,
0196                             hid_t lapl_id, hid_t dxpl_id, void **req);
0197 H5_DLL herr_t H5VLlink_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0198                            H5VL_link_get_args_t *args, hid_t dxpl_id, void **req);
0199 H5_DLL herr_t H5VLlink_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0200                                 H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req);
0201 H5_DLL herr_t H5VLlink_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0202                                 H5VL_optional_args_t *args, hid_t dxpl_id, void **req);
0203
0204 /* Public wrappers for object callbacks */
0205 H5_DLL void  *H5VLobject_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0206                               H5I_type_t *opened_type, hid_t dxpl_id, void **req);
0207 H5_DLL herr_t H5VLobject_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, const char *src_name,
0208                               void *dst_obj, const H5VL_loc_params_t *loc_params2, const char *dst_name,
0209                               hid_t connector_id, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req);
0210 H5_DLL herr_t H5VLobject_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0211                              H5VL_object_get_args_t *args, hid_t dxpl_id, void **req);
0212 H5_DLL herr_t H5VLobject_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0213                                   H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req);
0214 H5_DLL herr_t H5VLobject_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id,
0215                                   H5VL_optional_args_t *args, hid_t dxpl_id, void **req);
0216
0217 /* Public wrappers for connector/container introspection callbacks */
0218 H5_DLL herr_t H5VLintrospect_get_conn_cls(void *obj, hid_t connector_id, H5VL_get_conn_lvl_t lvl,
0219                                           const H5VL_class_t **conn_cls);
0220 H5_DLL herr_t H5VLintrospect_get_cap_flags(const void *info, hid_t connector_id, uint64_t *cap_flags);
0221 H5_DLL herr_t H5VLintrospect_opt_query(void *obj, hid_t connector_id, H5VL_subclass_t subcls, int opt_type,
0222                                        uint64_t *flags);
0223
0224 /* Public wrappers for asynchronous request callbacks */
0225 H5_DLL herr_t H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout,
0226                                H5VL_request_status_t *status);
0227 H5_DLL herr_t H5VLrequest_notify(void *req, hid_t connector_id, H5VL_request_notify_t cb, void *ctx);
0228 H5_DLL herr_t H5VLrequest_cancel(void *req, hid_t connector_id, H5VL_request_status_t *status);
0229 H5_DLL herr_t H5VLrequest_specific(void *req, hid_t connector_id, H5VL_request_specific_args_t *args);
0230 H5_DLL herr_t H5VLrequest_optional(void *req, hid_t connector_id, H5VL_optional_args_t *args);
0231 H5_DLL herr_t H5VLrequest_free(void *req, hid_t connector_id);
0232
0233 /* Public wrappers for blob callbacks */
0234 H5_DLL herr_t H5VLblob_put(void *obj, hid_t connector_id, const void *buf, size_t size, void *blob_id,
0235                            void *ctx);
0236 H5_DLL herr_t H5VLblob_get(void *obj, hid_t connector_id, const void *blob_id, void *buf, size_t size,
0237                            void *ctx);
0238 H5_DLL herr_t H5VLblob_specific(void *obj, hid_t connector_id, void *blob_id,
0239                                 H5VL_blob_specific_args_t *args);
0240 H5_DLL herr_t H5VLblob_optional(void *obj, hid_t connector_id, void *blob_id, H5VL_optional_args_t *args);
0241
0242 /* Public wrappers for token callbacks */
0243 H5_DLL herr_t H5VLtoken_cmp(void *obj, hid_t connector_id, const H5O_token_t *token1,
0244                             const H5O_token_t *token2, int *cmp_value);
0245 H5_DLL herr_t H5VLtoken_to_str(void *obj, H5I_type_t obj_type, hid_t connector_id, const H5O_token_t *token,
0246                                char **token_str);
0247 H5_DLL herr_t H5VLtoken_from_str(void *obj, H5I_type_t obj_type, hid_t connector_id, const char *token_str,
0248                                  H5O_token_t *token);
0249
0250 /* Public wrappers for generic 'optional' callback */
0251 H5_DLL herr_t H5VLoptional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id,
0252                            void **req);
0253
0254 #ifdef __cplusplus
0255 }
0256 #endif
0257
0258 #endif /* H5VLconnector_passthru_H */