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