EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-09-17 09:20:44
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 H5M module. 0015 * 0016 * NOTE: This is an experimental API. Everything in the H5M package 0017 * is subject to revision in a future release. 0018 */ 0019 #ifndef H5Mpublic_H 0020 #define H5Mpublic_H 0021 0022 #include "H5public.h" /* Generic Functions */ 0023 #include "H5Ipublic.h" /* Identifiers */ 0024 #include "H5VLpublic.h" /* Virtual Object Layer */ 0025 0026 /* Exposes VOL connector types, so it needs the connector header */ 0027 #include "H5VLconnector.h" 0028 0029 /*****************/ 0030 /* Public Macros */ 0031 /*****************/ 0032 0033 /* Macros defining operation IDs for map VOL callbacks (implemented using the 0034 * "optional" VOL callback) 0035 */ 0036 /** Callback operation ID for map create \since 1.12.0 */ 0037 #define H5VL_MAP_CREATE 1 0038 /** Callback operation ID for map open \since 1.12.0 */ 0039 #define H5VL_MAP_OPEN 2 0040 /** Callback operation ID for getting an associated value from a map \since 1.12.0 */ 0041 #define H5VL_MAP_GET_VAL 3 0042 /** Callback operation ID for checking if a value exists in a map \since 1.12.0 */ 0043 #define H5VL_MAP_EXISTS 4 0044 /** Callback operation ID for putting a key-value pair to a map \since 1.12.0 */ 0045 #define H5VL_MAP_PUT 5 0046 /** Callback operation ID for map get callback \since 1.12.0 */ 0047 #define H5VL_MAP_GET 6 0048 /** Callback operation ID for map specific operation \since 1.12.0 */ 0049 #define H5VL_MAP_SPECIFIC 7 0050 /** Currently unused \since 1.12.0 */ 0051 #define H5VL_MAP_OPTIONAL 8 0052 /** Callback operation ID for terminating access to a map \since 1.12.0 */ 0053 #define H5VL_MAP_CLOSE 9 0054 0055 /*******************/ 0056 /* Public Typedefs */ 0057 /*******************/ 0058 0059 /** 0060 * Types for map GET callback 0061 */ 0062 typedef enum H5VL_map_get_t { 0063 H5VL_MAP_GET_MAPL, /**< Callback operation ID for getting map access property list \since 1.12.0 */ 0064 H5VL_MAP_GET_MCPL, /**< Callback operation ID for getting map creation property list \since 1.12.0 */ 0065 H5VL_MAP_GET_KEY_TYPE, /**< Callback operation ID for getting the key datatype for a map \since 1.12.0 */ 0066 H5VL_MAP_GET_VAL_TYPE, /**< Callback operation ID for getting the value datatype for a map \since 1.12.0 0067 */ 0068 H5VL_MAP_GET_COUNT /**< Callback operation ID for getting the number of key-value pairs stored in a map 0069 \since 1.12.0 */ 0070 } H5VL_map_get_t; 0071 0072 /** 0073 * Types for map SPECIFIC callback 0074 */ 0075 typedef enum H5VL_map_specific_t { 0076 H5VL_MAP_ITER, /**< Callback operation ID for iterating over all key-value pairs stored in the map 0077 \since 1.12.0 */ 0078 H5VL_MAP_DELETE /**< Callback operation ID for deleting a key-value pair stored in the map \since 1.12.0 0079 */ 0080 } H5VL_map_specific_t; 0081 0082 //! <!-- [H5M_iterate_t_snip] --> 0083 /** 0084 * Callback for H5Miterate() 0085 */ 0086 typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); 0087 //! <!-- [H5M_iterate_t_snip] --> 0088 0089 /** 0090 * Parameters for map operations 0091 */ 0092 typedef union H5VL_map_args_t { 0093 0094 /** H5VL_MAP_CREATE */ 0095 struct { 0096 H5VL_loc_params_t loc_params; /**< Location parameters for object */ 0097 const char *name; /**< Name of new map object */ 0098 hid_t lcpl_id; /**< Link creation property list for map */ 0099 hid_t key_type_id; /**< Datatype for map keys */ 0100 hid_t val_type_id; /**< Datatype for map values */ 0101 hid_t mcpl_id; /**< Map creation property list */ 0102 hid_t mapl_id; /**< Map access property list */ 0103 void *map; /**< Pointer to newly created map object (OUT) */ 0104 } create; 0105 0106 /** H5VL_MAP_OPEN */ 0107 struct { 0108 H5VL_loc_params_t loc_params; /**< Location parameters for object */ 0109 const char *name; /**< Name of new map object */ 0110 hid_t mapl_id; /**< Map access property list */ 0111 void *map; /**< Pointer to newly created map object (OUT) */ 0112 } open; 0113 0114 /** H5VL_MAP_GET_VAL */ 0115 struct { 0116 hid_t key_mem_type_id; /**< Memory datatype for key */ 0117 const void *key; /**< Pointer to key */ 0118 hid_t value_mem_type_id; /**< Memory datatype for value */ 0119 void *value; /**< Buffer for value (OUT) */ 0120 } get_val; 0121 0122 /** H5VL_MAP_EXISTS */ 0123 struct { 0124 hid_t key_mem_type_id; /**< Memory datatype for key */ 0125 const void *key; /**< Pointer to key */ 0126 hbool_t exists; /**< Flag indicating whether key exists in map (OUT) */ 0127 } exists; 0128 0129 /** H5VL_MAP_PUT */ 0130 struct { 0131 hid_t key_mem_type_id; /**< Memory datatype for key */ 0132 const void *key; /**< Pointer to key */ 0133 hid_t value_mem_type_id; /**< Memory datatype for value */ 0134 const void *value; /**< Pointer to value */ 0135 } put; 0136 0137 /** H5VL_MAP_GET */ 0138 struct { 0139 H5VL_map_get_t get_type; /**< 'get' operation to perform */ 0140 0141 /** Parameters for each operation */ 0142 union { 0143 /** H5VL_MAP_GET_MAPL */ 0144 struct { 0145 hid_t mapl_id; /**< Get map access property list ID (OUT) */ 0146 } get_mapl; 0147 0148 /** H5VL_MAP_GET_MCPL */ 0149 struct { 0150 hid_t mcpl_id; /**< Get map creation property list ID (OUT) */ 0151 } get_mcpl; 0152 0153 /** H5VL_MAP_GET_KEY_TYPE */ 0154 struct { 0155 hid_t type_id; /**< Get datatype ID for map's keys (OUT) */ 0156 } get_key_type; 0157 0158 /** H5VL_MAP_GET_VAL_TYPE */ 0159 struct { 0160 hid_t type_id; /**< Get datatype ID for map's values (OUT) */ 0161 } get_val_type; 0162 0163 /** H5VL_MAP_GET_COUNT */ 0164 struct { 0165 hsize_t count; /**< Get number of key-value pairs in the map (OUT) */ 0166 } get_count; 0167 } args; 0168 } get; 0169 0170 /** H5VL_MAP_SPECIFIC */ 0171 struct { 0172 H5VL_map_specific_t specific_type; 0173 /**< 'specific' operation to perform */ 0174 0175 /** Parameters for each operation */ 0176 union { 0177 /* H5VL_MAP_ITER specific operation */ 0178 struct { 0179 H5VL_loc_params_t loc_params; /**< Location parameters for object */ 0180 hsize_t idx; /**< Start/end iteration index (IN/OUT) */ 0181 hid_t key_mem_type_id; /**< Memory datatype for key */ 0182 H5M_iterate_t op; /**< Iteration callback routine */ 0183 void *op_data; /**< Pointer to callback context */ 0184 } iterate; 0185 0186 /* H5VL_MAP_DELETE specific operation */ 0187 struct { 0188 H5VL_loc_params_t loc_params; /**< Location parameters for object */ 0189 hid_t key_mem_type_id; /**< Memory datatype for key */ 0190 const void *key; /**< Pointer to key */ 0191 } del; 0192 } args; 0193 } specific; 0194 0195 /** H5VL_MAP_OPTIONAL */ 0196 /* Unused */ 0197 0198 /** H5VL_MAP_CLOSE */ 0199 /* No args */ 0200 } H5VL_map_args_t; 0201 0202 /********************/ 0203 /* Public Variables */ 0204 /********************/ 0205 0206 /*********************/ 0207 /* Public Prototypes */ 0208 /*********************/ 0209 #ifdef __cplusplus 0210 extern "C" { 0211 #endif 0212 0213 /* The map API is only built when requested since there's no support in 0214 * the native file format at this time. It's only supported in a few VOL 0215 * connectors. 0216 */ 0217 #ifdef H5_HAVE_MAP_API 0218 0219 /** 0220 * \ingroup H5M 0221 * 0222 * \brief Creates a map object 0223 * 0224 * \fgdta_loc_id 0225 * \param[in] name Map object name 0226 * \type_id{key_type_id} 0227 * \type_id{val_type_id} 0228 * \lcpl_id 0229 * \mcpl_id 0230 * \mapl_id 0231 * \return \hid_t{map object} 0232 * 0233 * \details H5Mcreate() creates a new map object for storing key-value 0234 * pairs. The in-file datatype for keys is defined by \p key_type_id 0235 * and the in-file datatype for values is defined by \p val_type_id. \p 0236 * loc_id specifies the location to create the map object and \p 0237 * name specifies the name of the link to the map object relative to 0238 * \p loc_id. 0239 * 0240 * \since 1.12.0 0241 * 0242 */ 0243 H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, 0244 hid_t mcpl_id, hid_t mapl_id); 0245 /** 0246 * -------------------------------------------------------------------------- 0247 * \ingroup ASYNC 0248 * \async_variant_of{H5Mcreate} 0249 */ 0250 #ifndef H5_DOXYGEN 0251 H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, 0252 const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, 0253 hid_t mcpl_id, hid_t mapl_id, hid_t es_id); 0254 #else 0255 H5_DLL hid_t H5Mcreate_async(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, 0256 hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id, hid_t es_id); 0257 #endif 0258 0259 /** 0260 * \ingroup H5M 0261 * 0262 * \brief Creates a map object without linking it into a file 0263 * 0264 * \fgdta_loc_id 0265 * \type_id{key_type_id} 0266 * \type_id{val_type_id} 0267 * \mcpl_id 0268 * \mapl_id 0269 * \return \hid_t{map object} 0270 * The resulting ID should be linked into the file with H5Olink or it 0271 * will be deleted when closed. 0272 * 0273 * \details H5Mcreate_anon() creates a new map object for storing key-value 0274 * pairs. The in-file datatype for keys is defined by \p key_type_id 0275 * and the in-file datatype for values is defined by \p val_type_id. \p 0276 * loc_id specifies the file to create the map object, but no link to 0277 * the object is created. Other options can be specified through the 0278 * property lists \p mcpl_id and \p mapl_id. 0279 * 0280 * The new map should be linked into the group hierarchy before being 0281 * closed or it will be deleted. The map should be closed when the 0282 * caller no longer requires it. 0283 * 0284 * \since 1.12.0 0285 * 0286 */ 0287 H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id); 0288 0289 /** 0290 * \ingroup H5M 0291 * 0292 * \brief Opens a map object 0293 * 0294 * \fgdta_loc_id{loc_id} 0295 * \param[in] name Map object name relative to \p loc_id 0296 * \mapl_id 0297 * \return \hid_t{map object} 0298 * 0299 * \details H5Mopen() finds a map object specified by \p name under the location 0300 * specified by \p loc_id. The map object should be close with 0301 * H5Mclose() when the application is not longer interested in 0302 * accessing it. 0303 * 0304 * \since 1.12.0 0305 * 0306 */ 0307 H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); 0308 /** 0309 * -------------------------------------------------------------------------- 0310 * \ingroup ASYNC 0311 * \async_variant_of{H5Mopen} 0312 */ 0313 #ifndef H5_DOXYGEN 0314 H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, 0315 const char *name, hid_t mapl_id, hid_t es_id); 0316 #else 0317 H5_DLL hid_t H5Mopen_async(hid_t loc_id, const char *name, hid_t mapl_id, hid_t es_id); 0318 #endif 0319 0320 /** 0321 * \ingroup H5M 0322 * 0323 * \brief Terminates access to a map object 0324 * 0325 * \map_id 0326 * \return \herr_t 0327 * 0328 * \details H5Mclose() closes access to a map object specified by \p map_id and 0329 * releases resources used by it. 0330 * 0331 * It is illegal to subsequently use that same map identifier in calls 0332 * to other map functions. 0333 * 0334 * \since 1.12.0 0335 * 0336 */ 0337 H5_DLL herr_t H5Mclose(hid_t map_id); 0338 /** 0339 * -------------------------------------------------------------------------- 0340 * \ingroup ASYNC 0341 * \async_variant_of{H5Mclose} 0342 */ 0343 #ifndef H5_DOXYGEN 0344 H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, 0345 hid_t es_id); 0346 #else 0347 H5_DLL herr_t H5Mclose_async(hid_t map_id, hid_t es_id); 0348 #endif 0349 0350 /** 0351 * \ingroup H5M 0352 * 0353 * \brief Gets key datatype for a map object 0354 * 0355 * \map_id 0356 * \return \hid_t{datatype} 0357 * 0358 * \details H5Mget_key_type() retrieves key datatype as stored in the file for a 0359 * map object specified by \p map_id and returns identifier for the 0360 * datatype. 0361 * 0362 * \since 1.12.0 0363 * 0364 */ 0365 H5_DLL hid_t H5Mget_key_type(hid_t map_id); 0366 0367 /** 0368 * \ingroup H5M 0369 * 0370 * \brief Gets value datatype for a map object 0371 * 0372 * \map_id 0373 * \return \hid_t{datatype} 0374 * 0375 * \details H5Mget_val_type() retrieves value datatype as stored in the file for 0376 * a map object specified by \p map_id and returns identifier for the 0377 * datatype . 0378 * 0379 * \since 1.12.0 0380 * 0381 */ 0382 H5_DLL hid_t H5Mget_val_type(hid_t map_id); 0383 0384 /** 0385 * \ingroup H5M 0386 * 0387 * \brief Gets creation property list for a map object 0388 * 0389 * \map_id 0390 * \return \hid_t{map creation property list} 0391 * 0392 * \details H5Mget_create_plist() returns an identifier for a copy of the 0393 * creation property list for a map object specified by \p map_id. 0394 * 0395 * The creation property list identifier should be released with 0396 * H5Pclose() to prevent resource leaks. 0397 * 0398 * \since 1.12.0 0399 * 0400 */ 0401 H5_DLL hid_t H5Mget_create_plist(hid_t map_id); 0402 0403 /** 0404 * \ingroup H5M 0405 * 0406 * \brief Gets access property list for a map object 0407 * 0408 * \map_id 0409 * \return \hid_t{map access property list} 0410 * 0411 * \details H5Mget_access_plist() returns an identifier for a copy of the access 0412 * property list for a map object specified by \p map_id. 0413 * 0414 * \since 1.12.0 0415 * 0416 */ 0417 H5_DLL hid_t H5Mget_access_plist(hid_t map_id); 0418 0419 /** 0420 * \ingroup H5M 0421 * 0422 * \brief Retrieves the number of key-value pairs in a map object 0423 * 0424 * \map_id 0425 * \param[out] count The number of key-value pairs stored in the map object 0426 * \dxpl_id 0427 * \return \herr_t 0428 * 0429 * \details H5Mget_count() retrieves the number of key-value pairs stored in a 0430 * map specified by map_id. 0431 * 0432 * \since 1.12.0 0433 * 0434 */ 0435 H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); 0436 0437 /** 0438 * \ingroup H5M 0439 * 0440 * \brief Adds a key-value pair to a map object 0441 * 0442 * \map_id 0443 * \type_id{key_mem_type_id} 0444 * \param[in] key Pointer to key buffer 0445 * \type_id{val_mem_type_id} 0446 * \param[in] value Pointer to value buffer 0447 * \dxpl_id 0448 * \return \herr_t 0449 * 0450 * \details H5Mput() adds a key-value pair to a map object specified by \p 0451 * map_id, or updates the value for the specified key if one was set 0452 * previously. 0453 * 0454 * \p key_mem_type_id and \p val_mem_type_id specify the datatypes for 0455 * the provided key and value buffers, and if different from those used 0456 * to create the map object, the key and value will be internally 0457 * converted to the datatypes for the map object. 0458 * 0459 * Any further options can be specified through the property list 0460 * \p dxpl_id. 0461 * 0462 * \since 1.12.0 0463 * 0464 */ 0465 H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, 0466 const void *value, hid_t dxpl_id); 0467 /** 0468 * -------------------------------------------------------------------------- 0469 * \ingroup ASYNC 0470 * \async_variant_of{H5Mput} 0471 */ 0472 #ifndef H5_DOXYGEN 0473 H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, 0474 hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, 0475 hid_t dxpl_id, hid_t es_id); 0476 #else 0477 H5_DLL herr_t H5Mput_async(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, 0478 const void *value, hid_t dxpl_id, hid_t es_id); 0479 #endif 0480 0481 /** 0482 * \ingroup H5M 0483 * 0484 * \brief Retrieves a key-value pair from a map object 0485 * 0486 * \map_id 0487 * \type_id{key_mem_type_id} 0488 * \param[in] key Pointer to key buffer 0489 * \type_id{val_mem_type_id} 0490 * \param[out] value Pointer to value buffer 0491 * \dxpl_id 0492 * \return \herr_t 0493 * 0494 * \details H5Mget() retrieves from a map object specified by \p map_id, the 0495 * value associated with the provided key \p key. \p key_mem_type_id 0496 * and \p val_mem_type_id specify the datatypes for the provided key 0497 * and value buffers. If if the datatype specified by \p 0498 * key_mem_type_id is different from that used to create the map object 0499 * the key will be internally converted to the datatype for the map 0500 * object for the query, and if the datatype specified by \p 0501 * val_mem_type_id is different from that used to create the map object 0502 * the returned value will be converted to have a datatype as specified 0503 * by \p val_mem_type_id before the function returns. 0504 * 0505 * Any further options can be specified through the property list 0506 * \p dxpl_id. 0507 * 0508 * \since 1.12.0 0509 * 0510 */ 0511 H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, 0512 hid_t dxpl_id); 0513 /** 0514 * -------------------------------------------------------------------------- 0515 * \ingroup ASYNC 0516 * \async_variant_of{H5Mget} 0517 */ 0518 #ifndef H5_DOXYGEN 0519 H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, 0520 hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, 0521 hid_t dxpl_id, hid_t es_id); 0522 #else 0523 H5_DLL herr_t H5Mget_async(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, 0524 void *value, hid_t dxpl_id, hid_t es_id); 0525 #endif 0526 0527 /** 0528 * \ingroup H5M 0529 * 0530 * \brief Checks if provided key exists in a map object 0531 * 0532 * \map_id 0533 * \type_id{key_mem_type_id} 0534 * \param[in] key Pointer to key buffer 0535 * \param[out] exists Pointer to a buffer to return the existence status 0536 * \dxpl_id 0537 * \return \herr_t 0538 * 0539 * \details H5Mexists() checks if the provided key is stored in the map object 0540 * specified by \p map_id. If \p key_mem_type_id is different from that 0541 * used to create the map object the key will be internally converted 0542 * to the datatype for the map object for the query. 0543 * 0544 * Any further options can be specified through the property list 0545 * \p dxpl_id. 0546 * 0547 * \since 1.12.0 0548 * 0549 */ 0550 H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id); 0551 0552 /** 0553 * \ingroup H5M 0554 * 0555 * \brief Iterates over all key-value pairs in a map object 0556 * 0557 * \map_id 0558 * \param[in,out] idx iteration index 0559 * \type_id{key_mem_type_id} 0560 * \param[in] op User-defined iterator function 0561 * \op_data 0562 * \dxpl_id 0563 * \return \herr_t 0564 * 0565 * \details H5Miterate() iterates over all key-value pairs stored in the map 0566 * object specified by \p map_id, making the callback specified by \p 0567 * op for each. The \p idx parameter is an in/out parameter that may be 0568 * used to restart a previously interrupted iteration. At the start of 0569 * iteration \p idx should be set to 0, and to restart iteration at the 0570 * same location on a subsequent call to H5Miterate(), \p idx should be 0571 * the same value as returned by the previous call. Iterate callback is 0572 * defined as: 0573 * \snippet this H5M_iterate_t_snip 0574 * The \p key parameter is the buffer for the key for this iteration, 0575 * converted to the datatype specified by \p key_mem_type_id. The \p 0576 * op_data parameter is a simple pass through of the value passed to 0577 * H5Miterate(), which can be used to store application-defined data for 0578 * iteration. A negative return value from this function will cause 0579 * H5Miterate() to issue an error, while a positive return value will 0580 * cause H5Miterate() to stop iterating and return this value without 0581 * issuing an error. A return value of zero allows iteration to continue. 0582 * 0583 * Any further options can be specified through the property list \p dxpl_id. 0584 * 0585 * \warning Adding or removing key-value pairs to the map during iteration 0586 * will lead to undefined behavior. 0587 * 0588 * \callback_note 0589 * 0590 * \since 1.12.0 0591 * 0592 */ 0593 H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, 0594 hid_t dxpl_id); 0595 0596 /** 0597 * \ingroup H5M 0598 * 0599 * \brief Iterates over all key-value pairs in a map object 0600 * 0601 * \loc_id 0602 * \param[in] map_name Map object name relative to the location specified by \p loc_id 0603 * \param[in,out] idx Iteration index 0604 * \type_id{key_mem_type_id} 0605 * \param[in] op User-defined iterator function 0606 * \op_data 0607 * \dxpl_id 0608 * \lapl_id 0609 * \return \herr_t 0610 * 0611 * \details H5Miterate_by_name() iterates over all key-value pairs stored in the 0612 * map object specified by \p map_id, making the callback specified by 0613 * \p op for each. The \p idx parameter is an in/out parameter that may 0614 * be used to restart a previously interrupted iteration. At the start 0615 * of iteration \p idx should be set to 0, and to restart iteration at 0616 * the same location on a subsequent call to H5Miterate(), \p idx 0617 * should be the same value as returned by the previous call. Iterate 0618 * callback is defined as: 0619 * \snippet this H5M_iterate_t_snip 0620 * The\p key parameter is the buffer for the key for this iteration, 0621 * converted to the datatype specified by \p key_mem_type_id. The \p 0622 * op_data parameter is a simple pass through of the value passed to 0623 * H5Miterate(), which can be used to store application-defined data 0624 * for iteration. A negative return value from this function will cause 0625 * H5Miterate() to issue an error, while a positive return value will cause 0626 * H5Miterate() to stop iterating and return this value without issuing an 0627 * error. A return value of zero allows iteration to continue. 0628 * 0629 * Any further options can be specified through the property list \p dxpl_id. 0630 * 0631 * \warning Adding or removing key-value pairs to the map during iteration 0632 * will lead to undefined behavior. 0633 * 0634 * \callback_note 0635 * 0636 * \since 1.12.0 0637 * 0638 */ 0639 H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id, 0640 H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id); 0641 0642 /** 0643 * \ingroup H5M 0644 * 0645 * \brief Deletes a key-value pair from a map object 0646 * 0647 * \map_id 0648 * \type_id{key_mem_type_id} 0649 * \param[in] key Pointer to key buffer 0650 * \dxpl_id 0651 * \return \herr_t 0652 * 0653 * \details H5Mdelete() deletes a key-value pair from the map object specified 0654 * by \p map_id. \p key_mem_type_id specifies the datatype for the 0655 * provided key buffer key, and if different from that used to create 0656 * the map object, the key will be internally converted to the datatype 0657 * for the map object. 0658 * 0659 * Any further options can be specified through the property list \p dxpl_id. 0660 * 0661 * \since 1.12.0 0662 * 0663 */ 0664 H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); 0665 0666 /// \cond DEV 0667 /* API Wrappers for async routines */ 0668 /* (Must be defined _after_ the function prototype) */ 0669 /* (And must only defined when included in application code, not the library) */ 0670 #ifndef H5M_MODULE 0671 #define H5Mcreate_async(...) H5Mcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0672 #define H5Mopen_async(...) H5Mopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0673 #define H5Mclose_async(...) H5Mclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0674 #define H5Mput_async(...) H5Mput_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0675 #define H5Mget_async(...) H5Mget_async(__FILE__, __func__, __LINE__, __VA_ARGS__) 0676 0677 /* Define "wrapper" versions of function calls, to allow compile-time values to 0678 * be passed in by language wrapper or library layer on top of HDF5. */ 0679 #define H5Mcreate_async_wrap H5_NO_EXPAND(H5Mcreate_async) 0680 #define H5Mopen_async_wrap H5_NO_EXPAND(H5Mopen_async) 0681 #define H5Mclose_async_wrap H5_NO_EXPAND(H5Mclose_async) 0682 #define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async) 0683 #define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async) 0684 #endif /* H5M_MODULE */ 0685 /// \endcond 0686 0687 /* Symbols defined for compatibility with previous versions of the HDF5 API. 0688 * 0689 * Use of these symbols is deprecated. 0690 */ 0691 #ifndef H5_NO_DEPRECATED_SYMBOLS 0692 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 0693 0694 #endif /* H5_HAVE_MAP_API */ 0695 0696 #ifdef __cplusplus 0697 } 0698 #endif 0699 0700 #endif /* H5Mpublic_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|