lib: metadata: transform fast path precond. checks to BT_ASSERT_PRE()
[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>
9d408fca
PP
35
36/* For bt_bool */
c14d64fa 37#include <babeltrace/types.h>
adc315b8
JG
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
50842bdc 43struct bt_field_type;
9d408fca 44
91f379cb
PP
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
54A CTF IR <strong><em>field</em></strong> is an object which holds a
55concrete value, and which is described by a @ft.
56
57In the CTF IR hierarchy, you can set the root fields of two objects:
58
59- \ref ctfirpacket
50842bdc
PP
60 - Trace packet header field: bt_packet_set_header().
61 - Stream packet context field: bt_packet_set_context().
91f379cb 62- \ref ctfirevent
50842bdc
PP
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().
91f379cb
PP
67
68There 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
85You can create a field object from a @ft object with
50842bdc 86bt_field_create(). The enumeration and compound fields create their
91f379cb
PP
87contained fields with the following getters if such fields do not exist
88yet:
89
50842bdc
PP
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()
91f379cb 95
7fcd5734 96If you already have a field object, you can also assign it to a specific
2225de6b 97name within a @structfield with
50842bdc 98bt_field_structure_set_field_by_name().
7fcd5734 99
91f379cb 100You can get a reference to the @ft which was used to create a field with
50842bdc
PP
101bt_field_get_type(). You can get the
102\link #bt_field_type_id type ID\endlink of this field type directly with
103bt_field_get_type_id().
91f379cb 104
50842bdc 105You can get a deep copy of a field with bt_field_copy(). The field
91f379cb
PP
106copy, and its contained field copies if it's the case, have the same
107field type as the originals.
108
109As with any Babeltrace object, CTF IR field objects have
110<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
111counts</a>. See \ref refs to learn more about the reference counting
112management of Babeltrace objects.
113
114The functions which freeze CTF IR \link ctfirpacket packet\endlink and
115\link ctfirevent event\endlink objects also freeze their root field
116objects. You cannot modify a frozen field object: it is considered
117immutable, 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/**
50842bdc 130@struct bt_field
91f379cb
PP
131@brief A CTF IR field.
132@sa ctfirfields
133*/
50842bdc
PP
134struct bt_field;
135struct bt_event_class;
136struct bt_event;
137struct bt_field_type;
138struct bt_field_type_enumeration_mapping_iterator;
adc315b8 139
91f379cb
PP
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
149On success, \p field_type becomes the parent of the created field
150object.
151
152On success, this function creates an \em uninitialized field: it has
153no value. You need to set the value of the created field with one of the
154its 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*/
50842bdc
PP
163extern struct bt_field *bt_field_create(
164 struct bt_field_type *field_type);
adc315b8 165
91f379cb
PP
166/**
167@brief Returns the parent @ft of the @field \p field.
adc315b8 168
91f379cb 169This function returns a reference to the field type which was used to
50842bdc 170create the field object in the first place with bt_field_create().
cd95e351 171
91f379cb
PP
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.
adc315b8 175
91f379cb
PP
176@prenotnull{field}
177@postrefcountsame{field}
178@postsuccessrefcountretinc
179*/
50842bdc
PP
180extern struct bt_field_type *bt_field_get_type(
181 struct bt_field *field);
cd95e351 182
91f379cb 183/** @} */
adc315b8 184
91f379cb
PP
185/**
186@name Type information
187@{
188*/
adc315b8 189
91f379cb
PP
190/**
191@brief Returns the type ID of the @ft of the @field \p field.
adc315b8 192
91f379cb
PP
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,
50842bdc 196 or #BT_FIELD_TYPE_ID_UNKNOWN on error.
3f4a108d 197
91f379cb
PP
198@prenotnull{field}
199@postrefcountsame{field}
f78d67fb 200
50842bdc
PP
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
91f379cb 203 @intfield.
50842bdc 204@sa bt_field_is_floating_point(): Returns whether or not a given
91f379cb 205 field is a @floatfield.
50842bdc 206@sa bt_field_is_enumeration(): Returns whether or not a given field
91f379cb 207 is a @enumfield.
50842bdc 208@sa bt_field_is_string(): Returns whether or not a given field is a
91f379cb 209 @stringfield.
50842bdc 210@sa bt_field_is_structure(): Returns whether or not a given field is
91f379cb 211 a @structfield.
50842bdc 212@sa bt_field_is_array(): Returns whether or not a given field is a
91f379cb 213 @arrayfield.
50842bdc 214@sa bt_field_is_sequence(): Returns whether or not a given field is
91f379cb 215 a @seqfield.
50842bdc 216@sa bt_field_is_variant(): Returns whether or not a given field is a
91f379cb
PP
217 @varfield.
218*/
50842bdc
PP
219extern enum bt_field_type_id bt_field_get_type_id(
220 struct bt_field *field);
6ead1648 221
96e8f959 222/*
50842bdc 223 * bt_field_signed_integer_get_value: get a signed integer field's value
96e8f959
MD
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 */
50842bdc 232extern int bt_field_signed_integer_get_value(struct bt_field *integer,
96e8f959
MD
233 int64_t *value);
234
91f379cb
PP
235/**
236@brief Returns whether or not the @field \p field is a @intfield.
cd95e351 237
91f379cb 238@param[in] field Field to check (can be \c NULL).
c14d64fa
PP
239@returns #BT_TRUE if \p field is an integer field, or
240 #BT_FALSE otherwise (including if \p field is
91f379cb 241 \c NULL).
cd95e351 242
91f379cb
PP
243@prenotnull{field}
244@postrefcountsame{field}
adc315b8 245
50842bdc 246@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
247 field's type.
248*/
50842bdc 249extern bt_bool bt_field_is_integer(struct bt_field *field);
cd95e351 250
91f379cb
PP
251/**
252@brief Returns whether or not the @field \p field is a @floatfield.
adc315b8 253
91f379cb 254@param[in] field Field to check (can be \c NULL).
c14d64fa
PP
255@returns #BT_TRUE if \p field is a floating point number fiel
256 #BT_FALSE or 0 otherwise (including if \p field is
91f379cb
PP
257 \c NULL).
258
259@prenotnull{field}
260@postrefcountsame{field}
261
50842bdc 262@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
263 field's type.
264*/
50842bdc 265extern bt_bool bt_field_is_floating_point(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
271@returns #BT_TRUE if \p field is an enumeration field, or
272 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
273 \c NULL).
274
275@prenotnull{field}
276@postrefcountsame{field}
277
50842bdc 278@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
279 field's type.
280*/
50842bdc 281extern bt_bool bt_field_is_enumeration(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
287@returns #BT_TRUE if \p field is a string field, or
288 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
289 \c NULL).
290
291@prenotnull{field}
292@postrefcountsame{field}
293
50842bdc 294@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
295 field's type.
296*/
50842bdc 297extern bt_bool bt_field_is_string(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
303@returns #BT_TRUE if \p field is a structure field, or
304 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
305 \c NULL).
306
307@prenotnull{field}
308@postrefcountsame{field}
309
50842bdc 310@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
311 field's type.
312*/
50842bdc 313extern bt_bool bt_field_is_structure(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
319@returns #BT_TRUE if \p field is an array field, or
320 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
321 \c NULL).
322
323@prenotnull{field}
324@postrefcountsame{field}
325
50842bdc 326@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
327 field's type.
328*/
50842bdc 329extern bt_bool bt_field_is_array(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
335@returns #BT_TRUE if \p field is a sequence field, or
336 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
337 \c NULL).
338
339@prenotnull{field}
340@postrefcountsame{field}
341
50842bdc 342@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
343 field's type.
344*/
50842bdc 345extern bt_bool bt_field_is_sequence(struct bt_field *field);
91f379cb
PP
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).
c14d64fa
PP
351@returns #BT_TRUE if \p field is a variant field, or
352 #BT_FALSE otherwise (including if \p field is
91f379cb
PP
353 \c NULL).
354
355@prenotnull{field}
356@postrefcountsame{field}
357
50842bdc 358@sa bt_field_get_type_id(): Returns the type ID of a given
91f379cb
PP
359 field's type.
360*/
50842bdc 361extern bt_bool bt_field_is_variant(struct bt_field *field);
91f379cb
PP
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
373You 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*/
50842bdc 384extern struct bt_field *bt_field_copy(struct bt_field *field);
91f379cb
PP
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
399A CTF IR <strong><em>integer field</em></strong> is a @field which
400holds a signed or unsigned integral value, and which is described by
401a @intft.
402
403An integer field object is considered \em unsigned if
50842bdc 404bt_field_type_integer_get_signed() on its parent field type returns
91f379cb 4050. Otherwise it is considered \em signed. You \em must use
50842bdc
PP
406bt_field_unsigned_integer_get_value() and
407bt_field_unsigned_integer_set_value() with an unsigned integer
408field, and bt_field_signed_integer_get_value() and
409bt_field_signed_integer_set_value() with a signed integer field.
91f379cb 410
50842bdc 411After you create an integer field with bt_field_create(), you
91f379cb 412\em must set an integral value with
50842bdc
PP
413bt_field_unsigned_integer_set_value() or
414bt_field_signed_integer_set_value() before you can get the
415field's value with bt_field_unsigned_integer_get_value() or
416bt_field_signed_integer_get_value().
91f379cb
PP
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}
50842bdc 440@pre bt_field_type_integer_get_signed() returns 1 for the parent
91f379cb
PP
441 @ft of \p integer_field.
442@pre \p integer_field contains a signed integral value previously
50842bdc 443 set with bt_field_signed_integer_set_value().
91f379cb
PP
444@postrefcountsame{integer_field}
445
50842bdc 446@sa bt_field_signed_integer_set_value(): Sets the signed integral
91f379cb
PP
447 value of a given integer field.
448*/
50842bdc
PP
449extern int bt_field_signed_integer_get_value(
450 struct bt_field *integer_field, int64_t *value);
91f379cb
PP
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}
50842bdc 465@pre bt_field_type_integer_get_signed() returns 1 for the parent
91f379cb
PP
466 @ft of \p integer_field.
467@postrefcountsame{integer_field}
468
50842bdc 469@sa bt_field_signed_integer_get_value(): Returns the signed integral
91f379cb
PP
470 value of a given integer field.
471*/
50842bdc
PP
472extern int bt_field_signed_integer_set_value(
473 struct bt_field *integer_field, int64_t value);
91f379cb
PP
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}
50842bdc 490@pre bt_field_type_integer_get_signed() returns 0 for the parent
91f379cb
PP
491 @ft of \p integer_field.
492@pre \p integer_field contains an unsigned integral value previously
50842bdc 493 set with bt_field_unsigned_integer_set_value().
91f379cb
PP
494@postrefcountsame{integer_field}
495
50842bdc 496@sa bt_field_unsigned_integer_set_value(): Sets the unsigned
91f379cb
PP
497 integral value of a given integer field.
498*/
50842bdc
PP
499extern int bt_field_unsigned_integer_get_value(
500 struct bt_field *integer_field, uint64_t *value);
91f379cb
PP
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}
50842bdc 515@pre bt_field_type_integer_get_signed() returns 0 for the parent
91f379cb
PP
516 @ft of \p integer_field.
517@postrefcountsame{integer_field}
518
50842bdc 519@sa bt_field_unsigned_integer_get_value(): Returns the unsigned
91f379cb
PP
520 integral value of a given integer field.
521*/
50842bdc
PP
522extern int bt_field_unsigned_integer_set_value(
523 struct bt_field *integer_field, uint64_t value);
91f379cb
PP
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
536A CTF IR <strong><em>floating point number field</em></strong> is a
537@field which holds a floating point number value, and which is
538described by a @floatft.
539
50842bdc 540After you create a floating point number field with bt_field_create(), you
91f379cb 541\em must set a floating point number value with
50842bdc
PP
542bt_field_floating_point_set_value() before you can get the
543field's value with bt_field_floating_point_get_value().
91f379cb
PP
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
50842bdc 568 set with bt_field_floating_point_set_value().
91f379cb
PP
569@postrefcountsame{float_field}
570
50842bdc 571@sa bt_field_floating_point_set_value(): Sets the floating point
91f379cb
PP
572 number value of a given floating point number field.
573*/
50842bdc
PP
574extern int bt_field_floating_point_get_value(
575 struct bt_field *float_field, double *value);
cd95e351 576
91f379cb
PP
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
50842bdc 592@sa bt_field_floating_point_get_value(): Returns the floating point
91f379cb
PP
593 number value of a given floating point number field.
594*/
50842bdc
PP
595extern int bt_field_floating_point_set_value(
596 struct bt_field *float_field,
adc315b8
JG
597 double value);
598
91f379cb
PP
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
610A CTF IR <strong><em>enumeration field</em></strong> is a @field which
611holds a @intfield, and which is described by a @enumft.
612
613To set the current integral value of an enumeration field, you need to
50842bdc 614get its wrapped @intfield with bt_field_enumeration_get_container(),
91f379cb 615and then set the integral value with either
50842bdc
PP
616bt_field_signed_integer_set_value() or
617bt_field_unsigned_integer_set_value().
91f379cb
PP
618
619Once you set the integral value of an enumeration field by following the
5c3f3b7e 620previous paragraph, you can get the mappings containing this value in
50842bdc 621their range with bt_field_enumeration_get_mappings(). This function
5c3f3b7e 622returns a @enumftiter.
91f379cb
PP
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
635This function creates the @intfield to return if it does not currently
636exist.
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*/
50842bdc
PP
648extern struct bt_field *bt_field_enumeration_get_container(
649 struct bt_field *enum_field);
91f379cb
PP
650
651/**
5c3f3b7e
PP
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
656This function is the equivalent of using
50842bdc
PP
657bt_field_type_enumeration_find_mappings_by_unsigned_value() or
658bt_field_type_enumeration_find_mappings_by_signed_value() with the
5c3f3b7e
PP
659current 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.
91f379cb
PP
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}
8dc7eb94 675@postsuccessrefcountret1
5c3f3b7e
PP
676@post <strong>On success</strong>, the returned @enumftiter can iterate
677 on at least one mapping.
91f379cb 678*/
50842bdc
PP
679extern struct bt_field_type_enumeration_mapping_iterator *
680bt_field_enumeration_get_mappings(struct bt_field *enum_field);
91f379cb
PP
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
693A CTF IR <strong><em>string field</em></strong> is a @field which holds
694a string value, and which is described by a @stringft.
695
50842bdc
PP
696Use bt_field_string_set_value() to set the current string value
697of a string field object. You can also use bt_field_string_append()
698and bt_field_string_append_len() to append a string to the current
91f379cb
PP
699value of a string field.
700
50842bdc 701After you create a string field with bt_field_create(), you
91f379cb 702\em must set a string value with
50842bdc
PP
703bt_field_string_set_value(), bt_field_string_append(), or
704bt_field_string_append_len() before you can get the
705field's value with bt_field_string_get_value().
91f379cb
PP
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
717On success, \p string_field remains the sole owner of the returned
718value.
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
50842bdc
PP
728 set with bt_field_string_set_value(),
729 bt_field_string_append(), or
730 bt_field_string_append_len().
91f379cb
PP
731@postrefcountsame{string_field}
732
50842bdc 733@sa bt_field_string_set_value(): Sets the string value of a given
91f379cb
PP
734 string field.
735*/
50842bdc
PP
736extern const char *bt_field_string_get_value(
737 struct bt_field *string_field);
cd95e351 738
91f379cb
PP
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
50842bdc 755@sa bt_field_string_get_value(): Returns the string value of a
91f379cb
PP
756 given string field.
757*/
50842bdc 758extern int bt_field_string_set_value(struct bt_field *string_field,
adc315b8
JG
759 const char *value);
760
91f379cb
PP
761/**
762@brief Appends the string \p value to the current string value of
763 the @stringfield \p string_field.
764
765This function is the equivalent of:
766
767@code
50842bdc 768bt_field_string_append_len(string_field, value, strlen(value));
91f379cb
PP
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
50842bdc 783@sa bt_field_string_set_value(): Sets the string value of a given
91f379cb
PP
784 string field.
785*/
50842bdc 786extern int bt_field_string_append(struct bt_field *string_field,
c6f9c5a3
PP
787 const char *value);
788
91f379cb
PP
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
793If \p string_field has no current string value, this function first
794sets an empty string as the string value of \p string_field and then
795appends 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
50842bdc 813@sa bt_field_string_set_value(): Sets the string value of a given
91f379cb
PP
814 string field.
815*/
50842bdc
PP
816extern int bt_field_string_append_len(
817 struct bt_field *string_field, const char *value,
f98c6554
PP
818 unsigned int length);
819
91f379cb 820/** @} */
cd95e351 821
91f379cb
PP
822/**
823@defgroup ctfirstructfield CTF IR structure field
824@ingroup ctfirfields
825@brief CTF IR structure field.
4ebcc695 826
91f379cb
PP
827@code
828#include <babeltrace/ctf-ir/fields.h>
829@endcode
8f3553be 830
91f379cb
PP
831A CTF IR <strong><em>structure field</em></strong> is a @field which
832contains an ordered list of zero or more named @fields which can be
833different @fts, and which is described by a @structft.
8f3553be 834
91f379cb 835To set the value of a specific field of a structure field, you need to
50842bdc
PP
836first get the field with bt_field_structure_get_field_by_name() or
837bt_field_structure_get_field_by_index(). If you already have a
7fcd5734 838field object, you can assign it to a specific name within a structure
50842bdc 839field with bt_field_structure_set_field_by_name().
8f3553be 840
91f379cb
PP
841@sa ctfirstructfieldtype
842@sa ctfirfields
8f3553be 843
91f379cb
PP
844@addtogroup ctfirstructfield
845@{
846*/
8f3553be 847
91f379cb
PP
848/**
849@brief Returns the @field named \p name, potentially creating it,
850 in the @structfield \p struct_field.
8f3553be 851
91f379cb
PP
852This function creates the @field to return if it does not currently
853exist.
8f3553be 854
91f379cb
PP
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.
8f3553be 860
91f379cb
PP
861@prenotnull{struct_field}
862@prenotnull{name}
863@preisstructfield{struct_field}
864@postrefcountsame{struct_field}
865@postsuccessrefcountretinc
866
50842bdc 867@sa bt_field_structure_get_field_by_index(): Returns the field of a
91f379cb 868 given structure field by index.
50842bdc 869@sa bt_field_structure_set_field_by_name(): Sets the field of a
2225de6b 870 given structure field by name.
91f379cb 871*/
50842bdc
PP
872extern struct bt_field *bt_field_structure_get_field_by_name(
873 struct bt_field *struct_field, const char *name);
9ac68eb1 874
91f379cb
PP
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
50842bdc 889 bt_field_type_structure_get_field_count()).
91f379cb
PP
890@postrefcountsame{struct_field}
891@postsuccessrefcountretinc
892
50842bdc 893@sa bt_field_structure_get_field_by_name(): Returns the field of a
2225de6b 894 given structure field by name.
50842bdc 895@sa bt_field_structure_set_field_by_name(): Sets the field of a
91f379cb
PP
896 given structure field by name.
897*/
50842bdc
PP
898extern struct bt_field *bt_field_structure_get_field_by_index(
899 struct bt_field *struct_field, uint64_t index);
91f379cb 900
7fcd5734
JD
901/**
902@brief Sets the field of the @structfield \p struct_field named \p name
903 to the @field \p field.
904
0efd97ce
JG
905If \p struct_field already contains a field named \p name, then it may
906either be replaced by \p field and its reference count is decremented,
907or \p field's value is assigned to it.
7fcd5734 908
50842bdc 909The field type of \p field, as returned by bt_field_get_type(),
7fcd5734 910\em must be equivalent to the field type returned by
50842bdc 911bt_field_type_structure_get_field_type_by_name() with the field
7fcd5734
JD
912type of \p struct_field and the same name, \p name.
913
50842bdc 914bt_trace_get_packet_header_type() for the parent trace class of
7fcd5734
JD
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
50842bdc 929 bt_field_type_structure_get_field_type_by_name() for the
7fcd5734
JD
930 field type of \p struct_field with the name \p name.
931@postrefcountsame{struct_field}
0efd97ce
JG
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.
7fcd5734
JD
934@postsuccessrefcountinc{field}
935
50842bdc 936@sa bt_field_structure_get_field_by_index(): Returns the field of a
7fcd5734 937 given structure field by index.
50842bdc 938@sa bt_field_structure_get_field_by_name(): Returns the field of a
7fcd5734
JD
939 given structure field by name.
940*/
50842bdc
PP
941extern int bt_field_structure_set_field_by_name(
942 struct bt_field *struct_field,
943 const char *name, struct bt_field *field);
7fcd5734 944
91f379cb
PP
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
956A CTF IR <strong><em>array field</em></strong> is a @field which
957contains an ordered list of zero or more @fields sharing the same @ft,
958and which is described by a @arrayft.
959
960To set the value of a specific field of an array field, you need to
50842bdc 961first get the field with bt_field_array_get_field().
91f379cb
PP
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
974This function creates the @field to return if it does not currently
975exist.
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}
50842bdc 985@pre \p index is lesser than bt_field_type_array_get_length() called
91f379cb
PP
986 on the field type of \p array_field.
987@postrefcountsame{array_field}
988@postsuccessrefcountretinc
989*/
50842bdc
PP
990extern struct bt_field *bt_field_array_get_field(
991 struct bt_field *array_field, uint64_t index);
91f379cb
PP
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
1004A CTF IR <strong><em>sequence field</em></strong> is a @field which
1005contains an ordered list of zero or more @fields sharing the same @ft,
1006and which is described by a @seqft.
1007
1008Before you can get a specific field of a sequence field with
50842bdc
PP
1009bt_field_sequence_get_field(), you need to set its current length
1010@intfield with bt_field_sequence_set_length(). The integral value of
91f379cb
PP
1011the length field of a sequence field indicates the number of fields
1012it 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
1025This function creates the @field to return if it does not currently
1026exist.
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
50842bdc 1038 bt_field_sequence_set_length().
91f379cb
PP
1039@pre \p index is lesser than the current integral value of the current
1040 length field of \p sequence_field (see
50842bdc 1041 bt_field_sequence_get_length()).
91f379cb
PP
1042@postrefcountsame{sequence_field}
1043@postsuccessrefcountretinc
1044*/
50842bdc
PP
1045extern struct bt_field *bt_field_sequence_get_field(
1046 struct bt_field *sequence_field, uint64_t index);
91f379cb
PP
1047
1048/**
1049@brief Returns the length @intfield of the @seqfield \p sequence_field.
1050
1051The current integral value of the returned length field indicates the
1052number 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
50842bdc 1062 bt_field_sequence_set_length().
91f379cb
PP
1063@postrefcountsame{sequence_field}
1064@postsuccessrefcountretinc
1065@post <strong>On success</strong>, the returned field is a @intfield.
1066
50842bdc 1067@sa bt_field_sequence_set_length(): Sets the length field of a given
91f379cb
PP
1068 sequence field.
1069*/
50842bdc
PP
1070extern struct bt_field *bt_field_sequence_get_length(
1071 struct bt_field *sequence_field);
91f379cb
PP
1072
1073/**
1074@brief Sets the length @intfield of the @seqfield \p sequence_field
1075 to \p length_field.
1076
1077The current integral value of \p length_field indicates the number of
1078fields 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
50842bdc 1093@sa bt_field_sequence_get_length(): Returns the length field of a
91f379cb
PP
1094 given sequence field.
1095*/
50842bdc
PP
1096extern int bt_field_sequence_set_length(struct bt_field *sequence_field,
1097 struct bt_field *length_field);
91f379cb
PP
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
1110A CTF IR <strong><em>variant field</em></strong> is a @field which
1111contains a current @field amongst one or more choices, and which is
1112described by a @varft.
1113
50842bdc 1114Use bt_field_variant_get_field() to get the @field selected by
91f379cb 1115a specific tag @enumfield. Once you call this function, you can call
50842bdc 1116bt_field_variant_get_current_field() afterwards to get this last
91f379cb
PP
1117field 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
1130This function creates the @field to return if it does not currently
1131exist.
1132
1133Once you call this function, you can call
50842bdc
PP
1134bt_field_variant_get_current_field() to get the same field again,
1135and you can call bt_field_variant_get_tag() to get \p tag_field.
91f379cb
PP
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*/
50842bdc
PP
1151extern struct bt_field *bt_field_variant_get_field(
1152 struct bt_field *variant_field,
1153 struct bt_field *tag_field);
91f379cb
PP
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
50842bdc 1168 set with bt_field_variant_get_field().
91f379cb
PP
1169@postrefcountsame{variant_field}
1170@postsuccessrefcountretinc
1171*/
50842bdc
PP
1172extern struct bt_field *bt_field_variant_get_current_field(
1173 struct bt_field *variant_field);
91f379cb
PP
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
50842bdc 1186 set with bt_field_variant_get_field().
91f379cb
PP
1187@postrefcountsame{variant_field}
1188@postsuccessrefcountretinc
1189@post <strong>On success</strong>, the returned field is a @enumfield.
1190*/
50842bdc
PP
1191extern struct bt_field *bt_field_variant_get_tag(
1192 struct bt_field *variant_field);
91f379cb
PP
1193
1194/** @} */
a39fe52e 1195
50842bdc
PP
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
adc315b8
JG
1210#ifdef __cplusplus
1211}
1212#endif
1213
2e33ac5a 1214#endif /* BABELTRACE_CTF_IR_FIELDS_H */
This page took 0.108438 seconds and 4 git commands to generate.