EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-04-18 09:16:03
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 H5L (link) developer 0015 * support routines. 0016 */ 0017 0018 #ifndef H5Ldevelop_H 0019 #define H5Ldevelop_H 0020 0021 /* Include package's public header */ 0022 #include "H5Lpublic.h" 0023 0024 /*****************/ 0025 /* Public Macros */ 0026 /*****************/ 0027 0028 /** 0029 * \brief Current version of the H5L_class_t struct 0030 */ 0031 #define H5L_LINK_CLASS_T_VERS 1 0032 0033 /** 0034 * \brief Version of external link format 0035 */ 0036 #define H5L_EXT_VERSION 0 0037 0038 /** 0039 * \brief Valid flags for external links 0040 */ 0041 #define H5L_EXT_FLAGS_ALL 0 0042 0043 /*******************/ 0044 /* Public Typedefs */ 0045 /*******************/ 0046 0047 /* The H5L_class_t struct can be used to override the behavior of a 0048 * "user-defined" link class. Users should populate the struct with callback 0049 * functions defined below. 0050 */ 0051 /* Callback prototypes for user-defined links */ 0052 /** 0053 * \brief Link creation callback 0054 */ 0055 typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, 0056 size_t lnkdata_size, hid_t lcpl_id); 0057 /** 0058 * \brief Callback for link move 0059 */ 0060 typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, 0061 size_t lnkdata_size); 0062 /** 0063 * \brief Callback for link copy 0064 */ 0065 typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, 0066 size_t lnkdata_size); 0067 /** 0068 * \brief Callback during link traversal 0069 */ 0070 typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, 0071 size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id); 0072 /** 0073 * \brief Callback for link deletion 0074 */ 0075 typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, 0076 size_t lnkdata_size); 0077 /** 0078 * \brief Callback for querying the link. 0079 * 0080 * Returns the size of the buffer needed. 0081 */ 0082 typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, 0083 void *buf /*out*/, size_t buf_size); 0084 0085 /** 0086 * \brief Link prototype 0087 * 0088 * The H5L_class_t struct can be used to override the behavior of a 0089 * "user-defined" link class. Users should populate the struct with callback 0090 * functions defined elsewhere. 0091 */ 0092 //! <!-- [H5L_class_t_snip] --> 0093 typedef struct { 0094 int version; /**< Version number of this struct */ 0095 H5L_type_t id; /**< Link type ID */ 0096 const char *comment; /**< Comment for debugging */ 0097 H5L_create_func_t create_func; /**< Callback during link creation */ 0098 H5L_move_func_t move_func; /**< Callback after moving link */ 0099 H5L_copy_func_t copy_func; /**< Callback after copying link */ 0100 H5L_traverse_func_t trav_func; /**< Callback during link traversal */ 0101 H5L_delete_func_t del_func; /**< Callback for link deletion */ 0102 H5L_query_func_t query_func; /**< Callback for queries */ 0103 } H5L_class_t; 0104 //! <!-- [H5L_class_t_snip] --> 0105 0106 /********************/ 0107 /* Public Variables */ 0108 /********************/ 0109 0110 /*********************/ 0111 /* Public Prototypes */ 0112 /*********************/ 0113 0114 #ifdef __cplusplus 0115 extern "C" { 0116 #endif 0117 0118 /** 0119 * \ingroup H5LA 0120 * 0121 * \brief Registers a user-defined link class or changes behavior of an 0122 * existing class 0123 * 0124 * \param[in] cls Pointer to a buffer containing the struct describing the 0125 * user-defined link class 0126 * 0127 * \return \herr_t 0128 * 0129 * \details H5Lregister() registers a class of user-defined links, or changes 0130 * the behavior of an existing class. 0131 * 0132 * \p cls is a pointer to a buffer containing a copy of the 0133 * H5L_class_t struct. This struct is defined in H5Lpublic.h as 0134 * follows: 0135 * \snippet this H5L_class_t_snip 0136 * 0137 * The class definition passed with \p cls must include at least the 0138 * following: 0139 * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) 0140 * \li A link class identifier, \c class_id 0141 * \li A traversal function, \c trav_func 0142 * 0143 * Remaining \c struct members are optional and may be passed as NULL. 0144 * 0145 * The link class passed in \c class_id must be in the user-definable 0146 * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX 0147 * (see the table below) and will override 0148 * any existing link class with that identifier. 0149 * 0150 * As distributed, valid values of \c class_id used in HDF5 include 0151 * the following (defined in H5Lpublic.h): 0152 * \link_types 0153 * 0154 * The hard and soft link class identifiers cannot be modified or 0155 * reassigned, but the external link class is implemented as an 0156 * example in the user-definable link class identifier range. 0157 * H5Lregister() is used to register additional link classes. It could 0158 * also be used to modify the behavior of the external link class, 0159 * though that is not recommended. 0160 * 0161 * The following table summarizes existing link types and values and 0162 * the reserved and user-definable link class identifier value ranges. 0163 * <table> 0164 * <tr> 0165 * <th>Link class identifier or Value range</th> 0166 * <th>Description</th> 0167 * <th>Link class or label</th> 0168 * </tr> 0169 * <tr> 0170 * <td>0 to 63</td> 0171 * <td>Reserved range</td> 0172 * <td></td> 0173 * </tr> 0174 * <tr> 0175 * <td>64 to 255</td> 0176 * <td>User-definable range</td> 0177 * <td></td> 0178 * </tr> 0179 * <tr> 0180 * <td>64</td> 0181 * <td>Minimum user-defined value</td> 0182 * <td>#H5L_TYPE_UD_MIN</td> 0183 * </tr> 0184 * <tr> 0185 * <td>64</td> 0186 * <td>External link</td> 0187 * <td>#H5L_TYPE_EXTERNAL</td> 0188 * </tr> 0189 * <tr> 0190 * <td>255</td> 0191 * <td>Maximum user-defined value</td> 0192 * <td>#H5L_TYPE_UD_MAX</td> 0193 * </tr> 0194 * <tr> 0195 * <td>255</td> 0196 * <td>Maximum value</td> 0197 * <td>#H5L_TYPE_MAX</td> 0198 * </tr> 0199 * <tr> 0200 * <td>-1</td> 0201 * <td>Error</td> 0202 * <td>#H5L_TYPE_ERROR</td> 0203 * </tr> 0204 * </table> 0205 * 0206 * Note that HDF5 internally registers user-defined link classes only 0207 * by the numeric value of the link class identifier. An application, 0208 * on the other hand, will generally use a name for a user-defined 0209 * class, if for no other purpose than as a variable name. Assume, 0210 * for example, that a complex link type is registered with the link 0211 * class identifier 73 and that the code includes the following 0212 * assignment: 0213 * \code 0214 * H5L_TYPE_COMPLEX_A = 73 0215 * \endcode 0216 * The application can refer to the link class with a term, 0217 * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing 0218 * the code, while HDF5 recognizes it by the more cryptic numeric 0219 * identifier, 73. 0220 * 0221 * \attention Important details and considerations include the following: 0222 * \li If you plan to distribute files or software with a 0223 * user-defined link class, please contact the Help Desk at 0224 * The HDF Group to help prevent collisions between \c class_id 0225 * values. See below. 0226 * \li As distributed with HDF5, the external link class is 0227 * implemented as an example of a user-defined link class with 0228 * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in 0229 * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN 0230 * unless you intend to overwrite or modify the behavior of 0231 * external links. 0232 * \li H5Lregister() can be used only with link class identifiers 0233 * in the user-definable range (see table above). 0234 * \li The hard and soft links defined by the HDF5 library, 0235 * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved 0236 * range below #H5L_TYPE_UD_MIN and cannot be redefined or 0237 * modified. 0238 * \li H5Lis_registered() can be used to determine whether a desired 0239 * link class identifier is available. \Emph{Note that this 0240 * function will tell you only whether the link class identifier 0241 * has been registered with the installed copy of HDF5; it 0242 * cannot tell you whether the link class has been registered 0243 * with The HDF Group.} 0244 * \li #H5L_TYPE_MAX is the maximum allowed value for a link type 0245 * identifier. 0246 * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. 0247 * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. 0248 * \li #H5L_TYPE_ERROR indicates that an error has occurred. 0249 * 0250 * \note \Bold{Registration with The HDF Group:}\n 0251 * There are sometimes reasons to take a broader approach to registering 0252 * a user-defined link class than just invoking H5Lregister(). For 0253 * example: 0254 * \li A user-defined link class is intended for use across an 0255 * organization, among collaborators, or across a community of users. 0256 * \li An application or library overlying HDF5 invokes a user-defined 0257 * link class that must be shipped with the software. 0258 * \li Files are distributed that make use of a user-defined link class. 0259 * \li Or simply, a specific user-defined link class is thought to be 0260 * widely useful. 0261 * 0262 * In such cases, you are encouraged to register that link class with 0263 * The HDF Group's Helpdesk. The HDF Group maintains a registry of known 0264 * user-defined link classes and tracks the selected link class 0265 * identifiers. This registry is intended to reduce the risk of 0266 * collisions between \c class_id values and to help coordinate the use 0267 * of specialized link classes. 0268 * 0269 * \since 1.8.0 0270 * 0271 */ 0272 H5_DLL herr_t H5Lregister(const H5L_class_t *cls); 0273 /** 0274 * \ingroup H5LA 0275 * 0276 * \brief Unregisters a class of user-defined links 0277 * 0278 * \param[in] id User-defined link class identifier 0279 * 0280 * \return \herr_t 0281 * 0282 * \details H5Lunregister() unregisters a class of user-defined links, 0283 * preventing them from being traversed, queried, moved, etc. 0284 * 0285 * \note A link class can be re-registered using H5Lregister(). 0286 * 0287 * \since 1.8.0 0288 * 0289 */ 0290 H5_DLL herr_t H5Lunregister(H5L_type_t id); 0291 0292 #ifdef __cplusplus 0293 } 0294 #endif 0295 0296 /* Symbols defined for compatibility with previous versions of the HDF5 API. 0297 * 0298 * Use of these symbols is deprecated. 0299 */ 0300 #ifndef H5_NO_DEPRECATED_SYMBOLS 0301 0302 /* Previous versions of the H5L_class_t struct */ 0303 #define H5L_LINK_CLASS_T_VERS_0 0 0304 0305 /** Callback during link traversal */ 0306 typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, 0307 size_t lnkdata_size, hid_t lapl_id); 0308 0309 /** User-defined link types */ 0310 typedef struct { 0311 int version; /**< Version number of this struct */ 0312 H5L_type_t id; /**< Link type ID */ 0313 const char *comment; /**< Comment for debugging */ 0314 H5L_create_func_t create_func; /**< Callback during link creation */ 0315 H5L_move_func_t move_func; /**< Callback after moving link */ 0316 H5L_copy_func_t copy_func; /**< Callback after copying link */ 0317 H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */ 0318 H5L_delete_func_t del_func; /**< Callback for link deletion */ 0319 H5L_query_func_t query_func; /**< Callback for queries */ 0320 } H5L_class_0_t; 0321 0322 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 0323 0324 #endif /* H5Ldevelop_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|