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_enumeration_mapping_iterator;
 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 names of the mappings containing this
 611 value in the enumeration field with
 612 bt_ctf_field_enumeration_get_mappings().
 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 a @enumiter to the mappings selected by the current
 643         integral value of the @enumfield \p enum_field.
 644
 645 @param[in] enum_field   Enumeration field of which to get the name of
 646                         mapping associated to its current integral
 647                         value.
 648 @returns                An iterator to the mappings associated to the
 649                         current integral value of \p enum_field, or
 650                         \c NULL on error.
 651
 652 @prenotnull{enum_field}
 653 @preisenumfield{enum_field}
 654 @pre The wrapped integer field of \p enum_field contains an integral
 655         value.
 656 @postrefcountsame{enum_field}
 657 @postsuccessrefcountret1
 658 */
 659 extern struct bt_ctf_field_type_enumeration_mapping_iterator *
 660 bt_ctf_field_enumeration_get_mappings(struct bt_ctf_field *enum_field);
 661
 662 /** @} */
 663
 664 /**
 665 @defgroup ctfirstringfield CTF IR string field
 666 @ingroup ctfirfields
 667 @brief CTF IR string field.
 668
 669 @code
 670 #include <babeltrace/ctf-ir/fields.h>
 671 @endcode
 672
 673 A CTF IR <strong><em>string field</em></strong> is a @field which holds
 674 a string value, and which is described by a @stringft.
 675
 676 Use bt_ctf_field_string_set_value() to set the current string value
 677 of a string field object. You can also use bt_ctf_field_string_append()
 678 and bt_ctf_field_string_append_len() to append a string to the current
 679 value of a string field.
 680
 681 After you create a string field with bt_ctf_field_create(), you
 682 \em must set a string value with
 683 bt_ctf_field_string_set_value(), bt_ctf_field_string_append(), or
 684 bt_ctf_field_string_append_len() before you can get the
 685 field's value with bt_ctf_field_string_get_value().
 686
 687 @sa ctfirstringfieldtype
 688 @sa ctfirfields
 689
 690 @addtogroup ctfirstringfield
 691 @{
 692 */
 693
 694 /**
 695 @brief  Returns the string value of the @stringfield \p string_field.
 696
 697 On success, \p string_field remains the sole owner of the returned
 698 value.
 699
 700 @param[in] string_field String field field of which to get the
 701                         string value.
 702 @returns                String value, or \c NULL on error.
 703
 704 @prenotnull{string_field}
 705 @prenotnull{value}
 706 @preisstringfield{string_field}
 707 @pre \p string_field contains a string value previously
 708         set with bt_ctf_field_string_set_value(),
 709         bt_ctf_field_string_append(), or
 710         bt_ctf_field_string_append_len().
 711 @postrefcountsame{string_field}
 712
 713 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
 714         string field.
 715 */
 716 extern const char *bt_ctf_field_string_get_value(
 717                 struct bt_ctf_field *string_field);
 718
 719 /**
 720 @brief  Sets the string value of the @stringfield \p string_field to
 721         \p value.
 722
 723 @param[in] string_field String field of which to set
 724                         the string value.
 725 @param[in] value        New string value of \p string_field (copied
 726                         on success).
 727 @returns                0 on success, or a negative value on error.
 728
 729 @prenotnull{string_field}
 730 @prenotnull{value}
 731 @preisstringfield{string_field}
 732 @prehot{string_field}
 733 @postrefcountsame{string_field}
 734
 735 @sa bt_ctf_field_string_get_value(): Returns the string value of a
 736         given string field.
 737 */
 738 extern int bt_ctf_field_string_set_value(struct bt_ctf_field *string_field,
 739                 const char *value);
 740
 741 /**
 742 @brief  Appends the string \p value to the current string value of
 743         the @stringfield \p string_field.
 744
 745 This function is the equivalent of:
 746
 747 @code
 748 bt_ctf_field_string_append_len(string_field, value, strlen(value));
 749 @endcode
 750
 751 @param[in] string_field String field of which to append \p value to
 752                         its current value.
 753 @param[in] value        String to append to the current string value
 754                         of \p string_field (copied on success).
 755 @returns                0 on success, or a negative value on error.
 756
 757 @prenotnull{string_field}
 758 @prenotnull{value}
 759 @preisstringfield{string_field}
 760 @prehot{string_field}
 761 @postrefcountsame{string_field}
 762
 763 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
 764         string field.
 765 */
 766 extern int bt_ctf_field_string_append(struct bt_ctf_field *string_field,
 767                 const char *value);
 768
 769 /**
 770 @brief  Appends the first \p length characters of \p value to the
 771         current string value of the @stringfield \p string_field.
 772
 773 If \p string_field has no current string value, this function first
 774 sets an empty string as the string value of \p string_field and then
 775 appends the first \p length characters of \p value.
 776
 777 @param[in] string_field String field of which to append the first
 778                         \p length characters of \p value to
 779                         its current value.
 780 @param[in] value        String containing the characters to append to
 781                         the current string value of \p string_field
 782                         (copied on success).
 783 @param[in] length       Number of characters of \p value to append to
 784                         the current string value of \p string_field.
 785 @returns                0 on success, or a negative value on error.
 786
 787 @prenotnull{string_field}
 788 @prenotnull{value}
 789 @preisstringfield{string_field}
 790 @prehot{string_field}
 791 @postrefcountsame{string_field}
 792
 793 @sa bt_ctf_field_string_set_value(): Sets the string value of a given
 794         string field.
 795 */
 796 extern int bt_ctf_field_string_append_len(
 797                 struct bt_ctf_field *string_field, const char *value,
 798                 unsigned int length);
 799
 800 /** @} */
 801
 802 /**
 803 @defgroup ctfirstructfield CTF IR structure field
 804 @ingroup ctfirfields
 805 @brief CTF IR structure field.
 806
 807 @code
 808 #include <babeltrace/ctf-ir/fields.h>
 809 @endcode
 810
 811 A CTF IR <strong><em>structure field</em></strong> is a @field which
 812 contains an ordered list of zero or more named @fields which can be
 813 different @fts, and which is described by a @structft.
 814
 815 To set the value of a specific field of a structure field, you need to
 816 first get the field with bt_ctf_field_structure_get_field() or
 817 bt_ctf_field_structure_get_field_by_index().
 818
 819 @sa ctfirstructfieldtype
 820 @sa ctfirfields
 821
 822 @addtogroup ctfirstructfield
 823 @{
 824 */
 825
 826 /**
 827 @brief  Returns the @field named \p name, potentially creating it,
 828         in the @structfield \p struct_field.
 829
 830 This function creates the @field to return if it does not currently
 831 exist.
 832
 833 @param[in] struct_field Structure field of which to get the field
 834                         named \p name.
 835 @param[in] name         Name of the field to get from \p struct_field.
 836 @returns                Field named \p name in \p struct_field, or
 837                         \c NULL on error.
 838
 839 @prenotnull{struct_field}
 840 @prenotnull{name}
 841 @preisstructfield{struct_field}
 842 @postrefcountsame{struct_field}
 843 @postsuccessrefcountretinc
 844
 845 @sa bt_ctf_field_structure_get_field_by_index(): Returns the field of a
 846         given structure field by index.
 847 */
 848 extern struct bt_ctf_field *bt_ctf_field_structure_get_field(
 849                 struct bt_ctf_field *struct_field, const char *name);
 850
 851 /**
 852 @brief  Returns the @field at index \p index in the @structfield
 853         \p struct_field.
 854
 855 @param[in] struct_field Structure field of which to get the field
 856                         at index \p index.
 857 @param[in] index        Index of the field to get in \p struct_field.
 858 @returns                Field at index \p index in \p struct_field, or
 859                         \c NULL on error.
 860
 861 @prenotnull{struct_field}
 862 @preisstructfield{struct_field}
 863 @pre \p index is lesser than the number of fields contained in the
 864         parent field type of \p struct_field (see
 865         bt_ctf_field_type_structure_get_field_count()).
 866 @postrefcountsame{struct_field}
 867 @postsuccessrefcountretinc
 868
 869 @sa bt_ctf_field_structure_get_field(): Returns the field of a
 870         given structure field by name.
 871 */
 872 extern struct bt_ctf_field *bt_ctf_field_structure_get_field_by_index(
 873                 struct bt_ctf_field *struct_field, int index);
 874
 875 /** @} */
 876
 877 /**
 878 @defgroup ctfirarrayfield CTF IR array field
 879 @ingroup ctfirfields
 880 @brief CTF IR array field.
 881
 882 @code
 883 #include <babeltrace/ctf-ir/fields.h>
 884 @endcode
 885
 886 A CTF IR <strong><em>array field</em></strong> is a @field which
 887 contains an ordered list of zero or more @fields sharing the same @ft,
 888 and which is described by a @arrayft.
 889
 890 To set the value of a specific field of an array field, you need to
 891 first get the field with bt_ctf_field_array_get_field().
 892
 893 @sa ctfirarrayfieldtype
 894 @sa ctfirfields
 895
 896 @addtogroup ctfirarrayfield
 897 @{
 898 */
 899
 900 /**
 901 @brief  Returns the @field at index \p index, potentially creating it,
 902         in the @arrayfield \p array_field.
 903
 904 This function creates the @field to return if it does not currently
 905 exist.
 906
 907 @param[in] array_field  Array field of which to get the field
 908                         at index \p index.
 909 @param[in] index        Index of the field to get in \p array_field.
 910 @returns                Field at index \p index in \p array_field, or
 911                         \c NULL on error.
 912
 913 @prenotnull{array_field}
 914 @preisarrayfield{array_field}
 915 @pre \p index is lesser than bt_ctf_field_type_array_get_length() called
 916         on the field type of \p array_field.
 917 @postrefcountsame{array_field}
 918 @postsuccessrefcountretinc
 919 */
 920 extern struct bt_ctf_field *bt_ctf_field_array_get_field(
 921                 struct bt_ctf_field *array_field, uint64_t index);
 922
 923 /** @} */
 924
 925 /**
 926 @defgroup ctfirseqfield CTF IR sequence field
 927 @ingroup ctfirfields
 928 @brief CTF IR sequence field.
 929
 930 @code
 931 #include <babeltrace/ctf-ir/fields.h>
 932 @endcode
 933
 934 A CTF IR <strong><em>sequence field</em></strong> is a @field which
 935 contains an ordered list of zero or more @fields sharing the same @ft,
 936 and which is described by a @seqft.
 937
 938 Before you can get a specific field of a sequence field with
 939 bt_ctf_field_sequence_get_field(), you need to set its current length
 940 @intfield with bt_ctf_field_sequence_set_length(). The integral value of
 941 the length field of a sequence field indicates the number of fields
 942 it contains.
 943
 944 @sa ctfirseqfieldtype
 945 @sa ctfirfields
 946
 947 @addtogroup ctfirseqfield
 948 @{
 949 */
 950
 951 /**
 952 @brief  Returns the @field at index \p index, potentially creating it,
 953         in the @seqfield \p sequence_field.
 954
 955 This function creates the @field to return if it does not currently
 956 exist.
 957
 958 @param[in] sequence_field       Sequence field of which to get the field
 959                                 at index \p index.
 960 @param[in] index                Index of the field to get in
 961                                 \p sequence_field.
 962 @returns                        Field at index \p index in
 963                                 \p sequence_field, or \c NULL on error.
 964
 965 @prenotnull{sequence_field}
 966 @preisseqfield{sequence_field}
 967 @pre \p sequence_field has a length field previously set with
 968         bt_ctf_field_sequence_set_length().
 969 @pre \p index is lesser than the current integral value of the current
 970         length field of \p sequence_field (see
 971         bt_ctf_field_sequence_get_length()).
 972 @postrefcountsame{sequence_field}
 973 @postsuccessrefcountretinc
 974 */
 975 extern struct bt_ctf_field *bt_ctf_field_sequence_get_field(
 976                 struct bt_ctf_field *sequence_field, uint64_t index);
 977
 978 /**
 979 @brief  Returns the length @intfield of the @seqfield \p sequence_field.
 980
 981 The current integral value of the returned length field indicates the
 982 number of fields contained in \p sequence_field.
 983
 984 @param[in] sequence_field       Sequence field of which to get the
 985                                 length field.
 986 @returns                        Length field of \p sequence_field, or
 987                                 \c NULL on error.
 988
 989 @prenotnull{sequence_field}
 990 @preisseqfield{sequence_field}
 991 @pre \p sequence_field has a length field previously set with
 992         bt_ctf_field_sequence_set_length().
 993 @postrefcountsame{sequence_field}
 994 @postsuccessrefcountretinc
 995 @post <strong>On success</strong>, the returned field is a @intfield.
 996
 997 @sa bt_ctf_field_sequence_set_length(): Sets the length field of a given
 998         sequence field.
 999 */
1000 extern struct bt_ctf_field *bt_ctf_field_sequence_get_length(
1001                 struct bt_ctf_field *sequence_field);
1002
1003 /**
1004 @brief  Sets the length @intfield of the @seqfield \p sequence_field
1005         to \p length_field.
1006
1007 The current integral value of \p length_field indicates the number of
1008 fields contained in \p sequence_field.
1009
1010 @param[in] sequence_field       Sequence field of which to set the
1011                                 length field.
1012 @param[in] length_field         Length field of \p sequence_field.
1013 @returns                        0 on success, or a negative value on error.
1014
1015 @prenotnull{sequence_field}
1016 @prenotnull{length_field}
1017 @preisseqfield{sequence_field}
1018 @preisintfield{length_field}
1019 @prehot{sequence_field}
1020 @postrefcountsame{sequence_field}
1021 @postsuccessrefcountinc{length_field}
1022
1023 @sa bt_ctf_field_sequence_get_length(): Returns the length field of a
1024         given sequence field.
1025 */
1026 extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field *sequence_field,
1027                 struct bt_ctf_field *length_field);
1028
1029 /** @} */
1030
1031 /**
1032 @defgroup ctfirvarfield CTF IR variant field
1033 @ingroup ctfirfields
1034 @brief CTF IR variant field.
1035
1036 @code
1037 #include <babeltrace/ctf-ir/fields.h>
1038 @endcode
1039
1040 A CTF IR <strong><em>variant field</em></strong> is a @field which
1041 contains a current @field amongst one or more choices, and which is
1042 described by a @varft.
1043
1044 Use bt_ctf_field_variant_get_field() to get the @field selected by
1045 a specific tag @enumfield. Once you call this function, you can call
1046 bt_ctf_field_variant_get_current_field() afterwards to get this last
1047 field again.
1048
1049 @sa ctfirvarfieldtype
1050 @sa ctfirfields
1051
1052 @addtogroup ctfirvarfield
1053 @{
1054 */
1055
1056 /**
1057 @brief  Returns the @field, potentially creating it, selected by the
1058         tag @intfield \p tag_field in the @varfield \p variant_field.
1059
1060 This function creates the @field to return if it does not currently
1061 exist.
1062
1063 Once you call this function, you can call
1064 bt_ctf_field_variant_get_current_field() to get the same field again,
1065 and you can call bt_ctf_field_variant_get_tag() to get \p tag_field.
1066
1067 @param[in] variant_field        Variant field of which to get the field
1068                                 selected by \p tag_field.
1069 @param[in] tag_field            Tag field.
1070 @returns                        Field selected by \p tag_field in
1071                                 \p variant_field, or \c NULL on error.
1072
1073 @prenotnull{variant_field}
1074 @prenotnull{tag_field}
1075 @preisvarfield{variant_field}
1076 @preisenumfield{tag_field}
1077 @postrefcountsame{variant_field}
1078 @postsuccessrefcountinc{tag_field}
1079 @postsuccessrefcountretinc
1080 */
1081 extern struct bt_ctf_field *bt_ctf_field_variant_get_field(
1082                 struct bt_ctf_field *variant_field,
1083                 struct bt_ctf_field *tag_field);
1084
1085 /**
1086 @brief  Returns the currently selected @field of the @varfield
1087         \p variant_field.
1088
1089 @param[in] variant_field        Variant field of which to get the
1090                                 currently selected field.
1091 @returns                        Currently selected field of
1092                                 \p variant_field, or \c NULL if there's
1093                                 no selected field or on error.
1094
1095 @prenotnull{variant_field}
1096 @preisvarfield{variant_field}
1097 @pre \p variant_field contains has a current selected field previously
1098         set with bt_ctf_field_variant_get_field().
1099 @postrefcountsame{variant_field}
1100 @postsuccessrefcountretinc
1101 */
1102 extern struct bt_ctf_field *bt_ctf_field_variant_get_current_field(
1103                 struct bt_ctf_field *variant_field);
1104
1105 /**
1106 @brief  Returns the tag @enumfield of the @varfield \p variant_field.
1107
1108 @param[in] variant_field        Variant field of which to get the
1109                                 tag field.
1110 @returns                        Tag field of \p variant_field, or
1111                                 \c NULL on error.
1112
1113 @prenotnull{variant_field}
1114 @preisvarfield{variant_field}
1115 @pre \p variant_field contains has a current selected field previously
1116         set with bt_ctf_field_variant_get_field().
1117 @postrefcountsame{variant_field}
1118 @postsuccessrefcountretinc
1119 @post <strong>On success</strong>, the returned field is a @enumfield.
1120 */
1121 extern struct bt_ctf_field *bt_ctf_field_variant_get_tag(
1122                 struct bt_ctf_field *variant_field);
1123
1124 /** @} */
1125
1126 #ifdef __cplusplus
1127 }
1128 #endif
1129
1130 #endif /* BABELTRACE_CTF_IR_FIELDS_H */