Commit | Line | Data |
---|---|---|
56e18c4c | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
56e18c4c | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
56e18c4c PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_TRACE_IR_FIELD_H |
8 | #define BABELTRACE2_TRACE_IR_FIELD_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
56e18c4c PP |
16 | #include <stdint.h> |
17 | ||
3fadfbc0 | 18 | #include <babeltrace2/types.h> |
b19ff26f | 19 | |
56e18c4c PP |
20 | #ifdef __cplusplus |
21 | extern "C" { | |
22 | #endif | |
23 | ||
43c59509 PP |
24 | /*! |
25 | @defgroup api-tir-field Fields | |
26 | @ingroup api-tir | |
27 | ||
28 | @brief | |
29 | Containers of trace data. | |
30 | ||
31 | <strong><em>Fields</em></strong> are containers of trace data: they are | |
32 | found in \bt_p_ev and \bt_p_pkt. | |
33 | ||
34 | Fields are instances of \bt_p_fc: | |
35 | ||
36 | @image html field-class-zoom.png | |
37 | ||
38 | Borrow the class of a field with bt_field_borrow_class() and | |
39 | bt_field_borrow_class_const(). | |
40 | ||
41 | Fields are \ref api-tir "trace IR" data objects. | |
42 | ||
43 | There are many types of fields. They can be divided into two main | |
44 | categories: | |
45 | ||
46 | <dl> | |
47 | <dt>Scalar</dt> | |
48 | <dd> | |
49 | Fields which contain a simple value. | |
50 | ||
51 | The scalar fields are: | |
52 | ||
53 | - \ref api-tir-field-bool "Boolean" | |
54 | - \ref api-tir-field-ba "Bit array" | |
55 | - \ref api-tir-field-int "Integer" (unsigned and signed) | |
56 | - \ref api-tir-field-enum "Enumeration" (unsigned and signed) | |
57 | - \ref api-tir-field-real "Real" (single-precision and double-precision) | |
58 | - \ref api-tir-field-string "String" | |
59 | </dd> | |
60 | ||
61 | <dt>Container</dt> | |
62 | <dd> | |
63 | Fields which contain other fields. | |
64 | ||
65 | The container fields are: | |
66 | ||
67 | - \ref api-tir-field-array "Array" (static and dynamic) | |
68 | - \ref api-tir-field-struct "Structure" | |
69 | - \ref api-tir-field-opt "Option" | |
70 | - \ref api-tir-field-var "Variant" | |
71 | </dd> | |
72 | </dl> | |
73 | ||
74 | @image html fc-to-field.png "Fields (green) are instances of field classes (orange)." | |
75 | ||
76 | You cannot directly create a field: there are no | |
77 | <code>bt_field_*_create()</code> functions. The \bt_name library | |
78 | creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc. | |
79 | Therefore, to fill the payload fields of an \bt_ev, you must first | |
80 | borrow the event's existing payload \bt_struct_field with | |
81 | bt_event_borrow_payload_field() and then borrow each field, recursively, | |
82 | to set their values. | |
83 | ||
84 | The functions to borrow a field from an event or a packet are: | |
85 | ||
86 | - bt_packet_borrow_context_field() and | |
87 | bt_packet_borrow_context_field_const() | |
88 | - bt_event_borrow_common_context_field() and | |
89 | bt_event_borrow_common_context_field_const() | |
90 | - bt_event_borrow_specific_context_field() and | |
91 | bt_event_borrow_specific_context_field_const() | |
92 | - bt_event_borrow_payload_field() and | |
93 | bt_event_borrow_payload_field_const() | |
94 | ||
95 | Some fields conceptually inherit other fields, eventually | |
96 | making an inheritance hierarchy. For example, an \bt_enum_field | |
97 | \em is an \bt_int_field. Therefore, an enumeration field holds an | |
98 | integral value, just like an integer field does. | |
99 | ||
100 | The complete field inheritance hierarchy is: | |
101 | ||
102 | @image html all-fields.png | |
103 | ||
104 | This is the same inheritance hierarchy as the \bt_fc inheritance | |
105 | hierarchy. | |
106 | ||
107 | In the illustration above: | |
108 | ||
109 | - A field with a dark background is instantiated from a concrete \bt_fc, | |
110 | which you can directly create with a dedicated | |
111 | <code>bt_field_class_*_create()</code> function. | |
112 | ||
113 | - A field with a pale background is an \em abstract field: it's not a | |
114 | concrete instance, but it can have properties, therefore there can be | |
115 | functions which apply to it. | |
116 | ||
117 | For example, bt_field_integer_signed_set_value() applies to any | |
118 | \bt_sint_field. | |
119 | ||
120 | Fields are \ref api-fund-unique-object "unique objects": they belong | |
121 | to an \bt_ev or to a \bt_pkt. | |
122 | ||
123 | Some library functions \ref api-fund-freezing "freeze" fields on | |
124 | success. The documentation of those functions indicate this | |
125 | postcondition. | |
126 | ||
127 | All the field types share the same C type, #bt_field. | |
128 | ||
129 | Get the type enumerator of a field's class with bt_field_get_class_type(). | |
130 | Get whether or not a field class type conceptually \em is a given type | |
131 | with the inline bt_field_class_type_is() function. | |
132 | ||
133 | <h1>\anchor api-tir-field-bool Boolean field</h1> | |
134 | ||
135 | A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance. | |
136 | ||
137 | A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE). | |
138 | ||
139 | Set the value of a boolean field with bt_field_bool_set_value(). | |
140 | ||
141 | Get the value of a boolean field with bt_field_bool_get_value(). | |
142 | ||
143 | <h1>\anchor api-tir-field-ba Bit array field</h1> | |
144 | ||
145 | A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance. | |
146 | ||
147 | A bit array field contains a fixed-length array of bits. Its length | |
148 | is \ref api-tir-fc-ba-prop-len "given by its class". | |
149 | ||
150 | The bit array field API interprets the array as an unsigned integer | |
151 | value: the least significant bit's index is 0. | |
152 | ||
153 | For example, to get whether or not bit 3 of a bit array field is | |
154 | set: | |
155 | ||
156 | @code | |
157 | uint64_t value = bt_field_bit_array_get_value_as_integer(field); | |
158 | ||
159 | if (value & (UINT64_C(1) << UINT64_C(3))) { | |
160 | // Bit 3 is set | |
161 | } | |
162 | @endcode | |
163 | ||
164 | Set the bits of a bit array field with | |
165 | bt_field_bit_array_set_value_as_integer(). | |
166 | ||
167 | Get the bits of a bit array field with | |
168 | bt_field_bit_array_get_value_as_integer(). | |
169 | ||
170 | <h1>\anchor api-tir-field-int Integer fields</h1> | |
171 | ||
172 | <strong><em>Integer fields</em></strong> are \bt_int_fc instances. | |
173 | ||
174 | Integer fields contain integral values. | |
175 | ||
176 | An integer field is an \em abstract field. The concrete integer fields | |
177 | are: | |
178 | ||
179 | <dl> | |
180 | <dt>Unsigned integer field</dt> | |
181 | <dd> | |
182 | An \bt_uint_fc instance. | |
183 | ||
184 | An unsigned integer field contains an unsigned integral value | |
185 | (\c uint64_t). | |
186 | ||
187 | Set the value of an unsigned integer field with | |
188 | bt_field_integer_unsigned_set_value(). | |
189 | ||
190 | Get the value of an unsigned integer field with | |
191 | bt_field_integer_unsigned_get_value(). | |
192 | </dd> | |
193 | ||
194 | <dt>Signed integer field</dt> | |
195 | <dd> | |
196 | A \bt_sint_fc instance. | |
197 | ||
198 | A signed integer field contains a signed integral value (\c int64_t). | |
199 | ||
200 | Set the value of a signed integer field with | |
201 | bt_field_integer_signed_set_value(). | |
202 | ||
203 | Get the value of a signed integer field with | |
204 | bt_field_integer_signed_get_value(). | |
205 | </dd> | |
206 | </dl> | |
207 | ||
208 | <h2>\anchor api-tir-field-enum Enumeration fields</h2> | |
209 | ||
210 | <strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances. | |
211 | ||
212 | Enumeration fields \em are \bt_p_int_field: they contain integral | |
213 | values. | |
214 | ||
215 | An enumeration field is an \em abstract field. | |
216 | The concrete enumeration fields are: | |
217 | ||
218 | <dl> | |
219 | <dt>Unsigned enumeration field</dt> | |
220 | <dd> | |
221 | An \bt_uenum_fc instance. | |
222 | ||
223 | An unsigned enumeration field contains an unsigned integral value | |
224 | (\c uint64_t). | |
225 | ||
226 | Set the value of an unsigned enumeration field with | |
227 | bt_field_integer_unsigned_set_value(). | |
228 | ||
229 | Get the value of an unsigned enumeration field with | |
230 | bt_field_integer_unsigned_get_value(). | |
231 | ||
232 | Get all the enumeration field class labels mapped to the value of a | |
233 | given unsigned enumeration field with | |
234 | bt_field_enumeration_unsigned_get_mapping_labels(). | |
235 | </dd> | |
236 | ||
237 | <dt>Signed enumeration field</dt> | |
238 | <dd> | |
239 | A \bt_senum_fc instance. | |
240 | ||
241 | A signed enumeration field contains a signed integral value | |
242 | (\c int64_t). | |
243 | ||
244 | Set the value of a signed enumeration field with | |
245 | bt_field_integer_signed_set_value(). | |
246 | ||
247 | Get the value of a signed enumeration field with | |
248 | bt_field_integer_signed_get_value(). | |
249 | ||
250 | Get all the enumeration field class labels mapped to the value of a | |
251 | given signed enumeration field with | |
252 | bt_field_enumeration_signed_get_mapping_labels(). | |
253 | </dd> | |
254 | </dl> | |
255 | ||
256 | <h1>\anchor api-tir-field-real Real fields</h1> | |
257 | ||
258 | <strong><em>Real fields</em></strong> are \bt_real_fc instances. | |
259 | ||
260 | Real fields contain | |
261 | <a href="https://en.wikipedia.org/wiki/Real_number">real</a> | |
262 | values (\c float or \c double types). | |
263 | ||
264 | A real field is an \em abstract field. The concrete real fields are: | |
265 | ||
266 | <dl> | |
267 | <dt>Single-precision real field</dt> | |
268 | <dd> | |
269 | A single-precision real field class instance. | |
270 | ||
271 | A single-precision real field contains a \c float value. | |
272 | ||
273 | Set the value of a single-precision real field with | |
274 | bt_field_real_single_precision_set_value(). | |
275 | ||
276 | Get the value of a single-precision real field with | |
277 | bt_field_real_single_precision_get_value(). | |
278 | </dd> | |
279 | ||
280 | <dt>Double-precision real field</dt> | |
281 | <dd> | |
282 | A double-precision real field class instance. | |
283 | ||
284 | A double-precision real field contains a \c double value. | |
285 | ||
286 | Set the value of a double-precision real field with | |
287 | bt_field_real_double_precision_set_value(). | |
288 | ||
289 | Get the value of a double-precision real field with | |
290 | bt_field_real_double_precision_get_value(). | |
291 | </dd> | |
292 | </dl> | |
293 | ||
294 | <h1>\anchor api-tir-field-string String field</h1> | |
295 | ||
296 | A <strong><em>string field</em></strong> is a \bt_string_fc instance. | |
297 | ||
298 | A string field contains an UTF-8 string value. | |
299 | ||
300 | Set the value of a string field with | |
301 | bt_field_string_set_value(). | |
302 | ||
303 | Get the value of a string field with | |
304 | bt_field_string_get_value(). | |
305 | ||
306 | Get the length of a string field with | |
307 | bt_field_string_get_length(). | |
308 | ||
309 | Append a string to a string field's current value with | |
310 | bt_field_string_append() and bt_field_string_append_with_length(). | |
311 | ||
312 | Clear a string field with bt_field_string_clear(). | |
313 | ||
314 | <h1>\anchor api-tir-field-array Array fields</h1> | |
315 | ||
316 | <strong><em>Array fields</em></strong> are \bt_array_fc instances. | |
317 | ||
318 | Array fields contain zero or more fields which have the same class. | |
319 | ||
320 | An array field is an \em abstract field. The concrete array fields are: | |
321 | ||
322 | <dl> | |
323 | <dt>Static array field</dt> | |
324 | <dd> | |
325 | A \bt_sarray_fc instance. | |
326 | ||
327 | A static array field contains a fixed number of fields. Its length | |
328 | is \ref api-tir-fc-sarray-prop-len "given by its class". | |
329 | </dd> | |
330 | ||
331 | <dt>Dynamic array field class</dt> | |
332 | <dd> | |
333 | A \bt_darray_fc instance. | |
334 | ||
335 | A dynamic array field contains a variable number of fields, that is, | |
336 | each instance of the same dynamic array field class can contain a | |
337 | different number of elements. | |
338 | ||
339 | Set a dynamic array field's length with | |
340 | bt_field_array_dynamic_set_length() before you borrow any of its | |
341 | fields. | |
342 | </dd> | |
343 | </dl> | |
344 | ||
345 | Get an array field's length with bt_field_array_get_length(). | |
346 | ||
347 | Borrow a field from an array field at a given index with | |
348 | bt_field_array_borrow_element_field_by_index() and | |
349 | bt_field_array_borrow_element_field_by_index_const(). | |
350 | ||
351 | <h1>\anchor api-tir-field-struct Structure field</h1> | |
352 | ||
353 | A <strong><em>structure field</em></strong> is a \bt_struct_fc instance. | |
354 | ||
355 | A structure field contains an ordered list of zero or more members. A | |
356 | structure field member contains a field: it's an instance of a structure | |
357 | field class member. | |
358 | ||
359 | Borrow a member's field from a structure field at a given index with | |
360 | bt_field_structure_borrow_member_field_by_index() and | |
361 | bt_field_structure_borrow_member_field_by_index_const(). | |
362 | ||
363 | Borrow a member's field from a structure field by name with | |
364 | bt_field_structure_borrow_member_field_by_name() and | |
365 | bt_field_structure_borrow_member_field_by_name_const(). | |
366 | ||
367 | <h1>\anchor api-tir-field-opt Option field</h1> | |
368 | ||
369 | An <strong><em>option field</em></strong> is an \bt_opt_fc instance. | |
370 | ||
371 | An option field either does or doesn't contain a field. | |
372 | ||
373 | Set whether or not an option field has a field with | |
374 | bt_field_option_set_has_field(). | |
375 | ||
376 | Borrow the field from an option field with | |
377 | bt_field_option_borrow_field() or | |
378 | bt_field_option_borrow_field_const(). | |
379 | ||
380 | <h1>\anchor api-tir-field-var Variant field</h1> | |
381 | ||
382 | A <strong><em>variant field</em></strong> is a \bt_var_fc instance. | |
383 | ||
384 | A variant field has a single selected option amongst one or more | |
385 | possible options. A variant field option contains a field: it's an | |
386 | instance of a variant field class option. | |
387 | ||
388 | Set the current option of a variant field with | |
389 | bt_field_variant_select_option_by_index(). | |
390 | ||
391 | Get a variant field's selected option's index with | |
392 | bt_field_variant_get_selected_option_index(). | |
393 | ||
394 | Borrow a variant field's selected option's field with | |
395 | bt_field_variant_borrow_selected_option_field() and | |
396 | bt_field_variant_borrow_selected_option_field_const(). | |
397 | ||
398 | Borrow the class of a variant field's selected | |
399 | option with bt_field_variant_borrow_selected_option_class_const(), | |
400 | bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(), | |
401 | and | |
402 | bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(). | |
403 | */ | |
404 | ||
405 | /*! @{ */ | |
406 | ||
407 | /*! | |
408 | @name Type | |
409 | @{ | |
410 | ||
411 | @typedef struct bt_field bt_field; | |
412 | ||
413 | @brief | |
414 | Field. | |
415 | ||
416 | @} | |
417 | */ | |
418 | ||
419 | /*! | |
420 | @name Type query | |
421 | @{ | |
422 | */ | |
423 | ||
424 | /*! | |
425 | @brief | |
426 | Returns the type enumerator of the \ref api-tir-fc "class" of the | |
427 | field \bt_p{field}. | |
428 | ||
429 | This function returns | |
430 | ||
431 | @code | |
432 | bt_field_class_get_type(bt_field_borrow_class(field)) | |
433 | @endcode | |
434 | ||
435 | @param[in] field | |
436 | Field of which to get the class's type enumerator | |
437 | ||
438 | @returns | |
439 | Type enumerator of the class of \bt_p{field}. | |
440 | ||
441 | @bt_pre_not_null{field} | |
442 | ||
443 | @sa bt_field_class_get_type() — | |
444 | Returns the type enumerator of a \bt_fc. | |
445 | */ | |
446 | extern bt_field_class_type bt_field_get_class_type( | |
4c81a2b7 | 447 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
448 | |
449 | /*! @} */ | |
450 | ||
451 | /*! | |
452 | @name Class access | |
453 | @{ | |
454 | */ | |
455 | ||
456 | /*! | |
457 | @brief | |
458 | Borrows the \ref api-tir-fc "class" of the field \bt_p{field}. | |
459 | ||
460 | @param[in] field | |
461 | Field of which to borrow the class. | |
462 | ||
463 | @returns | |
464 | \em Borrowed reference of the class of \bt_p{field}. | |
465 | ||
466 | @bt_pre_not_null{field} | |
467 | ||
468 | @sa bt_field_borrow_class_const() — | |
469 | \c const version of this function. | |
470 | */ | |
4c81a2b7 | 471 | extern bt_field_class *bt_field_borrow_class(bt_field *field) __BT_NOEXCEPT; |
d29378b1 | 472 | |
43c59509 PP |
473 | /*! |
474 | @brief | |
475 | Borrows the \ref api-tir-fc "class" of the field \bt_p{field} | |
476 | (\c const version). | |
477 | ||
478 | See bt_field_borrow_class(). | |
479 | */ | |
480 | extern const bt_field_class *bt_field_borrow_class_const( | |
4c81a2b7 | 481 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
482 | |
483 | /*! @} */ | |
484 | ||
485 | /*! | |
486 | @name Boolean field | |
487 | @{ | |
488 | */ | |
489 | ||
490 | /*! | |
491 | @brief | |
492 | Sets the value of the \bt_bool_field \bt_p{field} to | |
493 | \bt_p{value}. | |
494 | ||
495 | @param[in] field | |
496 | Boolean field of which to set the value to \bt_p{value}. | |
497 | @param[in] value | |
498 | New value of \bt_p{field}. | |
499 | ||
500 | @bt_pre_not_null{field} | |
501 | @bt_pre_is_bool_field{field} | |
502 | @bt_pre_hot{field} | |
503 | ||
504 | @sa bt_field_bool_get_value() — | |
505 | Returns the value of a boolean field. | |
506 | */ | |
4c81a2b7 PP |
507 | extern void bt_field_bool_set_value(bt_field *field, bt_bool value) |
508 | __BT_NOEXCEPT; | |
5cebbe7f | 509 | |
43c59509 PP |
510 | /*! |
511 | @brief | |
512 | Returns the value of the \bt_bool_field \bt_p{field}. | |
513 | ||
514 | @param[in] field | |
515 | Boolean field of which to get the value. | |
516 | ||
517 | @returns | |
518 | Value of \bt_p{field}. | |
519 | ||
520 | @bt_pre_not_null{field} | |
521 | @bt_pre_is_bool_field{field} | |
522 | ||
523 | @sa bt_field_bool_set_value() — | |
524 | Sets the value of a boolean field. | |
525 | */ | |
4c81a2b7 | 526 | extern bt_bool bt_field_bool_get_value(const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
527 | |
528 | /*! @} */ | |
529 | ||
530 | /*! | |
531 | @name Bit array field | |
532 | @{ | |
533 | */ | |
534 | ||
535 | /*! | |
536 | @brief | |
537 | Sets the bits of the \bt_ba_field \bt_p{field} to the bits of | |
538 | \bt_p{bits}. | |
539 | ||
540 | The least significant bit's index is 0. | |
541 | ||
542 | See \bt_c_ba_field to learn more. | |
543 | ||
544 | @param[in] field | |
545 | Bit array field of which to set the bits to \bt_p{bits}. | |
546 | @param[in] bits | |
547 | New bits of \bt_p{field}. | |
548 | ||
549 | @bt_pre_not_null{field} | |
550 | @bt_pre_is_ba_field{field} | |
551 | @bt_pre_hot{field} | |
552 | ||
553 | @sa bt_field_bit_array_get_value_as_integer() — | |
554 | Returns the bits of a bit array field as an integer. | |
555 | */ | |
1094efa4 | 556 | extern void bt_field_bit_array_set_value_as_integer(bt_field *field, |
4c81a2b7 | 557 | uint64_t bits) __BT_NOEXCEPT; |
43c59509 PP |
558 | |
559 | /*! | |
560 | @brief | |
561 | Returns the bits of the \bt_ba_field \bt_p{field} as an | |
562 | unsigned integer. | |
563 | ||
564 | The least significant bit's index is 0. | |
565 | ||
566 | See \bt_c_ba_field to learn more. | |
567 | ||
568 | @param[in] field | |
569 | Bit array field of which to get the bits. | |
570 | ||
571 | @returns | |
572 | Bits of \bt_p{field} as an unsigned integer. | |
573 | ||
574 | @bt_pre_not_null{field} | |
575 | @bt_pre_is_ba_field{field} | |
576 | ||
577 | @sa bt_field_bit_array_set_value_as_integer() — | |
578 | Sets the bits of a bit array field from an integer. | |
579 | */ | |
580 | extern uint64_t bt_field_bit_array_get_value_as_integer( | |
4c81a2b7 | 581 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
582 | |
583 | /*! @} */ | |
584 | ||
585 | /*! | |
586 | @name Integer field | |
587 | @{ | |
588 | */ | |
589 | ||
590 | /*! | |
591 | @brief | |
592 | Sets the value of the \bt_uint_field \bt_p{field} to | |
593 | \bt_p{value}. | |
594 | ||
595 | @param[in] field | |
596 | Unsigned integer field of which to set the value to \bt_p{value}. | |
597 | @param[in] value | |
598 | New value of \bt_p{field}. | |
599 | ||
600 | @bt_pre_not_null{field} | |
601 | @bt_pre_is_uint_field{field} | |
602 | @bt_pre_hot{field} | |
603 | @pre | |
604 | \bt_p{value} is within the | |
605 | \ref api-tir-fc-int-prop-size "field value range" of the | |
606 | class of \bt_p{field}. | |
607 | ||
608 | @sa bt_field_integer_unsigned_get_value() — | |
609 | Returns the value of an unsigned integer field. | |
610 | */ | |
611 | extern void bt_field_integer_unsigned_set_value(bt_field *field, | |
4c81a2b7 | 612 | uint64_t value) __BT_NOEXCEPT; |
1094efa4 | 613 | |
43c59509 PP |
614 | /*! |
615 | @brief | |
616 | Returns the value of the \bt_uint_field \bt_p{field}. | |
617 | ||
618 | @param[in] field | |
619 | Unsigned integer field of which to get the value. | |
620 | ||
621 | @returns | |
622 | Value of \bt_p{field}. | |
623 | ||
624 | @bt_pre_not_null{field} | |
625 | @bt_pre_is_uint_field{field} | |
626 | ||
627 | @sa bt_field_integer_unsigned_set_value() — | |
628 | Sets the value of an unsigned integer field. | |
629 | */ | |
630 | extern uint64_t bt_field_integer_unsigned_get_value( | |
4c81a2b7 | 631 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
632 | |
633 | /*! | |
634 | @brief | |
635 | Sets the value of the \bt_sint_field \bt_p{field} to | |
636 | \bt_p{value}. | |
637 | ||
638 | @param[in] field | |
639 | Signed integer field of which to set the value to \bt_p{value}. | |
640 | @param[in] value | |
641 | New value of \bt_p{field}. | |
642 | ||
643 | @bt_pre_not_null{field} | |
644 | @bt_pre_is_sint_field{field} | |
645 | @bt_pre_hot{field} | |
646 | @pre | |
647 | \bt_p{value} is within the | |
648 | \ref api-tir-fc-int-prop-size "field value range" of the | |
649 | class of \bt_p{field}. | |
650 | ||
651 | @sa bt_field_integer_signed_get_value() — | |
652 | Returns the value of an signed integer field. | |
653 | */ | |
9c08c816 | 654 | extern void bt_field_integer_signed_set_value(bt_field *field, |
4c81a2b7 | 655 | int64_t value) __BT_NOEXCEPT; |
56e18c4c | 656 | |
43c59509 PP |
657 | /*! |
658 | @brief | |
659 | Returns the value of the \bt_sint_field \bt_p{field}. | |
660 | ||
661 | @param[in] field | |
662 | Signed integer field of which to get the value. | |
663 | ||
664 | @returns | |
665 | Value of \bt_p{field}. | |
666 | ||
667 | @bt_pre_not_null{field} | |
668 | @bt_pre_is_sint_field{field} | |
669 | ||
670 | @sa bt_field_integer_signed_set_value() — | |
671 | Sets the value of an signed integer field. | |
672 | */ | |
4c81a2b7 PP |
673 | extern int64_t bt_field_integer_signed_get_value( |
674 | const bt_field *field) __BT_NOEXCEPT; | |
43c59509 PP |
675 | |
676 | /*! @} */ | |
677 | ||
678 | /*! | |
679 | @name Enumeration field | |
680 | @{ | |
681 | */ | |
682 | ||
683 | /*! | |
684 | @brief | |
685 | Status codes for | |
686 | bt_field_enumeration_unsigned_get_mapping_labels() and | |
687 | bt_field_enumeration_signed_get_mapping_labels(). | |
688 | */ | |
689 | typedef enum bt_field_enumeration_get_mapping_labels_status { | |
690 | /*! | |
691 | @brief | |
692 | Success. | |
693 | */ | |
694 | BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK = __BT_FUNC_STATUS_OK, | |
695 | ||
696 | /*! | |
697 | @brief | |
698 | Out of memory. | |
699 | */ | |
700 | BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
701 | } bt_field_enumeration_get_mapping_labels_status; | |
702 | ||
703 | /*! | |
704 | @brief | |
705 | Returns an array of all the labels of the mappings of the | |
706 | \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field} | |
707 | of which the \bt_p_uint_rg contain the integral value | |
708 | of \bt_p{field}. | |
709 | ||
710 | This function returns | |
711 | ||
712 | @code | |
713 | (bt_field_enumeration_get_mapping_labels_status) | |
714 | bt_field_class_enumeration_unsigned_get_mapping_labels_for_value( | |
715 | bt_field_borrow_class_const(field), | |
716 | bt_field_integer_unsigned_get_value(field), | |
717 | labels, count) | |
718 | @endcode | |
719 | ||
720 | @param[in] field | |
721 | Unsigned enumeration field having the class from which to get the | |
722 | labels of the mappings of which the ranges contain its | |
723 | integral value. | |
724 | @param[out] labels | |
725 | See | |
726 | bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(). | |
727 | @param[out] count | |
728 | See | |
729 | bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(). | |
730 | ||
731 | @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK | |
732 | Success. | |
733 | @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR | |
734 | Out of memory. | |
735 | ||
736 | @bt_pre_not_null{field} | |
737 | @bt_pre_is_uenum_field{field} | |
738 | @bt_pre_not_null{labels} | |
739 | @bt_pre_not_null{count} | |
740 | */ | |
741 | extern bt_field_enumeration_get_mapping_labels_status | |
742 | bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field, | |
743 | bt_field_class_enumeration_mapping_label_array *labels, | |
4c81a2b7 | 744 | uint64_t *count) __BT_NOEXCEPT; |
43c59509 PP |
745 | |
746 | /*! | |
747 | @brief | |
748 | Returns an array of all the labels of the mappings of the | |
749 | \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field} | |
750 | of which the \bt_p_sint_rg contain the integral value | |
751 | of \bt_p{field}. | |
752 | ||
753 | This function returns | |
56e18c4c | 754 | |
43c59509 PP |
755 | @code |
756 | (bt_field_enumeration_get_mapping_labels_status) | |
757 | bt_field_class_enumeration_signed_get_mapping_labels_for_value( | |
758 | bt_field_borrow_class_const(field), | |
759 | bt_field_integer_signed_get_value(field), | |
760 | labels, count) | |
761 | @endcode | |
762 | ||
763 | @param[in] field | |
764 | Signed enumeration field having the class from which to get the | |
765 | labels of the mappings of which the ranges contain its | |
766 | integral value. | |
767 | @param[out] labels | |
768 | See | |
769 | bt_field_class_enumeration_signed_get_mapping_labels_for_value(). | |
770 | @param[out] count | |
771 | See | |
772 | bt_field_class_enumeration_signed_get_mapping_labels_for_value(). | |
773 | ||
774 | @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK | |
775 | Success. | |
776 | @retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR | |
777 | Out of memory. | |
778 | ||
779 | @bt_pre_not_null{field} | |
780 | @bt_pre_is_senum_field{field} | |
781 | @bt_pre_not_null{labels} | |
782 | @bt_pre_not_null{count} | |
783 | */ | |
784 | extern bt_field_enumeration_get_mapping_labels_status | |
785 | bt_field_enumeration_signed_get_mapping_labels(const bt_field *field, | |
786 | bt_field_class_enumeration_mapping_label_array *labels, | |
4c81a2b7 | 787 | uint64_t *count) __BT_NOEXCEPT; |
43c59509 PP |
788 | |
789 | /*! @} */ | |
790 | ||
791 | /*! | |
792 | @name Real field | |
793 | @{ | |
794 | */ | |
795 | ||
796 | /*! | |
797 | @brief | |
798 | Sets the value of the \bt_sreal_field \bt_p{field} to | |
799 | \bt_p{value}. | |
800 | ||
801 | @param[in] field | |
802 | Single-precision real field of which to set the value to | |
803 | \bt_p{value}. | |
804 | @param[in] value | |
805 | New value of \bt_p{field}. | |
806 | ||
807 | @bt_pre_not_null{field} | |
808 | @bt_pre_is_sreal_field{field} | |
809 | @bt_pre_hot{field} | |
810 | ||
811 | @sa bt_field_real_single_precision_get_value() — | |
812 | Returns the value of a single-precision real field. | |
813 | */ | |
fe4df857 | 814 | extern void bt_field_real_single_precision_set_value(bt_field *field, |
4c81a2b7 | 815 | float value) __BT_NOEXCEPT; |
fe4df857 | 816 | |
43c59509 PP |
817 | /*! |
818 | @brief | |
819 | Returns the value of the \bt_sreal_field \bt_p{field}. | |
820 | ||
821 | @param[in] field | |
822 | Single-precision real field of which to get the value. | |
823 | ||
824 | @returns | |
825 | Value of \bt_p{field}. | |
826 | ||
827 | @bt_pre_not_null{field} | |
828 | @bt_pre_is_sreal_field{field} | |
829 | ||
830 | @sa bt_field_real_single_precision_set_value() — | |
831 | Sets the value of a single-precision real field. | |
832 | */ | |
4c81a2b7 PP |
833 | extern float bt_field_real_single_precision_get_value( |
834 | const bt_field *field) __BT_NOEXCEPT; | |
43c59509 PP |
835 | |
836 | /*! | |
837 | @brief | |
838 | Sets the value of the \bt_dreal_field \bt_p{field} to | |
839 | \bt_p{value}. | |
840 | ||
841 | @param[in] field | |
842 | Double-precision real field of which to set the value to | |
843 | \bt_p{value}. | |
844 | @param[in] value | |
845 | New value of \bt_p{field}. | |
846 | ||
847 | @bt_pre_not_null{field} | |
848 | @bt_pre_is_dreal_field{field} | |
849 | @bt_pre_hot{field} | |
850 | ||
851 | @sa bt_field_real_double_precision_get_value() — | |
852 | Returns the value of a double-precision real field. | |
853 | */ | |
fe4df857 | 854 | extern void bt_field_real_double_precision_set_value(bt_field *field, |
4c81a2b7 | 855 | double value) __BT_NOEXCEPT; |
56e18c4c | 856 | |
43c59509 PP |
857 | /*! |
858 | @brief | |
859 | Returns the value of the \bt_dreal_field \bt_p{field}. | |
860 | ||
861 | @param[in] field | |
862 | Double-precision real field of which to get the value. | |
863 | ||
864 | @returns | |
865 | Value of \bt_p{field}. | |
866 | ||
867 | @bt_pre_not_null{field} | |
868 | @bt_pre_is_dreal_field{field} | |
869 | ||
870 | @sa bt_field_real_double_precision_set_value() — | |
871 | Sets the value of a double-precision real field. | |
872 | */ | |
4c81a2b7 PP |
873 | extern double bt_field_real_double_precision_get_value( |
874 | const bt_field *field) __BT_NOEXCEPT; | |
43c59509 PP |
875 | |
876 | /*! @} */ | |
877 | ||
878 | /*! | |
879 | @name String field | |
880 | @{ | |
881 | */ | |
882 | ||
883 | /*! | |
884 | @brief | |
885 | Status codes for bt_field_string_set_value(). | |
886 | */ | |
d24d5663 | 887 | typedef enum bt_field_string_set_value_status { |
43c59509 PP |
888 | /*! |
889 | @brief | |
890 | Success. | |
891 | */ | |
d24d5663 | 892 | BT_FIELD_STRING_SET_VALUE_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
893 | |
894 | /*! | |
895 | @brief | |
896 | Out of memory. | |
897 | */ | |
898 | BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 | 899 | } bt_field_string_set_value_status; |
56e18c4c | 900 | |
43c59509 PP |
901 | /*! |
902 | @brief | |
903 | Sets the value of the \bt_string_field \bt_p{field} to | |
904 | a copy of \bt_p{value}. | |
905 | ||
906 | @param[in] field | |
907 | String field of which to set the value to \bt_p{value}. | |
908 | @param[in] value | |
909 | New value of \bt_p{field} (copied). | |
910 | ||
911 | @retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK | |
912 | Success. | |
913 | @retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR | |
914 | Out of memory. | |
915 | ||
916 | @bt_pre_not_null{field} | |
917 | @bt_pre_is_string_field{field} | |
918 | @bt_pre_hot{field} | |
919 | @bt_pre_not_null{value} | |
920 | ||
921 | @sa bt_field_string_get_value() — | |
922 | Returns the value of a string field. | |
923 | @sa bt_field_string_append() — | |
924 | Appends a string to a string field. | |
925 | @sa bt_field_string_clear() — | |
926 | Clears a string field. | |
927 | */ | |
d24d5663 | 928 | extern bt_field_string_set_value_status bt_field_string_set_value( |
4c81a2b7 | 929 | bt_field *field, const char *value) __BT_NOEXCEPT; |
56e18c4c | 930 | |
43c59509 PP |
931 | /*! |
932 | @brief | |
933 | Returns the length of the \bt_string_field \bt_p{field}. | |
934 | ||
935 | @param[in] field | |
936 | String field of which to get the length. | |
937 | ||
938 | @returns | |
939 | Length of \bt_p{field}. | |
940 | ||
941 | @bt_pre_not_null{field} | |
942 | @bt_pre_is_string_field{field} | |
943 | */ | |
4c81a2b7 | 944 | extern uint64_t bt_field_string_get_length(const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
945 | |
946 | /*! | |
947 | @brief | |
948 | Returns the value of the \bt_string_field \bt_p{field}. | |
949 | ||
950 | @param[in] field | |
951 | String field of which to get the value. | |
952 | ||
953 | @returns | |
954 | @parblock | |
955 | Value of \bt_p{field}. | |
956 | ||
957 | The returned pointer remains valid until \bt_p{field} is modified. | |
958 | @endparblock | |
959 | ||
960 | @bt_pre_not_null{field} | |
961 | @bt_pre_is_string_field{field} | |
962 | ||
963 | @sa bt_field_string_set_value() — | |
964 | Sets the value of a string field. | |
965 | */ | |
4c81a2b7 PP |
966 | extern const char *bt_field_string_get_value( |
967 | const bt_field *field) __BT_NOEXCEPT; | |
43c59509 PP |
968 | |
969 | /*! | |
970 | @brief | |
971 | Status codes for bt_field_string_append() and | |
972 | bt_field_string_append_with_length(). | |
973 | */ | |
d24d5663 | 974 | typedef enum bt_field_string_append_status { |
43c59509 PP |
975 | /*! |
976 | @brief | |
977 | Success. | |
978 | */ | |
d24d5663 | 979 | BT_FIELD_STRING_APPEND_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
980 | |
981 | /*! | |
982 | @brief | |
983 | Out of memory. | |
984 | */ | |
985 | BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 | 986 | } bt_field_string_append_status; |
56e18c4c | 987 | |
43c59509 PP |
988 | /*! |
989 | @brief | |
990 | Appends a copy of the string \bt_p{value} to the current value of | |
991 | the \bt_string_field \bt_p{field}. | |
992 | ||
993 | @attention | |
994 | If you didn't set the value of \bt_p{field} yet, you must call | |
995 | bt_field_string_clear() before you call this function. | |
996 | ||
997 | @param[in] field | |
998 | String field to which to append the string \bt_p{value}. | |
999 | @param[in] value | |
1000 | String to append to \bt_p{field} (copied). | |
1001 | ||
1002 | @retval #BT_FIELD_STRING_APPEND_STATUS_OK | |
1003 | Success. | |
1004 | @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR | |
1005 | Out of memory. | |
1006 | ||
1007 | @bt_pre_not_null{field} | |
1008 | @bt_pre_is_string_field{field} | |
1009 | @bt_pre_hot{field} | |
1010 | @bt_pre_not_null{value} | |
1011 | ||
1012 | @sa bt_field_string_append_with_length() — | |
1013 | Appends a string with a given length to a string field. | |
1014 | @sa bt_field_string_set_value() — | |
1015 | Sets the value of a string field. | |
1016 | */ | |
d24d5663 | 1017 | extern bt_field_string_append_status bt_field_string_append( |
4c81a2b7 | 1018 | bt_field *field, const char *value) __BT_NOEXCEPT; |
d24d5663 | 1019 | |
43c59509 PP |
1020 | /*! |
1021 | @brief | |
1022 | Appends a copy of the first \bt_p{length} bytes of the string | |
1023 | \bt_p{value} to the current value of the \bt_string_field | |
1024 | \bt_p{field}. | |
1025 | ||
1026 | @attention | |
1027 | If you didn't set the value of \bt_p{field} yet, you must call | |
1028 | bt_field_string_clear() before you call this function. | |
1029 | ||
1030 | @param[in] field | |
1031 | String field to which to append the first \bt_p{length} bytes of | |
1032 | the string \bt_p{value}. | |
1033 | @param[in] value | |
1034 | String of which to append the first \bt_p{length} bytes to | |
1035 | \bt_p{field} (copied). | |
1036 | @param[in] length | |
1037 | Number of bytes of \bt_p{value} to append to \bt_p{field}. | |
1038 | ||
1039 | @retval #BT_FIELD_STRING_APPEND_STATUS_OK | |
1040 | Success. | |
1041 | @retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR | |
1042 | Out of memory. | |
1043 | ||
1044 | @bt_pre_not_null{field} | |
1045 | @bt_pre_is_string_field{field} | |
1046 | @bt_pre_hot{field} | |
1047 | @bt_pre_not_null{value} | |
1048 | ||
1049 | @sa bt_field_string_append() — | |
1050 | Appends a string to a string field. | |
1051 | @sa bt_field_string_set_value() — | |
1052 | Sets the value of a string field. | |
1053 | */ | |
d24d5663 | 1054 | extern bt_field_string_append_status bt_field_string_append_with_length( |
4c81a2b7 PP |
1055 | bt_field *field, const char *value, uint64_t length) |
1056 | __BT_NOEXCEPT; | |
d24d5663 | 1057 | |
43c59509 PP |
1058 | /*! |
1059 | @brief | |
1060 | Clears the \bt_string_field \bt_p{field}, making its value an empty | |
1061 | string. | |
1062 | ||
1063 | @param[in] field | |
1064 | String field to clear. | |
1065 | ||
1066 | @bt_pre_not_null{field} | |
1067 | @bt_pre_is_string_field{field} | |
1068 | @bt_pre_hot{field} | |
1069 | ||
1070 | @sa bt_field_string_set_value() — | |
1071 | Sets the value of a string field. | |
1072 | */ | |
4c81a2b7 | 1073 | extern void bt_field_string_clear(bt_field *field) __BT_NOEXCEPT; |
56e18c4c | 1074 | |
43c59509 | 1075 | /*! @} */ |
56e18c4c | 1076 | |
43c59509 PP |
1077 | /*! |
1078 | @name Array field | |
1079 | @{ | |
1080 | */ | |
1081 | ||
1082 | /*! | |
1083 | @brief | |
1084 | Returns the length of the \bt_array_field \bt_p{field}. | |
1085 | ||
1086 | @param[in] field | |
1087 | Array field of which to get the length. | |
1088 | ||
1089 | @returns | |
1090 | Length of \bt_p{field}. | |
1091 | ||
1092 | @bt_pre_not_null{field} | |
1093 | @bt_pre_is_array_field{field} | |
1094 | */ | |
4c81a2b7 | 1095 | extern uint64_t bt_field_array_get_length(const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1096 | |
1097 | /*! | |
1098 | @brief | |
1099 | Borrows the field at index \bt_p{index} from the \bt_array_field | |
1100 | \bt_p{field}. | |
56e18c4c | 1101 | |
43c59509 PP |
1102 | @attention |
1103 | If \bt_p{field} is a dynamic array field, it must have a length | |
1104 | (call bt_field_array_dynamic_set_length()) before you call this | |
1105 | function. | |
1106 | ||
1107 | @param[in] field | |
1108 | Array field from which to borrow the field at index \bt_p{index}. | |
1109 | @param[in] index | |
1110 | Index of the field to borrow from \bt_p{field}. | |
1111 | ||
1112 | @returns | |
1113 | @parblock | |
1114 | \em Borrowed reference of the field of \bt_p{field} at index | |
1115 | \bt_p{index}. | |
1116 | ||
1117 | The returned pointer remains valid as long as \bt_p{field} exists. | |
1118 | @endparblock | |
1119 | ||
1120 | @bt_pre_not_null{field} | |
1121 | @bt_pre_is_array_field{field} | |
1122 | @pre | |
1123 | \bt_p{index} is less than the length of \bt_p{field} (as returned by | |
1124 | bt_field_array_get_length()). | |
1125 | ||
1126 | @sa bt_field_array_borrow_element_field_by_index_const() — | |
1127 | \c const version of this function. | |
1128 | */ | |
b19ff26f | 1129 | extern bt_field *bt_field_array_borrow_element_field_by_index( |
4c81a2b7 | 1130 | bt_field *field, uint64_t index) __BT_NOEXCEPT; |
56e18c4c | 1131 | |
43c59509 PP |
1132 | /*! |
1133 | @brief | |
1134 | Borrows the field at index \bt_p{index} from the \bt_array_field | |
1135 | \bt_p{field} (\c const version). | |
1136 | ||
1137 | See bt_field_array_borrow_element_field_by_index(). | |
1138 | */ | |
1139 | extern const bt_field * | |
1140 | bt_field_array_borrow_element_field_by_index_const( | |
4c81a2b7 | 1141 | const bt_field *field, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1142 | |
1143 | /*! | |
1144 | @brief | |
1145 | Status codes for bt_field_array_dynamic_set_length(). | |
1146 | */ | |
9c08c816 | 1147 | typedef enum bt_field_array_dynamic_set_length_status { |
43c59509 PP |
1148 | /*! |
1149 | @brief | |
1150 | Success. | |
1151 | */ | |
d24d5663 | 1152 | BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1153 | |
1154 | /*! | |
1155 | @brief | |
1156 | Out of memory. | |
1157 | */ | |
1158 | BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
9c08c816 | 1159 | } bt_field_array_dynamic_set_length_status; |
d24d5663 | 1160 | |
43c59509 PP |
1161 | /*! |
1162 | @brief | |
1163 | Sets the length of the \bt_darray_field \bt_p{field}. | |
1164 | ||
1165 | @param[in] field | |
1166 | Dynamic array field of which to set the length. | |
1167 | @param[in] length | |
1168 | New length of \bt_p{field}. | |
1169 | ||
1170 | @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK | |
1171 | Success. | |
1172 | @retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR | |
1173 | Out of memory. | |
1174 | ||
1175 | @bt_pre_not_null{field} | |
1176 | @bt_pre_is_darray_field{field} | |
1177 | @bt_pre_hot{field} | |
1178 | */ | |
9c08c816 | 1179 | extern bt_field_array_dynamic_set_length_status |
4c81a2b7 PP |
1180 | bt_field_array_dynamic_set_length(bt_field *field, uint64_t length) |
1181 | __BT_NOEXCEPT; | |
43c59509 PP |
1182 | |
1183 | /*! @} */ | |
1184 | ||
1185 | /*! | |
1186 | @name Structure field | |
1187 | @{ | |
1188 | */ | |
1189 | ||
1190 | /*! | |
1191 | @brief | |
1192 | Borrows the field of the member at index \bt_p{index} from the | |
1193 | \bt_struct_field \bt_p{field}. | |
1194 | ||
1195 | @param[in] field | |
1196 | Structure field from which to borrow the field of the member at | |
1197 | index \bt_p{index}. | |
1198 | @param[in] index | |
1199 | Index of the member containing the field to borrow from | |
1200 | \bt_p{field}. | |
1201 | ||
1202 | @returns | |
1203 | @parblock | |
1204 | \em Borrowed reference of the field of the member of \bt_p{field} at | |
1205 | index \bt_p{index}. | |
1206 | ||
1207 | The returned pointer remains valid as long as \bt_p{field} exists. | |
1208 | @endparblock | |
1209 | ||
1210 | @bt_pre_not_null{field} | |
1211 | @bt_pre_is_struct_field{field} | |
1212 | @pre | |
1213 | \bt_p{index} is less than the number of members in the | |
1214 | \ref api-tir-fc-struct "class" of \bt_p{field} (as | |
1215 | returned by bt_field_class_structure_get_member_count()). | |
1216 | ||
1217 | @sa bt_field_structure_borrow_member_field_by_index_const() — | |
1218 | \c const version of this function. | |
1219 | */ | |
1220 | extern bt_field *bt_field_structure_borrow_member_field_by_index( | |
4c81a2b7 | 1221 | bt_field *field, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1222 | |
1223 | /*! | |
1224 | @brief | |
1225 | Borrows the field of the member at index \bt_p{index} from the | |
1226 | \bt_struct_field \bt_p{field} (\c const version). | |
1227 | ||
1228 | See bt_field_structure_borrow_member_field_by_index(). | |
1229 | */ | |
1230 | extern const bt_field * | |
1231 | bt_field_structure_borrow_member_field_by_index_const( | |
4c81a2b7 | 1232 | const bt_field *field, uint64_t index) __BT_NOEXCEPT; |
43c59509 PP |
1233 | |
1234 | /*! | |
1235 | @brief | |
1236 | Borrows the field of the member having the name \bt_p{name} from the | |
1237 | \bt_struct_field \bt_p{field}. | |
1238 | ||
1239 | If there's no member having the name \bt_p{name} in the | |
1240 | \ref api-tir-fc-struct "class" of \bt_p{field}, this function | |
1241 | returns \c NULL. | |
1242 | ||
1243 | @param[in] field | |
1244 | Structure field from which to borrow the field of the member having | |
1245 | the name \bt_p{name}. | |
1246 | @param[in] name | |
1247 | Name of the member containing the field to borrow from \bt_p{field}. | |
1248 | ||
1249 | @returns | |
1250 | @parblock | |
1251 | \em Borrowed reference of the field of the member of \bt_p{field} | |
1252 | having the name \bt_p{name}, or \c NULL if none. | |
1253 | ||
1254 | The returned pointer remains valid as long as \bt_p{field} exists. | |
1255 | @endparblock | |
1256 | ||
1257 | @bt_pre_not_null{field} | |
1258 | @bt_pre_is_struct_field{field} | |
1259 | @bt_pre_not_null{name} | |
1260 | ||
1261 | @sa bt_field_structure_borrow_member_field_by_name_const() — | |
1262 | \c const version of this function. | |
1263 | */ | |
1264 | extern bt_field *bt_field_structure_borrow_member_field_by_name( | |
4c81a2b7 | 1265 | bt_field *field, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
1266 | |
1267 | /*! | |
1268 | @brief | |
1269 | Borrows the field of the member having the name \bt_p{name} from the | |
1270 | \bt_struct_field \bt_p{field} (\c const version). | |
1271 | ||
1272 | See bt_field_structure_borrow_member_field_by_name(). | |
1273 | */ | |
1274 | extern const bt_field * | |
1275 | bt_field_structure_borrow_member_field_by_name_const( | |
4c81a2b7 | 1276 | const bt_field *field, const char *name) __BT_NOEXCEPT; |
43c59509 PP |
1277 | |
1278 | /*! @} */ | |
1279 | ||
1280 | /*! | |
1281 | @name Option field | |
1282 | @{ | |
1283 | */ | |
1284 | ||
1285 | /*! | |
1286 | @brief | |
1287 | Sets whether or not the \bt_opt_field \bt_p{field} | |
1288 | has a field. | |
40f4ba76 | 1289 | |
43c59509 PP |
1290 | @param[in] field |
1291 | Option field of which to set whether or not it has a field. | |
1292 | @param[in] has_field | |
1293 | #BT_TRUE to make \bt_p{field} have a field. | |
1294 | ||
1295 | @bt_pre_not_null{field} | |
1296 | @bt_pre_is_opt_field{field} | |
1297 | */ | |
4c81a2b7 PP |
1298 | extern void bt_field_option_set_has_field(bt_field *field, bt_bool has_field) |
1299 | __BT_NOEXCEPT; | |
b38aea74 | 1300 | |
43c59509 PP |
1301 | /*! |
1302 | @brief | |
1303 | Borrows the field of the \bt_opt_field \bt_p{field}. | |
1304 | ||
1305 | @attention | |
1306 | You must call bt_field_option_set_has_field() before you call | |
1307 | this function. | |
1308 | ||
1309 | If \bt_p{field} has no field, this function returns \c NULL. | |
1310 | ||
1311 | @param[in] field | |
1312 | Option field from which to borrow the field. | |
1313 | ||
1314 | @returns | |
1315 | @parblock | |
1316 | \em Borrowed reference of the field of \bt_p{field}, | |
1317 | or \c NULL if none. | |
1318 | ||
1319 | The returned pointer remains valid as long as \bt_p{field} exists. | |
1320 | @endparblock | |
1321 | ||
1322 | @bt_pre_not_null{field} | |
1323 | @bt_pre_is_opt_field{field} | |
1324 | ||
1325 | @sa bt_field_option_set_has_field() — | |
1326 | Sets whether or not an option field has a field. | |
1327 | @sa bt_field_option_borrow_field_const() — | |
1328 | \c const version of this function. | |
1329 | */ | |
4c81a2b7 | 1330 | extern bt_field *bt_field_option_borrow_field(bt_field *field) __BT_NOEXCEPT; |
b38aea74 | 1331 | |
43c59509 PP |
1332 | /*! |
1333 | @brief | |
1334 | Borrows the field of the \bt_opt_field \bt_p{field} | |
1335 | (\c const version). | |
1336 | ||
1337 | See bt_field_option_borrow_field(). | |
1338 | */ | |
1339 | extern const bt_field * | |
4c81a2b7 | 1340 | bt_field_option_borrow_field_const(const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1341 | |
1342 | /*! @} */ | |
1343 | ||
1344 | /*! | |
1345 | @name Variant field | |
1346 | @{ | |
1347 | */ | |
1348 | ||
1349 | /*! | |
1350 | @brief | |
1351 | Status code for bt_field_variant_select_option_by_index(). | |
1352 | */ | |
7b4311c1 | 1353 | typedef enum bt_field_variant_select_option_by_index_status { |
43c59509 PP |
1354 | /*! |
1355 | @brief | |
1356 | Success. | |
1357 | */ | |
1358 | BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK = __BT_FUNC_STATUS_OK, | |
7b4311c1 | 1359 | } bt_field_variant_select_option_by_index_status; |
d24d5663 | 1360 | |
43c59509 PP |
1361 | /*! |
1362 | @brief | |
1363 | Sets the selected option of the \bt_var_field \bt_p{field} | |
1364 | to the option at index \bt_p{index}. | |
1365 | ||
1366 | @param[in] field | |
1367 | Variant field of which to set the selected option. | |
1368 | @param[in] index | |
1369 | Index of the option to set as the selected option of \bt_p{field}. | |
1370 | ||
1371 | @retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK | |
1372 | Success. | |
1373 | ||
1374 | @bt_pre_not_null{field} | |
1375 | @bt_pre_is_var_field{field} | |
1376 | @pre | |
1377 | \bt_p{index} is less than the number of options in the | |
1378 | \ref api-tir-fc-var "class" of \bt_p{field} (as | |
1379 | returned by bt_field_class_variant_get_option_count()). | |
1380 | */ | |
7b4311c1 PP |
1381 | extern bt_field_variant_select_option_by_index_status |
1382 | bt_field_variant_select_option_by_index( | |
4c81a2b7 | 1383 | bt_field *field, uint64_t index) __BT_NOEXCEPT; |
56e18c4c | 1384 | |
43c59509 PP |
1385 | /*! |
1386 | @brief | |
1387 | Borrows the field of the selected option of the \bt_var_field | |
1388 | \bt_p{field}. | |
1389 | ||
1390 | @attention | |
1391 | You must call bt_field_variant_select_option_by_index() before | |
1392 | you call this function. | |
1393 | ||
1394 | @param[in] field | |
1395 | Variant field from which to borrow the selected option's field. | |
1396 | ||
1397 | @returns | |
1398 | @parblock | |
1399 | \em Borrowed reference of the field of the selected option of | |
1400 | \bt_p{field}, or \c NULL if none. | |
1401 | ||
1402 | The returned pointer remains valid as long as \bt_p{field} exists. | |
1403 | @endparblock | |
1404 | ||
1405 | @bt_pre_not_null{field} | |
1406 | @bt_pre_is_var_field{field} | |
1407 | ||
1408 | @sa bt_field_variant_select_option_by_index() — | |
1409 | Sets a variant field's selected option. | |
1410 | @sa bt_field_variant_get_selected_option_index() — | |
1411 | Returns the index of a variant field's selected option. | |
1412 | @sa bt_field_variant_borrow_selected_option_field_const() — | |
1413 | \c const version of this function. | |
1414 | */ | |
b19ff26f | 1415 | extern bt_field *bt_field_variant_borrow_selected_option_field( |
4c81a2b7 | 1416 | bt_field *field) __BT_NOEXCEPT; |
56e18c4c | 1417 | |
43c59509 PP |
1418 | /*! |
1419 | @brief | |
1420 | Borrows the field of the selected option of the \bt_var_field | |
1421 | \bt_p{field} (\c const version). | |
1422 | ||
1423 | See bt_field_variant_borrow_selected_option_field(). | |
1424 | */ | |
1425 | extern const bt_field * | |
1426 | bt_field_variant_borrow_selected_option_field_const( | |
4c81a2b7 | 1427 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1428 | |
1429 | /*! | |
1430 | @brief | |
1431 | Returns the index of the selected option of the \bt_var_field | |
1432 | \bt_p{field}. | |
1433 | ||
1434 | @param[in] field | |
1435 | Variant field of which to get the index of the selected option. | |
1436 | ||
1437 | @returns | |
1438 | Index of the selected option of \bt_p{field}. | |
1439 | ||
1440 | @bt_pre_not_null{field} | |
1441 | @bt_pre_is_var_field{field} | |
1442 | ||
1443 | @sa bt_field_variant_borrow_selected_option_field_const() — | |
1444 | Borrows the field of a variant field's selected option. | |
1445 | */ | |
1446 | extern uint64_t bt_field_variant_get_selected_option_index( | |
4c81a2b7 | 1447 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1448 | |
1449 | /*! | |
1450 | @brief | |
1451 | Borrows the class of the selected option of the \bt_var_field | |
1452 | \bt_p{field}. | |
1453 | ||
1454 | This function returns | |
1455 | ||
1456 | @code | |
1457 | bt_field_class_variant_borrow_option_by_index( | |
1458 | bt_field_variant_get_selected_option_index(field)) | |
1459 | @endcode | |
1460 | ||
1461 | @param[in] field | |
1462 | Variant field of which to get the selected option's class. | |
1463 | ||
1464 | @returns | |
1465 | Class of the selected option of \bt_p{field}. | |
1466 | ||
1467 | @bt_pre_not_null{field} | |
1468 | @bt_pre_is_var_field{field} | |
1469 | */ | |
1470 | extern const bt_field_class_variant_option * | |
1471 | bt_field_variant_borrow_selected_option_class_const( | |
4c81a2b7 | 1472 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1473 | |
1474 | /*! | |
1475 | @brief | |
1476 | Borrows the class of the selected option of the \bt_var_field | |
1477 | (with an unsigned integer selector field) \bt_p{field}. | |
1478 | ||
1479 | This function returns | |
1480 | ||
1481 | @code | |
1482 | bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const( | |
1483 | bt_field_variant_get_selected_option_index(field)) | |
1484 | @endcode | |
1485 | ||
1486 | @param[in] field | |
1487 | Variant field of which to get the selected option's class. | |
1488 | ||
1489 | @returns | |
1490 | Class of the selected option of \bt_p{field}. | |
1491 | ||
1492 | @bt_pre_not_null{field} | |
1493 | @bt_pre_is_var_wuis_field{field} | |
1494 | */ | |
1495 | extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * | |
1496 | bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const( | |
4c81a2b7 | 1497 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1498 | |
1499 | /*! | |
1500 | @brief | |
1501 | Borrows the class of the selected option of the \bt_var_field | |
1502 | (with a signed integer selector field) \bt_p{field}. | |
1503 | ||
1504 | This function returns | |
1505 | ||
1506 | @code | |
1507 | bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const( | |
1508 | bt_field_variant_get_selected_option_index(field)) | |
1509 | @endcode | |
1510 | ||
1511 | @param[in] field | |
1512 | Variant field of which to get the selected option's class. | |
1513 | ||
1514 | @returns | |
1515 | Class of the selected option of \bt_p{field}. | |
1516 | ||
1517 | @bt_pre_not_null{field} | |
1518 | @bt_pre_is_var_wsis_field{field} | |
1519 | */ | |
1520 | extern const bt_field_class_variant_with_selector_field_integer_signed_option * | |
1521 | bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const( | |
4c81a2b7 | 1522 | const bt_field *field) __BT_NOEXCEPT; |
43c59509 PP |
1523 | |
1524 | /*! @} */ | |
1525 | ||
1526 | /*! @} */ | |
1527 | ||
56e18c4c PP |
1528 | #ifdef __cplusplus |
1529 | } | |
1530 | #endif | |
1531 | ||
924dc299 | 1532 | #endif /* BABELTRACE2_TRACE_IR_FIELD_H */ |