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