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