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