include/babeltrace/ctf-ir/fields.h

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