include/babeltrace/ctf-ir/fields.h

   1 #ifndef BABELTRACE_CTF_IR_FIELDS_H
   2 #define BABELTRACE_CTF_IR_FIELDS_H
   3
   4 /*
   5  * Babeltrace - CTF IR: Event Fields
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <stdint.h>
  34 #include <stddef.h>
  35
  36 /* For bt_get() */
  37 #include <babeltrace/ref.h>
  38
  39 /* For bt_bool */
  40 #include <babeltrace/types.h>
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 struct bt_field_type;
  47
  48 /**
  49 @defgroup ctfirfields CTF IR fields
  50 @ingroup ctfir
  51 @brief CTF IR fields.
  52
  53 @code
  54 #include <babeltrace/ctf-ir/fields.h>
  55 @endcode
  56
  57 A CTF IR <strong><em>field</em></strong> is an object which holds a
  58 concrete value, and which is described by a @ft.
  59
  60 In the CTF IR hierarchy, you can set the root fields of two objects:
  61
  62 - \ref ctfirpacket
  63   - Trace packet header field: bt_packet_set_header().
  64   - Stream packet context field: bt_packet_set_context().
  65 - \ref ctfirevent
  66   - Stream event header field: bt_event_set_header().
  67   - Stream event context field: bt_event_set_stream_event_context().
  68   - Event context field: bt_event_set_event_context().
  69   - Event payload field: bt_event_set_payload_field().
  70
  71 There are two categories of fields:
  72
  73 - <strong>Basic fields</strong>:
  74   - @intfield: contains an integral value.
  75   - @floatfield: contains a floating point number value.
  76   - @enumfield: contains an integer field which contains an integral
  77     value.
  78   - @stringfield: contains a string value.
  79 - <strong>Compound fields</strong>:
  80   - @structfield: contains an ordered list of named fields
  81     (possibly with different @fts).
  82   - @arrayfield: contains an ordered list of fields which share
  83     the same field type.
  84   - @seqfield: contains an ordered list of fields which share
  85     the same field type.
  86   - @varfield: contains a single, current field.
  87
  88 You can create a field object from a @ft object with
  89 bt_field_create(). The enumeration and compound fields create their
  90 contained fields with the following getters if such fields do not exist
  91 yet:
  92
  93 - bt_field_enumeration_get_container()
  94 - bt_field_structure_get_field_by_name()
  95 - bt_field_array_get_field()
  96 - bt_field_sequence_get_field()
  97 - bt_field_variant_get_field()
  98
  99 If you already have a field object, you can also assign it to a specific
 100 name within a @structfield with
 101 bt_field_structure_set_field_by_name().
 102
 103 You can get a reference to the @ft which was used to create a field with
 104 bt_field_get_type(). You can get the
 105 \link #bt_field_type_id type ID\endlink of this field type directly with
 106 bt_field_get_type_id().
 107
 108 You can get a deep copy of a field with bt_field_copy(). The field
 109 copy, and its contained field copies if it's the case, have the same
 110 field type as the originals.
 111
 112 As with any Babeltrace object, CTF IR field objects have
 113 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 114 counts</a>. See \ref refs to learn more about the reference counting
 115 management of Babeltrace objects.
 116
 117 The functions which freeze CTF IR \link ctfirpacket packet\endlink and
 118 \link ctfirevent event\endlink objects also freeze their root field
 119 objects. You cannot modify a frozen field object: it is considered
 120 immutable, except for \link refs reference counting\endlink.
 121
 122 @sa ctfirfieldtypes
 123
 124 @file
 125 @brief CTF IR fields type and functions.
 126 @sa ctfirfields
 127
 128 @addtogroup ctfirfields
 129 @{
 130 */
 131
 132 /**
 133 @struct bt_field
 134 @brief A CTF IR field.
 135 @sa ctfirfields
 136 */
 137 struct bt_field;
 138 struct bt_event_class;
 139 struct bt_event;
 140 struct bt_field_type;
 141 struct bt_field_type_enumeration_mapping_iterator;
 142
 143 /**
 144 @name Creation and parent field type access functions
 145 @{
 146 */
 147
 148 extern struct bt_field_type *bt_field_borrow_type(struct bt_field *field);
 149
 150 /**
 151 @brief  Returns the parent @ft of the @field \p field.
 152
 153 This function returns a reference to the field type which was used to
 154 create the field object in the first place with bt_field_create().
 155
 156 @param[in] field        Field of which to get the parent field type.
 157 @returns                Parent field type of \p event,
 158                         or \c NULL on error.
 159
 160 @prenotnull{field}
 161 @postrefcountsame{field}
 162 @postsuccessrefcountretinc
 163 */
 164 static inline
 165 struct bt_field_type *bt_field_get_type(struct bt_field *field)
 166 {
 167         return bt_get(bt_field_borrow_type(field));
 168 }
 169
 170 /** @} */
 171
 172 /**
 173 @name Type information
 174 @{
 175 */
 176
 177 /**
 178 @brief  Returns the type ID of the @ft of the @field \p field.
 179
 180 @param[in] field        Field of which to get the type ID of its
 181                         parent field type..
 182 @returns                Type ID of the parent field type of \p field,
 183                         or #BT_FIELD_TYPE_ID_UNKNOWN on error.
 184
 185 @prenotnull{field}
 186 @postrefcountsame{field}
 187
 188 @sa #bt_field_type_id: CTF IR field type ID.
 189 @sa bt_field_is_integer(): Returns whether or not a given field is a
 190         @intfield.
 191 @sa bt_field_is_floating_point(): Returns whether or not a given
 192         field is a @floatfield.
 193 @sa bt_field_is_enumeration(): Returns whether or not a given field
 194         is a @enumfield.
 195 @sa bt_field_is_string(): Returns whether or not a given field is a
 196         @stringfield.
 197 @sa bt_field_is_structure(): Returns whether or not a given field is
 198         a @structfield.
 199 @sa bt_field_is_array(): Returns whether or not a given field is a
 200         @arrayfield.
 201 @sa bt_field_is_sequence(): Returns whether or not a given field is
 202         a @seqfield.
 203 @sa bt_field_is_variant(): Returns whether or not a given field is a
 204         @varfield.
 205 */
 206 extern enum bt_field_type_id bt_field_get_type_id(struct bt_field *field);
 207
 208 /**
 209 @brief  Returns whether or not the @field \p field is a @intfield.
 210
 211 @param[in] field        Field to check (can be \c NULL).
 212 @returns                #BT_TRUE if \p field is an integer field, or
 213                         #BT_FALSE otherwise (including if \p field is
 214                         \c NULL).
 215
 216 @prenotnull{field}
 217 @postrefcountsame{field}
 218
 219 @sa bt_field_get_type_id(): Returns the type ID of a given
 220         field's type.
 221 */
 222 extern bt_bool bt_field_is_integer(struct bt_field *field);
 223
 224 /**
 225 @brief  Returns whether or not the @field \p field is a @floatfield.
 226
 227 @param[in] field        Field to check (can be \c NULL).
 228 @returns                #BT_TRUE if \p field is a floating point number fiel
 229                         #BT_FALSE or 0 otherwise (including if \p field is
 230                         \c NULL).
 231
 232 @prenotnull{field}
 233 @postrefcountsame{field}
 234
 235 @sa bt_field_get_type_id(): Returns the type ID of a given
 236         field's type.
 237 */
 238 extern bt_bool bt_field_is_floating_point(struct bt_field *field);
 239
 240 /**
 241 @brief  Returns whether or not the @field \p field is a @enumfield.
 242
 243 @param[in] field        Field to check (can be \c NULL).
 244 @returns                #BT_TRUE if \p field is an enumeration field, or
 245                         #BT_FALSE otherwise (including if \p field is
 246                         \c NULL).
 247
 248 @prenotnull{field}
 249 @postrefcountsame{field}
 250
 251 @sa bt_field_get_type_id(): Returns the type ID of a given
 252         field's type.
 253 */
 254 extern bt_bool bt_field_is_enumeration(struct bt_field *field);
 255
 256 /**
 257 @brief  Returns whether or not the @field \p field is a @stringfield.
 258
 259 @param[in] field        Field to check (can be \c NULL).
 260 @returns                #BT_TRUE if \p field is a string field, or
 261                         #BT_FALSE otherwise (including if \p field is
 262                         \c NULL).
 263
 264 @prenotnull{field}
 265 @postrefcountsame{field}
 266
 267 @sa bt_field_get_type_id(): Returns the type ID of a given
 268         field's type.
 269 */
 270 extern bt_bool bt_field_is_string(struct bt_field *field);
 271
 272 /**
 273 @brief  Returns whether or not the @field \p field is a @structfield.
 274
 275 @param[in] field        Field to check (can be \c NULL).
 276 @returns                #BT_TRUE if \p field is a structure field, or
 277                         #BT_FALSE otherwise (including if \p field is
 278                         \c NULL).
 279
 280 @prenotnull{field}
 281 @postrefcountsame{field}
 282
 283 @sa bt_field_get_type_id(): Returns the type ID of a given
 284         field's type.
 285 */
 286 extern bt_bool bt_field_is_structure(struct bt_field *field);
 287
 288 /**
 289 @brief  Returns whether or not the @field \p field is a @arrayfield.
 290
 291 @param[in] field        Field to check (can be \c NULL).
 292 @returns                #BT_TRUE if \p field is an array field, or
 293                         #BT_FALSE otherwise (including if \p field is
 294                         \c NULL).
 295
 296 @prenotnull{field}
 297 @postrefcountsame{field}
 298
 299 @sa bt_field_get_type_id(): Returns the type ID of a given
 300         field's type.
 301 */
 302 extern bt_bool bt_field_is_array(struct bt_field *field);
 303
 304 /**
 305 @brief  Returns whether or not the @field \p field is a @seqfield.
 306
 307 @param[in] field        Field to check (can be \c NULL).
 308 @returns                #BT_TRUE if \p field is a sequence field, or
 309                         #BT_FALSE otherwise (including if \p field is
 310                         \c NULL).
 311
 312 @prenotnull{field}
 313 @postrefcountsame{field}
 314
 315 @sa bt_field_get_type_id(): Returns the type ID of a given
 316         field's type.
 317 */
 318 extern bt_bool bt_field_is_sequence(struct bt_field *field);
 319
 320 /**
 321 @brief  Returns whether or not the @field \p field is a @varfield.
 322
 323 @param[in] field        Field to check (can be \c NULL).
 324 @returns                #BT_TRUE if \p field is a variant field, or
 325                         #BT_FALSE otherwise (including if \p field is
 326                         \c NULL).
 327
 328 @prenotnull{field}
 329 @postrefcountsame{field}
 330
 331 @sa bt_field_get_type_id(): Returns the type ID of a given
 332         field's type.
 333 */
 334 extern bt_bool bt_field_is_variant(struct bt_field *field);
 335
 336 /** @} */
 337
 338 /**
 339 @name Misc. functions
 340 @{
 341 */
 342
 343 /** @} */
 344
 345 /** @} */
 346
 347 /**
 348 @defgroup ctfirintfield CTF IR integer field
 349 @ingroup ctfirfields
 350 @brief CTF IR integer field.
 351
 352 @code
 353 #include <babeltrace/ctf-ir/fields.h>
 354 @endcode
 355
 356 A CTF IR <strong><em>integer field</em></strong> is a @field which
 357 holds a signed or unsigned integral value, and which is described by
 358 a @intft.
 359
 360 An integer field object is considered \em unsigned if
 361 bt_field_type_integer_get_signed() on its parent field type returns
 362 0. Otherwise it is considered \em signed. You \em must use
 363 bt_field_integer_unsigned_get_value() and
 364 bt_field_integer_unsigned_set_value() with an unsigned integer
 365 field, and bt_field_integer_signed_get_value() and
 366 bt_field_integer_signed_set_value() with a signed integer field.
 367
 368 After you create an integer field with bt_field_create(), you
 369 \em must set an integral value with
 370 bt_field_integer_unsigned_set_value() or
 371 bt_field_integer_signed_set_value() before you can get the
 372 field's value with bt_field_integer_unsigned_get_value() or
 373 bt_field_integer_signed_get_value().
 374
 375 @sa ctfirintfieldtype
 376 @sa ctfirfields
 377
 378 @addtogroup ctfirintfield
 379 @{
 380 */
 381
 382 /**
 383 @brief  Returns the signed integral value of the @intfield
 384         \p integer_field.
 385
 386 @param[in] integer_field        Integer field of which to get the
 387                                 signed integral value.
 388 @param[out] value               Returned signed integral value of
 389                                 \p integer_field.
 390 @returns                        0 on success, or a negative value on
 391                                 error, including if \p integer_field
 392                                 has no integral value yet.
 393
 394 @prenotnull{integer_field}
 395 @prenotnull{value}
 396 @preisintfield{integer_field}
 397 @pre bt_field_type_integer_get_signed() returns 1 for the parent
 398         @ft of \p integer_field.
 399 @pre \p integer_field contains a signed integral value previously
 400         set with bt_field_integer_signed_set_value().
 401 @postrefcountsame{integer_field}
 402
 403 @sa bt_field_integer_signed_set_value(): Sets the signed integral
 404         value of a given integer field.
 405 */
 406 extern int bt_field_integer_signed_get_value(
 407                 struct bt_field *integer_field, int64_t *value);
 408
 409 /**
 410 @brief  Sets the signed integral value of the @intfield
 411         \p integer_field to \p value.
 412
 413 @param[in] integer_field        Integer field of which to set
 414                                 the signed integral value.
 415 @param[in] value                New signed integral value of
 416                                 \p integer_field.
 417 @returns                        0 on success, or a negative value on error.
 418
 419 @prenotnull{integer_field}
 420 @preisintfield{integer_field}
 421 @prehot{integer_field}
 422 @pre bt_field_type_integer_get_signed() returns 1 for the parent
 423         @ft of \p integer_field.
 424 @postrefcountsame{integer_field}
 425
 426 @sa bt_field_integer_signed_get_value(): Returns the signed integral
 427         value of a given integer field.
 428 */
 429 extern int bt_field_integer_signed_set_value(
 430                 struct bt_field *integer_field, int64_t value);
 431
 432 /**
 433 @brief  Returns the unsigned integral value of the @intfield
 434         \p integer_field.
 435
 436 @param[in] integer_field        Integer field of which to get the
 437                                 unsigned integral value.
 438 @param[out] value               Returned unsigned integral value of
 439                                 \p integer_field.
 440 @returns                        0 on success, or a negative value on
 441                                 error, including if \p integer_field
 442                                 has no integral value yet.
 443
 444 @prenotnull{integer_field}
 445 @prenotnull{value}
 446 @preisintfield{integer_field}
 447 @pre bt_field_type_integer_get_signed() returns 0 for the parent
 448         @ft of \p integer_field.
 449 @pre \p integer_field contains an unsigned integral value previously
 450         set with bt_field_integer_unsigned_set_value().
 451 @postrefcountsame{integer_field}
 452
 453 @sa bt_field_integer_unsigned_set_value(): Sets the unsigned
 454         integral value of a given integer field.
 455 */
 456 extern int bt_field_integer_unsigned_get_value(
 457                 struct bt_field *integer_field, uint64_t *value);
 458
 459 /**
 460 @brief  Sets the unsigned integral value of the @intfield
 461         \p integer_field to \p value.
 462
 463 @param[in] integer_field        Integer field of which to set
 464                                 the unsigned integral value.
 465 @param[in] value                New unsigned integral value of
 466                                 \p integer_field.
 467 @returns                        0 on success, or a negative value on error.
 468
 469 @prenotnull{integer_field}
 470 @preisintfield{integer_field}
 471 @prehot{integer_field}
 472 @pre bt_field_type_integer_get_signed() returns 0 for the parent
 473         @ft of \p integer_field.
 474 @postrefcountsame{integer_field}
 475
 476 @sa bt_field_integer_unsigned_get_value(): Returns the unsigned
 477         integral value of a given integer field.
 478 */
 479 extern int bt_field_integer_unsigned_set_value(
 480                 struct bt_field *integer_field, uint64_t value);
 481
 482 /** @} */
 483
 484 /**
 485 @defgroup ctfirfloatfield CTF IR floating point number field
 486 @ingroup ctfirfields
 487 @brief CTF IR floating point number field.
 488
 489 @code
 490 #include <babeltrace/ctf-ir/fields.h>
 491 @endcode
 492
 493 A CTF IR <strong><em>floating point number field</em></strong> is a
 494 @field which holds a floating point number value, and which is
 495 described by a @floatft.
 496
 497 After you create a floating point number field with bt_field_create(), you
 498 \em must set a floating point number value with
 499 bt_field_floating_point_set_value() before you can get the
 500 field's value with bt_field_floating_point_get_value().
 501
 502 @sa ctfirfloatfieldtype
 503 @sa ctfirfields
 504
 505 @addtogroup ctfirfloatfield
 506 @{
 507 */
 508
 509 /**
 510 @brief  Returns the floating point number value of the @floatfield
 511         \p float_field.
 512
 513 @param[in] float_field  Floating point number field of which to get the
 514                         floating point number value.
 515 @param[out] value       Returned floating point number value of
 516                         \p float_field.
 517 @returns                0 on success, or a negative value on error,
 518                         including if \p float_field has no floating
 519                         point number value yet.
 520
 521 @prenotnull{float_field}
 522 @prenotnull{value}
 523 @preisfloatfield{float_field}
 524 @pre \p float_field contains a floating point number value previously
 525         set with bt_field_floating_point_set_value().
 526 @postrefcountsame{float_field}
 527
 528 @sa bt_field_floating_point_set_value(): Sets the floating point
 529         number value of a given floating point number field.
 530 */
 531 extern int bt_field_floating_point_get_value(
 532                 struct bt_field *float_field, double *value);
 533
 534 /**
 535 @brief  Sets the floating point number value of the @floatfield
 536         \p float_field to \p value.
 537
 538 @param[in] float_field  Floating point number field of which to set
 539                         the floating point number value.
 540 @param[in] value        New floating point number value of
 541                         \p float_field.
 542 @returns                0 on success, or a negative value on error.
 543
 544 @prenotnull{float_field}
 545 @preisfloatfield{float_field}
 546 @prehot{float_field}
 547 @postrefcountsame{float_field}
 548
 549 @sa bt_field_floating_point_get_value(): Returns the floating point
 550         number value of a given floating point number field.
 551 */
 552 extern int bt_field_floating_point_set_value(
 553                 struct bt_field *float_field, double value);
 554
 555 /** @} */
 556
 557 /**
 558 @brief  Returns a @enumftiter on all the mappings of the field type of
 559         \p enum_field which contain the current integral value of the
 560         @enumfield \p enum_field in their range.
 561
 562 This function is the equivalent of using
 563 bt_field_type_enumeration_find_mappings_by_unsigned_value() or
 564 bt_field_type_enumeration_find_mappings_by_signed_value() with the
 565 current integral value of \p enum_field.
 566
 567 @param[in] enum_field   Enumeration field of which to get the mappings
 568                         containing the current integral value of \p
 569                         enum_field in their range.
 570 @returns                @enumftiter on the set of mappings of the field
 571                         type of \p enum_field which contain the current
 572                         integral value of \p enum_field in their range,
 573                         or \c NULL if no mappings were found or on
 574                         error.
 575
 576 @prenotnull{enum_field}
 577 @preisenumfield{enum_field}
 578 @pre The wrapped integer field of \p enum_field contains an integral
 579         value.
 580 @postrefcountsame{enum_field}
 581 @postsuccessrefcountret1
 582 @post <strong>On success</strong>, the returned @enumftiter can iterate
 583         on at least one mapping.
 584 */
 585 extern struct bt_field_type_enumeration_mapping_iterator *
 586 bt_field_enumeration_get_mappings(struct bt_field *enum_field);
 587
 588 /** @} */
 589
 590 /**
 591 @defgroup ctfirstringfield CTF IR string field
 592 @ingroup ctfirfields
 593 @brief CTF IR string field.
 594
 595 @code
 596 #include <babeltrace/ctf-ir/fields.h>
 597 @endcode
 598
 599 A CTF IR <strong><em>string field</em></strong> is a @field which holds
 600 a string value, and which is described by a @stringft.
 601
 602 Use bt_field_string_set_value() to set the current string value
 603 of a string field object. You can also use bt_field_string_append()
 604 and bt_field_string_append_len() to append a string to the current
 605 value of a string field.
 606
 607 After you create a string field with bt_field_create(), you
 608 \em must set a string value with
 609 bt_field_string_set_value(), bt_field_string_append(), or
 610 bt_field_string_append_len() before you can get the
 611 field's value with bt_field_string_get_value().
 612
 613 @sa ctfirstringfieldtype
 614 @sa ctfirfields
 615
 616 @addtogroup ctfirstringfield
 617 @{
 618 */
 619
 620 /**
 621 @brief  Returns the string value of the @stringfield \p string_field.
 622
 623 On success, \p string_field remains the sole owner of the returned
 624 value.
 625
 626 @param[in] string_field String field field of which to get the
 627                         string value.
 628 @returns                String value, or \c NULL on error.
 629
 630 @prenotnull{string_field}
 631 @prenotnull{value}
 632 @preisstringfield{string_field}
 633 @pre \p string_field contains a string value previously
 634         set with bt_field_string_set_value(),
 635         bt_field_string_append(), or
 636         bt_field_string_append_len().
 637 @postrefcountsame{string_field}
 638
 639 @sa bt_field_string_set_value(): Sets the string value of a given
 640         string field.
 641 */
 642 extern const char *bt_field_string_get_value(struct bt_field *string_field);
 643
 644 /**
 645 @brief  Sets the string value of the @stringfield \p string_field to
 646         \p value.
 647
 648 @param[in] string_field String field of which to set
 649                         the string value.
 650 @param[in] value        New string value of \p string_field (copied
 651                         on success).
 652 @returns                0 on success, or a negative value on error.
 653
 654 @prenotnull{string_field}
 655 @prenotnull{value}
 656 @preisstringfield{string_field}
 657 @prehot{string_field}
 658 @postrefcountsame{string_field}
 659
 660 @sa bt_field_string_get_value(): Returns the string value of a
 661         given string field.
 662 */
 663 extern int bt_field_string_set_value(struct bt_field *string_field,
 664                 const char *value);
 665
 666 /**
 667 @brief  Appends the string \p value to the current string value of
 668         the @stringfield \p string_field.
 669
 670 This function is the equivalent of:
 671
 672 @code
 673 bt_field_string_append_len(string_field, value, strlen(value));
 674 @endcode
 675
 676 @param[in] string_field String field of which to append \p value to
 677                         its current value.
 678 @param[in] value        String to append to the current string value
 679                         of \p string_field (copied on success).
 680 @returns                0 on success, or a negative value on error.
 681
 682 @prenotnull{string_field}
 683 @prenotnull{value}
 684 @preisstringfield{string_field}
 685 @prehot{string_field}
 686 @postrefcountsame{string_field}
 687
 688 @sa bt_field_string_set_value(): Sets the string value of a given
 689         string field.
 690 */
 691 extern int bt_field_string_append(struct bt_field *string_field,
 692                 const char *value);
 693
 694 /**
 695 @brief  Appends the first \p length characters of \p value to the
 696         current string value of the @stringfield \p string_field.
 697
 698 If \p string_field has no current string value, this function first
 699 sets an empty string as the string value of \p string_field and then
 700 appends the first \p length characters of \p value.
 701
 702 @param[in] string_field String field of which to append the first
 703                         \p length characters of \p value to
 704                         its current value.
 705 @param[in] value        String containing the characters to append to
 706                         the current string value of \p string_field
 707                         (copied on success).
 708 @param[in] length       Number of characters of \p value to append to
 709                         the current string value of \p string_field.
 710 @returns                0 on success, or a negative value on error.
 711
 712 @prenotnull{string_field}
 713 @prenotnull{value}
 714 @preisstringfield{string_field}
 715 @prehot{string_field}
 716 @postrefcountsame{string_field}
 717
 718 @sa bt_field_string_set_value(): Sets the string value of a given
 719         string field.
 720 */
 721 extern int bt_field_string_append_len(
 722                 struct bt_field *string_field, const char *value,
 723                 unsigned int length);
 724
 725 extern int bt_field_string_clear(struct bt_field *string_field);
 726
 727 /** @} */
 728
 729 /**
 730 @defgroup ctfirstructfield CTF IR structure field
 731 @ingroup ctfirfields
 732 @brief CTF IR structure field.
 733
 734 @code
 735 #include <babeltrace/ctf-ir/fields.h>
 736 @endcode
 737
 738 A CTF IR <strong><em>structure field</em></strong> is a @field which
 739 contains an ordered list of zero or more named @fields which can be
 740 different @fts, and which is described by a @structft.
 741
 742 To set the value of a specific field of a structure field, you need to
 743 first get the field with bt_field_structure_get_field_by_name() or
 744 bt_field_structure_get_field_by_index(). If you already have a
 745 field object, you can assign it to a specific name within a structure
 746 field with bt_field_structure_set_field_by_name().
 747
 748 @sa ctfirstructfieldtype
 749 @sa ctfirfields
 750
 751 @addtogroup ctfirstructfield
 752 @{
 753 */
 754
 755 extern struct bt_field *bt_field_structure_borrow_field_by_name(
 756                 struct bt_field *struct_field, const char *name);
 757
 758 extern struct bt_field *bt_field_structure_borrow_field_by_index(
 759                 struct bt_field *struct_field, uint64_t index);
 760
 761 /** @} */
 762
 763 /**
 764 @defgroup ctfirarrayfield CTF IR array field
 765 @ingroup ctfirfields
 766 @brief CTF IR array field.
 767
 768 @code
 769 #include <babeltrace/ctf-ir/fields.h>
 770 @endcode
 771
 772 A CTF IR <strong><em>array field</em></strong> is a @field which
 773 contains an ordered list of zero or more @fields sharing the same @ft,
 774 and which is described by a @arrayft.
 775
 776 To set the value of a specific field of an array field, you need to
 777 first get the field with bt_field_array_get_field().
 778
 779 @sa ctfirarrayfieldtype
 780 @sa ctfirfields
 781
 782 @addtogroup ctfirarrayfield
 783 @{
 784 */
 785
 786 extern struct bt_field *bt_field_array_borrow_field(
 787                 struct bt_field *array_field, uint64_t index);
 788
 789 /** @} */
 790
 791 /**
 792 @defgroup ctfirseqfield CTF IR sequence field
 793 @ingroup ctfirfields
 794 @brief CTF IR sequence field.
 795
 796 @code
 797 #include <babeltrace/ctf-ir/fields.h>
 798 @endcode
 799
 800 A CTF IR <strong><em>sequence field</em></strong> is a @field which
 801 contains an ordered list of zero or more @fields sharing the same @ft,
 802 and which is described by a @seqft.
 803
 804 Before you can get a specific field of a sequence field with
 805 bt_field_sequence_get_field(), you need to set its current length
 806 @intfield with bt_field_sequence_set_length(). The integral value of
 807 the length field of a sequence field indicates the number of fields
 808 it contains.
 809
 810 @sa ctfirseqfieldtype
 811 @sa ctfirfields
 812
 813 @addtogroup ctfirseqfield
 814 @{
 815 */
 816
 817 extern struct bt_field *bt_field_sequence_borrow_field(
 818                 struct bt_field *sequence_field, uint64_t index);
 819
 820 extern int64_t bt_field_sequence_get_length(struct bt_field *sequence_field);
 821
 822 /**
 823 @brief  Sets the length @intfield of the @seqfield \p sequence_field
 824         to \p length_field.
 825
 826 The current integral value of \p length_field indicates the number of
 827 fields contained in \p sequence_field.
 828
 829 @param[in] sequence_field       Sequence field of which to set the
 830                                 length field.
 831 @param[in] length_field         Length field of \p sequence_field.
 832 @returns                        0 on success, or a negative value on error.
 833
 834 @prenotnull{sequence_field}
 835 @prenotnull{length_field}
 836 @preisseqfield{sequence_field}
 837 @preisintfield{length_field}
 838 @prehot{sequence_field}
 839 @postrefcountsame{sequence_field}
 840 @postsuccessrefcountinc{length_field}
 841
 842 @sa bt_field_sequence_get_length(): Returns the length field of a
 843         given sequence field.
 844 */
 845 extern int bt_field_sequence_set_length(struct bt_field *sequence_field,
 846                 uint64_t length);
 847
 848 /** @} */
 849
 850 /**
 851 @defgroup ctfirvarfield CTF IR variant field
 852 @ingroup ctfirfields
 853 @brief CTF IR variant field.
 854
 855 @code
 856 #include <babeltrace/ctf-ir/fields.h>
 857 @endcode
 858
 859 A CTF IR <strong><em>variant field</em></strong> is a @field which
 860 contains a current @field amongst one or more choices, and which is
 861 described by a @varft.
 862
 863 Use bt_field_variant_get_field() to get the @field selected by
 864 a specific tag @enumfield. Once you call this function, you can call
 865 bt_field_variant_get_current_field() afterwards to get this last
 866 field again.
 867
 868 @sa ctfirvarfieldtype
 869 @sa ctfirfields
 870
 871 @addtogroup ctfirvarfield
 872 @{
 873 */
 874
 875 extern int bt_field_variant_set_tag_signed(struct bt_field *variant_field,
 876                 int64_t tag);
 877
 878 extern int bt_field_variant_set_tag_unsigned(struct bt_field *variant_field,
 879                 uint64_t tag);
 880
 881 extern int bt_field_variant_get_tag_signed(struct bt_field *variant_field,
 882                 int64_t *tag);
 883
 884 extern int bt_field_variant_get_tag_unsigned(struct bt_field *variant_field,
 885                 uint64_t *tag);
 886
 887 extern struct bt_field *bt_field_variant_borrow_current_field(
 888                 struct bt_field *variant_field);
 889
 890 /** @} */
 891
 892 #ifdef __cplusplus
 893 }
 894 #endif
 895
 896 #endif /* BABELTRACE_CTF_IR_FIELDS_H */