1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
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://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 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 */
|
