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