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