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