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
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 H5T (datatype) developer
* support routines.
*/
#ifndef H5Tdevelop_H
#define H5Tdevelop_H
/* Include package's public header */
#include "H5Tpublic.h"
/*****************/
/* Public Macros */
/*****************/
/*******************/
/* Public Typedefs */
/*******************/
/**
* Commands sent to conversion functions
*/
typedef enum H5T_cmd_t {
H5T_CONV_INIT = 0, /**< query and/or initialize private data */
H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */
H5T_CONV_FREE = 2 /**< function is being removed from path */
} H5T_cmd_t;
/**
* How is the `bkg' buffer used by the conversion function?
*/
typedef enum H5T_bkg_t {
H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */
H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */
H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */
} H5T_bkg_t;
/**
* Type conversion client data
*/
//! <!-- [H5T_cdata_t_snip] -->
typedef struct H5T_cdata_t {
H5T_cmd_t command; /**< what should the conversion function do? */
H5T_bkg_t need_bkg; /**< is the background buffer needed? */
hbool_t recalc; /**< recalculate private data */
void *priv; /**< private data */
} H5T_cdata_t;
//! <!-- [H5T_cdata_t_snip] -->
/**
* Conversion function persistence
*/
typedef enum H5T_pers_t {
H5T_PERS_DONTCARE = -1, /**< wild card */
H5T_PERS_HARD = 0, /**< hard conversion function */
H5T_PERS_SOFT = 1 /**< soft conversion function */
} H5T_pers_t;
/**
* All datatype conversion functions are...
*/
//! <!-- [H5T_conv_t_snip] -->
typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride,
size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist);
//! <!-- [H5T_conv_t_snip] -->
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \ingroup CONV
*
* \brief Registers a datatype conversion function
*
* \param[in] pers Conversion function type
* \param[in] name Name displayed in diagnostic output
* \type_id{src_id} of source datatype
* \type_id{dst_id} of destination datatype
* \param[in] func Function to convert between source and destination datatypes
*
* \return \herr_t
*
* \details H5Tregister() registers a hard or soft conversion function for a
* datatype conversion path. The parameter \p pers indicates whether a
* conversion function is hard (#H5T_PERS_HARD) or soft
* (#H5T_PERS_SOFT). User-defined functions employing compiler casting
* are designated as \Emph{hard}; other user-defined conversion
* functions registered with the HDF5 library (with H5Tregister() )
* are designated as \Emph{soft}. The HDF5 library also has its own
* hard and soft conversion functions.
*
* A conversion path can have only one hard function. When type is
* #H5T_PERS_HARD, \p func replaces any previous hard function.
*
* When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the
* end of the master soft list and replaces the soft function in all
* applicable existing conversion paths. Soft functions are used when
* determining which conversion function is appropriate for this path.
*
* The \p name is used only for debugging and should be a short
* identifier for the function.
*
* The path is specified by the source and destination datatypes \p
* src_id and \p dst_id. For soft conversion functions, only the class
* of these types is important.
*
* The type of the conversion function pointer is declared as:
* \snippet this H5T_conv_t_snip
*
* The \ref H5T_cdata_t \c struct is declared as:
* \snippet this H5T_cdata_t_snip
*
* \since 1.6.3 The following change occurred in the \ref H5T_conv_t function:
* the \c nelmts parameter type changed to size_t.
*
*/
H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
/**
* \ingroup CONV
*
* \brief Removes a conversion function
*
* \param[in] pers Conversion function type
* \param[in] name Name displayed in diagnostic output
* \type_id{src_id} of source datatype
* \type_id{dst_id} of destination datatype
* \param[in] func Function to convert between source and destination datatypes
*
* \return \herr_t
*
* \details H5Tunregister() removes a conversion function matching criteria
* such as soft or hard conversion, source and destination types, and
* the conversion function.
*
* If a user is trying to remove a conversion function he registered,
* all parameters can be used. If he is trying to remove a library's
* default conversion function, there is no guarantee the \p name and
* \p func parameters will match the user's chosen values. Passing in
* some values may cause this function to fail. A good practice is to
* pass in NULL as their values.
*
* All parameters are optional. The missing parameters will be used to
* generalize the search criteria.
*
* The conversion function pointer type declaration is described in
* H5Tregister().
*
* \version 1.6.3 The following change occurred in the \ref H5T_conv_t function:
* the \c nelmts parameter type changed to size_t.
*
*/
H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
/**
* \ingroup CONV
*
* \brief Finds a conversion function
*
* \type_id{src_id} of source datatype
* \type_id{dst_id} of destination datatype
* \param[out] pcdata Pointer to type conversion data
*
* \return Returns a pointer to a suitable conversion function if successful.
* Otherwise returns NULL.
*
* \details H5Tfind() finds a conversion function that can handle a conversion
* from type \p src_id to type \p dst_id. The \p pcdata argument is a
* pointer to a pointer to type conversion data which was created and
* initialized by the soft type conversion function of this path when
* the conversion function was installed on the path.
*
*/
H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata);
/**
* \ingroup CONV
*
* \brief Check whether the library's default conversion is hard conversion
*
* \type_id{src_id} of source datatype
* \type_id{dst_id} of destination datatype
*
* \return \htri_t
*
* \details H5Tcompiler_conv() determines whether the library's conversion
* function from type \p src_id to type \p dst_id is a compiler (hard)
* conversion or not. A compiler conversion uses compiler's casting; a
* library (soft) conversion uses the library's own conversion
* function.
*
* \since 1.8.0
*
*/
H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_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
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#endif /* H5Tdevelop_H */
|
