Commit | Line | Data |
---|---|---|
924dc299 PP |
1 | #ifndef BABELTRACE2_TRACE_IR_FIELD_H |
2 | #define BABELTRACE2_TRACE_IR_FIELD_H | |
56e18c4c PP |
3 | |
4 | /* | |
bbb7b5f0 | 5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation |
56e18c4c | 6 | * |
56e18c4c PP |
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. | |
56e18c4c PP |
24 | */ |
25 | ||
4fa90f32 PP |
26 | #ifndef __BT_IN_BABELTRACE_H |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
56e18c4c PP |
30 | #include <stdint.h> |
31 | ||
3fadfbc0 | 32 | #include <babeltrace2/types.h> |
b19ff26f | 33 | |
56e18c4c PP |
34 | #ifdef __cplusplus |
35 | extern "C" { | |
36 | #endif | |
37 | ||
43c59509 PP |
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 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() — | |
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() — | |
483 | \c const version of this function. | |
484 | */ | |
d29378b1 FD |
485 | extern bt_field_class *bt_field_borrow_class(bt_field *field); |
486 | ||
43c59509 PP |
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() — | |
519 | Returns the value of a boolean field. | |
520 | */ | |
5cebbe7f PP |
521 | extern void bt_field_bool_set_value(bt_field *field, bt_bool value); |
522 | ||
43c59509 PP |
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() — | |
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() — | |
567 | Returns the bits of a bit array field as an integer. | |
568 | */ | |
1094efa4 | 569 | extern void bt_field_bit_array_set_value_as_integer(bt_field *field, |
43c59509 PP |
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() — | |
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() — | |
622 | Returns the value of an unsigned integer field. | |
623 | */ | |
624 | extern void bt_field_integer_unsigned_set_value(bt_field *field, | |
1094efa4 PP |
625 | uint64_t value); |
626 | ||
43c59509 PP |
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() — | |
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() — | |
665 | Returns the value of an signed integer field. | |
666 | */ | |
9c08c816 | 667 | extern void bt_field_integer_signed_set_value(bt_field *field, |
40f4ba76 | 668 | int64_t value); |
56e18c4c | 669 | |
43c59509 PP |
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() — | |
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 | |
56e18c4c | 766 | |
43c59509 PP |
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() — | |
824 | Returns the value of a single-precision real field. | |
825 | */ | |
fe4df857 FD |
826 | extern void bt_field_real_single_precision_set_value(bt_field *field, |
827 | float value); | |
828 | ||
43c59509 PP |
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() — | |
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() — | |
863 | Returns the value of a double-precision real field. | |
864 | */ | |
fe4df857 FD |
865 | extern void bt_field_real_double_precision_set_value(bt_field *field, |
866 | double value); | |
56e18c4c | 867 | |
43c59509 PP |
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() — | |
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 | */ | |
d24d5663 | 897 | typedef enum bt_field_string_set_value_status { |
43c59509 PP |
898 | /*! |
899 | @brief | |
900 | Success. | |
901 | */ | |
d24d5663 | 902 | BT_FIELD_STRING_SET_VALUE_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
903 | |
904 | /*! | |
905 | @brief | |
906 | Out of memory. | |
907 | */ | |
908 | BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 | 909 | } bt_field_string_set_value_status; |
56e18c4c | 910 | |
43c59509 PP |
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() — | |
932 | Returns the value of a string field. | |
933 | @sa bt_field_string_append() — | |
934 | Appends a string to a string field. | |
935 | @sa bt_field_string_clear() — | |
936 | Clears a string field. | |
937 | */ | |
d24d5663 PP |
938 | extern bt_field_string_set_value_status bt_field_string_set_value( |
939 | bt_field *field, const char *value); | |
56e18c4c | 940 | |
43c59509 PP |
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() — | |
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 | */ | |
d24d5663 | 983 | typedef enum bt_field_string_append_status { |
43c59509 PP |
984 | /*! |
985 | @brief | |
986 | Success. | |
987 | */ | |
d24d5663 | 988 | BT_FIELD_STRING_APPEND_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
989 | |
990 | /*! | |
991 | @brief | |
992 | Out of memory. | |
993 | */ | |
994 | BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
d24d5663 | 995 | } bt_field_string_append_status; |
56e18c4c | 996 | |
43c59509 PP |
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() — | |
1022 | Appends a string with a given length to a string field. | |
1023 | @sa bt_field_string_set_value() — | |
1024 | Sets the value of a string field. | |
1025 | */ | |
d24d5663 PP |
1026 | extern bt_field_string_append_status bt_field_string_append( |
1027 | bt_field *field, const char *value); | |
1028 | ||
43c59509 PP |
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() — | |
1059 | Appends a string to a string field. | |
1060 | @sa bt_field_string_set_value() — | |
1061 | Sets the value of a string field. | |
1062 | */ | |
d24d5663 PP |
1063 | extern bt_field_string_append_status bt_field_string_append_with_length( |
1064 | bt_field *field, const char *value, uint64_t length); | |
1065 | ||
43c59509 PP |
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() — | |
1079 | Sets the value of a string field. | |
1080 | */ | |
d24d5663 | 1081 | extern void bt_field_string_clear(bt_field *field); |
56e18c4c | 1082 | |
43c59509 | 1083 | /*! @} */ |
56e18c4c | 1084 | |
43c59509 PP |
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}. | |
56e18c4c | 1109 | |
43c59509 PP |
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() — | |
1135 | \c const version of this function. | |
1136 | */ | |
b19ff26f PP |
1137 | extern bt_field *bt_field_array_borrow_element_field_by_index( |
1138 | bt_field *field, uint64_t index); | |
56e18c4c | 1139 | |
43c59509 PP |
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 | */ | |
9c08c816 | 1155 | typedef enum bt_field_array_dynamic_set_length_status { |
43c59509 PP |
1156 | /*! |
1157 | @brief | |
1158 | Success. | |
1159 | */ | |
d24d5663 | 1160 | BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
1161 | |
1162 | /*! | |
1163 | @brief | |
1164 | Out of memory. | |
1165 | */ | |
1166 | BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, | |
9c08c816 | 1167 | } bt_field_array_dynamic_set_length_status; |
d24d5663 | 1168 | |
43c59509 PP |
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 | */ | |
9c08c816 | 1187 | extern bt_field_array_dynamic_set_length_status |
43c59509 PP |
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() — | |
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() — | |
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. | |
40f4ba76 | 1296 | |
43c59509 PP |
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 | */ | |
b38aea74 PP |
1305 | extern void bt_field_option_set_has_field(bt_field *field, bt_bool has_field); |
1306 | ||
43c59509 PP |
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() — | |
1332 | Sets whether or not an option field has a field. | |
1333 | @sa bt_field_option_borrow_field_const() — | |
1334 | \c const version of this function. | |
1335 | */ | |
b38aea74 PP |
1336 | extern bt_field *bt_field_option_borrow_field(bt_field *field); |
1337 | ||
43c59509 PP |
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 | */ | |
7b4311c1 | 1359 | typedef enum bt_field_variant_select_option_by_index_status { |
43c59509 PP |
1360 | /*! |
1361 | @brief | |
1362 | Success. | |
1363 | */ | |
1364 | BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK = __BT_FUNC_STATUS_OK, | |
7b4311c1 | 1365 | } bt_field_variant_select_option_by_index_status; |
d24d5663 | 1366 | |
43c59509 PP |
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 | */ | |
7b4311c1 PP |
1387 | extern bt_field_variant_select_option_by_index_status |
1388 | bt_field_variant_select_option_by_index( | |
743eec93 | 1389 | bt_field *field, uint64_t index); |
56e18c4c | 1390 | |
43c59509 PP |
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() — | |
1415 | Sets a variant field's selected option. | |
1416 | @sa bt_field_variant_get_selected_option_index() — | |
1417 | Returns the index of a variant field's selected option. | |
1418 | @sa bt_field_variant_borrow_selected_option_field_const() — | |
1419 | \c const version of this function. | |
1420 | */ | |
b19ff26f PP |
1421 | extern bt_field *bt_field_variant_borrow_selected_option_field( |
1422 | bt_field *field); | |
56e18c4c | 1423 | |
43c59509 PP |
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() — | |
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 | ||
56e18c4c PP |
1534 | #ifdef __cplusplus |
1535 | } | |
1536 | #endif | |
1537 | ||
924dc299 | 1538 | #endif /* BABELTRACE2_TRACE_IR_FIELD_H */ |