diff options
Diffstat (limited to 'src/H5Ldevelop.h')
| -rw-r--r-- | src/H5Ldevelop.h | 314 |
1 files changed, 314 insertions, 0 deletions
diff --git a/src/H5Ldevelop.h b/src/H5Ldevelop.h new file mode 100644 index 0000000..43ed7de --- /dev/null +++ b/src/H5Ldevelop.h @@ -0,0 +1,314 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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://support.hdfgroup.org/ftp/HDF5/releases. * + * 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 H5L (link) developer + * support routines. + */ + +#ifndef _H5Ldevelop_H +#define _H5Ldevelop_H + +/* Include package's public header */ +#include "H5Lpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/** + * \brief Current version of the H5L_class_t struct + */ +#define H5L_LINK_CLASS_T_VERS 1 + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/* The H5L_class_t struct can be used to override the behavior of a + * "user-defined" link class. Users should populate the struct with callback + * functions defined below. + */ +/* Callback prototypes for user-defined links */ +/** + * \brief Link creation callback + */ +typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, + size_t lnkdata_size, hid_t lcpl_id); +/** + * \brief Callback for link move + */ +typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback for link copy + */ +typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback during link traversal + */ +typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, + size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id); +/** + * \brief Callback for link deletion + */ +typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback for querying the link. + * + * Returns the size of the buffer needed. + */ +typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, + void *buf /*out*/, size_t buf_size); + +/** + * \brief Link prototype + * + * The H5L_class_t struct can be used to override the behavior of a + * "user-defined" link class. Users should populate the struct with callback + * functions defined elsewhere. + */ +//! <!-- [H5L_class_t_snip] --> +typedef struct { + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char * comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ +} H5L_class_t; +//! <!-- [H5L_class_t_snip] --> + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup H5LA + * + * \brief Registers a user-defined link class or changes behavior of an + * existing class + * + * \param[in] cls Pointer to a buffer containing the struct describing the + * user-defined link class + * + * \return \herr_t + * + * \details H5Lregister() registers a class of user-defined links, or changes + * the behavior of an existing class. + * + * \p cls is a pointer to a buffer containing a copy of the + * H5L_class_t struct. This struct is defined in H5Lpublic.h as + * follows: + * \snippet this H5L_class_t_snip + * + * The class definition passed with \p cls must include at least the + * following: + * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) + * \li A link class identifier, \c class_id + * \li A traversal function, \c trav_func + * + * Remaining \c struct members are optional and may be passed as NULL. + * + * The link class passed in \c class_id must be in the user-definable + * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX + * (see the table below) and will override + * any existing link class with that identifier. + * + * As distributed, valid values of \c class_id used in HDF5 include + * the following (defined in H5Lpublic.h): + * \link_types + * + * The hard and soft link class identifiers cannot be modified or + * reassigned, but the external link class is implemented as an + * example in the user-definable link class identifier range. + * H5Lregister() is used to register additional link classes. It could + * also be used to modify the behavior of the external link class, + * though that is not recommended. + * + * The following table summarizes existing link types and values and + * the reserved and user-definable link class identifier value ranges. + * <table> + * <tr> + * <th>Link class identifier or Value range</th> + * <th>Description</th> + * <th>Link class or label</th> + * </tr> + * <tr> + * <td>0 to 63</td> + * <td>Reserved range</td> + * <td></td> + * </tr> + * <tr> + * <td>64 to 255</td> + * <td>User-definable range</td> + * <td></td> + * </tr> + * <tr> + * <td>64</td> + * <td>Minimum user-defined value</td> + * <td>#H5L_TYPE_UD_MIN</td> + * </tr> + * <tr> + * <td>64</td> + * <td>External link</td> + * <td>#H5L_TYPE_EXTERNAL</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum user-defined value</td> + * <td>#H5L_TYPE_UD_MAX</td> + * </tr> + * <tr> + * <td>255</td> + * <td>Maximum value</td> + * <td>#H5L_TYPE_MAX</td> + * </tr> + * <tr> + * <td>-1</td> + * <td>Error</td> + * <td>#H5L_TYPE_ERROR</td> + * </tr> + * </table> + * + * Note that HDF5 internally registers user-defined link classes only + * by the numeric value of the link class identifier. An application, + * on the other hand, will generally use a name for a user-defined + * class, if for no other purpose than as a variable name. Assume, + * for example, that a complex link type is registered with the link + * class identifier 73 and that the code includes the following + * assignment: + * \code + * H5L_TYPE_COMPLEX_A = 73 + * \endcode + * The application can refer to the link class with a term, + * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing + * the code, while HDF5 recognizes it by the more cryptic numeric + * identifier, 73. + * + * \attention Important details and considerations include the following: + * \li If you plan to distribute files or software with a + * user-defined link class, please contact the Help Desk at + * The HDF Group to help prevent collisions between \c class_id + * values. See below. + * \li As distributed with HDF5, the external link class is + * implemented as an example of a user-defined link class with + * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in + * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN + * unless you intend to overwrite or modify the behavior of + * external links. + * \li H5Lregister() can be used only with link class identifiers + * in the user-definable range (see table above). + * \li The hard and soft links defined by the HDF5 library, + * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved + * range below #H5L_TYPE_UD_MIN and cannot be redefined or + * modified. + * \li H5Lis_registered() can be used to determine whether a desired + * link class identifier is available. \Emph{Note that this + * function will tell you only whether the link class identifier + * has been registered with the installed copy of HDF5; it + * cannot tell you whether the link class has been registered + * with The HDF Group.} + * \li #H5L_TYPE_MAX is the maximum allowed value for a link type + * identifier. + * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. + * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. + * \li #H5L_TYPE_ERROR indicates that an error has occurred. + * + * \note \Bold{Registration with The HDF Group:}\n + * There are sometimes reasons to take a broader approach to registering + * a user-defined link class than just invoking H5Lregister(). For + * example: + * \li A user-defined link class is intended for use across an + * organization, among collaborators, or across a community of users. + * \li An application or library overlying HDF5 invokes a user-defined + * link class that must be shipped with the software. + * \li Files are distributed that make use of a user-defined link class. + * \li Or simply, a specific user-defined link class is thought to be + * widely useful. + * + * In such cases, you are encouraged to register that link class with + * The HDF Group's Helpdesk. The HDF Group maintains a registry of known + * user-defined link classes and tracks the selected link class + * identifiers. This registry is intended to reduce the risk of + * collisions between \c class_id values and to help coordinate the use + * of specialized link classes. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lregister(const H5L_class_t *cls); +/** + * \ingroup H5LA + * + * \brief Unregisters a class of user-defined links + * + * \param[in] id User-defined link class identifier + * + * \return \herr_t + * + * \details H5Lunregister() unregisters a class of user-defined links, + * preventing them from being traversed, queried, moved, etc. + * + * \note A link class can be re-registered using H5Lregister(). + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lunregister(H5L_type_t id); + +#ifdef __cplusplus +} +#endif + +/* Symbols defined for compatibility with previous versions of the HDF5 API. + * + * Use of these symbols is deprecated. + */ +#ifndef H5_NO_DEPRECATED_SYMBOLS + +/* Previous versions of the H5L_class_t struct */ +#define H5L_LINK_CLASS_T_VERS_0 0 + +/** Callback during link traversal */ +typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, + size_t lnkdata_size, hid_t lapl_id); + +/** User-defined link types */ +typedef struct { + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char * comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ +} H5L_class_0_t; + +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + +#endif /* _H5Ldevelop_H */ |