summaryrefslogtreecommitdiffstats
path: root/src/H5VLpublic.h
blob: 10be480cef3d7138cf502fdfb0e9bae679d2387b (plain)
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
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * 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 H5VL (VOL) module.
 */

#ifndef _H5VLpublic_H
#define _H5VLpublic_H

/* Public headers needed by this file */
#include "H5public.h"  /* Generic Functions                    */
#include "H5Ipublic.h" /* IDs                                  */

/*****************/
/* Public Macros */
/*****************/

/**
 * \ingroup H5VLDEF
 * \brief Version # of VOL class struct & callbacks
 *
 * \details Each VOL connector must set the 'version' field in the H5VL_class_t
 *          struct to the version of the H5VL_class_t struct that the connector
 *          implements.  The HDF5 library will reject connectors with
 *          incompatible structs.
 */
#define H5VL_VERSION 2

/* VOL connector identifier values
 * These are H5VL_class_value_t values, NOT hid_t values!
 */
/**
 * \ingroup H5VLDEF
 * Invalid ID for VOL connector ID
 */
#define H5_VOL_INVALID (-1)
/**
 * \ingroup H5VLDEF
 * Native HDF5 file format VOL connector
 */
#define H5_VOL_NATIVE 0
/**
 * \ingroup H5VLDEF
 * VOL connector IDs below this value are reserved for library use
 */
#define H5_VOL_RESERVED 256
/**
 * \ingroup H5VLDEF
 * Maximum VOL connector ID
 */
#define H5_VOL_MAX 65535

/* Flags to return from H5VLquery_optional API and 'opt_query' callbacks */
/* Note: Operations which access multiple objects' data or metadata in a
 *      container should be registered as file-level optional operations.
 *      (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so
 *      a VOL connector that implemented it should register it as an optional
 *      file operation, and pass-through VOL connectors that are stacked above
 *      the connector that registered it should assume that dataset elements
 *      for _any_ dataset in the file could be written to)
 */
#define H5VL_OPT_QUERY_SUPPORTED       0x0001 /* VOL connector supports this operation */
#define H5VL_OPT_QUERY_READ_DATA       0x0002 /* Operation reads data for object */
#define H5VL_OPT_QUERY_WRITE_DATA      0x0004 /* Operation writes data for object */
#define H5VL_OPT_QUERY_QUERY_METADATA  0x0008 /* Operation reads metadata for object */
#define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /* Operation modifies metadata for object */
#define H5VL_OPT_QUERY_COLLECTIVE                                                                            \
    0x0020 /* Operation is collective (operations without this flag are assumed to be independent) */
#define H5VL_OPT_QUERY_NO_ASYNC  0x0040 /* Operation may NOT be executed asynchronously */
#define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /* Operation involves multiple objects */

/*******************/
/* Public Typedefs */
/*******************/

/**
 * \ingroup H5VLDEF
 *
 * \brief VOL connector identifiers.
 *
 * \details Values 0 through 255 are for connectors defined by the HDF5
 *          library. Values 256 through 511 are available for testing new
 *          connectors. Subsequent values should be obtained from the HDF5
 *          development team at mailto:help@hdfgroup.org.
 */
//! [H5VL_class_value_t_snip]
typedef int H5VL_class_value_t;
//! [H5VL_class_value_t_snip]

/**
 * \ingroup H5VLDEF
 * \details Enum type for each VOL subclass
 *          (Used for various queries, etc)
 */
typedef enum H5VL_subclass_t {
    H5VL_SUBCLS_NONE,     /**< Operations outside of a subclass */
    H5VL_SUBCLS_INFO,     /**< 'Info' subclass */
    H5VL_SUBCLS_WRAP,     /**< 'Wrap' subclass */
    H5VL_SUBCLS_ATTR,     /**< 'Attribute' subclass */
    H5VL_SUBCLS_DATASET,  /**< 'Dataset' subclass */
    H5VL_SUBCLS_DATATYPE, /**< 'Named datatype' subclass */
    H5VL_SUBCLS_FILE,     /**< 'File' subclass */
    H5VL_SUBCLS_GROUP,    /**< 'Group' subclass */
    H5VL_SUBCLS_LINK,     /**< 'Link' subclass */
    H5VL_SUBCLS_OBJECT,   /**< 'Object' subclass */
    H5VL_SUBCLS_REQUEST,  /**< 'Request' subclass */
    H5VL_SUBCLS_BLOB,     /**< 'Blob' subclass */
    H5VL_SUBCLS_TOKEN     /**< 'Token' subclass */
} H5VL_subclass_t;

/********************/
/* Public Variables */
/********************/

/*********************/
/* Public Prototypes */
/*********************/

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \ingroup H5VL
 * \brief Registers a new VOL connector by name
 *
 * \param[in] connector_name Connector name
 * \vipl_id
 * \return \hid_t{VOL connector}
 *
 * \details H5VLregister_connector_by_name() registers a new VOL connector with
 *          the name \p connector_name as a member of the virtual object layer
 *          class. This VOL connector identifier is good until the library is
 *          closed or the connector is unregistered.
 *
 *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
 *          initialization property list of class #H5P_VOL_INITIALIZE created
 *          with H5Pcreate(). When created, this property list contains no
 *          library properties. If a VOL connector author decides that
 *          initialization-specific data are needed, they can be added to the
 *          empty list and retrieved by the connector in the VOL connector's
 *          initialize callback. Use of the VOL initialization property list is
 *          uncommon, as most VOL-specific properties are added to the file
 *          access property list via the connector's API calls which set the
 *          VOL connector for the file open/create. For more information, see
 *          the VOL documentation.
 *
 * \todo Fix the reference to VOL documentation.
 *
 * \since 1.12.0
 */
H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id);
/**
 * \ingroup H5VL
 * \brief Registers a new VOL connector by value
 *
 * \param[in] connector_value Connector value
 * \vipl_id
 * \return \hid_t{VOL connector}
 *
 * \details H5VLregister_connector_by_value() registers a new VOL connector
 *          with value connector_value as a member of the virtual object layer
 *          class. This VOL connector identifier is good until the library is
 *          closed or the connector is unregistered.
 *
 *          \p connector_value has a type of H5VL_class_value_t, which is
 *          defined in H5VLpublic.h as follows:
 *          \snippet this H5VL_class_value_t_snip
 *
 *          Valid VOL connector identifiers can have values from 0 through 255
 *          for connectors defined by the HDF5 library. Values 256 through 511
 *          are available for testing new connectors. Subsequent values should
 *          be obtained by contacting the The HDF Help Desk.
 *
 *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
 *          initialization property list of class #H5P_VOL_INITIALIZE created
 *          with H5Pcreate(). When created, this property list contains no
 *          library properties. If a VOL connector author decides that
 *          initialization-specific data are needed, they can be added to the
 *          empty list and retrieved by the connector in the VOL connector's
 *          initialize callback. Use of the VOL initialization property list is
 *          uncommon, as most VOL-specific properties are added to the file
 *          access property list via the connector's API calls which set the
 *          VOL connector for the file open/create. For more information, see
 *          the VOL documentation.
 *
 * \todo Fix the reference to VOL documentation.
 *
 * \since 1.12.0
 */
H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id);
/**
 * \ingroup H5VL
 * \brief Tests whether a VOL class has been registered under a certain name
 *
 * \param[in] name Alleged name of connector
 * \return \htri_t
 *
 * \details H5VLis_connector_registered_by_name() tests whether a VOL class has
 *          been registered or not, according to the supplied connector name
 *          \p name.
 *
 * \since 1.12.0
 */
H5_DLL htri_t H5VLis_connector_registered_by_name(const char *name);
/**
 * \ingroup H5VL
 * \brief Tests whether a VOL class has been registered for a given value
 *
 * \param[in] connector_value Connector value
 * \return \htri_t
 *
 * \details H5VLis_connector_registered_by_value() tests whether a VOL class
 *          has been registered, according to the supplied connector value \p
 *          connector_value.
 *
 *          \p connector_value has a type of H5VL_class_value_t, which is
 *          defined in H5VLpublic.h as follows:
 *          \snippet this H5VL_class_value_t_snip
 *
 *          Valid VOL connector identifiers can have values from 0 through 255
 *          for connectors defined by the HDF5 library. Values 256 through 511
 *          are available for testing new connectors. Subsequent values should
 *          be obtained by contacting the The HDF Help Desk.
 *
 * \since 1.12.0
 */
H5_DLL htri_t H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value);
/**
 * \ingroup H5VL
 * \brief Retrieves the VOL connector identifier for a given object identifier
 *
 * \obj_id
 * \return \hid_t{VOL connector}
 *
 * \details H5VLget_connector_id() retrieves the registered VOL connector
 *          identifier for the specified object identifier \p obj_id. The VOL
 *          connector identifier must be closed with H5VLclose() when no longer
 *          in use.
 *
 * \since 1.12.0
 */
H5_DLL hid_t H5VLget_connector_id(hid_t obj_id);
/**
 * \ingroup H5VL
 * \brief Retrieves the identifier for a registered VOL connector name
 *
 * \param[in] name Connector name
 * \return \hid_t{VOL connector}
 *
 * \details H5VLget_connector_id_by_name() retrieves the identifier for a
 *          registered VOL connector with the name \p name. The identifier must
 *          be closed with H5VLclose() when no longer in use.
 *
 * \since 1.12.0
 */
H5_DLL hid_t H5VLget_connector_id_by_name(const char *name);
/**
 * \ingroup H5VL
 * \brief Retrieves the identifier for a registered VOL connector value
 *
 * \param[in] connector_value Connector value
 * \return \hid_t{VOL connector}
 *
 * \details H5VLget_connector_id_by_value() retrieves the identifier for a
 *          registered VOL connector with the value \p connector_value. The
 *          identifier will need to be closed by H5VLclose().
 *
 *          \p connector_value has a type of H5VL_class_value_t, which is
 *          defined in H5VLpublic.h as follows:
 *          \snippet this H5VL_class_value_t_snip
 *
 *          Valid VOL connector identifiers can have values from 0 through 255
 *          for connectors defined by the HDF5 library. Values 256 through 511
 *          are available for testing new connectors. Subsequent values should
 *          be obtained by contacting the The HDF Help Desk.
 *
 * \since 1.12.0
 */
H5_DLL hid_t H5VLget_connector_id_by_value(H5VL_class_value_t connector_value);
/**
 * \ingroup H5VL
 * \brief Retrieves a connector name for a VOL
 *
 * \obj_id{id} or file identifier
 * \param[out] name Connector name
 * \param[in] size Maximum length of the name to retrieve
 * \return Returns the length of the connector name on success, and a negative value on failure.
 *
 * \details H5VLget_connector_name() retrieves up to \p size elements of the
 *          VOL name \p name associated with the object or file identifier \p
 *          id.
 *
 *          Passing in a NULL pointer for size will return the size of the
 *          connector name. This can be used to determine the size of the
 *          buffer to allocate for the name.
 *
 * \since 1.12.0
 */
H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size);
/**
 * \ingroup H5VL
 * \brief Closes a VOL connector identifier
 *
 * \param[in] connector_id Connector identifier
 * \return \herr_t
 *
 * \details H5VLclose() closes a VOL connector identifier. This does not affect
 *          the file access property lists which have been defined to use this
 *          VOL connector or files which are already opened under this
 *          connector.
 *
 * \since 1.12.0
 */
H5_DLL herr_t H5VLclose(hid_t connector_id);
/**
 * \ingroup H5VL
 * \brief Removes a VOL connector identifier from the library
 *
 * \param[in] connector_id Connector identifier
 * \return \herr_t
 *
 * \details H5VLunregister_connector() removes a VOL connector identifier from
 *          the library. This does not affect the file access property lists
 *          which have been defined to use the VOL connector or any files which
 *          are already opened with this connector.
 *
 * \attention H5VLunregister_connector() will fail if attempting to unregister
 *            the native VOL connector.
 *
 * \since 1.12.0
 */
H5_DLL herr_t H5VLunregister_connector(hid_t connector_id);
/**
 * \ingroup H5VL
 * \brief Determine if a VOL connector supports a particular
 *        optional callback operation.
 *
 * \obj_id
 * \param[in] subcls VOL subclass
 * \param[in] opt_type Option type
 * \param[out] flags Operation flags
 * \return \herr_t
 *
 * \since 1.12.0
 */
H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags);

#ifdef __cplusplus
}
#endif

/* Semi-public headers mainly for VOL connector authors */
#include "H5VLconnector.h"          /* VOL connector author routines */
#include "H5VLconnector_passthru.h" /* Pass-through VOL connector author routines */
#include "H5VLnative.h"             /* Native VOL connector macros, for VOL connector authors */

#endif /* _H5VLpublic_H */