include/babeltrace/ctf-ir/fields.h

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