Replace assert() -> BT_ASSERT() and some preconditions with BT_ASSERT_PRE()
[babeltrace.git] / include / babeltrace / ctf-ir / fields.h
1 #ifndef BABELTRACE_CTF_IR_FIELDS_H
2 #define BABELTRACE_CTF_IR_FIELDS_H
3
4 /*
5 * Babeltrace - CTF IR: Event Fields
6 *
7 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 *
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
31 */
32
33 #include <stdint.h>
34 #include <stddef.h>
35
36 /* For bt_bool */
37 #include <babeltrace/types.h>
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 struct bt_field_type;
44
45 /**
46 @defgroup ctfirfields CTF IR fields
47 @ingroup ctfir
48 @brief CTF IR fields.
49
50 @code
51 #include <babeltrace/ctf-ir/fields.h>
52 @endcode
53
54 A CTF IR <strong><em>field</em></strong> is an object which holds a
55 concrete value, and which is described by a @ft.
56
57 In the CTF IR hierarchy, you can set the root fields of two objects:
58
59 - \ref ctfirpacket
60 - Trace packet header field: bt_packet_set_header().
61 - Stream packet context field: bt_packet_set_context().
62 - \ref ctfirevent
63 - Stream event header field: bt_event_set_header().
64 - Stream event context field: bt_event_set_stream_event_context().
65 - Event context field: bt_event_set_event_context().
66 - Event payload field: bt_event_set_payload_field().
67
68 There are two categories of fields:
69
70 - <strong>Basic fields</strong>:
71 - @intfield: contains an integral value.
72 - @floatfield: contains a floating point number value.
73 - @enumfield: contains an integer field which contains an integral
74 value.
75 - @stringfield: contains a string value.
76 - <strong>Compound fields</strong>:
77 - @structfield: contains an ordered list of named fields
78 (possibly with different @fts).
79 - @arrayfield: contains an ordered list of fields which share
80 the same field type.
81 - @seqfield: contains an ordered list of fields which share
82 the same field type.
83 - @varfield: contains a single, current field.
84
85 You can create a field object from a @ft object with
86 bt_field_create(). The enumeration and compound fields create their
87 contained fields with the following getters if such fields do not exist
88 yet:
89
90 - bt_field_enumeration_get_container()
91 - bt_field_structure_get_field_by_name()
92 - bt_field_array_get_field()
93 - bt_field_sequence_get_field()
94 - bt_field_variant_get_field()
95
96 If you already have a field object, you can also assign it to a specific
97 name within a @structfield with
98 bt_field_structure_set_field_by_name().
99
100 You can get a reference to the @ft which was used to create a field with
101 bt_field_get_type(). You can get the
102 \link #bt_field_type_id type ID\endlink of this field type directly with
103 bt_field_get_type_id().
104
105 You can get a deep copy of a field with bt_field_copy(). The field
106 copy, and its contained field copies if it's the case, have the same
107 field type as the originals.
108
109 As with any Babeltrace object, CTF IR field objects have
110 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
111 counts</a>. See \ref refs to learn more about the reference counting
112 management of Babeltrace objects.
113
114 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
115 \link ctfirevent event\endlink objects also freeze their root field
116 objects. You cannot modify a frozen field object: it is considered
117 immutable, except for \link refs reference counting\endlink.
118
119 @sa ctfirfieldtypes
120
121 @file
122 @brief CTF IR fields type and functions.
123 @sa ctfirfields
124
125 @addtogroup ctfirfields
126 @{
127 */
128
129 /**
130 @struct bt_field
131 @brief A CTF IR field.
132 @sa ctfirfields
133 */
134 struct bt_field;
135 struct bt_event_class;
136 struct bt_event;
137 struct bt_field_type;
138 struct bt_field_type_enumeration_mapping_iterator;
139
140 /**
141 @name Creation and parent field type access functions
142 @{
143 */
144
145 /**
146 @brief Creates an uninitialized @field described by the @ft
147 \p field_type.
148
149 On success, \p field_type becomes the parent of the created field
150 object.
151
152 On success, this function creates an \em uninitialized field: it has
153 no value. You need to set the value of the created field with one of the
154 its specific setters.
155
156 @param[in] field_type Field type which describes the field to create.
157 @returns Created field object, or \c NULL on error.
158
159 @prenotnull{field_type}
160 @postsuccessrefcountret1
161 @postsuccessfrozen{field_type}
162 */
163 extern struct bt_field *bt_field_create(
164 struct bt_field_type *field_type);
165
166 /**
167 @brief Returns the parent @ft of the @field \p field.
168
169 This function returns a reference to the field type which was used to
170 create the field object in the first place with bt_field_create().
171
172 @param[in] field Field of which to get the parent field type.
173 @returns Parent field type of \p event,
174 or \c NULL on error.
175
176 @prenotnull{field}
177 @postrefcountsame{field}
178 @postsuccessrefcountretinc
179 */
180 extern struct bt_field_type *bt_field_get_type(
181 struct bt_field *field);
182
183 /** @} */
184
185 /**
186 @name Type information
187 @{
188 */
189
190 /**
191 @brief Returns the type ID of the @ft of the @field \p field.
192
193 @param[in] field Field of which to get the type ID of its
194 parent field type..
195 @returns Type ID of the parent field type of \p field,
196 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
197
198 @prenotnull{field}
199 @postrefcountsame{field}
200
201 @sa #bt_field_type_id: CTF IR field type ID.
202 @sa bt_field_is_integer(): Returns whether or not a given field is a
203 @intfield.
204 @sa bt_field_is_floating_point(): Returns whether or not a given
205 field is a @floatfield.
206 @sa bt_field_is_enumeration(): Returns whether or not a given field
207 is a @enumfield.
208 @sa bt_field_is_string(): Returns whether or not a given field is a
209 @stringfield.
210 @sa bt_field_is_structure(): Returns whether or not a given field is
211 a @structfield.
212 @sa bt_field_is_array(): Returns whether or not a given field is a
213 @arrayfield.
214 @sa bt_field_is_sequence(): Returns whether or not a given field is
215 a @seqfield.
216 @sa bt_field_is_variant(): Returns whether or not a given field is a
217 @varfield.
218 */
219 extern enum bt_field_type_id bt_field_get_type_id(
220 struct bt_field *field);
221
222 /*
223 * bt_field_signed_integer_get_value: get a signed integer field's value
224 *
225 * Get a signed integer field's value.
226 *
227 * @param integer Signed integer field instance.
228 * @param value Pointer to a signed integer where the value will be stored.
229 *
230 * Returns 0 on success, a negative value on error.
231 */
232 extern int bt_field_signed_integer_get_value(struct bt_field *integer,
233 int64_t *value);
234
235 /**
236 @brief Returns whether or not the @field \p field is a @intfield.
237
238 @param[in] field Field to check (can be \c NULL).
239 @returns #BT_TRUE if \p field is an integer field, or
240 #BT_FALSE otherwise (including if \p field is
241 \c NULL).
242
243 @prenotnull{field}
244 @postrefcountsame{field}
245
246 @sa bt_field_get_type_id(): Returns the type ID of a given
247 field's type.
248 */
249 extern bt_bool bt_field_is_integer(struct bt_field *field);
250
251 /**
252 @brief Returns whether or not the @field \p field is a @floatfield.
253
254 @param[in] field Field to check (can be \c NULL).
255 @returns #BT_TRUE if \p field is a floating point number fiel
256 #BT_FALSE or 0 otherwise (including if \p field is
257 \c NULL).
258
259 @prenotnull{field}
260 @postrefcountsame{field}
261
262 @sa bt_field_get_type_id(): Returns the type ID of a given
263 field's type.
264 */
265 extern bt_bool bt_field_is_floating_point(struct bt_field *field);
266
267 /**
268 @brief Returns whether or not the @field \p field is a @enumfield.
269
270 @param[in] field Field to check (can be \c NULL).
271 @returns #BT_TRUE if \p field is an enumeration field, or
272 #BT_FALSE otherwise (including if \p field is
273 \c NULL).
274
275 @prenotnull{field}
276 @postrefcountsame{field}
277
278 @sa bt_field_get_type_id(): Returns the type ID of a given
279 field's type.
280 */
281 extern bt_bool bt_field_is_enumeration(struct bt_field *field);
282
283 /**
284 @brief Returns whether or not the @field \p field is a @stringfield.
285
286 @param[in] field Field to check (can be \c NULL).
287 @returns #BT_TRUE if \p field is a string field, or
288 #BT_FALSE otherwise (including if \p field is
289 \c NULL).
290
291 @prenotnull{field}
292 @postrefcountsame{field}
293
294 @sa bt_field_get_type_id(): Returns the type ID of a given
295 field's type.
296 */
297 extern bt_bool bt_field_is_string(struct bt_field *field);
298
299 /**
300 @brief Returns whether or not the @field \p field is a @structfield.
301
302 @param[in] field Field to check (can be \c NULL).
303 @returns #BT_TRUE if \p field is a structure field, or
304 #BT_FALSE otherwise (including if \p field is
305 \c NULL).
306
307 @prenotnull{field}
308 @postrefcountsame{field}
309
310 @sa bt_field_get_type_id(): Returns the type ID of a given
311 field's type.
312 */
313 extern bt_bool bt_field_is_structure(struct bt_field *field);
314
315 /**
316 @brief Returns whether or not the @field \p field is a @arrayfield.
317
318 @param[in] field Field to check (can be \c NULL).
319 @returns #BT_TRUE if \p field is an array field, or
320 #BT_FALSE otherwise (including if \p field is
321 \c NULL).
322
323 @prenotnull{field}
324 @postrefcountsame{field}
325
326 @sa bt_field_get_type_id(): Returns the type ID of a given
327 field's type.
328 */
329 extern bt_bool bt_field_is_array(struct bt_field *field);
330
331 /**
332 @brief Returns whether or not the @field \p field is a @seqfield.
333
334 @param[in] field Field to check (can be \c NULL).
335 @returns #BT_TRUE if \p field is a sequence field, or
336 #BT_FALSE otherwise (including if \p field is
337 \c NULL).
338
339 @prenotnull{field}
340 @postrefcountsame{field}
341
342 @sa bt_field_get_type_id(): Returns the type ID of a given
343 field's type.
344 */
345 extern bt_bool bt_field_is_sequence(struct bt_field *field);
346
347 /**
348 @brief Returns whether or not the @field \p field is a @varfield.
349
350 @param[in] field Field to check (can be \c NULL).
351 @returns #BT_TRUE if \p field is a variant field, or
352 #BT_FALSE otherwise (including if \p field is
353 \c NULL).
354
355 @prenotnull{field}
356 @postrefcountsame{field}
357
358 @sa bt_field_get_type_id(): Returns the type ID of a given
359 field's type.
360 */
361 extern bt_bool bt_field_is_variant(struct bt_field *field);
362
363 /** @} */
364
365 /**
366 @name Misc. functions
367 @{
368 */
369
370 /**
371 @brief Creates a \em deep copy of the @field \p field.
372
373 You can copy a frozen field: the resulting copy is <em>not frozen</em>.
374
375 @param[in] field Field to copy.
376 @returns Deep copy of \p field on success,
377 or \c NULL on error.
378
379 @prenotnull{field}
380 @postrefcountsame{field}
381 @postsuccessrefcountret1
382 @post <strong>On success</strong>, the returned field is not frozen.
383 */
384 extern struct bt_field *bt_field_copy(struct bt_field *field);
385
386 /** @} */
387
388 /** @} */
389
390 /**
391 @defgroup ctfirintfield CTF IR integer field
392 @ingroup ctfirfields
393 @brief CTF IR integer field.
394
395 @code
396 #include <babeltrace/ctf-ir/fields.h>
397 @endcode
398
399 A CTF IR <strong><em>integer field</em></strong> is a @field which
400 holds a signed or unsigned integral value, and which is described by
401 a @intft.
402
403 An integer field object is considered \em unsigned if
404 bt_field_type_integer_get_signed() on its parent field type returns
405 0. Otherwise it is considered \em signed. You \em must use
406 bt_field_unsigned_integer_get_value() and
407 bt_field_unsigned_integer_set_value() with an unsigned integer
408 field, and bt_field_signed_integer_get_value() and
409 bt_field_signed_integer_set_value() with a signed integer field.
410
411 After you create an integer field with bt_field_create(), you
412 \em must set an integral value with
413 bt_field_unsigned_integer_set_value() or
414 bt_field_signed_integer_set_value() before you can get the
415 field's value with bt_field_unsigned_integer_get_value() or
416 bt_field_signed_integer_get_value().
417
418 @sa ctfirintfieldtype
419 @sa ctfirfields
420
421 @addtogroup ctfirintfield
422 @{
423 */
424
425 /**
426 @brief Returns the signed integral value of the @intfield
427 \p integer_field.
428
429 @param[in] integer_field Integer field of which to get the
430 signed integral value.
431 @param[out] value Returned signed integral value of
432 \p integer_field.
433 @returns 0 on success, or a negative value on
434 error, including if \p integer_field
435 has no integral value yet.
436
437 @prenotnull{integer_field}
438 @prenotnull{value}
439 @preisintfield{integer_field}
440 @pre bt_field_type_integer_get_signed() returns 1 for the parent
441 @ft of \p integer_field.
442 @pre \p integer_field contains a signed integral value previously
443 set with bt_field_signed_integer_set_value().
444 @postrefcountsame{integer_field}
445
446 @sa bt_field_signed_integer_set_value(): Sets the signed integral
447 value of a given integer field.
448 */
449 extern int bt_field_signed_integer_get_value(
450 struct bt_field *integer_field, int64_t *value);
451
452 /**
453 @brief Sets the signed integral value of the @intfield
454 \p integer_field to \p value.
455
456 @param[in] integer_field Integer field of which to set
457 the signed integral value.
458 @param[in] value New signed integral value of
459 \p integer_field.
460 @returns 0 on success, or a negative value on error.
461
462 @prenotnull{integer_field}
463 @preisintfield{integer_field}
464 @prehot{integer_field}
465 @pre bt_field_type_integer_get_signed() returns 1 for the parent
466 @ft of \p integer_field.
467 @postrefcountsame{integer_field}
468
469 @sa bt_field_signed_integer_get_value(): Returns the signed integral
470 value of a given integer field.
471 */
472 extern int bt_field_signed_integer_set_value(
473 struct bt_field *integer_field, int64_t value);
474
475 /**
476 @brief Returns the unsigned integral value of the @intfield
477 \p integer_field.
478
479 @param[in] integer_field Integer field of which to get the
480 unsigned integral value.
481 @param[out] value Returned unsigned integral value of
482 \p integer_field.
483 @returns 0 on success, or a negative value on
484 error, including if \p integer_field
485 has no integral value yet.
486
487 @prenotnull{integer_field}
488 @prenotnull{value}
489 @preisintfield{integer_field}
490 @pre bt_field_type_integer_get_signed() returns 0 for the parent
491 @ft of \p integer_field.
492 @pre \p integer_field contains an unsigned integral value previously
493 set with bt_field_unsigned_integer_set_value().
494 @postrefcountsame{integer_field}
495
496 @sa bt_field_unsigned_integer_set_value(): Sets the unsigned
497 integral value of a given integer field.
498 */
499 extern int bt_field_unsigned_integer_get_value(
500 struct bt_field *integer_field, uint64_t *value);
501
502 /**
503 @brief Sets the unsigned integral value of the @intfield
504 \p integer_field to \p value.
505
506 @param[in] integer_field Integer field of which to set
507 the unsigned integral value.
508 @param[in] value New unsigned integral value of
509 \p integer_field.
510 @returns 0 on success, or a negative value on error.
511
512 @prenotnull{integer_field}
513 @preisintfield{integer_field}
514 @prehot{integer_field}
515 @pre bt_field_type_integer_get_signed() returns 0 for the parent
516 @ft of \p integer_field.
517 @postrefcountsame{integer_field}
518
519 @sa bt_field_unsigned_integer_get_value(): Returns the unsigned
520 integral value of a given integer field.
521 */
522 extern int bt_field_unsigned_integer_set_value(
523 struct bt_field *integer_field, uint64_t value);
524
525 /** @} */
526
527 /**
528 @defgroup ctfirfloatfield CTF IR floating point number field
529 @ingroup ctfirfields
530 @brief CTF IR floating point number field.
531
532 @code
533 #include <babeltrace/ctf-ir/fields.h>
534 @endcode
535
536 A CTF IR <strong><em>floating point number field</em></strong> is a
537 @field which holds a floating point number value, and which is
538 described by a @floatft.
539
540 After you create a floating point number field with bt_field_create(), you
541 \em must set a floating point number value with
542 bt_field_floating_point_set_value() before you can get the
543 field's value with bt_field_floating_point_get_value().
544
545 @sa ctfirfloatfieldtype
546 @sa ctfirfields
547
548 @addtogroup ctfirfloatfield
549 @{
550 */
551
552 /**
553 @brief Returns the floating point number value of the @floatfield
554 \p float_field.
555
556 @param[in] float_field Floating point number field of which to get the
557 floating point number value.
558 @param[out] value Returned floating point number value of
559 \p float_field.
560 @returns 0 on success, or a negative value on error,
561 including if \p float_field has no floating
562 point number value yet.
563
564 @prenotnull{float_field}
565 @prenotnull{value}
566 @preisfloatfield{float_field}
567 @pre \p float_field contains a floating point number value previously
568 set with bt_field_floating_point_set_value().
569 @postrefcountsame{float_field}
570
571 @sa bt_field_floating_point_set_value(): Sets the floating point
572 number value of a given floating point number field.
573 */
574 extern int bt_field_floating_point_get_value(
575 struct bt_field *float_field, double *value);
576
577 /**
578 @brief Sets the floating point number value of the @floatfield
579 \p float_field to \p value.
580
581 @param[in] float_field Floating point number field of which to set
582 the floating point number value.
583 @param[in] value New floating point number value of
584 \p float_field.
585 @returns 0 on success, or a negative value on error.
586
587 @prenotnull{float_field}
588 @preisfloatfield{float_field}
589 @prehot{float_field}
590 @postrefcountsame{float_field}
591
592 @sa bt_field_floating_point_get_value(): Returns the floating point
593 number value of a given floating point number field.
594 */
595 extern int bt_field_floating_point_set_value(
596 struct bt_field *float_field,
597 double value);
598
599 /** @} */
600
601 /**
602 @defgroup ctfirenumfield CTF IR enumeration field
603 @ingroup ctfirfields
604 @brief CTF IR enumeration field.
605
606 @code
607 #include <babeltrace/ctf-ir/fields.h>
608 @endcode
609
610 A CTF IR <strong><em>enumeration field</em></strong> is a @field which
611 holds a @intfield, and which is described by a @enumft.
612
613 To set the current integral value of an enumeration field, you need to
614 get its wrapped @intfield with bt_field_enumeration_get_container(),
615 and then set the integral value with either
616 bt_field_signed_integer_set_value() or
617 bt_field_unsigned_integer_set_value().
618
619 Once you set the integral value of an enumeration field by following the
620 previous paragraph, you can get the mappings containing this value in
621 their range with bt_field_enumeration_get_mappings(). This function
622 returns a @enumftiter.
623
624 @sa ctfirenumfieldtype
625 @sa ctfirfields
626
627 @addtogroup ctfirenumfield
628 @{
629 */
630
631 /**
632 @brief Returns the @intfield, potentially creating it, wrapped by the
633 @enumfield \p enum_field.
634
635 This function creates the @intfield to return if it does not currently
636 exist.
637
638 @param[in] enum_field Enumeration field of which to get the wrapped
639 integer field.
640 @returns Integer field wrapped by \p enum_field, or
641 \c NULL on error.
642
643 @prenotnull{enum_field}
644 @preisenumfield{enum_field}
645 @postrefcountsame{enum_field}
646 @postsuccessrefcountretinc
647 */
648 extern struct bt_field *bt_field_enumeration_get_container(
649 struct bt_field *enum_field);
650
651 /**
652 @brief Returns a @enumftiter on all the mappings of the field type of
653 \p enum_field which contain the current integral value of the
654 @enumfield \p enum_field in their range.
655
656 This function is the equivalent of using
657 bt_field_type_enumeration_find_mappings_by_unsigned_value() or
658 bt_field_type_enumeration_find_mappings_by_signed_value() with the
659 current integral value of \p enum_field.
660
661 @param[in] enum_field Enumeration field of which to get the mappings
662 containing the current integral value of \p
663 enum_field in their range.
664 @returns @enumftiter on the set of mappings of the field
665 type of \p enum_field which contain the current
666 integral value of \p enum_field in their range,
667 or \c NULL if no mappings were found or on
668 error.
669
670 @prenotnull{enum_field}
671 @preisenumfield{enum_field}
672 @pre The wrapped integer field of \p enum_field contains an integral
673 value.
674 @postrefcountsame{enum_field}
675 @postsuccessrefcountret1
676 @post <strong>On success</strong>, the returned @enumftiter can iterate
677 on at least one mapping.
678 */
679 extern struct bt_field_type_enumeration_mapping_iterator *
680 bt_field_enumeration_get_mappings(struct bt_field *enum_field);
681
682 /** @} */
683
684 /**
685 @defgroup ctfirstringfield CTF IR string field
686 @ingroup ctfirfields
687 @brief CTF IR string field.
688
689 @code
690 #include <babeltrace/ctf-ir/fields.h>
691 @endcode
692
693 A CTF IR <strong><em>string field</em></strong> is a @field which holds
694 a string value, and which is described by a @stringft.
695
696 Use bt_field_string_set_value() to set the current string value
697 of a string field object. You can also use bt_field_string_append()
698 and bt_field_string_append_len() to append a string to the current
699 value of a string field.
700
701 After you create a string field with bt_field_create(), you
702 \em must set a string value with
703 bt_field_string_set_value(), bt_field_string_append(), or
704 bt_field_string_append_len() before you can get the
705 field's value with bt_field_string_get_value().
706
707 @sa ctfirstringfieldtype
708 @sa ctfirfields
709
710 @addtogroup ctfirstringfield
711 @{
712 */
713
714 /**
715 @brief Returns the string value of the @stringfield \p string_field.
716
717 On success, \p string_field remains the sole owner of the returned
718 value.
719
720 @param[in] string_field String field field of which to get the
721 string value.
722 @returns String value, or \c NULL on error.
723
724 @prenotnull{string_field}
725 @prenotnull{value}
726 @preisstringfield{string_field}
727 @pre \p string_field contains a string value previously
728 set with bt_field_string_set_value(),
729 bt_field_string_append(), or
730 bt_field_string_append_len().
731 @postrefcountsame{string_field}
732
733 @sa bt_field_string_set_value(): Sets the string value of a given
734 string field.
735 */
736 extern const char *bt_field_string_get_value(
737 struct bt_field *string_field);
738
739 /**
740 @brief Sets the string value of the @stringfield \p string_field to
741 \p value.
742
743 @param[in] string_field String field of which to set
744 the string value.
745 @param[in] value New string value of \p string_field (copied
746 on success).
747 @returns 0 on success, or a negative value on error.
748
749 @prenotnull{string_field}
750 @prenotnull{value}
751 @preisstringfield{string_field}
752 @prehot{string_field}
753 @postrefcountsame{string_field}
754
755 @sa bt_field_string_get_value(): Returns the string value of a
756 given string field.
757 */
758 extern int bt_field_string_set_value(struct bt_field *string_field,
759 const char *value);
760
761 /**
762 @brief Appends the string \p value to the current string value of
763 the @stringfield \p string_field.
764
765 This function is the equivalent of:
766
767 @code
768 bt_field_string_append_len(string_field, value, strlen(value));
769 @endcode
770
771 @param[in] string_field String field of which to append \p value to
772 its current value.
773 @param[in] value String to append to the current string value
774 of \p string_field (copied on success).
775 @returns 0 on success, or a negative value on error.
776
777 @prenotnull{string_field}
778 @prenotnull{value}
779 @preisstringfield{string_field}
780 @prehot{string_field}
781 @postrefcountsame{string_field}
782
783 @sa bt_field_string_set_value(): Sets the string value of a given
784 string field.
785 */
786 extern int bt_field_string_append(struct bt_field *string_field,
787 const char *value);
788
789 /**
790 @brief Appends the first \p length characters of \p value to the
791 current string value of the @stringfield \p string_field.
792
793 If \p string_field has no current string value, this function first
794 sets an empty string as the string value of \p string_field and then
795 appends the first \p length characters of \p value.
796
797 @param[in] string_field String field of which to append the first
798 \p length characters of \p value to
799 its current value.
800 @param[in] value String containing the characters to append to
801 the current string value of \p string_field
802 (copied on success).
803 @param[in] length Number of characters of \p value to append to
804 the current string value of \p string_field.
805 @returns 0 on success, or a negative value on error.
806
807 @prenotnull{string_field}
808 @prenotnull{value}
809 @preisstringfield{string_field}
810 @prehot{string_field}
811 @postrefcountsame{string_field}
812
813 @sa bt_field_string_set_value(): Sets the string value of a given
814 string field.
815 */
816 extern int bt_field_string_append_len(
817 struct bt_field *string_field, const char *value,
818 unsigned int length);
819
820 /** @} */
821
822 /**
823 @defgroup ctfirstructfield CTF IR structure field
824 @ingroup ctfirfields
825 @brief CTF IR structure field.
826
827 @code
828 #include <babeltrace/ctf-ir/fields.h>
829 @endcode
830
831 A CTF IR <strong><em>structure field</em></strong> is a @field which
832 contains an ordered list of zero or more named @fields which can be
833 different @fts, and which is described by a @structft.
834
835 To set the value of a specific field of a structure field, you need to
836 first get the field with bt_field_structure_get_field_by_name() or
837 bt_field_structure_get_field_by_index(). If you already have a
838 field object, you can assign it to a specific name within a structure
839 field with bt_field_structure_set_field_by_name().
840
841 @sa ctfirstructfieldtype
842 @sa ctfirfields
843
844 @addtogroup ctfirstructfield
845 @{
846 */
847
848 /**
849 @brief Returns the @field named \p name, potentially creating it,
850 in the @structfield \p struct_field.
851
852 This function creates the @field to return if it does not currently
853 exist.
854
855 @param[in] struct_field Structure field of which to get the field
856 named \p name.
857 @param[in] name Name of the field to get from \p struct_field.
858 @returns Field named \p name in \p struct_field, or
859 \c NULL on error.
860
861 @prenotnull{struct_field}
862 @prenotnull{name}
863 @preisstructfield{struct_field}
864 @postrefcountsame{struct_field}
865 @postsuccessrefcountretinc
866
867 @sa bt_field_structure_get_field_by_index(): Returns the field of a
868 given structure field by index.
869 @sa bt_field_structure_set_field_by_name(): Sets the field of a
870 given structure field by name.
871 */
872 extern struct bt_field *bt_field_structure_get_field_by_name(
873 struct bt_field *struct_field, const char *name);
874
875 /**
876 @brief Returns the @field at index \p index in the @structfield
877 \p struct_field.
878
879 @param[in] struct_field Structure field of which to get the field
880 at index \p index.
881 @param[in] index Index of the field to get in \p struct_field.
882 @returns Field at index \p index in \p struct_field, or
883 \c NULL on error.
884
885 @prenotnull{struct_field}
886 @preisstructfield{struct_field}
887 @pre \p index is lesser than the number of fields contained in the
888 parent field type of \p struct_field (see
889 bt_field_type_structure_get_field_count()).
890 @postrefcountsame{struct_field}
891 @postsuccessrefcountretinc
892
893 @sa bt_field_structure_get_field_by_name(): Returns the field of a
894 given structure field by name.
895 @sa bt_field_structure_set_field_by_name(): Sets the field of a
896 given structure field by name.
897 */
898 extern struct bt_field *bt_field_structure_get_field_by_index(
899 struct bt_field *struct_field, uint64_t index);
900
901 /**
902 @brief Sets the field of the @structfield \p struct_field named \p name
903 to the @field \p field.
904
905 If \p struct_field already contains a field named \p name, then it may
906 either be replaced by \p field and its reference count is decremented,
907 or \p field's value is assigned to it.
908
909 The field type of \p field, as returned by bt_field_get_type(),
910 \em must be equivalent to the field type returned by
911 bt_field_type_structure_get_field_type_by_name() with the field
912 type of \p struct_field and the same name, \p name.
913
914 bt_trace_get_packet_header_type() for the parent trace class of
915 \p packet.
916
917 @param[in] struct_field Structure field of which to set the field
918 named \p name.
919 @param[in] name Name of the field to set in \p struct_field.
920 @param[in] field Field named \p name to set in \p struct_field.
921 @returns 0 on success, or -1 on error.
922
923 @prenotnull{struct_field}
924 @prenotnull{name}
925 @prenotnull{field}
926 @prehot{struct_field}
927 @preisstructfield{struct_field}
928 @pre \p field has a field type equivalent to the field type returned by
929 bt_field_type_structure_get_field_type_by_name() for the
930 field type of \p struct_field with the name \p name.
931 @postrefcountsame{struct_field}
932 @post <strong>On success, the field in \p struct_field named \p name</strong>
933 may either be replaced by \p field or have the same value as \p field.
934 @postsuccessrefcountinc{field}
935
936 @sa bt_field_structure_get_field_by_index(): Returns the field of a
937 given structure field by index.
938 @sa bt_field_structure_get_field_by_name(): Returns the field of a
939 given structure field by name.
940 */
941 extern int bt_field_structure_set_field_by_name(
942 struct bt_field *struct_field,
943 const char *name, struct bt_field *field);
944
945 /** @} */
946
947 /**
948 @defgroup ctfirarrayfield CTF IR array field
949 @ingroup ctfirfields
950 @brief CTF IR array field.
951
952 @code
953 #include <babeltrace/ctf-ir/fields.h>
954 @endcode
955
956 A CTF IR <strong><em>array field</em></strong> is a @field which
957 contains an ordered list of zero or more @fields sharing the same @ft,
958 and which is described by a @arrayft.
959
960 To set the value of a specific field of an array field, you need to
961 first get the field with bt_field_array_get_field().
962
963 @sa ctfirarrayfieldtype
964 @sa ctfirfields
965
966 @addtogroup ctfirarrayfield
967 @{
968 */
969
970 /**
971 @brief Returns the @field at index \p index, potentially creating it,
972 in the @arrayfield \p array_field.
973
974 This function creates the @field to return if it does not currently
975 exist.
976
977 @param[in] array_field Array field of which to get the field
978 at index \p index.
979 @param[in] index Index of the field to get in \p array_field.
980 @returns Field at index \p index in \p array_field, or
981 \c NULL on error.
982
983 @prenotnull{array_field}
984 @preisarrayfield{array_field}
985 @pre \p index is lesser than bt_field_type_array_get_length() called
986 on the field type of \p array_field.
987 @postrefcountsame{array_field}
988 @postsuccessrefcountretinc
989 */
990 extern struct bt_field *bt_field_array_get_field(
991 struct bt_field *array_field, uint64_t index);
992
993 /** @} */
994
995 /**
996 @defgroup ctfirseqfield CTF IR sequence field
997 @ingroup ctfirfields
998 @brief CTF IR sequence field.
999
1000 @code
1001 #include <babeltrace/ctf-ir/fields.h>
1002 @endcode
1003
1004 A CTF IR <strong><em>sequence field</em></strong> is a @field which
1005 contains an ordered list of zero or more @fields sharing the same @ft,
1006 and which is described by a @seqft.
1007
1008 Before you can get a specific field of a sequence field with
1009 bt_field_sequence_get_field(), you need to set its current length
1010 @intfield with bt_field_sequence_set_length(). The integral value of
1011 the length field of a sequence field indicates the number of fields
1012 it contains.
1013
1014 @sa ctfirseqfieldtype
1015 @sa ctfirfields
1016
1017 @addtogroup ctfirseqfield
1018 @{
1019 */
1020
1021 /**
1022 @brief Returns the @field at index \p index, potentially creating it,
1023 in the @seqfield \p sequence_field.
1024
1025 This function creates the @field to return if it does not currently
1026 exist.
1027
1028 @param[in] sequence_field Sequence field of which to get the field
1029 at index \p index.
1030 @param[in] index Index of the field to get in
1031 \p sequence_field.
1032 @returns Field at index \p index in
1033 \p sequence_field, or \c NULL on error.
1034
1035 @prenotnull{sequence_field}
1036 @preisseqfield{sequence_field}
1037 @pre \p sequence_field has a length field previously set with
1038 bt_field_sequence_set_length().
1039 @pre \p index is lesser than the current integral value of the current
1040 length field of \p sequence_field (see
1041 bt_field_sequence_get_length()).
1042 @postrefcountsame{sequence_field}
1043 @postsuccessrefcountretinc
1044 */
1045 extern struct bt_field *bt_field_sequence_get_field(
1046 struct bt_field *sequence_field, uint64_t index);
1047
1048 /**
1049 @brief Returns the length @intfield of the @seqfield \p sequence_field.
1050
1051 The current integral value of the returned length field indicates the
1052 number of fields contained in \p sequence_field.
1053
1054 @param[in] sequence_field Sequence field of which to get the
1055 length field.
1056 @returns Length field of \p sequence_field, or
1057 \c NULL on error.
1058
1059 @prenotnull{sequence_field}
1060 @preisseqfield{sequence_field}
1061 @pre \p sequence_field has a length field previously set with
1062 bt_field_sequence_set_length().
1063 @postrefcountsame{sequence_field}
1064 @postsuccessrefcountretinc
1065 @post <strong>On success</strong>, the returned field is a @intfield.
1066
1067 @sa bt_field_sequence_set_length(): Sets the length field of a given
1068 sequence field.
1069 */
1070 extern struct bt_field *bt_field_sequence_get_length(
1071 struct bt_field *sequence_field);
1072
1073 /**
1074 @brief Sets the length @intfield of the @seqfield \p sequence_field
1075 to \p length_field.
1076
1077 The current integral value of \p length_field indicates the number of
1078 fields contained in \p sequence_field.
1079
1080 @param[in] sequence_field Sequence field of which to set the
1081 length field.
1082 @param[in] length_field Length field of \p sequence_field.
1083 @returns 0 on success, or a negative value on error.
1084
1085 @prenotnull{sequence_field}
1086 @prenotnull{length_field}
1087 @preisseqfield{sequence_field}
1088 @preisintfield{length_field}
1089 @prehot{sequence_field}
1090 @postrefcountsame{sequence_field}
1091 @postsuccessrefcountinc{length_field}
1092
1093 @sa bt_field_sequence_get_length(): Returns the length field of a
1094 given sequence field.
1095 */
1096 extern int bt_field_sequence_set_length(struct bt_field *sequence_field,
1097 struct bt_field *length_field);
1098
1099 /** @} */
1100
1101 /**
1102 @defgroup ctfirvarfield CTF IR variant field
1103 @ingroup ctfirfields
1104 @brief CTF IR variant field.
1105
1106 @code
1107 #include <babeltrace/ctf-ir/fields.h>
1108 @endcode
1109
1110 A CTF IR <strong><em>variant field</em></strong> is a @field which
1111 contains a current @field amongst one or more choices, and which is
1112 described by a @varft.
1113
1114 Use bt_field_variant_get_field() to get the @field selected by
1115 a specific tag @enumfield. Once you call this function, you can call
1116 bt_field_variant_get_current_field() afterwards to get this last
1117 field again.
1118
1119 @sa ctfirvarfieldtype
1120 @sa ctfirfields
1121
1122 @addtogroup ctfirvarfield
1123 @{
1124 */
1125
1126 /**
1127 @brief Returns the @field, potentially creating it, selected by the
1128 tag @intfield \p tag_field in the @varfield \p variant_field.
1129
1130 This function creates the @field to return if it does not currently
1131 exist.
1132
1133 Once you call this function, you can call
1134 bt_field_variant_get_current_field() to get the same field again,
1135 and you can call bt_field_variant_get_tag() to get \p tag_field.
1136
1137 @param[in] variant_field Variant field of which to get the field
1138 selected by \p tag_field.
1139 @param[in] tag_field Tag field.
1140 @returns Field selected by \p tag_field in
1141 \p variant_field, or \c NULL on error.
1142
1143 @prenotnull{variant_field}
1144 @prenotnull{tag_field}
1145 @preisvarfield{variant_field}
1146 @preisenumfield{tag_field}
1147 @postrefcountsame{variant_field}
1148 @postsuccessrefcountinc{tag_field}
1149 @postsuccessrefcountretinc
1150 */
1151 extern struct bt_field *bt_field_variant_get_field(
1152 struct bt_field *variant_field,
1153 struct bt_field *tag_field);
1154
1155 /**
1156 @brief Returns the currently selected @field of the @varfield
1157 \p variant_field.
1158
1159 @param[in] variant_field Variant field of which to get the
1160 currently selected field.
1161 @returns Currently selected field of
1162 \p variant_field, or \c NULL if there's
1163 no selected field or on error.
1164
1165 @prenotnull{variant_field}
1166 @preisvarfield{variant_field}
1167 @pre \p variant_field contains has a current selected field previously
1168 set with bt_field_variant_get_field().
1169 @postrefcountsame{variant_field}
1170 @postsuccessrefcountretinc
1171 */
1172 extern struct bt_field *bt_field_variant_get_current_field(
1173 struct bt_field *variant_field);
1174
1175 /**
1176 @brief Returns the tag @enumfield of the @varfield \p variant_field.
1177
1178 @param[in] variant_field Variant field of which to get the
1179 tag field.
1180 @returns Tag field of \p variant_field, or
1181 \c NULL on error.
1182
1183 @prenotnull{variant_field}
1184 @preisvarfield{variant_field}
1185 @pre \p variant_field contains has a current selected field previously
1186 set with bt_field_variant_get_field().
1187 @postrefcountsame{variant_field}
1188 @postsuccessrefcountretinc
1189 @post <strong>On success</strong>, the returned field is a @enumfield.
1190 */
1191 extern struct bt_field *bt_field_variant_get_tag(
1192 struct bt_field *variant_field);
1193
1194 /** @} */
1195
1196 /* Pre-2.0 CTF writer compatibility */
1197 #define bt_ctf_field bt_field
1198 #define bt_ctf_field_create bt_field_create
1199 #define bt_ctf_field_structure_get_field bt_field_structure_get_field_by_name
1200 #define bt_ctf_field_variant_get_field bt_field_variant_get_field
1201 #define bt_ctf_field_array_get_field bt_field_array_get_field
1202 #define bt_ctf_field_sequence_set_length bt_field_sequence_set_length
1203 #define bt_ctf_field_sequence_get_field bt_field_sequence_get_field
1204 #define bt_ctf_field_enumeration_get_container bt_field_enumeration_get_container
1205 #define bt_ctf_field_signed_integer_set_value bt_field_signed_integer_set_value
1206 #define bt_ctf_field_unsigned_integer_set_value bt_field_unsigned_integer_set_value
1207 #define bt_ctf_field_floating_point_set_value bt_field_floating_point_set_value
1208 #define bt_ctf_field_string_set_value bt_field_string_set_value
1209
1210 #ifdef __cplusplus
1211 }
1212 #endif
1213
1214 #endif /* BABELTRACE_CTF_IR_FIELDS_H */
This page took 0.055253 seconds and 4 git commands to generate.