Commit | Line | Data |
---|---|---|
2e33ac5a PP |
1 | #ifndef BABELTRACE_CTF_IR_FIELDS_H |
2 | #define BABELTRACE_CTF_IR_FIELDS_H | |
adc315b8 JG |
3 | |
4 | /* | |
2e33ac5a | 5 | * Babeltrace - CTF IR: Event Fields |
adc315b8 | 6 | * |
de9dd397 | 7 | * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
adc315b8 JG |
8 | * |
9 | * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
10 | * | |
11 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
12 | * of this software and associated documentation files (the "Software"), to deal | |
13 | * in the Software without restriction, including without limitation the rights | |
14 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
15 | * copies of the Software, and to permit persons to whom the Software is | |
16 | * furnished to do so, subject to the following conditions: | |
17 | * | |
18 | * The above copyright notice and this permission notice shall be included in | |
19 | * all copies or substantial portions of the Software. | |
20 | * | |
21 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
22 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
23 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
24 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
25 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
26 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
27 | * SOFTWARE. | |
28 | * | |
29 | * The Common Trace Format (CTF) Specification is available at | |
30 | * http://www.efficios.com/ctf | |
31 | */ | |
32 | ||
33 | #include <stdint.h> | |
cd95e351 | 34 | #include <stddef.h> |
9d408fca | 35 | |
094ff7c0 PP |
36 | /* For bt_get() */ |
37 | #include <babeltrace/ref.h> | |
38 | ||
9d408fca | 39 | /* For bt_bool */ |
c14d64fa | 40 | #include <babeltrace/types.h> |
adc315b8 | 41 | |
13d80369 PP |
42 | /* For BT_FIELD_TYPE_ID_* */ |
43 | #include <babeltrace/ctf-ir/field-types.h> | |
44 | ||
adc315b8 JG |
45 | #ifdef __cplusplus |
46 | extern "C" { | |
47 | #endif | |
48 | ||
50842bdc | 49 | struct bt_field_type; |
9d408fca | 50 | |
91f379cb PP |
51 | /** |
52 | @defgroup ctfirfields CTF IR fields | |
53 | @ingroup ctfir | |
54 | @brief CTF IR fields. | |
55 | ||
56 | @code | |
57 | #include <babeltrace/ctf-ir/fields.h> | |
58 | @endcode | |
59 | ||
60 | A CTF IR <strong><em>field</em></strong> is an object which holds a | |
61 | concrete value, and which is described by a @ft. | |
62 | ||
63 | In the CTF IR hierarchy, you can set the root fields of two objects: | |
64 | ||
65 | - \ref ctfirpacket | |
50842bdc PP |
66 | - Trace packet header field: bt_packet_set_header(). |
67 | - Stream packet context field: bt_packet_set_context(). | |
91f379cb | 68 | - \ref ctfirevent |
50842bdc PP |
69 | - Stream event header field: bt_event_set_header(). |
70 | - Stream event context field: bt_event_set_stream_event_context(). | |
71 | - Event context field: bt_event_set_event_context(). | |
72 | - Event payload field: bt_event_set_payload_field(). | |
91f379cb PP |
73 | |
74 | There are two categories of fields: | |
75 | ||
76 | - <strong>Basic fields</strong>: | |
77 | - @intfield: contains an integral value. | |
78 | - @floatfield: contains a floating point number value. | |
79 | - @enumfield: contains an integer field which contains an integral | |
80 | value. | |
81 | - @stringfield: contains a string value. | |
82 | - <strong>Compound fields</strong>: | |
83 | - @structfield: contains an ordered list of named fields | |
84 | (possibly with different @fts). | |
85 | - @arrayfield: contains an ordered list of fields which share | |
86 | the same field type. | |
87 | - @seqfield: contains an ordered list of fields which share | |
88 | the same field type. | |
89 | - @varfield: contains a single, current field. | |
90 | ||
91 | You can create a field object from a @ft object with | |
50842bdc | 92 | bt_field_create(). The enumeration and compound fields create their |
91f379cb PP |
93 | contained fields with the following getters if such fields do not exist |
94 | yet: | |
95 | ||
50842bdc PP |
96 | - bt_field_enumeration_get_container() |
97 | - bt_field_structure_get_field_by_name() | |
98 | - bt_field_array_get_field() | |
99 | - bt_field_sequence_get_field() | |
100 | - bt_field_variant_get_field() | |
91f379cb | 101 | |
7fcd5734 | 102 | If you already have a field object, you can also assign it to a specific |
2225de6b | 103 | name within a @structfield with |
50842bdc | 104 | bt_field_structure_set_field_by_name(). |
7fcd5734 | 105 | |
91f379cb | 106 | You can get a reference to the @ft which was used to create a field with |
50842bdc PP |
107 | bt_field_get_type(). You can get the |
108 | \link #bt_field_type_id type ID\endlink of this field type directly with | |
109 | bt_field_get_type_id(). | |
91f379cb | 110 | |
50842bdc | 111 | You can get a deep copy of a field with bt_field_copy(). The field |
91f379cb PP |
112 | copy, and its contained field copies if it's the case, have the same |
113 | field type as the originals. | |
114 | ||
115 | As with any Babeltrace object, CTF IR field objects have | |
116 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
117 | counts</a>. See \ref refs to learn more about the reference counting | |
118 | management of Babeltrace objects. | |
119 | ||
120 | The functions which freeze CTF IR \link ctfirpacket packet\endlink and | |
121 | \link ctfirevent event\endlink objects also freeze their root field | |
122 | objects. You cannot modify a frozen field object: it is considered | |
123 | immutable, except for \link refs reference counting\endlink. | |
124 | ||
125 | @sa ctfirfieldtypes | |
126 | ||
127 | @file | |
128 | @brief CTF IR fields type and functions. | |
129 | @sa ctfirfields | |
130 | ||
131 | @addtogroup ctfirfields | |
132 | @{ | |
133 | */ | |
134 | ||
135 | /** | |
50842bdc | 136 | @struct bt_field |
91f379cb PP |
137 | @brief A CTF IR field. |
138 | @sa ctfirfields | |
139 | */ | |
50842bdc PP |
140 | struct bt_field; |
141 | struct bt_event_class; | |
142 | struct bt_event; | |
143 | struct bt_field_type; | |
144 | struct bt_field_type_enumeration_mapping_iterator; | |
adc315b8 | 145 | |
91f379cb PP |
146 | /** |
147 | @name Creation and parent field type access functions | |
148 | @{ | |
149 | */ | |
150 | ||
094ff7c0 PP |
151 | extern struct bt_field_type *bt_field_borrow_type(struct bt_field *field); |
152 | ||
91f379cb PP |
153 | /** |
154 | @brief Returns the parent @ft of the @field \p field. | |
adc315b8 | 155 | |
91f379cb | 156 | This function returns a reference to the field type which was used to |
50842bdc | 157 | create the field object in the first place with bt_field_create(). |
cd95e351 | 158 | |
91f379cb PP |
159 | @param[in] field Field of which to get the parent field type. |
160 | @returns Parent field type of \p event, | |
161 | or \c NULL on error. | |
adc315b8 | 162 | |
91f379cb PP |
163 | @prenotnull{field} |
164 | @postrefcountsame{field} | |
165 | @postsuccessrefcountretinc | |
166 | */ | |
094ff7c0 PP |
167 | static inline |
168 | struct bt_field_type *bt_field_get_type(struct bt_field *field) | |
169 | { | |
170 | return bt_get(bt_field_borrow_type(field)); | |
171 | } | |
cd95e351 | 172 | |
91f379cb | 173 | /** @} */ |
adc315b8 | 174 | |
91f379cb PP |
175 | /** |
176 | @name Type information | |
177 | @{ | |
178 | */ | |
adc315b8 | 179 | |
91f379cb PP |
180 | /** |
181 | @brief Returns the type ID of the @ft of the @field \p field. | |
adc315b8 | 182 | |
91f379cb PP |
183 | @param[in] field Field of which to get the type ID of its |
184 | parent field type.. | |
185 | @returns Type ID of the parent field type of \p field, | |
50842bdc | 186 | or #BT_FIELD_TYPE_ID_UNKNOWN on error. |
3f4a108d | 187 | |
91f379cb PP |
188 | @prenotnull{field} |
189 | @postrefcountsame{field} | |
f78d67fb | 190 | |
50842bdc PP |
191 | @sa #bt_field_type_id: CTF IR field type ID. |
192 | @sa bt_field_is_integer(): Returns whether or not a given field is a | |
91f379cb | 193 | @intfield. |
50842bdc | 194 | @sa bt_field_is_floating_point(): Returns whether or not a given |
91f379cb | 195 | field is a @floatfield. |
50842bdc | 196 | @sa bt_field_is_enumeration(): Returns whether or not a given field |
91f379cb | 197 | is a @enumfield. |
50842bdc | 198 | @sa bt_field_is_string(): Returns whether or not a given field is a |
91f379cb | 199 | @stringfield. |
50842bdc | 200 | @sa bt_field_is_structure(): Returns whether or not a given field is |
91f379cb | 201 | a @structfield. |
50842bdc | 202 | @sa bt_field_is_array(): Returns whether or not a given field is a |
91f379cb | 203 | @arrayfield. |
50842bdc | 204 | @sa bt_field_is_sequence(): Returns whether or not a given field is |
91f379cb | 205 | a @seqfield. |
50842bdc | 206 | @sa bt_field_is_variant(): Returns whether or not a given field is a |
91f379cb PP |
207 | @varfield. |
208 | */ | |
3dca2276 | 209 | extern enum bt_field_type_id bt_field_get_type_id(struct bt_field *field); |
96e8f959 | 210 | |
91f379cb PP |
211 | /** |
212 | @brief Returns whether or not the @field \p field is a @intfield. | |
cd95e351 | 213 | |
91f379cb | 214 | @param[in] field Field to check (can be \c NULL). |
c14d64fa PP |
215 | @returns #BT_TRUE if \p field is an integer field, or |
216 | #BT_FALSE otherwise (including if \p field is | |
91f379cb | 217 | \c NULL). |
cd95e351 | 218 | |
91f379cb PP |
219 | @prenotnull{field} |
220 | @postrefcountsame{field} | |
adc315b8 | 221 | |
50842bdc | 222 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
223 | field's type. |
224 | */ | |
13d80369 PP |
225 | static inline |
226 | bt_bool bt_field_is_integer(struct bt_field *field) | |
227 | { | |
228 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_INTEGER; | |
229 | } | |
cd95e351 | 230 | |
91f379cb PP |
231 | /** |
232 | @brief Returns whether or not the @field \p field is a @floatfield. | |
adc315b8 | 233 | |
91f379cb | 234 | @param[in] field Field to check (can be \c NULL). |
c14d64fa PP |
235 | @returns #BT_TRUE if \p field is a floating point number fiel |
236 | #BT_FALSE or 0 otherwise (including if \p field is | |
91f379cb PP |
237 | \c NULL). |
238 | ||
239 | @prenotnull{field} | |
240 | @postrefcountsame{field} | |
241 | ||
50842bdc | 242 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
243 | field's type. |
244 | */ | |
13d80369 PP |
245 | static inline |
246 | bt_bool bt_field_is_floating_point(struct bt_field *field) | |
247 | { | |
248 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_FLOAT; | |
249 | } | |
91f379cb PP |
250 | |
251 | /** | |
252 | @brief Returns whether or not the @field \p field is a @enumfield. | |
253 | ||
254 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
255 | @returns #BT_TRUE if \p field is an enumeration field, or |
256 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
257 | \c NULL). |
258 | ||
259 | @prenotnull{field} | |
260 | @postrefcountsame{field} | |
261 | ||
50842bdc | 262 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
263 | field's type. |
264 | */ | |
13d80369 PP |
265 | static inline |
266 | bt_bool bt_field_is_enumeration(struct bt_field *field) | |
267 | { | |
268 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_ENUM; | |
269 | } | |
91f379cb PP |
270 | |
271 | /** | |
272 | @brief Returns whether or not the @field \p field is a @stringfield. | |
273 | ||
274 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
275 | @returns #BT_TRUE if \p field is a string field, or |
276 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
277 | \c NULL). |
278 | ||
279 | @prenotnull{field} | |
280 | @postrefcountsame{field} | |
281 | ||
50842bdc | 282 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
283 | field's type. |
284 | */ | |
13d80369 PP |
285 | static inline |
286 | bt_bool bt_field_is_string(struct bt_field *field) | |
287 | { | |
288 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_STRING; | |
289 | } | |
91f379cb PP |
290 | |
291 | /** | |
292 | @brief Returns whether or not the @field \p field is a @structfield. | |
293 | ||
294 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
295 | @returns #BT_TRUE if \p field is a structure field, or |
296 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
297 | \c NULL). |
298 | ||
299 | @prenotnull{field} | |
300 | @postrefcountsame{field} | |
301 | ||
50842bdc | 302 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
303 | field's type. |
304 | */ | |
13d80369 PP |
305 | static inline |
306 | bt_bool bt_field_is_structure(struct bt_field *field) | |
307 | { | |
308 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_STRUCT; | |
309 | } | |
91f379cb PP |
310 | |
311 | /** | |
312 | @brief Returns whether or not the @field \p field is a @arrayfield. | |
313 | ||
314 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
315 | @returns #BT_TRUE if \p field is an array field, or |
316 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
317 | \c NULL). |
318 | ||
319 | @prenotnull{field} | |
320 | @postrefcountsame{field} | |
321 | ||
50842bdc | 322 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
323 | field's type. |
324 | */ | |
13d80369 PP |
325 | static inline |
326 | bt_bool bt_field_is_array(struct bt_field *field) | |
327 | { | |
328 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_ARRAY; | |
329 | } | |
91f379cb PP |
330 | |
331 | /** | |
332 | @brief Returns whether or not the @field \p field is a @seqfield. | |
333 | ||
334 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
335 | @returns #BT_TRUE if \p field is a sequence field, or |
336 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
337 | \c NULL). |
338 | ||
339 | @prenotnull{field} | |
340 | @postrefcountsame{field} | |
341 | ||
50842bdc | 342 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
343 | field's type. |
344 | */ | |
13d80369 PP |
345 | static inline |
346 | bt_bool bt_field_is_sequence(struct bt_field *field) | |
347 | { | |
348 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_SEQUENCE; | |
349 | } | |
91f379cb PP |
350 | |
351 | /** | |
352 | @brief Returns whether or not the @field \p field is a @varfield. | |
353 | ||
354 | @param[in] field Field to check (can be \c NULL). | |
c14d64fa PP |
355 | @returns #BT_TRUE if \p field is a variant field, or |
356 | #BT_FALSE otherwise (including if \p field is | |
91f379cb PP |
357 | \c NULL). |
358 | ||
359 | @prenotnull{field} | |
360 | @postrefcountsame{field} | |
361 | ||
50842bdc | 362 | @sa bt_field_get_type_id(): Returns the type ID of a given |
91f379cb PP |
363 | field's type. |
364 | */ | |
13d80369 PP |
365 | static inline |
366 | bt_bool bt_field_is_variant(struct bt_field *field) | |
367 | { | |
368 | return bt_field_get_type_id(field) == BT_FIELD_TYPE_ID_VARIANT; | |
369 | } | |
91f379cb PP |
370 | |
371 | /** @} */ | |
372 | ||
373 | /** | |
374 | @name Misc. functions | |
375 | @{ | |
376 | */ | |
377 | ||
91f379cb PP |
378 | /** @} */ |
379 | ||
380 | /** @} */ | |
381 | ||
382 | /** | |
383 | @defgroup ctfirintfield CTF IR integer field | |
384 | @ingroup ctfirfields | |
385 | @brief CTF IR integer field. | |
386 | ||
387 | @code | |
388 | #include <babeltrace/ctf-ir/fields.h> | |
389 | @endcode | |
390 | ||
391 | A CTF IR <strong><em>integer field</em></strong> is a @field which | |
392 | holds a signed or unsigned integral value, and which is described by | |
393 | a @intft. | |
394 | ||
395 | An integer field object is considered \em unsigned if | |
50842bdc | 396 | bt_field_type_integer_get_signed() on its parent field type returns |
91f379cb | 397 | 0. Otherwise it is considered \em signed. You \em must use |
3dca2276 PP |
398 | bt_field_integer_unsigned_get_value() and |
399 | bt_field_integer_unsigned_set_value() with an unsigned integer | |
400 | field, and bt_field_integer_signed_get_value() and | |
401 | bt_field_integer_signed_set_value() with a signed integer field. | |
91f379cb | 402 | |
50842bdc | 403 | After you create an integer field with bt_field_create(), you |
91f379cb | 404 | \em must set an integral value with |
3dca2276 PP |
405 | bt_field_integer_unsigned_set_value() or |
406 | bt_field_integer_signed_set_value() before you can get the | |
407 | field's value with bt_field_integer_unsigned_get_value() or | |
408 | bt_field_integer_signed_get_value(). | |
91f379cb PP |
409 | |
410 | @sa ctfirintfieldtype | |
411 | @sa ctfirfields | |
412 | ||
413 | @addtogroup ctfirintfield | |
414 | @{ | |
415 | */ | |
416 | ||
417 | /** | |
418 | @brief Returns the signed integral value of the @intfield | |
419 | \p integer_field. | |
420 | ||
421 | @param[in] integer_field Integer field of which to get the | |
422 | signed integral value. | |
423 | @param[out] value Returned signed integral value of | |
424 | \p integer_field. | |
425 | @returns 0 on success, or a negative value on | |
426 | error, including if \p integer_field | |
427 | has no integral value yet. | |
428 | ||
429 | @prenotnull{integer_field} | |
430 | @prenotnull{value} | |
431 | @preisintfield{integer_field} | |
50842bdc | 432 | @pre bt_field_type_integer_get_signed() returns 1 for the parent |
91f379cb PP |
433 | @ft of \p integer_field. |
434 | @pre \p integer_field contains a signed integral value previously | |
3dca2276 | 435 | set with bt_field_integer_signed_set_value(). |
91f379cb PP |
436 | @postrefcountsame{integer_field} |
437 | ||
3dca2276 | 438 | @sa bt_field_integer_signed_set_value(): Sets the signed integral |
91f379cb PP |
439 | value of a given integer field. |
440 | */ | |
3dca2276 | 441 | extern int bt_field_integer_signed_get_value( |
50842bdc | 442 | struct bt_field *integer_field, int64_t *value); |
91f379cb PP |
443 | |
444 | /** | |
445 | @brief Sets the signed integral value of the @intfield | |
446 | \p integer_field to \p value. | |
447 | ||
448 | @param[in] integer_field Integer field of which to set | |
449 | the signed integral value. | |
450 | @param[in] value New signed integral value of | |
451 | \p integer_field. | |
452 | @returns 0 on success, or a negative value on error. | |
453 | ||
454 | @prenotnull{integer_field} | |
455 | @preisintfield{integer_field} | |
456 | @prehot{integer_field} | |
50842bdc | 457 | @pre bt_field_type_integer_get_signed() returns 1 for the parent |
91f379cb PP |
458 | @ft of \p integer_field. |
459 | @postrefcountsame{integer_field} | |
460 | ||
3dca2276 | 461 | @sa bt_field_integer_signed_get_value(): Returns the signed integral |
91f379cb PP |
462 | value of a given integer field. |
463 | */ | |
3dca2276 | 464 | extern int bt_field_integer_signed_set_value( |
50842bdc | 465 | struct bt_field *integer_field, int64_t value); |
91f379cb PP |
466 | |
467 | /** | |
468 | @brief Returns the unsigned integral value of the @intfield | |
469 | \p integer_field. | |
470 | ||
471 | @param[in] integer_field Integer field of which to get the | |
472 | unsigned integral value. | |
473 | @param[out] value Returned unsigned integral value of | |
474 | \p integer_field. | |
475 | @returns 0 on success, or a negative value on | |
476 | error, including if \p integer_field | |
477 | has no integral value yet. | |
478 | ||
479 | @prenotnull{integer_field} | |
480 | @prenotnull{value} | |
481 | @preisintfield{integer_field} | |
50842bdc | 482 | @pre bt_field_type_integer_get_signed() returns 0 for the parent |
91f379cb PP |
483 | @ft of \p integer_field. |
484 | @pre \p integer_field contains an unsigned integral value previously | |
3dca2276 | 485 | set with bt_field_integer_unsigned_set_value(). |
91f379cb PP |
486 | @postrefcountsame{integer_field} |
487 | ||
3dca2276 | 488 | @sa bt_field_integer_unsigned_set_value(): Sets the unsigned |
91f379cb PP |
489 | integral value of a given integer field. |
490 | */ | |
3dca2276 | 491 | extern int bt_field_integer_unsigned_get_value( |
50842bdc | 492 | struct bt_field *integer_field, uint64_t *value); |
91f379cb PP |
493 | |
494 | /** | |
495 | @brief Sets the unsigned integral value of the @intfield | |
496 | \p integer_field to \p value. | |
497 | ||
498 | @param[in] integer_field Integer field of which to set | |
499 | the unsigned integral value. | |
500 | @param[in] value New unsigned integral value of | |
501 | \p integer_field. | |
502 | @returns 0 on success, or a negative value on error. | |
503 | ||
504 | @prenotnull{integer_field} | |
505 | @preisintfield{integer_field} | |
506 | @prehot{integer_field} | |
50842bdc | 507 | @pre bt_field_type_integer_get_signed() returns 0 for the parent |
91f379cb PP |
508 | @ft of \p integer_field. |
509 | @postrefcountsame{integer_field} | |
510 | ||
3dca2276 | 511 | @sa bt_field_integer_unsigned_get_value(): Returns the unsigned |
91f379cb PP |
512 | integral value of a given integer field. |
513 | */ | |
3dca2276 | 514 | extern int bt_field_integer_unsigned_set_value( |
50842bdc | 515 | struct bt_field *integer_field, uint64_t value); |
91f379cb PP |
516 | |
517 | /** @} */ | |
518 | ||
519 | /** | |
520 | @defgroup ctfirfloatfield CTF IR floating point number field | |
521 | @ingroup ctfirfields | |
522 | @brief CTF IR floating point number field. | |
523 | ||
524 | @code | |
525 | #include <babeltrace/ctf-ir/fields.h> | |
526 | @endcode | |
527 | ||
528 | A CTF IR <strong><em>floating point number field</em></strong> is a | |
529 | @field which holds a floating point number value, and which is | |
530 | described by a @floatft. | |
531 | ||
50842bdc | 532 | After you create a floating point number field with bt_field_create(), you |
91f379cb | 533 | \em must set a floating point number value with |
50842bdc PP |
534 | bt_field_floating_point_set_value() before you can get the |
535 | field's value with bt_field_floating_point_get_value(). | |
91f379cb PP |
536 | |
537 | @sa ctfirfloatfieldtype | |
538 | @sa ctfirfields | |
539 | ||
540 | @addtogroup ctfirfloatfield | |
541 | @{ | |
542 | */ | |
543 | ||
544 | /** | |
545 | @brief Returns the floating point number value of the @floatfield | |
546 | \p float_field. | |
547 | ||
548 | @param[in] float_field Floating point number field of which to get the | |
549 | floating point number value. | |
550 | @param[out] value Returned floating point number value of | |
551 | \p float_field. | |
552 | @returns 0 on success, or a negative value on error, | |
553 | including if \p float_field has no floating | |
554 | point number value yet. | |
555 | ||
556 | @prenotnull{float_field} | |
557 | @prenotnull{value} | |
558 | @preisfloatfield{float_field} | |
559 | @pre \p float_field contains a floating point number value previously | |
50842bdc | 560 | set with bt_field_floating_point_set_value(). |
91f379cb PP |
561 | @postrefcountsame{float_field} |
562 | ||
50842bdc | 563 | @sa bt_field_floating_point_set_value(): Sets the floating point |
91f379cb PP |
564 | number value of a given floating point number field. |
565 | */ | |
50842bdc PP |
566 | extern int bt_field_floating_point_get_value( |
567 | struct bt_field *float_field, double *value); | |
cd95e351 | 568 | |
91f379cb PP |
569 | /** |
570 | @brief Sets the floating point number value of the @floatfield | |
571 | \p float_field to \p value. | |
572 | ||
573 | @param[in] float_field Floating point number field of which to set | |
574 | the floating point number value. | |
575 | @param[in] value New floating point number value of | |
576 | \p float_field. | |
577 | @returns 0 on success, or a negative value on error. | |
578 | ||
579 | @prenotnull{float_field} | |
580 | @preisfloatfield{float_field} | |
581 | @prehot{float_field} | |
582 | @postrefcountsame{float_field} | |
583 | ||
50842bdc | 584 | @sa bt_field_floating_point_get_value(): Returns the floating point |
91f379cb PP |
585 | number value of a given floating point number field. |
586 | */ | |
50842bdc | 587 | extern int bt_field_floating_point_set_value( |
3dca2276 | 588 | struct bt_field *float_field, double value); |
adc315b8 | 589 | |
91f379cb PP |
590 | /** @} */ |
591 | ||
91f379cb | 592 | /** |
5c3f3b7e PP |
593 | @brief Returns a @enumftiter on all the mappings of the field type of |
594 | \p enum_field which contain the current integral value of the | |
595 | @enumfield \p enum_field in their range. | |
596 | ||
597 | This function is the equivalent of using | |
50842bdc PP |
598 | bt_field_type_enumeration_find_mappings_by_unsigned_value() or |
599 | bt_field_type_enumeration_find_mappings_by_signed_value() with the | |
5c3f3b7e PP |
600 | current integral value of \p enum_field. |
601 | ||
602 | @param[in] enum_field Enumeration field of which to get the mappings | |
603 | containing the current integral value of \p | |
604 | enum_field in their range. | |
605 | @returns @enumftiter on the set of mappings of the field | |
606 | type of \p enum_field which contain the current | |
607 | integral value of \p enum_field in their range, | |
608 | or \c NULL if no mappings were found or on | |
609 | error. | |
91f379cb PP |
610 | |
611 | @prenotnull{enum_field} | |
612 | @preisenumfield{enum_field} | |
613 | @pre The wrapped integer field of \p enum_field contains an integral | |
614 | value. | |
615 | @postrefcountsame{enum_field} | |
8dc7eb94 | 616 | @postsuccessrefcountret1 |
5c3f3b7e PP |
617 | @post <strong>On success</strong>, the returned @enumftiter can iterate |
618 | on at least one mapping. | |
91f379cb | 619 | */ |
50842bdc PP |
620 | extern struct bt_field_type_enumeration_mapping_iterator * |
621 | bt_field_enumeration_get_mappings(struct bt_field *enum_field); | |
91f379cb PP |
622 | |
623 | /** @} */ | |
624 | ||
625 | /** | |
626 | @defgroup ctfirstringfield CTF IR string field | |
627 | @ingroup ctfirfields | |
628 | @brief CTF IR string field. | |
629 | ||
630 | @code | |
631 | #include <babeltrace/ctf-ir/fields.h> | |
632 | @endcode | |
633 | ||
634 | A CTF IR <strong><em>string field</em></strong> is a @field which holds | |
635 | a string value, and which is described by a @stringft. | |
636 | ||
50842bdc PP |
637 | Use bt_field_string_set_value() to set the current string value |
638 | of a string field object. You can also use bt_field_string_append() | |
639 | and bt_field_string_append_len() to append a string to the current | |
91f379cb PP |
640 | value of a string field. |
641 | ||
50842bdc | 642 | After you create a string field with bt_field_create(), you |
91f379cb | 643 | \em must set a string value with |
50842bdc PP |
644 | bt_field_string_set_value(), bt_field_string_append(), or |
645 | bt_field_string_append_len() before you can get the | |
646 | field's value with bt_field_string_get_value(). | |
91f379cb PP |
647 | |
648 | @sa ctfirstringfieldtype | |
649 | @sa ctfirfields | |
650 | ||
651 | @addtogroup ctfirstringfield | |
652 | @{ | |
653 | */ | |
654 | ||
655 | /** | |
656 | @brief Returns the string value of the @stringfield \p string_field. | |
657 | ||
658 | On success, \p string_field remains the sole owner of the returned | |
659 | value. | |
660 | ||
661 | @param[in] string_field String field field of which to get the | |
662 | string value. | |
663 | @returns String value, or \c NULL on error. | |
664 | ||
665 | @prenotnull{string_field} | |
666 | @prenotnull{value} | |
667 | @preisstringfield{string_field} | |
668 | @pre \p string_field contains a string value previously | |
50842bdc PP |
669 | set with bt_field_string_set_value(), |
670 | bt_field_string_append(), or | |
671 | bt_field_string_append_len(). | |
91f379cb PP |
672 | @postrefcountsame{string_field} |
673 | ||
50842bdc | 674 | @sa bt_field_string_set_value(): Sets the string value of a given |
91f379cb PP |
675 | string field. |
676 | */ | |
3dca2276 | 677 | extern const char *bt_field_string_get_value(struct bt_field *string_field); |
cd95e351 | 678 | |
91f379cb PP |
679 | /** |
680 | @brief Sets the string value of the @stringfield \p string_field to | |
681 | \p value. | |
682 | ||
683 | @param[in] string_field String field of which to set | |
684 | the string value. | |
685 | @param[in] value New string value of \p string_field (copied | |
686 | on success). | |
687 | @returns 0 on success, or a negative value on error. | |
688 | ||
689 | @prenotnull{string_field} | |
690 | @prenotnull{value} | |
691 | @preisstringfield{string_field} | |
692 | @prehot{string_field} | |
693 | @postrefcountsame{string_field} | |
694 | ||
50842bdc | 695 | @sa bt_field_string_get_value(): Returns the string value of a |
91f379cb PP |
696 | given string field. |
697 | */ | |
50842bdc | 698 | extern int bt_field_string_set_value(struct bt_field *string_field, |
adc315b8 JG |
699 | const char *value); |
700 | ||
91f379cb PP |
701 | /** |
702 | @brief Appends the string \p value to the current string value of | |
703 | the @stringfield \p string_field. | |
704 | ||
705 | This function is the equivalent of: | |
706 | ||
707 | @code | |
50842bdc | 708 | bt_field_string_append_len(string_field, value, strlen(value)); |
91f379cb PP |
709 | @endcode |
710 | ||
711 | @param[in] string_field String field of which to append \p value to | |
712 | its current value. | |
713 | @param[in] value String to append to the current string value | |
714 | of \p string_field (copied on success). | |
715 | @returns 0 on success, or a negative value on error. | |
716 | ||
717 | @prenotnull{string_field} | |
718 | @prenotnull{value} | |
719 | @preisstringfield{string_field} | |
720 | @prehot{string_field} | |
721 | @postrefcountsame{string_field} | |
722 | ||
50842bdc | 723 | @sa bt_field_string_set_value(): Sets the string value of a given |
91f379cb PP |
724 | string field. |
725 | */ | |
50842bdc | 726 | extern int bt_field_string_append(struct bt_field *string_field, |
c6f9c5a3 PP |
727 | const char *value); |
728 | ||
91f379cb PP |
729 | /** |
730 | @brief Appends the first \p length characters of \p value to the | |
731 | current string value of the @stringfield \p string_field. | |
732 | ||
733 | If \p string_field has no current string value, this function first | |
734 | sets an empty string as the string value of \p string_field and then | |
735 | appends the first \p length characters of \p value. | |
736 | ||
737 | @param[in] string_field String field of which to append the first | |
738 | \p length characters of \p value to | |
739 | its current value. | |
740 | @param[in] value String containing the characters to append to | |
741 | the current string value of \p string_field | |
742 | (copied on success). | |
743 | @param[in] length Number of characters of \p value to append to | |
744 | the current string value of \p string_field. | |
745 | @returns 0 on success, or a negative value on error. | |
746 | ||
747 | @prenotnull{string_field} | |
748 | @prenotnull{value} | |
749 | @preisstringfield{string_field} | |
750 | @prehot{string_field} | |
751 | @postrefcountsame{string_field} | |
752 | ||
50842bdc | 753 | @sa bt_field_string_set_value(): Sets the string value of a given |
91f379cb PP |
754 | string field. |
755 | */ | |
50842bdc PP |
756 | extern int bt_field_string_append_len( |
757 | struct bt_field *string_field, const char *value, | |
f98c6554 PP |
758 | unsigned int length); |
759 | ||
312c056a PP |
760 | extern int bt_field_string_clear(struct bt_field *string_field); |
761 | ||
91f379cb | 762 | /** @} */ |
cd95e351 | 763 | |
91f379cb PP |
764 | /** |
765 | @defgroup ctfirstructfield CTF IR structure field | |
766 | @ingroup ctfirfields | |
767 | @brief CTF IR structure field. | |
4ebcc695 | 768 | |
91f379cb PP |
769 | @code |
770 | #include <babeltrace/ctf-ir/fields.h> | |
771 | @endcode | |
8f3553be | 772 | |
91f379cb PP |
773 | A CTF IR <strong><em>structure field</em></strong> is a @field which |
774 | contains an ordered list of zero or more named @fields which can be | |
775 | different @fts, and which is described by a @structft. | |
8f3553be | 776 | |
91f379cb | 777 | To set the value of a specific field of a structure field, you need to |
50842bdc PP |
778 | first get the field with bt_field_structure_get_field_by_name() or |
779 | bt_field_structure_get_field_by_index(). If you already have a | |
7fcd5734 | 780 | field object, you can assign it to a specific name within a structure |
50842bdc | 781 | field with bt_field_structure_set_field_by_name(). |
8f3553be | 782 | |
91f379cb PP |
783 | @sa ctfirstructfieldtype |
784 | @sa ctfirfields | |
8f3553be | 785 | |
91f379cb PP |
786 | @addtogroup ctfirstructfield |
787 | @{ | |
788 | */ | |
8f3553be | 789 | |
094ff7c0 PP |
790 | extern struct bt_field *bt_field_structure_borrow_field_by_name( |
791 | struct bt_field *struct_field, const char *name); | |
792 | ||
094ff7c0 PP |
793 | extern struct bt_field *bt_field_structure_borrow_field_by_index( |
794 | struct bt_field *struct_field, uint64_t index); | |
9ac68eb1 | 795 | |
91f379cb PP |
796 | /** @} */ |
797 | ||
798 | /** | |
799 | @defgroup ctfirarrayfield CTF IR array field | |
800 | @ingroup ctfirfields | |
801 | @brief CTF IR array field. | |
802 | ||
803 | @code | |
804 | #include <babeltrace/ctf-ir/fields.h> | |
805 | @endcode | |
806 | ||
807 | A CTF IR <strong><em>array field</em></strong> is a @field which | |
808 | contains an ordered list of zero or more @fields sharing the same @ft, | |
809 | and which is described by a @arrayft. | |
810 | ||
811 | To set the value of a specific field of an array field, you need to | |
50842bdc | 812 | first get the field with bt_field_array_get_field(). |
91f379cb PP |
813 | |
814 | @sa ctfirarrayfieldtype | |
815 | @sa ctfirfields | |
816 | ||
817 | @addtogroup ctfirarrayfield | |
818 | @{ | |
819 | */ | |
820 | ||
094ff7c0 PP |
821 | extern struct bt_field *bt_field_array_borrow_field( |
822 | struct bt_field *array_field, uint64_t index); | |
823 | ||
91f379cb PP |
824 | /** @} */ |
825 | ||
826 | /** | |
827 | @defgroup ctfirseqfield CTF IR sequence field | |
828 | @ingroup ctfirfields | |
829 | @brief CTF IR sequence field. | |
830 | ||
831 | @code | |
832 | #include <babeltrace/ctf-ir/fields.h> | |
833 | @endcode | |
834 | ||
835 | A CTF IR <strong><em>sequence field</em></strong> is a @field which | |
836 | contains an ordered list of zero or more @fields sharing the same @ft, | |
837 | and which is described by a @seqft. | |
838 | ||
839 | Before you can get a specific field of a sequence field with | |
50842bdc PP |
840 | bt_field_sequence_get_field(), you need to set its current length |
841 | @intfield with bt_field_sequence_set_length(). The integral value of | |
91f379cb PP |
842 | the length field of a sequence field indicates the number of fields |
843 | it contains. | |
844 | ||
845 | @sa ctfirseqfieldtype | |
846 | @sa ctfirfields | |
847 | ||
848 | @addtogroup ctfirseqfield | |
849 | @{ | |
850 | */ | |
851 | ||
094ff7c0 PP |
852 | extern struct bt_field *bt_field_sequence_borrow_field( |
853 | struct bt_field *sequence_field, uint64_t index); | |
854 | ||
312c056a | 855 | extern int64_t bt_field_sequence_get_length(struct bt_field *sequence_field); |
91f379cb PP |
856 | |
857 | /** | |
858 | @brief Sets the length @intfield of the @seqfield \p sequence_field | |
859 | to \p length_field. | |
860 | ||
861 | The current integral value of \p length_field indicates the number of | |
862 | fields contained in \p sequence_field. | |
863 | ||
864 | @param[in] sequence_field Sequence field of which to set the | |
865 | length field. | |
866 | @param[in] length_field Length field of \p sequence_field. | |
867 | @returns 0 on success, or a negative value on error. | |
868 | ||
869 | @prenotnull{sequence_field} | |
870 | @prenotnull{length_field} | |
871 | @preisseqfield{sequence_field} | |
872 | @preisintfield{length_field} | |
873 | @prehot{sequence_field} | |
874 | @postrefcountsame{sequence_field} | |
875 | @postsuccessrefcountinc{length_field} | |
876 | ||
50842bdc | 877 | @sa bt_field_sequence_get_length(): Returns the length field of a |
91f379cb PP |
878 | given sequence field. |
879 | */ | |
50842bdc | 880 | extern int bt_field_sequence_set_length(struct bt_field *sequence_field, |
312c056a | 881 | uint64_t length); |
91f379cb PP |
882 | |
883 | /** @} */ | |
884 | ||
885 | /** | |
886 | @defgroup ctfirvarfield CTF IR variant field | |
887 | @ingroup ctfirfields | |
888 | @brief CTF IR variant field. | |
889 | ||
890 | @code | |
891 | #include <babeltrace/ctf-ir/fields.h> | |
892 | @endcode | |
893 | ||
894 | A CTF IR <strong><em>variant field</em></strong> is a @field which | |
895 | contains a current @field amongst one or more choices, and which is | |
896 | described by a @varft. | |
897 | ||
50842bdc | 898 | Use bt_field_variant_get_field() to get the @field selected by |
91f379cb | 899 | a specific tag @enumfield. Once you call this function, you can call |
50842bdc | 900 | bt_field_variant_get_current_field() afterwards to get this last |
91f379cb PP |
901 | field again. |
902 | ||
903 | @sa ctfirvarfieldtype | |
904 | @sa ctfirfields | |
905 | ||
906 | @addtogroup ctfirvarfield | |
907 | @{ | |
908 | */ | |
909 | ||
312c056a PP |
910 | extern int bt_field_variant_set_tag_signed(struct bt_field *variant_field, |
911 | int64_t tag); | |
094ff7c0 | 912 | |
312c056a PP |
913 | extern int bt_field_variant_set_tag_unsigned(struct bt_field *variant_field, |
914 | uint64_t tag); | |
094ff7c0 | 915 | |
312c056a PP |
916 | extern int bt_field_variant_get_tag_signed(struct bt_field *variant_field, |
917 | int64_t *tag); | |
91f379cb | 918 | |
312c056a PP |
919 | extern int bt_field_variant_get_tag_unsigned(struct bt_field *variant_field, |
920 | uint64_t *tag); | |
094ff7c0 | 921 | |
312c056a | 922 | extern struct bt_field *bt_field_variant_borrow_current_field( |
50842bdc | 923 | struct bt_field *variant_field); |
91f379cb | 924 | |
91f379cb | 925 | /** @} */ |
a39fe52e | 926 | |
adc315b8 JG |
927 | #ifdef __cplusplus |
928 | } | |
929 | #endif | |
930 | ||
2e33ac5a | 931 | #endif /* BABELTRACE_CTF_IR_FIELDS_H */ |