diff options
Diffstat (limited to 'src/H5Mpublic.h')
| -rw-r--r-- | src/H5Mpublic.h | 647 |
1 files changed, 647 insertions, 0 deletions
diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h new file mode 100644 index 0000000..2cea579 --- /dev/null +++ b/src/H5Mpublic.h @@ -0,0 +1,647 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5M module. + * + * NOTE: This is an experimental API. Everything in the H5M package + * is subject to revision in a future release. + */ +#ifndef H5Mpublic_H +#define H5Mpublic_H + +/* System headers needed by this file */ + +/* Public headers needed by this file */ +#include "H5public.h" +#include "H5Ipublic.h" +#include "H5VLconnector.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/* Macros defining operation IDs for map VOL callbacks (implemented using the + * "optional" VOL callback) */ +#define H5VL_MAP_CREATE 1 +#define H5VL_MAP_OPEN 2 +#define H5VL_MAP_GET_VAL 3 +#define H5VL_MAP_EXISTS 4 +#define H5VL_MAP_PUT 5 +#define H5VL_MAP_GET 6 +#define H5VL_MAP_SPECIFIC 7 +#define H5VL_MAP_OPTIONAL 8 +#define H5VL_MAP_CLOSE 9 + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/* types for map GET callback */ +typedef enum H5VL_map_get_t { + H5VL_MAP_GET_MAPL, /* map access property list */ + H5VL_MAP_GET_MCPL, /* map creation property list */ + H5VL_MAP_GET_KEY_TYPE, /* key type */ + H5VL_MAP_GET_VAL_TYPE, /* value type */ + H5VL_MAP_GET_COUNT /* key count */ +} H5VL_map_get_t; + +/* types for map SPECIFIC callback */ +typedef enum H5VL_map_specific_t { + H5VL_MAP_ITER, /* H5Miterate */ + H5VL_MAP_DELETE /* H5Mdelete */ +} H5VL_map_specific_t; + +//! <!-- [H5M_iterate_t_snip] --> +/** + * Callback for H5Miterate() + */ +typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); +//! <!-- [H5M_iterate_t_snip] --> + +/* Parameters for map operations */ +typedef union H5VL_map_args_t { + /* H5VL_MAP_CREATE */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + const char *name; /* Name of new map object */ + hid_t lcpl_id; /* Link creation property list for map */ + hid_t key_type_id; /* Datatype for map keys */ + hid_t val_type_id; /* Datatype for map values */ + hid_t mcpl_id; /* Map creation property list */ + hid_t mapl_id; /* Map access property list */ + void *map; /* Pointer to newly created map object (OUT) */ + } create; + + /* H5VL_MAP_OPEN */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + const char *name; /* Name of new map object */ + hid_t mapl_id; /* Map access property list */ + void *map; /* Pointer to newly created map object (OUT) */ + } open; + + /* H5VL_MAP_GET_VAL */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hid_t value_mem_type_id; /* Memory datatype for value */ + void *value; /* Buffer for value (OUT) */ + } get_val; + + /* H5VL_MAP_EXISTS */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hbool_t exists; /* Flag indicating whether key exists in map (OUT) */ + } exists; + + /* H5VL_MAP_PUT */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hid_t value_mem_type_id; /* Memory datatype for value */ + const void *value; /* Pointer to value */ + } put; + + /* H5VL_MAP_GET */ + struct { + H5VL_map_get_t get_type; /* 'get' operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_MAP_GET_MAPL */ + struct { + hid_t mapl_id; /* Map access property list ID (OUT) */ + } get_mapl; + + /* H5VL_MAP_GET_MCPL */ + struct { + hid_t mcpl_id; /* Map creation property list ID (OUT) */ + } get_mcpl; + + /* H5VL_MAP_GET_KEY_TYPE */ + struct { + hid_t type_id; /* Datatype ID for map's keys (OUT) */ + } get_key_type; + + /* H5VL_MAP_GET_VAL_TYPE */ + struct { + hid_t type_id; /* Datatype ID for map's values (OUT) */ + } get_val_type; + + /* H5VL_MAP_GET_COUNT */ + struct { + hsize_t count; /* # of KV pairs in map (OUT) */ + } get_count; + } args; + } get; + + /* H5VL_MAP_SPECIFIC */ + struct { + H5VL_map_specific_t specific_type; /* 'specific' operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_MAP_ITER */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + hsize_t idx; /* Start/end iteration index (IN/OUT) */ + hid_t key_mem_type_id; /* Memory datatype for key */ + H5M_iterate_t op; /* Iteration callback routine */ + void *op_data; /* Pointer to callback context */ + } iterate; + + /* H5VL_MAP_DELETE */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + } del; + } args; + } specific; + + /* H5VL_MAP_OPTIONAL */ + /* Unused */ + + /* H5VL_MAP_CLOSE */ + /* No args */ +} H5VL_map_args_t; + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ +#ifdef __cplusplus +extern "C" { +#endif + +/* The map API is only built when requested since there's no support in + * the native file format at this time. It's only supported in a few VOL + * connectors. + */ +#ifdef H5_HAVE_MAP_API + +/** + * \ingroup H5M + * + * \brief Creates a map object + * + * \fgdta_loc_id + * \param[in] name Map object name + * \type_id{key_type_id} + * \type_id{val_type_id} + * \lcpl_id + * \mcpl_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mcreate() creates a new map object for storing key-value + * pairs. The in-file datatype for keys is defined by \p key_type_id + * and the in-file datatype for values is defined by \p val_type_id. \p + * loc_id specifies the location to create the the map object and \p + * name specifies the name of the link to the map object relative to + * \p loc_id. + * + * \since 1.12.0 + * + */ +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, + hid_t mcpl_id, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mcreate} + */ +#ifndef H5_DOXYGEN +H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, + const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, + hid_t mcpl_id, hid_t mapl_id, hid_t es_id); +#else +H5_DLL hid_t H5Mcreate_async(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, + hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id, hid_t es_id); +#endif + +/** + * \ingroup H5M + * + * \brief + * + * \details + * + * \since 1.12.0 + * + */ +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); + +/** + * \ingroup H5M + * + * \brief Opens a map object + * + * \fgdta_loc_id{loc_id} + * \param[in] name Map object name relative to \p loc_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mopen() finds a map object specified by \p name under the location + * specified by \p loc_id. The map object should be close with + * H5Mclose() when the application is not longer interested in + * accessing it. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mopen} + */ +#ifndef H5_DOXYGEN +H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, + const char *name, hid_t mapl_id, hid_t es_id); +#else +H5_DLL hid_t H5Mopen_async(hid_t loc_id, const char *name, hid_t mapl_id, hid_t es_id); +#endif + +/** + * \ingroup H5M + * + * \brief Terminates access to a map object + * + * \map_id + * \returns \herr_t + * + * \details H5Mclose() closes access to a map object specified by \p map_id and + * releases resources used by it. + * + * It is illegal to subsequently use that same map identifier in calls + * to other map functions. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Mclose(hid_t map_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mclose} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, + hid_t es_id); +#else +H5_DLL herr_t H5Mclose_async(hid_t map_id, hid_t es_id); +#endif + +/** + * \ingroup H5M + * + * \brief Gets key datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_key_type() retrieves key datatype as stored in the file for a + * map object specified by \p map_id and returns identifier for the + * datatype. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_key_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets value datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_val_type() retrieves value datatype as stored in the file for + * a map object specified by \p map_id and returns identifier for the + * datatype . + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_val_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets creation property list for a map object + * + * \map_id + * \returns \hid_t{map creation property list} + * + * \details H5Mget_create_plist() returns an identifier for a copy of the + * creation property list for a map object specified by \p map_id. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_create_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets access property list for a map object + * + * \map_id + * \returns \hid_t{map access property list} + * + * \details H5Mget_access_plist() returns an identifier for a copy of the access + * property list for a map object specified by \p map_id. + * + * \since 1.12.0 + * + */ +H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Retrieves the number of key-value pairs in a map object + * + * \map_id + * \param[out] count The number of key-value pairs stored in the map object + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget_count() retrieves the number of key-value pairs stored in a + * map specified by map_id. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Adds a key-value pair to a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[in] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mput() adds a key-value pair to a map object specified by \p + * map_id, or updates the value for the specified key if one was set + * previously. + * + * \p key_mem_type_id and \p val_mem_type_id specify the datatypes for + * the provided key and value buffers, and if different from those used + * to create the map object, the key and value will be internally + * converted to the datatypes for the map object. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, + const void *value, hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mput} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, + hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, + hid_t dxpl_id, hid_t es_id); +#else +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, + const void *value, hid_t dxpl_id, hid_t es_id); +#endif + +/** + * \ingroup H5M + * + * \brief Retrieves a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[out] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget() retrieves from a map object specified by \p map_id, the + * value associated with the provided key \p key. \p key_mem_type_id + * and \p val_mem_type_id specify the datatypes for the provided key + * and value buffers. If if the datatype specified by \p + * key_mem_type_id is different from that used to create the map object + * the key will be internally converted to the datatype for the map + * object for the query, and if the datatype specified by \p + * val_mem_type_id is different from that used to create the map object + * the returned value will be converted to have a datatype as specified + * by \p val_mem_type_id before the function returns. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ +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, + hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mget} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, + hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, + hid_t dxpl_id, hid_t es_id); +#else +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, + void *value, hid_t dxpl_id, hid_t es_id); +#endif + +/** + * \ingroup H5M + * + * \brief Checks if provided key exists in a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \param[out] exists Pointer to a buffer to return the existence status + * \dxpl_id + * \returns \herr_t + * + * \details H5Mexists() checks if the provided key is stored in the map object + * specified by \p map_id. If \p key_mem_type_id is different from that + * used to create the map object the key will be internally converted + * to the datatype for the map object for the query. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.12.0 + * + */ +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); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \map_id + * \param[in,out] idx iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \returns \herr_t + * + * \details H5Miterate() iterates over all key-value pairs stored in the map + * object specified by \p map_id, making the callback specified by \p + * op for each. The \p idx parameter is an in/out parameter that may be + * used to restart a previously interrupted iteration. At the start of + * iteration \p idx should be set to 0, and to restart iteration at the + * same location on a subsequent call to H5Miterate(), \p idx should be + * the same value as returned by the previous call. Iterate callback is + * defined as: + * \snippet this H5M_iterate_t_snip + * The \p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data for + * iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will + * cause H5Miterate() to stop iterating and return this value without + * issuing an error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ +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, + hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \loc_id + * \param[in] map_name Map object name relative to the location specified by \p loc_id + * \param[in,out] idx Iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \lapl_id + * \returns \herr_t + * + * \details H5Miterate_by_name() iterates over all key-value pairs stored in the + * map object specified by \p map_id, making the callback specified by + * \p op for each. The \p idx parameter is an in/out parameter that may + * be used to restart a previously interrupted iteration. At the start + * of iteration \p idx should be set to 0, and to restart iteration at + * the same location on a subsequent call to H5Miterate(), \p idx + * should be the same value as returned by the previous call. Iterate + * callback is defined as: + * \snippet this H5M_iterate_t_snip + * The\p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data + * for iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will cause + * H5Miterate() to stop iterating and return this value without issuing an + * error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id, + H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id); + +/** + * \ingroup H5M + * + * \brief Deletes a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mdelete() deletes a key-value pair from the map object specified + * by \p map_id. \p key_mem_type_id specifies the datatype for the + * provided key buffer key, and if different from that used to create + * the map object, the key will be internally converted to the datatype + * for the map object. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.12.0 + * + */ +H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); + +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5M_MODULE +#define H5Mcreate_async(...) H5Mcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mopen_async(...) H5Mopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mclose_async(...) H5Mclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mput_async(...) H5Mput_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mget_async(...) H5Mget_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. */ +#define H5Mcreate_async_wrap H5_NO_EXPAND(H5Mcreate_async) +#define H5Mopen_async_wrap H5_NO_EXPAND(H5Mopen_async) +#define H5Mclose_async_wrap H5_NO_EXPAND(H5Mclose_async) +#define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async) +#define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async) +#endif /* H5M_MODULE */ +/// \endcond + +/* Symbols defined for compatibility with previous versions of the HDF5 API. + * + * Use of these symbols is deprecated. + */ +#ifndef H5_NO_DEPRECATED_SYMBOLS +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + +#endif /* H5_HAVE_MAP_API */ + +#ifdef __cplusplus +} +#endif + +#endif /* H5Mpublic_H */ |