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