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