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