include/babeltrace/ctf-ir/fields.h

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