1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * All rights reserved. * 4 * * 5 * This file is part of HDF5. The full HDF5 copyright notice, including * 6 * terms governing use, modification, and redistribution, is contained in * 7 * the COPYING file, which can be found at the root of the source code * 8 * distribution tree, or in https://www.hdfgroup.org/licenses. * 9 * If you do not have access to either file, you may request a copy from * 10 * help@hdfgroup.org. * 11 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 12 13 /* 14 * This file contains public declarations for the H5VL (VOL) module. 15 */ 16 17 #ifndef H5VLpublic_H 18 #define H5VLpublic_H 19 20 /* Public headers needed by this file */ 21 #include "H5public.h" /* Generic Functions */ 22 #include "H5Ipublic.h" /* IDs */ 23 24 /*****************/ 25 /* Public Macros */ 26 /*****************/ 27 28 /** 29 * \ingroup H5VLDEF 30 * \brief Version # of VOL class struct & callbacks 31 * 32 * \details Each VOL connector must set the 'version' field in the H5VL_class_t 33 * struct to the version of the H5VL_class_t struct that the connector 34 * implements. The HDF5 library will reject connectors with 35 * incompatible structs. 36 */ 37 #define H5VL_VERSION 0 38 39 /* VOL connector identifier values 40 * These are H5VL_class_value_t values, NOT hid_t values! 41 */ 42 /** 43 * \ingroup H5VLDEF 44 * Invalid ID for VOL connector ID 45 */ 46 #define H5_VOL_INVALID (-1) 47 /** 48 * \ingroup H5VLDEF 49 * Native HDF5 file format VOL connector 50 */ 51 #define H5_VOL_NATIVE 0 52 /** 53 * \ingroup H5VLDEF 54 * VOL connector IDs below this value are reserved for library use 55 */ 56 #define H5_VOL_RESERVED 256 57 /** 58 * \ingroup H5VLDEF 59 * Maximum VOL connector ID 60 */ 61 #define H5_VOL_MAX 65535 62 63 /*******************/ 64 /* Public Typedefs */ 65 /*******************/ 66 67 /** 68 * \ingroup H5VLDEF 69 * 70 * \brief VOL connector identifiers. 71 * 72 * \details Values 0 through 255 are for connectors defined by the HDF5 73 * library. Values 256 through 511 are available for testing new 74 * connectors. Subsequent values should be obtained from the HDF5 75 * development team at mailto:help@hdfgroup.org. 76 */ 77 //! <!-- [H5VL_class_value_t_snip] --> 78 typedef int H5VL_class_value_t; 79 //! <!-- [H5VL_class_value_t_snip] --> 80 81 /** 82 * \ingroup H5VLDEF 83 * \details Enum type for each VOL subclass 84 * (Used for various queries, etc) 85 */ 86 typedef enum H5VL_subclass_t { 87 H5VL_SUBCLS_NONE, /**< Operations outside of a subclass */ 88 H5VL_SUBCLS_INFO, /**< 'Info' subclass */ 89 H5VL_SUBCLS_WRAP, /**< 'Wrap' subclass */ 90 H5VL_SUBCLS_ATTR, /**< 'Attribute' subclass */ 91 H5VL_SUBCLS_DATASET, /**< 'Dataset' subclass */ 92 H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */ 93 H5VL_SUBCLS_FILE, /**< 'File' subclass */ 94 H5VL_SUBCLS_GROUP, /**< 'Group' subclass */ 95 H5VL_SUBCLS_LINK, /**< 'Link' subclass */ 96 H5VL_SUBCLS_OBJECT, /**< 'Object' subclass */ 97 H5VL_SUBCLS_REQUEST, /**< 'Request' subclass */ 98 H5VL_SUBCLS_BLOB, /**< 'Blob' subclass */ 99 H5VL_SUBCLS_TOKEN /**< 'Token' subclass */ 100 } H5VL_subclass_t; 101 102 /********************/ 103 /* Public Variables */ 104 /********************/ 105 106 /*********************/ 107 /* Public Prototypes */ 108 /*********************/ 109 110 #ifdef __cplusplus 111 extern "C" { 112 #endif 113 114 /** 115 * \ingroup H5VL 116 * \brief Registers a new VOL connector by name 117 * 118 * \param[in] connector_name Connector name 119 * \vipl_id 120 * \return \hid_t{VOL connector} 121 * 122 * \details H5VLregister_connector_by_name() registers a new VOL connector with 123 * the name \p connector_name as a member of the virtual object layer 124 * class. This VOL connector identifier is good until the library is 125 * closed or the connector is unregistered. 126 * 127 * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL 128 * initialization property list of class #H5P_VOL_INITIALIZE created 129 * with H5Pcreate(). When created, this property list contains no 130 * library properties. If a VOL connector author decides that 131 * initialization-specific data are needed, they can be added to the 132 * empty list and retrieved by the connector in the VOL connector's 133 * initialize callback. Use of the VOL initialization property list is 134 * uncommon, as most VOL-specific properties are added to the file 135 * access property list via the connector's API calls which set the 136 * VOL connector for the file open/create. For more information, see 137 * \ref_vol_doc. 138 * 139 * \since 1.12.0 140 * 141 */ 142 H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); 143 /** 144 * \ingroup H5VL 145 * \brief Registers a new VOL connector by value 146 * 147 * \param[in] connector_value Connector value 148 * \vipl_id 149 * \return \hid_t{VOL connector} 150 * 151 * \details H5VLregister_connector_by_value() registers a new VOL connector 152 * with value connector_value as a member of the virtual object layer 153 * class. This VOL connector identifier is good until the library is 154 * closed or the connector is unregistered. 155 * 156 * \p connector_value has a type of H5VL_class_value_t, which is 157 * defined in H5VLpublic.h as follows: 158 * \snippet this H5VL_class_value_t_snip 159 * 160 * Valid VOL connector identifiers can have values from 0 through 255 161 * for connectors defined by the HDF5 library. Values 256 through 511 162 * are available for testing new connectors. Subsequent values should 163 * be obtained by contacting the The HDF Help Desk. 164 * 165 * \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL 166 * initialization property list of class #H5P_VOL_INITIALIZE created 167 * with H5Pcreate(). When created, this property list contains no 168 * library properties. If a VOL connector author decides that 169 * initialization-specific data are needed, they can be added to the 170 * empty list and retrieved by the connector in the VOL connector's 171 * initialize callback. Use of the VOL initialization property list is 172 * uncommon, as most VOL-specific properties are added to the file 173 * access property list via the connector's API calls which set the 174 * VOL connector for the file open/create. For more information, see 175 * the \ref_vol_doc. 176 * 177 * \since 1.12.0 178 * 179 */ 180 H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); 181 /** 182 * \ingroup H5VL 183 * \brief Tests whether a VOL class has been registered under a certain name 184 * 185 * \param[in] name Alleged name of connector 186 * \return \htri_t 187 * 188 * \details H5VLis_connector_registered_by_name() tests whether a VOL class has 189 * been registered or not, according to the supplied connector name 190 * \p name. 191 * 192 * \since 1.12.0 193 */ 194 H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name); 195 /** 196 * \ingroup H5VL 197 * \brief Tests whether a VOL class has been registered for a given value 198 * 199 * \param[in] connector_value Connector value 200 * \return \htri_t 201 * 202 * \details H5VLis_connector_registered_by_value() tests whether a VOL class 203 * has been registered, according to the supplied connector value \p 204 * connector_value. 205 * 206 * \p connector_value has a type of H5VL_class_value_t, which is 207 * defined in H5VLpublic.h as follows: 208 * \snippet this H5VL_class_value_t_snip 209 * 210 * Valid VOL connector identifiers can have values from 0 through 255 211 * for connectors defined by the HDF5 library. Values 256 through 511 212 * are available for testing new connectors. Subsequent values should 213 * be obtained by contacting the The HDF Help Desk. 214 * 215 * \since 1.12.0 216 */ 217 H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value); 218 /** 219 * \ingroup H5VL 220 * \brief Retrieves the VOL connector identifier for a given object identifier 221 * 222 * \obj_id 223 * \return \hid_t{VOL connector} 224 * 225 * \details H5VLget_connector_id() retrieves the registered VOL connector 226 * identifier for the specified object identifier \p obj_id. The VOL 227 * connector identifier must be closed with H5VLclose() when no longer 228 * in use. 229 * 230 * \since 1.12.0 231 */ 232 H5_DLL hid_t H5VLget_connector_id(hid_t obj_id); 233 /** 234 * \ingroup H5VL 235 * \brief Retrieves the identifier for a registered VOL connector name 236 * 237 * \param[in] name Connector name 238 * \return \hid_t{VOL connector} 239 * 240 * \details H5VLget_connector_id_by_name() retrieves the identifier for a 241 * registered VOL connector with the name \p name. The identifier must 242 * be closed with H5VLclose() when no longer in use. 243 * 244 * \since 1.12.0 245 */ 246 H5_DLL hid_t H5VLget_connector_id_by_name(const char *name); 247 /** 248 * \ingroup H5VL 249 * \brief Retrieves the identifier for a registered VOL connector value 250 * 251 * \param[in] connector_value Connector value 252 * \return \hid_t{VOL connector} 253 * 254 * \details H5VLget_connector_id_by_value() retrieves the identifier for a 255 * registered VOL connector with the value \p connector_value. The 256 * identifier will need to be closed by H5VLclose(). 257 * 258 * \p connector_value has a type of H5VL_class_value_t, which is 259 * defined in H5VLpublic.h as follows: 260 * \snippet this H5VL_class_value_t_snip 261 * 262 * Valid VOL connector identifiers can have values from 0 through 255 263 * for connectors defined by the HDF5 library. Values 256 through 511 264 * are available for testing new connectors. Subsequent values should 265 * be obtained by contacting the The HDF Help Desk. 266 * 267 * \since 1.12.0 268 */ 269 H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value); 270 /** 271 * \ingroup H5VL 272 * \brief Retrieves a connector name for a VOL 273 * 274 * \obj_id{id} or file identifier 275 * \param[out] name Connector name 276 * \param[in] size Maximum length of the name to retrieve 277 * \return Returns the length of the connector name on success, and a negative value on failure. 278 * 279 * \details H5VLget_connector_name() retrieves up to \p size elements of the 280 * VOL name \p name associated with the object or file identifier \p 281 * id. 282 * 283 * Passing in a NULL pointer for size will return the size of the 284 * connector name. This can be used to determine the size of the 285 * buffer to allocate for the name. 286 * 287 * \since 1.12.0 288 */ 289 H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size); 290 /** 291 * \ingroup H5VL 292 * \brief Closes a VOL connector identifier 293 * 294 * \param[in] connector_id Connector identifier 295 * \return \herr_t 296 * 297 * \details H5VLclose() closes a VOL connector identifier. This does not affect 298 * the file access property lists which have been defined to use this 299 * VOL connector or files which are already opened under this 300 * connector. 301 * 302 * \since 1.12.0 303 */ 304 H5_DLL herr_t H5VLclose(hid_t connector_id); 305 /** 306 * \ingroup H5VL 307 * \brief Removes a VOL connector identifier from the library 308 * 309 * \param[in] connector_id Connector identifier 310 * \return \herr_t 311 * 312 * \details H5VLunregister_connector() removes a VOL connector identifier from 313 * the library. This does not affect the file access property lists 314 * which have been defined to use the VOL connector or any files which 315 * are already opened with this connector. 316 * 317 * \attention H5VLunregister_connector() will fail if attempting to unregister 318 * the native VOL connector. 319 * 320 * \since 1.12.0 321 */ 322 H5_DLL herr_t H5VLunregister_connector(hid_t connector_id); 323 /** 324 * \ingroup H5VL 325 * \brief Determine if a VOL connector supports a particular 326 * optional callback operation. 327 * 328 * \obj_id 329 * \param[in] subcls VOL subclass 330 * \param[in] opt_type Option type 331 * \param[out] supported Flag 332 * \return \herr_t 333 * 334 * \since 1.12.0 335 */ 336 H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported); 337 338 #ifdef __cplusplus 339 } 340 #endif 341 342 /* Semi-public headers mainly for VOL connector authors */ 343 #include "H5VLconnector.h" /* VOL connector author routines */ 344 #include "H5VLconnector_passthru.h" /* Pass-through VOL connector author routines */ 345 #include "H5VLnative.h" /* Native VOL connector macros, for VOL connector authors */ 346 347 #endif /* H5VLpublic_H */ 348