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