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