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