include/babeltrace/ctf-ir/fields.h

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