*_string() enumerator to string functions: remove common prefix
[babeltrace.git] / src / plugins / ctf / common / bfcr / bfcr.h
1 #ifndef CTF_BFCR_H
2 #define CTF_BFCR_H
3
4 /*
5 * Babeltrace - CTF binary field class reader (BFCR)
6 *
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 * SOFTWARE.
27 */
28
29 #include <stdint.h>
30 #include <stddef.h>
31 #include <stdio.h>
32 #include <babeltrace2/babeltrace.h>
33 #include "common/macros.h"
34
35 #include "../metadata/ctf-meta.h"
36
37 /**
38 * @file bfcr.h
39 *
40 * Event-driven CTF binary field class reader (BFCR).
41 *
42 * This is a common, internal API used by CTF source plugins. It allows
43 * a binary CTF IR field class to be decoded from user-provided buffers.
44 * As the class is decoded (and, possibly, its nested classes),
45 * registered user callback functions are called.
46 *
47 * This API is only concerned with reading one CTF class at a time from
48 * one or more buffer of bytes. It does not know CTF dynamic scopes,
49 * events, or streams. Sequence lengths and selected variant classes are
50 * requested to the user when needed.
51 */
52
53 /**
54 * Binary class reader API status codes.
55 */
56 enum bt_bfcr_status {
57 /** Out of memory. */
58 BT_BFCR_STATUS_ENOMEM = -5,
59 /**
60 * The binary stream reader reached the end of the user-provided
61 * buffer, but data is still needed to finish decoding the
62 * requested class.
63 *
64 * The user needs to call bt_bfcr_continue() as long as
65 * #BT_BFCR_STATUS_EOF is returned to complete the decoding
66 * process of a given class.
67 */
68 BT_BFCR_STATUS_EOF = 1,
69
70 /** Invalid argument. */
71 BT_BFCR_STATUS_INVAL = -3,
72
73 /** General error. */
74 BT_BFCR_STATUS_ERROR = -1,
75
76 /** Everything okay. */
77 BT_BFCR_STATUS_OK = 0,
78 };
79
80 /** Field class reader. */
81 struct bt_bfcr;
82
83 typedef enum bt_bfcr_status (* bt_bfcr_unsigned_int_cb_func)(uint64_t,
84 struct ctf_field_class *, void *);
85
86 /*
87 * Field class reader user callback functions.
88 */
89 struct bt_bfcr_cbs {
90 /**
91 * Field class callback functions.
92 *
93 * This CTF binary class reader is event-driven. The following
94 * functions are called during the decoding process, either when
95 * a compound class begins/ends, or when a basic class is
96 * completely decoded (along with its value).
97 *
98 * Each function also receives the CTF field class associated
99 * with the call, and user data (registered to the class reader
100 * calling them).
101 *
102 * Actual trace IR fields are \em not created here; this would
103 * be the responsibility of a class reader's user (the provider
104 * of those callback functions).
105 *
106 * All the class callback functions return one of the following
107 * values:
108 *
109 * - <b>#BT_BFCR_STATUS_OK</b>: Everything is okay;
110 * continue the decoding process.
111 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error (reported
112 * to class reader's user).
113 *
114 * Any member of this structure may be set to \c NULL, should
115 * a specific message be not needed.
116 */
117 struct {
118 /**
119 * Called when a signed integer class is completely
120 * decoded. This could also be the supporting signed
121 * integer class of an enumeration class (\p class will
122 * indicate this).
123 *
124 * @param value Signed integer value
125 * @param class Integer or enumeration class
126 * @param data User data
127 * @returns #BT_BFCR_STATUS_OK or
128 * #BT_BFCR_STATUS_ERROR
129 */
130 enum bt_bfcr_status (* signed_int)(int64_t value,
131 struct ctf_field_class *cls, void *data);
132
133 /**
134 * Called when an unsigned integer class is completely
135 * decoded. This could also be the supporting signed
136 * integer class of an enumeration class (\p class will
137 * indicate this).
138 *
139 * @param value Unsigned integer value
140 * @param class Integer or enumeration class
141 * @param data User data
142 * @returns #BT_BFCR_STATUS_OK or
143 * #BT_BFCR_STATUS_ERROR
144 */
145 bt_bfcr_unsigned_int_cb_func unsigned_int;
146
147 /**
148 * Called when a floating point number class is
149 * completely decoded.
150 *
151 * @param value Floating point number value
152 * @param class Floating point number class
153 * @param data User data
154 * @returns #BT_BFCR_STATUS_OK or
155 * #BT_BFCR_STATUS_ERROR
156 */
157 enum bt_bfcr_status (* floating_point)(double value,
158 struct ctf_field_class *cls, void *data);
159
160 /**
161 * Called when a string class begins.
162 *
163 * All the following user callback function calls will
164 * be made to bt_bfcr_cbs::classes::string(), each of
165 * them providing one substring of the complete string
166 * class's value.
167 *
168 * @param class Beginning string class
169 * @param data User data
170 * @returns #BT_BFCR_STATUS_OK or
171 * #BT_BFCR_STATUS_ERROR
172 */
173 enum bt_bfcr_status (* string_begin)(
174 struct ctf_field_class *cls, void *data);
175
176 /**
177 * Called when a string class's substring is decoded
178 * (between a call to bt_bfcr_cbs::classes::string_begin()
179 * and a call to bt_bfcr_cbs::classes::string_end()).
180 *
181 * @param value String value (\em not null-terminated)
182 * @param len String value length
183 * @param class String class
184 * @param data User data
185 * @returns #BT_BFCR_STATUS_OK or
186 * #BT_BFCR_STATUS_ERROR
187 */
188 enum bt_bfcr_status (* string)(const char *value,
189 size_t len, struct ctf_field_class *cls,
190 void *data);
191
192 /**
193 * Called when a string class ends.
194 *
195 * @param class Ending string class
196 * @param data User data
197 * @returns #BT_BFCR_STATUS_OK or
198 * #BT_BFCR_STATUS_ERROR
199 */
200 enum bt_bfcr_status (* string_end)(
201 struct ctf_field_class *cls, void *data);
202
203 /**
204 * Called when a compound class begins.
205 *
206 * All the following class callback function calls will
207 * signal sequential elements of this compound class,
208 * until the next corresponding
209 * bt_bfcr_cbs::classes::compound_end() is called.
210 *
211 * If \p class is a variant class, then only one class
212 * callback function call will follow before the call to
213 * bt_bfcr_cbs::classes::compound_end(). This single
214 * call indicates the selected class of this variant
215 * class.
216 *
217 * @param class Beginning compound class
218 * @param data User data
219 * @returns #BT_BFCR_STATUS_OK or
220 * #BT_BFCR_STATUS_ERROR
221 */
222 enum bt_bfcr_status (* compound_begin)(
223 struct ctf_field_class *cls, void *data);
224
225 /**
226 * Called when a compound class ends.
227 *
228 * @param class Ending compound class
229 * @param data User data
230 * @returns #BT_BFCR_STATUS_OK or
231 * #BT_BFCR_STATUS_ERROR
232 */
233 enum bt_bfcr_status (* compound_end)(
234 struct ctf_field_class *cls, void *data);
235 } classes;
236
237 /**
238 * Query callback functions are used when the class reader needs
239 * dynamic information, i.e. a sequence class's current length
240 * or a variant class's current selected class.
241 *
242 * Both functions need to be set unless it is known that no
243 * sequences or variants will have to be decoded.
244 */
245 struct {
246 /**
247 * Called to query the current length of a given sequence
248 * class.
249 *
250 * @param class Sequence class
251 * @param data User data
252 * @returns Sequence length or
253 * #BT_BFCR_STATUS_ERROR on error
254 */
255 int64_t (* get_sequence_length)(struct ctf_field_class *cls,
256 void *data);
257
258 /**
259 * Called to query the current selected class of a given
260 * variant class.
261 *
262 * @param class Variant class
263 * @param data User data
264 * @returns Current selected class (owned by
265 * this) or \c NULL on error
266 */
267 struct ctf_field_class * (* borrow_variant_selected_field_class)(
268 struct ctf_field_class *cls, void *data);
269 } query;
270 };
271
272 /**
273 * Creates a CTF binary class reader.
274 *
275 * @param cbs User callback functions
276 * @param data User data (passed to user callback functions)
277 * @returns New binary class reader on success, or \c NULL on error
278 */
279 BT_HIDDEN
280 struct bt_bfcr *bt_bfcr_create(struct bt_bfcr_cbs cbs, void *data,
281 bt_logging_level log_level, bt_self_component *self_comp);
282
283 /**
284 * Destroys a CTF binary class reader, freeing all internal resources.
285 *
286 * @param bfcr Binary class reader
287 */
288 BT_HIDDEN
289 void bt_bfcr_destroy(struct bt_bfcr *bfcr);
290
291 /**
292 * Decodes a given CTF class from a buffer of bytes.
293 *
294 * The number of \em bits consumed by this function is returned.
295 *
296 * The \p status output parameter is where a status is written, amongst
297 * the following:
298 *
299 * - <b>#BT_BFCR_STATUS_OK</b>: Decoding is done.
300 * - <b>#BT_BFCR_STATUS_EOF</b>: The end of the buffer was reached,
301 * but more data is needed to finish the decoding process of the
302 * requested class. The user needs to call bt_bfcr_continue()
303 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
304 * decoding process of the original class.
305 * - <b>#BT_BFCR_STATUS_INVAL</b>: Invalid argument.
306 * - <b>#BT_BFCR_STATUS_ERROR</b>: General error.
307 *
308 * Calling this function resets the class reader's internal state. If
309 * #BT_BFCR_STATUS_EOF is returned, bt_bfcr_continue() needs to
310 * be called next, \em not bt_bfcr_decode().
311 *
312 * @param bfcr Binary class reader
313 * @param class Field class to decode
314 * @param buf Buffer
315 * @param offset Offset of first bit from \p buf (bits)
316 * @param packet_offset Offset of \p offset within the CTF
317 * binary packet containing \p class (bits)
318 * @param sz Size of buffer in bytes (from \p buf)
319 * @param status Returned status (see description above)
320 * @returns Number of consumed bits
321 */
322 BT_HIDDEN
323 size_t bt_bfcr_start(struct bt_bfcr *bfcr,
324 struct ctf_field_class *cls, const uint8_t *buf,
325 size_t offset, size_t packet_offset, size_t sz,
326 enum bt_bfcr_status *status);
327
328 /**
329 * Continues the decoding process a given CTF class.
330 *
331 * The number of bits consumed by this function is returned.
332 *
333 * The \p status output parameter is where a status is placed, amongst
334 * the following:
335 *
336 * - <b>#BT_BFCR_STATUS_OK</b>: decoding is done.
337 * - <b>#BT_BFCR_STATUS_EOF</b>: the end of the buffer was reached,
338 * but more data is needed to finish the decoding process of the
339 * requested class. The user needs to call bt_bfcr_continue()
340 * as long as #BT_BFCR_STATUS_EOF is returned to complete the
341 * decoding process of the original class.
342 * - <b>#BT_BFCR_STATUS_INVAL</b>: invalid argument.
343 * - <b>#BT_BFCR_STATUS_ERROR</b>: general error.
344 *
345 * @param bfcr Binary class reader
346 * @param buf Buffer
347 * @param sz Size of buffer in bytes (from \p offset)
348 * @param status Returned status (see description above)
349 * @returns Number of consumed bits
350 */
351 BT_HIDDEN
352 size_t bt_bfcr_continue(struct bt_bfcr *bfcr,
353 const uint8_t *buf, size_t sz,
354 enum bt_bfcr_status *status);
355
356 BT_HIDDEN
357 void bt_bfcr_set_unsigned_int_cb(struct bt_bfcr *bfcr,
358 bt_bfcr_unsigned_int_cb_func cb);
359
360 static inline
361 const char *bt_bfcr_status_string(enum bt_bfcr_status status)
362 {
363 switch (status) {
364 case BT_BFCR_STATUS_ENOMEM:
365 return "ENOMEM";
366 case BT_BFCR_STATUS_EOF:
367 return "EOF";
368 case BT_BFCR_STATUS_INVAL:
369 return "INVAL";
370 case BT_BFCR_STATUS_ERROR:
371 return "ERROR";
372 case BT_BFCR_STATUS_OK:
373 return "OK";
374 default:
375 return "(unknown)";
376 }
377 }
378
379 #endif /* CTF_BFCR_H */
This page took 0.037701 seconds and 4 git commands to generate.