include/babeltrace/ctf-ir/field-types.h

   1 #ifndef BABELTRACE_CTF_IR_FIELD_TYPES_H
   2 #define BABELTRACE_CTF_IR_FIELD_TYPES_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event field types
   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
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40 @defgroup ctfirfieldtypes CTF IR field types
  41 @ingroup ctfir
  42 @brief CTF IR field types.
  43
  44 @code
  45 #include <babeltrace/ctf-ir/field-types.h>
  46 @endcode
  47
  48 A CTF IR <strong><em>field type</em></strong> is a field type that you
  49 can use to create concrete @fields.
  50
  51 You can create a @field object from a CTF IR field type object
  52 with bt_ctf_field_create().
  53
  54 In the CTF IR hierarchy, you can set the root field types of three
  55 objects:
  56
  57 - \ref ctfirtraceclass
  58   - Trace packet header field type: bt_ctf_trace_set_packet_header_type().
  59 - \ref ctfirstreamclass
  60   - Stream packet context field type:
  61     bt_ctf_stream_class_set_packet_context_type().
  62   - Stream event header field type:
  63     bt_ctf_stream_class_set_event_header_type().
  64   - Stream event context field type:
  65     bt_ctf_stream_class_set_event_context_type().
  66 - \ref ctfireventclass
  67   - Event context field type: bt_ctf_event_class_set_context_type().
  68   - Event payload field type: bt_ctf_event_class_set_payload_type().
  69
  70 As of Babeltrace \btversion, those six previous "root" field types
  71 \em must be @structft objects.
  72
  73 If, at any level within a given root field type, you add a @seqft or a
  74 @varft, you do not need to specify its associated length
  75 or tag field type: the length or tag string is enough for the Babeltrace
  76 system to resolve the needed field type depending on where this
  77 dynamic field type is located within the whole hierarchy. It is
  78 guaranteed that this automatic resolving is performed for all the field
  79 types contained in a given
  80 \link ctfirstreamclass CTF IR stream class\endlink (and in its
  81 children \link ctfireventclass CTF IR event classes\endlink) once you
  82 add it to a \link ctfirtraceclass CTF IR trace class\endlink with
  83 bt_ctf_trace_add_stream_class(). Once a stream class is the child of
  84 a trace class, this automatic resolving is performed for the field
  85 types of an event class when you add it with
  86 bt_ctf_stream_class_add_event_class(). If the system cannot find a path
  87 to a field in the hierarchy for a dynamic field type, the adding
  88 function fails.
  89
  90 The standard CTF field types are:
  91
  92 <table>
  93   <tr>
  94     <th>Type ID
  95     <th>CTF IR field type
  96     <th>CTF IR field which you can create from this field type
  97   </tr>
  98   <tr>
  99     <td>#BT_CTF_TYPE_ID_INTEGER
 100     <td>\ref ctfirintfieldtype
 101     <td>\ref ctfirintfield
 102   </tr>
 103   <tr>
 104     <td>#BT_CTF_TYPE_ID_FLOAT
 105     <td>\ref ctfirfloatfieldtype
 106     <td>\ref ctfirfloatfield
 107   </tr>
 108   <tr>
 109     <td>#BT_CTF_TYPE_ID_ENUM
 110     <td>\ref ctfirenumfieldtype
 111     <td>\ref ctfirenumfield
 112   </tr>
 113   <tr>
 114     <td>#BT_CTF_TYPE_ID_STRING
 115     <td>\ref ctfirstringfieldtype
 116     <td>\ref ctfirstringfield
 117   </tr>
 118   <tr>
 119     <td>#BT_CTF_TYPE_ID_STRUCT
 120     <td>\ref ctfirstructfieldtype
 121     <td>\ref ctfirstructfield
 122   </tr>
 123   <tr>
 124     <td>#BT_CTF_TYPE_ID_ARRAY
 125     <td>\ref ctfirarrayfieldtype
 126     <td>\ref ctfirarrayfield
 127   </tr>
 128   <tr>
 129     <td>#BT_CTF_TYPE_ID_SEQUENCE
 130     <td>\ref ctfirseqfieldtype
 131     <td>\ref ctfirseqfield
 132   </tr>
 133   <tr>
 134     <td>#BT_CTF_TYPE_ID_VARIANT
 135     <td>\ref ctfirvarfieldtype
 136     <td>\ref ctfirvarfield
 137   </tr>
 138 </table>
 139
 140 Each field type has its own <strong>type ID</strong> (see
 141 #bt_ctf_type_id). You get the type ID of a field type object
 142 with bt_ctf_field_type_get_type_id().
 143
 144 You can get a deep copy of a field type with bt_ctf_field_type_copy().
 145 This function resets, in the field type copy, the resolved field type
 146 of the dynamic field types. The automatic resolving can be done again
 147 when you eventually call bt_ctf_event_create(),
 148 bt_ctf_stream_class_add_event_class(), or
 149 bt_ctf_trace_add_stream_class().
 150
 151 You \em must always use bt_ctf_field_type_compare() to compare two
 152 field types. Since some parts of the Babeltrace system can copy field
 153 types behind the scenes, you \em cannot rely on a simple field type
 154 pointer comparison.
 155
 156 As with any Babeltrace object, CTF IR field type objects have
 157 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 158 counts</a>. See \ref refs to learn more about the reference counting
 159 management of Babeltrace objects.
 160
 161 The following functions can \em freeze field type objects:
 162
 163 - bt_ctf_field_create() freezes its field type parameter.
 164 - bt_ctf_stream_class_add_event_class(), if its
 165   \link ctfirstreamclass CTF IR stream class\endlink parameter has a
 166   \link ctfirtraceclass CTF IR trace class\endlink parent, freezes
 167   the root field types of its
 168   \link ctfireventclass CTF IR event class\endlink parameter.
 169 - bt_ctf_trace_add_stream_class() freezes the root field types of the
 170   whole trace class hierarchy (trace class, children stream classes,
 171   and their children event classes).
 172 - bt_ctf_writer_create_stream() freezes the root field types of the
 173   whole CTF writer's trace class hierarchy.
 174 - bt_ctf_event_create() freezes the root field types of its event class
 175   parameter and of ther parent stream class of this event class.
 176
 177 You cannot modify a frozen field type object: it is considered
 178 immutable, except for \link refs reference counting\endlink.
 179
 180 @sa ctfirfields
 181
 182 @file
 183 @brief CTF IR field types type and functions.
 184 @sa ctfirfieldtypes
 185
 186 @addtogroup ctfirfieldtypes
 187 @{
 188 */
 189
 190 /**
 191 @struct bt_ctf_field_type
 192 @brief A CTF IR field type.
 193 @sa ctfirfieldtypes
 194 */
 195 struct bt_ctf_field_type;
 196 struct bt_ctf_event_class;
 197 struct bt_ctf_event;
 198 struct bt_ctf_field;
 199 struct bt_ctf_field_path;
 200
 201 /** @cond DOCUMENT */
 202
 203 /*
 204  * Babeltrace 1.x enumerations that were also used in CTF writer's API.
 205  * They are left here for backward compatibility reasons, but
 206  * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used
 207  * in new code. Both new enumerations are compatible with their legacy
 208  * counterpart.
 209  */
 210 enum ctf_type_id {
 211         CTF_TYPE_UNKNOWN = 0,
 212         CTF_TYPE_INTEGER,
 213         CTF_TYPE_FLOAT,
 214         CTF_TYPE_ENUM,
 215         CTF_TYPE_STRING,
 216         CTF_TYPE_STRUCT,
 217         CTF_TYPE_UNTAGGED_VARIANT,
 218         CTF_TYPE_VARIANT,
 219         CTF_TYPE_ARRAY,
 220         CTF_TYPE_SEQUENCE,
 221         NR_CTF_TYPES,
 222 };
 223
 224 /*
 225  * Old enum.
 226  */
 227 enum ctf_string_encoding {
 228         CTF_STRING_NONE = 0,
 229         CTF_STRING_UTF8,
 230         CTF_STRING_ASCII,
 231         CTF_STRING_UNKNOWN,
 232 };
 233
 234 /** @endcond */
 235
 236 /**
 237 @brief  CTF scope.
 238 */
 239 enum bt_ctf_scope {
 240         /// Unknown, used for errors.
 241         BT_CTF_SCOPE_UNKNOWN = -1,
 242
 243         /// Trace packet header.
 244         BT_CTF_SCOPE_TRACE_PACKET_HEADER = 1,
 245
 246         /// Stream packet context.
 247         BT_CTF_SCOPE_STREAM_PACKET_CONTEXT = 2,
 248
 249         /// Stream event header.
 250         BT_CTF_SCOPE_STREAM_EVENT_HEADER = 3,
 251
 252         /// Stream event context.
 253         BT_CTF_SCOPE_STREAM_EVENT_CONTEXT = 4,
 254
 255         /// Event context.
 256         BT_CTF_SCOPE_EVENT_CONTEXT = 5,
 257
 258         /// Event payload.
 259         BT_CTF_SCOPE_EVENT_PAYLOAD = 6,
 260
 261         /// @cond DOCUMENT
 262         BT_CTF_SCOPE_ENV = 0,
 263         BT_CTF_SCOPE_EVENT_FIELDS = 6,
 264         /// @endcond
 265 };
 266
 267 /**
 268 @name Type information
 269 @{
 270 */
 271
 272 /**
 273 @brief  Type ID of a @ft.
 274 */
 275 enum bt_ctf_type_id {
 276         /// Unknown, used for errors.
 277         BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN,
 278
 279         /// \ref ctfirintfieldtype
 280         BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER,
 281
 282         /// \ref ctfirfloatfieldtype
 283         BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT,
 284
 285         /// \ref ctfirenumfieldtype
 286         BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM,
 287
 288         /// \ref ctfirstringfieldtype
 289         BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING,
 290
 291         /// \ref ctfirstructfieldtype
 292         BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT,
 293
 294         /// @cond DOCUMENT
 295         BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT,
 296         /// @endcond
 297
 298         /// \ref ctfirarrayfieldtype
 299         BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY,
 300
 301         /// \ref ctfirseqfieldtype
 302         BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE,
 303
 304         /// \ref ctfirvarfieldtype
 305         BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT,
 306
 307         /// Number of enumeration entries.
 308         BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES,
 309 };
 310
 311 /**
 312 @brief  Returns the type ID of the @ft \p field_type.
 313
 314 @param[in] field_type   Field type of which to get the type ID.
 315 @returns                Type ID of \p field_type,
 316                         or #BT_CTF_TYPE_ID_UNKNOWN on error.
 317
 318 @prenotnull{field_type}
 319 @postrefcountsame{field_type}
 320
 321 @sa #bt_ctf_type_id: CTF IR field type ID.
 322 @sa bt_ctf_field_type_is_integer(): Returns whether or not a given
 323         field type is a @intft.
 324 @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a
 325         given field type is a @floatft.
 326 @sa bt_ctf_field_type_is_enumeration(): Returns whether or not a given
 327         field type is a @enumft.
 328 @sa bt_ctf_field_type_is_string(): Returns whether or not a given
 329         field type is a @stringft.
 330 @sa bt_ctf_field_type_is_structure(): Returns whether or not a given
 331         field type is a @structft.
 332 @sa bt_ctf_field_type_is_array(): Returns whether or not a given
 333         field type is a @arrayft.
 334 @sa bt_ctf_field_type_is_sequence(): Returns whether or not a given
 335         field type is a @seqft.
 336 @sa bt_ctf_field_type_is_variant(): Returns whether or not a given
 337         field type is a @varft.
 338 */
 339 extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id(
 340                 struct bt_ctf_field_type *field_type);
 341
 342 /**
 343 @brief  Returns whether or not the @ft \p field_type is a @intft.
 344
 345 @param[in] field_type   Field type to check (can be \c NULL).
 346 @returns                1 if \p field_type is an integer field type,
 347                         or 0 otherwise (including if \p field_type is
 348                         \c NULL).
 349
 350 @prenotnull{field_type}
 351 @postrefcountsame{field_type}
 352
 353 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 354         field type.
 355 */
 356 extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type);
 357
 358 /**
 359 @brief  Returns whether or not the @ft \p field_type is a @floatft.
 360
 361 @param[in] field_type   Field type to check (can be \c NULL).
 362 @returns                1 if \p field_type is a floating point
 363                         number field type,
 364                         or 0 otherwise (including if \p field_type is
 365                         \c NULL).
 366
 367 @postrefcountsame{field_type}
 368
 369 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 370         field type.
 371 */
 372 extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_type);
 373
 374 /**
 375 @brief  Returns whether or not the @ft \p field_type is a @enumft.
 376
 377 @param[in] field_type   Field type to check (can be \c NULL).
 378 @returns                1 if \p field_type is an enumeration field type,
 379                         or 0 otherwise (including if \p field_type is
 380                         \c NULL).
 381
 382 @postrefcountsame{field_type}
 383
 384 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 385         field type.
 386 */
 387 extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type);
 388
 389 /**
 390 @brief  Returns whether or not the @ft \p field_type is a @stringft.
 391
 392 @param[in] field_type   Field type to check (can be \c NULL).
 393 @returns                1 if \p field_type is a string field type,
 394                         or 0 otherwise (including if \p field_type is
 395                         \c NULL).
 396
 397 @postrefcountsame{field_type}
 398
 399 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 400         field type.
 401 */
 402 extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type);
 403
 404 /**
 405 @brief  Returns whether or not the @ft \p field_type is a @structft.
 406
 407 @param[in] field_type   Field type to check (can be \c NULL).
 408 @returns                1 if \p field_type is a structure field type,
 409                         or 0 otherwise (including if \p field_type is
 410                         \c NULL).
 411
 412 @postrefcountsame{field_type}
 413
 414 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 415         field type.
 416 */
 417 extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type);
 418
 419 /**
 420 @brief  Returns whether or not the @ft \p field_type is a @arrayft.
 421
 422 @param[in] field_type   Field type to check (can be \c NULL).
 423 @returns                1 if \p field_type is an array field type,
 424                         or 0 otherwise (including if \p field_type is
 425                         \c NULL).
 426
 427 @postrefcountsame{field_type}
 428
 429 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 430         field type.
 431 */
 432 extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type);
 433
 434 /**
 435 @brief  Returns whether or not the @ft \p field_type is a @seqft.
 436
 437 @param[in] field_type   Field type to check (can be \c NULL).
 438 @returns                1 if \p field_type is a sequence field type,
 439                         or 0 otherwise (including if \p field_type is
 440                         \c NULL).
 441
 442 @postrefcountsame{field_type}
 443
 444 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 445         field type.
 446 */
 447 extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type);
 448
 449 /**
 450 @brief  Returns whether or not the @ft \p field_type is a @varft.
 451
 452 @param[in] field_type   Field type to check (can be \c NULL).
 453 @returns                1 if \p field_type is a variant field type,
 454                         or 0 otherwise (including if \p field_type is
 455                         \c NULL).
 456
 457 @postrefcountsame{field_type}
 458
 459 @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given
 460         field type.
 461 */
 462 extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type);
 463
 464 /** @} */
 465
 466 /**
 467 @name Common properties types and functions
 468 @{
 469 */
 470
 471 /**
 472 @brief  <a href="https://en.wikipedia.org/wiki/Endianness">Byte order</a>
 473         of a @ft.
 474 */
 475 enum bt_ctf_byte_order {
 476         /// Unknown, used for errors.
 477         BT_CTF_BYTE_ORDER_UNKNOWN = -1,
 478
 479         /*
 480          * Note that native, in the context of the CTF specification, is defined
 481          * as "the byte order described in the trace" and does not mean that the
 482          * host's endianness will be used.
 483          */
 484         /// Native (default) byte order.
 485         BT_CTF_BYTE_ORDER_NATIVE = 0,
 486
 487         /// Little-endian.
 488         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
 489
 490         /// Big-endian.
 491         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
 492
 493         /// Network byte order (big-endian).
 494         BT_CTF_BYTE_ORDER_NETWORK,
 495 };
 496
 497 /**
 498 @brief  String encoding of a @ft.
 499 */
 500 enum bt_ctf_string_encoding {
 501         /// Unknown, used for errors.
 502         BT_CTF_STRING_ENCODING_UNKNOWN = CTF_STRING_UNKNOWN,
 503
 504         /// No encoding.
 505         BT_CTF_STRING_ENCODING_NONE = CTF_STRING_NONE,
 506
 507         /// <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>.
 508         BT_CTF_STRING_ENCODING_UTF8 = CTF_STRING_UTF8,
 509
 510         /// <a href="https://en.wikipedia.org/wiki/ASCII">ASCII</a>.
 511         BT_CTF_STRING_ENCODING_ASCII = CTF_STRING_ASCII,
 512 };
 513
 514 /**
 515 @brief  Returns the alignment of the @fields described by
 516         the @ft \p field_type.
 517
 518 @param[in] field_type   Field type which describes the
 519                         fields of which to get the alignment.
 520 @returns                Alignment of the fields described by
 521                         \p field_type, or a negative value on error.
 522
 523 @prenotnull{field_type}
 524 @postrefcountsame{field_type}
 525
 526 @sa bt_ctf_field_type_set_alignment(): Sets the alignment
 527         of the fields described by a given field type.
 528 */
 529 extern int bt_ctf_field_type_get_alignment(
 530                 struct bt_ctf_field_type *field_type);
 531
 532 /**
 533 @brief  Sets the alignment of the @fields described by the
 534         @ft \p field_type to \p alignment.
 535
 536 \p alignment \em must be greater than 0 and a power of two.
 537
 538 @param[in] field_type   Field type which describes the fields of
 539                         which to set the alignment.
 540 @param[in] alignment    Alignment of the fields described by
 541                         \p field_type.
 542 @returns                0 on success, or a negative value on error.
 543
 544 @prenotnull{field_type}
 545 @prehot{field_type}
 546 @pre \p alignment is greater than 0 and a power of two.
 547 @postrefcountsame{field_type}
 548
 549 @sa bt_ctf_field_type_get_alignment(): Returns the alignment of the
 550         fields described by a given field type.
 551 */
 552 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *field_type,
 553                 unsigned int alignment);
 554
 555 /**
 556 @brief  Returns the byte order of the @fields described by
 557         the @ft \p field_type.
 558
 559 You can only call this function if \p field_type is a @intft, a
 560 @floatft, or a @enumft.
 561
 562 @param[in] field_type   Field type which describes the
 563                         fields of which to get the byte order.
 564 @returns                Byte order of the fields described by
 565                         \p field_type, or #BT_CTF_BYTE_ORDER_UNKNOWN on
 566                         error.
 567
 568 @prenotnull{field_type}
 569 @pre \p field_type is a @intft, a @floatft, or a @enumft.
 570 @postrefcountsame{field_type}
 571
 572 @sa bt_ctf_field_type_set_byte_order(): Sets the byte order
 573         of the fields described by a given field type.
 574 */
 575 extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order(
 576                 struct bt_ctf_field_type *field_type);
 577
 578 /**
 579 @brief  Sets the byte order of the @fields described by the
 580         @ft \p field_type to \p byte_order.
 581
 582 If \p field_type is a compound field type, this function also
 583 recursively sets the byte order of its children to \p byte_order.
 584
 585 @param[in] field_type   Field type which describes the fields of
 586                         which to set the byte order.
 587 @param[in] byte_order   Alignment of the fields described by
 588                         \p field_type.
 589 @returns                0 on success, or a negative value on error.
 590
 591 @prenotnull{field_type}
 592 @prehot{field_type}
 593 @pre \p byte_order is #BT_CTF_BYTE_ORDER_NATIVE,
 594         #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, #BT_CTF_BYTE_ORDER_BIG_ENDIAN,
 595         or #BT_CTF_BYTE_ORDER_NETWORK.
 596 @postrefcountsame{field_type}
 597
 598 @sa bt_ctf_field_type_get_byte_order(): Returns the byte order of the
 599         fields described by a given field type.
 600 */
 601 extern int bt_ctf_field_type_set_byte_order(
 602                 struct bt_ctf_field_type *field_type,
 603                 enum bt_ctf_byte_order byte_order);
 604
 605 /** @} */
 606
 607 /**
 608 @name Utility functions
 609 @{
 610 */
 611
 612 /**
 613 @brief  Returns whether or not the @ft \p field_type_a
 614         is equivalent to the field type \p field_type_b.
 615
 616 You \em must use this function to compare two field types: it is not
 617 safe to compare two pointer values directly, because, for internal
 618 reasons, some parts of the Babeltrace system can copy user field types
 619 and discard the original ones.
 620
 621 @param[in] field_type_a Field type to compare to \p field_type_b.
 622 @param[in] field_type_b Field type to compare to \p field_type_a.
 623 @returns                0 if \p field_type_a is equivalent to
 624                         \p field_type_b, 1 if they are not equivalent,
 625                         or a negative value on error.
 626
 627 @prenotnull{field_type_a}
 628 @prenotnull{field_type_b}
 629 @postrefcountsame{field_type_a}
 630 @postrefcountsame{field_type_b}
 631 */
 632 extern int bt_ctf_field_type_compare(struct bt_ctf_field_type *field_type_a,
 633                 struct bt_ctf_field_type *field_type_b);
 634
 635 /**
 636 @brief  Creates a \em deep copy of the @ft \p field_type.
 637
 638 You can copy a frozen field type: the resulting copy is
 639 <em>not frozen</em>.
 640
 641 This function resets the tag field type of a copied @varft. The
 642 automatic field resolving which some functions of the API perform
 643 can set it again when the returned field type is used (learn more
 644 in the detailed description of this module).
 645
 646 @param[in] field_type   Field type to copy.
 647 @returns                Deep copy of \p field_type on success,
 648                         or \c NULL on error.
 649
 650 @prenotnull{field_type}
 651 @postrefcountsame{field_type}
 652 @postsuccessrefcountret1
 653 @post <strong>On success</strong>, the returned field type is not frozen.
 654 */
 655 extern struct bt_ctf_field_type *bt_ctf_field_type_copy(
 656                 struct bt_ctf_field_type *field_type);
 657
 658 /** @} */
 659
 660 /** @} */
 661
 662 /**
 663 @defgroup ctfirintfieldtype CTF IR integer field type
 664 @ingroup ctfirfieldtypes
 665 @brief CTF IR integer field type.
 666
 667 @code
 668 #include <babeltrace/ctf-ir/field-types.h>
 669 @endcode
 670
 671 A CTF IR <strong><em>integer field type</em></strong> is a field type that
 672 you can use to create concrete @intfield objects.
 673
 674 You can create an integer field type
 675 with bt_ctf_field_type_integer_create().
 676
 677 An integer field type has the following properties:
 678
 679 <table>
 680   <tr>
 681     <th>Property
 682     <th>Value at creation
 683     <th>Getter
 684     <th>Setter
 685   </tr>
 686   <tr>
 687     <td>\b Alignment (bits) of the described integer fields
 688     <td>1
 689     <td>bt_ctf_field_type_get_alignment()
 690     <td>bt_ctf_field_type_set_alignment()
 691   </tr>
 692   <tr>
 693     <td><strong>Byte order</strong> of the described integer fields
 694     <td>#BT_CTF_BYTE_ORDER_NATIVE
 695     <td>bt_ctf_field_type_get_byte_order()
 696     <td>bt_ctf_field_type_set_byte_order()
 697   </tr>
 698   <tr>
 699     <td><strong>Storage size</strong> (bits) of the described
 700         integer fields
 701     <td>Specified at creation
 702     <td>bt_ctf_field_type_integer_get_size()
 703     <td>None: specified at creation (bt_ctf_field_type_integer_create())
 704   </tr>
 705   <tr>
 706     <td><strong>Signedness</strong> of the described integer fields
 707     <td>Unsigned
 708     <td>bt_ctf_field_type_integer_get_signed()
 709     <td>bt_ctf_field_type_integer_set_signed()
 710   </tr>
 711   <tr>
 712     <td><strong>Preferred display base</strong> of the described
 713         integer fields
 714     <td>#BT_CTF_INTEGER_BASE_DECIMAL
 715     <td>bt_ctf_field_type_integer_get_base()
 716     <td>bt_ctf_field_type_integer_set_base()
 717   </tr>
 718   <tr>
 719     <td>\b Encoding of the described integer fields
 720     <td>#BT_CTF_STRING_ENCODING_NONE
 721     <td>bt_ctf_field_type_integer_get_encoding()
 722     <td>bt_ctf_field_type_integer_set_encoding()
 723   </tr>
 724   <tr>
 725     <td><strong>Mapped
 726         \link ctfirclockclass CTF IR clock class\endlink</strong>
 727     <td>None
 728     <td>bt_ctf_field_type_integer_get_mapped_clock_class()
 729     <td>bt_ctf_field_type_integer_set_mapped_clock_class()
 730   </tr>
 731 </table>
 732
 733 @sa ctfirintfield
 734 @sa ctfirfieldtypes
 735
 736 @addtogroup ctfirintfieldtype
 737 @{
 738 */
 739
 740 /**
 741 @brief  Preferred display base (radix) of a @intft.
 742 */
 743 enum bt_ctf_integer_base {
 744         /// Unknown, used for errors.
 745         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
 746
 747         /// Binary.
 748         BT_CTF_INTEGER_BASE_BINARY = 2,
 749
 750         /// Octal.
 751         BT_CTF_INTEGER_BASE_OCTAL = 8,
 752
 753         /// Decimal.
 754         BT_CTF_INTEGER_BASE_DECIMAL = 10,
 755
 756         /// Hexadecimal.
 757         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
 758 };
 759
 760 /**
 761 @brief  Creates a default @intft with \p size bits as the storage size
 762         of the @intfields it describes.
 763
 764 @param[in] size Storage size (bits) of the described integer fields.
 765 @returns        Created integer field type, or \c NULL on error.
 766
 767 @pre \p size is greater than 0 and lesser than or equal to 64.
 768 @postsuccessrefcountret1
 769 */
 770 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
 771                 unsigned int size);
 772
 773 /**
 774 @brief  Returns the storage size, in bits, of the @intfields
 775         described by the @intft \p int_field_type.
 776
 777 @param[in] int_field_type       Integer field type which describes the
 778                                 integer fields of which to get the
 779                                 storage size.
 780 @returns                        Storage size (bits) of the integer
 781                                 fields described by \p int_field_type,
 782                                 or a negative value on error.
 783
 784 @prenotnull{int_field_type}
 785 @preisintft{int_field_type}
 786 @postrefcountsame{int_field_type}
 787 */
 788 extern int bt_ctf_field_type_integer_get_size(
 789                 struct bt_ctf_field_type *int_field_type);
 790
 791 /**
 792 @brief  Returns whether or not the @intfields described by the @intft
 793         \p int_field_type are signed.
 794
 795 @param[in] int_field_type       Integer field type which describes the
 796                                 integer fields of which to get the
 797                                 signedness.
 798 @returns                        1 if the integer fields described by
 799                                 \p int_field_type are signed, 0 if they
 800                                 are unsigned, or a negative value on
 801                                 error.
 802
 803 @prenotnull{int_field_type}
 804 @preisintft{int_field_type}
 805 @postrefcountsame{int_field_type}
 806
 807 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
 808         integer fields described by a given integer field type.
 809 */
 810 extern int bt_ctf_field_type_integer_get_signed(
 811                 struct bt_ctf_field_type *int_field_type);
 812
 813 /**
 814 @brief  Sets whether or not the @intfields described by
 815         the @intft \p int_field_type are signed.
 816
 817 @param[in] int_field_type       Integer field type which describes the
 818                                 integer fields of which to set the
 819                                 signedness.
 820 @param[in] is_signed            Signedness of the integer fields
 821                                 described by \p int_field_type; 0 means
 822                                 \em unsigned, 1 means \em signed.
 823 @returns                        0 on success, or a negative value on error.
 824
 825 @prenotnull{int_field_type}
 826 @preisintft{int_field_type}
 827 @prehot{int_field_type}
 828 @pre \p is_signed is 0 or 1.
 829 @postrefcountsame{event_class}
 830
 831 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
 832         the integer fields described by a given integer field type.
 833 */
 834 extern int bt_ctf_field_type_integer_set_signed(
 835                 struct bt_ctf_field_type *int_field_type, int is_signed);
 836
 837 /**
 838 @brief  Returns the preferred display base (radix) of the @intfields
 839         described by the @intft \p int_field_type.
 840
 841 @param[in] int_field_type       Integer field type which describes the
 842                                 integer fields of which to get the
 843                                 preferred display base.
 844 @returns                        Preferred display base of the integer
 845                                 fields described by \p int_field_type,
 846                                 or #BT_CTF_INTEGER_BASE_UNKNOWN on
 847                                 error.
 848
 849 @prenotnull{int_field_type}
 850 @preisintft{int_field_type}
 851 @postrefcountsame{int_field_type}
 852
 853 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
 854         base of the integer fields described by a given integer field
 855         type.
 856 */
 857 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 858                 struct bt_ctf_field_type *int_field_type);
 859
 860 /**
 861 @brief  Sets the preferred display base (radix) of the @intfields
 862         described by the @intft \p int_field_type to \p base.
 863
 864 @param[in] int_field_type       Integer field type which describes the
 865                                 integer fields of which to set the
 866                                 preferred display base.
 867 @param[in] base                 Preferred display base of the integer
 868                                 fields described by \p int_field_type.
 869 @returns                        0 on success, or a negative value on error.
 870
 871 @prenotnull{int_field_type}
 872 @preisintft{int_field_type}
 873 @prehot{int_field_type}
 874 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
 875         #BT_CTF_INTEGER_BASE_DECIMAL, or
 876         #BT_CTF_INTEGER_BASE_HEXADECIMAL.
 877 @postrefcountsame{int_field_type}
 878
 879 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
 880         base of the integer fields described by a given
 881         integer field type.
 882 */
 883 extern int bt_ctf_field_type_integer_set_base(
 884                 struct bt_ctf_field_type *int_field_type,
 885                 enum bt_ctf_integer_base base);
 886
 887 /**
 888 @brief  Returns the encoding of the @intfields described by
 889         the @intft \p int_field_type.
 890
 891 @param[in] int_field_type       Integer field type which describes the
 892                                 integer fields of which to get the
 893                                 encoding.
 894 @returns                        Encoding of the integer
 895                                 fields described by \p int_field_type,
 896                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
 897                                 error.
 898
 899 @prenotnull{int_field_type}
 900 @preisintft{int_field_type}
 901 @postrefcountsame{int_field_type}
 902
 903 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
 904         of the integer fields described by a given integer field type.
 905 */
 906 extern enum bt_ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 907                 struct bt_ctf_field_type *int_field_type);
 908
 909 /**
 910 @brief  Sets the encoding of the @intfields described by the @intft
 911         \p int_field_type to \p encoding.
 912
 913 You can use this property, in CTF IR, to create "text" @arrayfts or
 914 @seqfts. A text array field type is array field type with an unsigned,
 915 8-bit integer field type having an encoding as its element field type.
 916
 917 @param[in] int_field_type       Integer field type which describes the
 918                                 integer fields of which to set the
 919                                 encoding.
 920 @param[in] encoding             Encoding of the integer
 921                                 fields described by \p int_field_type.
 922 @returns                        0 on success, or a negative value on error.
 923
 924 @prenotnull{int_field_type}
 925 @preisintft{int_field_type}
 926 @prehot{int_field_type}
 927 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
 928         #BT_CTF_STRING_ENCODING_ASCII, or
 929         #BT_CTF_STRING_ENCODING_UTF8.
 930 @postrefcountsame{int_field_type}
 931
 932 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
 933         the integer fields described by a given integer field type.
 934 */
 935 extern int bt_ctf_field_type_integer_set_encoding(
 936                 struct bt_ctf_field_type *int_field_type,
 937                 enum bt_ctf_string_encoding encoding);
 938
 939 /**
 940 @brief  Returns the \link ctfirclockclass CTF IR clock class\endlink
 941         mapped to the @intft \p int_field_type.
 942
 943 The mapped clock class, if any, indicates the class of the clock which
 944 an @intfield described by \p int_field_type should sample or update.
 945 This mapped clock class is only indicative.
 946
 947 @param[in] int_field_type       Integer field type of which to get the
 948                                 mapped clock class.
 949 @returns                        Mapped clock class of \p int_field_type,
 950                                 or \c NULL if there's no mapped clock
 951                                 class or on error.
 952
 953 @prenotnull{int_field_type}
 954 @preisintft{int_field_type}
 955 @postrefcountsame{int_field_type}
 956 @postsuccessrefcountretinc
 957
 958 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
 959         clock class of a given integer field type.
 960 */
 961 extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class(
 962                 struct bt_ctf_field_type *int_field_type);
 963
 964 /**
 965 @brief  Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
 966         to the @intft \p int_field_type to \p clock_class.
 967
 968 The mapped clock class, if any, indicates the class of the clock which
 969 an integer field described by \p int_field_type should sample or update.
 970 This mapped clock class is only indicative.
 971
 972 @param[in] int_field_type       Integer field type of which to set the
 973                                 mapped clock class.
 974 @param[in] clock_class          Mapped clock class of \p int_field_type.
 975 @returns                        0 on success, or a negative value on error.
 976
 977 @prenotnull{int_field_type}
 978 @prenotnull{clock_class}
 979 @preisintft{int_field_type}
 980 @prehot{int_field_type}
 981 @postrefcountsame{int_field_type}
 982 @postsuccessrefcountinc{clock_class}
 983
 984 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
 985         clock class of a given integer field type.
 986 */
 987 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
 988                 struct bt_ctf_field_type *int_field_type,
 989                 struct bt_ctf_clock_class *clock_class);
 990
 991 /** @} */
 992
 993 /**
 994 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
 995 @ingroup ctfirfieldtypes
 996 @brief CTF IR floating point number field type.
 997
 998 @code
 999 #include <babeltrace/ctf-ir/field-types.h>
1000 @endcode
1001
1002 A CTF IR <strong><em>floating point number field type</em></strong> is
1003 a field type that you can use to create concrete @floatfields.
1004
1005 You can create a floating point number field type
1006 with bt_ctf_field_type_floating_point_create().
1007
1008 A floating point number field type has the following properties:
1009
1010 <table>
1011   <tr>
1012     <th>Property
1013     <th>Value at creation
1014     <th>Getter
1015     <th>Setter
1016   </tr>
1017   <tr>
1018     <td>\b Alignment (bits) of the described floating point
1019         number fields
1020     <td>1
1021     <td>bt_ctf_field_type_get_alignment()
1022     <td>bt_ctf_field_type_set_alignment()
1023   </tr>
1024   <tr>
1025     <td><strong>Byte order</strong> of the described floating point
1026         number fields
1027     <td>#BT_CTF_BYTE_ORDER_NATIVE
1028     <td>bt_ctf_field_type_get_byte_order()
1029     <td>bt_ctf_field_type_set_byte_order()
1030   </tr>
1031   <tr>
1032     <td><strong>Exponent storage size</strong> (bits) of the described
1033         floating point number fields
1034     <td>8
1035     <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1036     <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1037   </tr>
1038   <tr>
1039     <td><strong>Mantissa and sign storage size</strong> (bits) of the
1040         described floating point number fields
1041     <td>24 (23-bit mantissa, 1-bit sign)
1042     <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1043     <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1044   </tr>
1045 </table>
1046
1047 @sa ctfirfloatfield
1048 @sa ctfirfieldtypes
1049
1050 @addtogroup ctfirfloatfieldtype
1051 @{
1052 */
1053
1054 /**
1055 @brief  Creates a default @floatft.
1056
1057 @returns        Created floating point number field type,
1058                 or \c NULL on error.
1059
1060 @postsuccessrefcountret1
1061 */
1062 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
1063
1064 /**
1065 @brief  Returns the exponent storage size of the @floatfields
1066         described by the @floatft \p float_field_type.
1067
1068 @param[in] float_field_type     Floating point number field type which
1069                                 describes the floating point number
1070                                 fields of which to get the exponent
1071                                 storage size.
1072 @returns                        Exponent storage size of the
1073                                 floating point number fields
1074                                 described by \p float_field_type,
1075                                 or a negative value on error.
1076
1077 @prenotnull{float_field_type}
1078 @preisfloatft{float_field_type}
1079 @postrefcountsame{float_field_type}
1080
1081 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1082         exponent storage size of the floating point number fields
1083         described by a given floating point number field type.
1084 */
1085 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1086                 struct bt_ctf_field_type *float_field_type);
1087
1088 /**
1089 @brief  Sets the exponent storage size of the @floatfields described by
1090         the @floatft \p float_field_type to \p exponent_size.
1091
1092 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1093
1094 @param[in] float_field_type     Floating point number field type which
1095                                 describes the floating point number
1096                                 fields of which to set the exponent
1097                                 storage size.
1098 @param[in] exponent_size        Exponent storage size of the floating
1099                                 point number fields described by \p
1100                                 float_field_type.
1101 @returns                        0 on success, or a negative value on error.
1102
1103 @prenotnull{float_field_type}
1104 @preisfloatft{float_field_type}
1105 @prehot{float_field_type}
1106 @pre \p exponent_size is 8 or 11.
1107 @postrefcountsame{float_field_type}
1108
1109 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1110         exponent storage size of the floating point number fields
1111         described by a given floating point number field type.
1112 */
1113 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1114                 struct bt_ctf_field_type *float_field_type,
1115                 unsigned int exponent_size);
1116
1117 /**
1118 @brief  Returns the mantissa and sign storage size of the @floatfields
1119         described by the @floatft \p float_field_type.
1120
1121 On success, the returned value is the sum of the mantissa \em and
1122 sign storage sizes.
1123
1124 @param[in] float_field_type     Floating point number field type which
1125                                 describes the floating point number
1126                                 fields of which to get the mantissa and
1127                                 sign storage size.
1128 @returns                        Mantissa and sign storage size of the
1129                                 floating point number fields
1130                                 described by \p float_field_type,
1131                                 or a negative value on error.
1132
1133 @prenotnull{float_field_type}
1134 @preisfloatft{float_field_type}
1135 @postrefcountsame{float_field_type}
1136
1137 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1138         mantissa and size storage size of the floating point number
1139         fields described by a given floating point number field type.
1140 */
1141 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1142                 struct bt_ctf_field_type *float_field_type);
1143
1144 /**
1145 @brief  Sets the mantissa and sign storage size of the @floatfields
1146         described by the @floatft \p float_field_type to \p
1147         mantissa_sign_size.
1148
1149 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1150
1151 @param[in] float_field_type     Floating point number field type which
1152                                 describes the floating point number
1153                                 fields of which to set the mantissa and
1154                                 sign storage size.
1155 @param[in] mantissa_sign_size   Mantissa and sign storage size of the
1156                                 floating point number fields described
1157                                 by \p float_field_type.
1158 @returns                        0 on success, or a negative value on error.
1159
1160 @prenotnull{float_field_type}
1161 @preisfloatft{float_field_type}
1162 @prehot{float_field_type}
1163 @pre \p mantissa_sign_size is 24 or 53.
1164 @postrefcountsame{float_field_type}
1165
1166 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1167         mantissa and sign storage size of the floating point number
1168         fields described by a given floating point number field type.
1169 */
1170 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1171                 struct bt_ctf_field_type *float_field_type,
1172                 unsigned int mantissa_sign_size);
1173
1174 /** @} */
1175
1176 /**
1177 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1178 @ingroup ctfirfieldtypes
1179 @brief CTF IR enumeration field type.
1180
1181 @code
1182 #include <babeltrace/ctf-ir/field-types.h>
1183 @endcode
1184
1185 A CTF IR <strong><em>enumeration field type</em></strong> is
1186 a field type that you can use to create concrete @enumfields.
1187
1188 You can create an enumeration field type with
1189 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1190 which represents the storage field type of the created enumeration field
1191 type. In other words, an enumeration field type wraps an integer field
1192 type and adds label-value mappings to it.
1193
1194 An enumeration mapping has:
1195
1196 - A <strong>name</strong>.
1197 - A <strong>range of values</strong> given by a beginning and an ending
1198   value, both included in the range.
1199
1200 You can add a mapping to an enumeration field type with
1201 bt_ctf_field_type_enumeration_add_mapping() or
1202 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1203 signedness of the wrapped @intft.
1204
1205 Many mappings can share the same name, but the ranges of a given
1206 enumeration field type <strong>must not overlap</strong>. For example,
1207 this is a valid set of mappings:
1208
1209 @verbatim
1210 APPLE  -> [  3, 19]
1211 BANANA -> [-15,  1]
1212 CHERRY -> [ 25, 34]
1213 APPLE  -> [ 55, 55]
1214 @endverbatim
1215
1216 The following set of mappings is \em not valid, however:
1217
1218 @verbatim
1219 APPLE  -> [  3, 19]
1220 BANANA -> [-15,  1]
1221 CHERRY -> [ 25, 34]
1222 APPLE  -> [ 30, 55]
1223 @endverbatim
1224
1225 Here, the range of the second \c APPLE mapping overlaps the range of
1226 the \c CHERRY mapping.
1227
1228 @sa ctfirenumfield
1229 @sa ctfirfieldtypes
1230
1231 @addtogroup ctfirenumfieldtype
1232 @{
1233 */
1234
1235 /**
1236 @brief  Creates a default @enumft wrapping the @intft \p int_field_type.
1237
1238 @param[in] int_field_type       Integer field type wrapped by the
1239                                 created enumeration field type.
1240 @returns                        Created enumeration field type,
1241                                 or \c NULL on error.
1242
1243 @prenotnull{int_field_type}
1244 @preisintft{int_field_type}
1245 @postsuccessrefcountinc{int_field_type}
1246 @postsuccessrefcountret1
1247 */
1248 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
1249                 struct bt_ctf_field_type *int_field_type);
1250
1251 /**
1252 @brief  Returns the @intft wrapped by the @enumft \p enum_field_type.
1253
1254 @param[in] enum_field_type      Enumeration field type of which to get
1255                                 the wrapped integer field type.
1256 @returns                        Integer field type wrapped by
1257                                 \p enum_field_type, or \c NULL on
1258                                 error.
1259
1260 @prenotnull{enum_field_type}
1261 @preisenumft{enum_field_type}
1262 @postrefcountsame{enum_field_type}
1263 @postsuccessrefcountretinc
1264 */
1265 extern
1266 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
1267                 struct bt_ctf_field_type *enum_field_type);
1268
1269 /**
1270 @brief  Returns the number of mappings contained in the
1271         @enumft \p enum_field_type.
1272
1273 @param[in] enum_field_type      Enumeration field type of which to get
1274                                 the number of contained mappings.
1275 @returns                        Number of mappings contained in
1276                                 \p enum_field_type, or a negative
1277                                 value on error.
1278
1279 @prenotnull{enum_field_type}
1280 @preisenumft{enum_field_type}
1281 @postrefcountsame{enum_field_type}
1282 */
1283 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1284                 struct bt_ctf_field_type *enum_field_type);
1285
1286 /**
1287 @brief  Returns the signed mapping of the @enumft
1288         \p enum_field_type at index \p index.
1289
1290 The @intft wrapped by \p enum_field_type, as returned by
1291 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1292 to use this function.
1293
1294 On success, \p enum_field_type remains the sole owner of \p *name.
1295
1296 @param[in] enum_field_type      Enumeration field type of which to get
1297                                 the mapping at index \p index.
1298 @param[in] index              Index of the mapping to get from
1299                                 \p enum_field_type.
1300 @param[out] name                Returned name of the mapping at index
1301                                 \p index.
1302 @param[out] range_begin         Returned beginning of the range
1303                                 (included) of the mapping at index \p
1304                                 index.
1305 @param[out] range_end           Returned end of the range (included) of
1306                                 the mapping at index \p index.
1307 @returns                        0 on success, or a negative value on error.
1308
1309 @prenotnull{enum_field_type}
1310 @prenotnull{name}
1311 @prenotnull{range_begin}
1312 @prenotnull{range_end}
1313 @preisenumft{enum_field_type}
1314 @pre The wrapped @intft of \p enum_field_type is signed.
1315 @pre \p index is lesser than the number of mappings contained in the
1316         enumeration field type \p enum_field_type (see
1317         bt_ctf_field_type_enumeration_get_mapping_count()).
1318 @postrefcountsame{enum_field_type}
1319
1320 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1321         unsigned mapping contained by a given enumeration field type
1322         at a given index.
1323 */
1324 extern int bt_ctf_field_type_enumeration_get_mapping(
1325                 struct bt_ctf_field_type *enum_field_type, int index,
1326                 const char **name, int64_t *range_begin, int64_t *range_end);
1327
1328 /**
1329 @brief  Returns the unsigned mapping of the @enumft
1330         \p enum_field_type at index \p index.
1331
1332 The @intft wrapped by \p enum_field_type, as returned by
1333 bt_ctf_field_type_enumeration_get_container_type(), must be
1334 \b unsigned to use this function.
1335
1336 On success, \p enum_field_type remains the sole owner of \p *name.
1337
1338 @param[in] enum_field_type      Enumeration field type of which to get
1339                                 the mapping at index \p index.
1340 @param[in] index              Index of the mapping to get from
1341                                 \p enum_field_type.
1342 @param[out] name                Returned name of the mapping at index
1343                                 \p index.
1344 @param[out] range_begin         Returned beginning of the range
1345                                 (included) of the mapping at index \p
1346                                 index.
1347 @param[out] range_end           Returned end of the range (included) of
1348                                 the mapping at index \p index.
1349 @returns                        0 on success, or a negative value on error.
1350
1351 @prenotnull{enum_field_type}
1352 @prenotnull{name}
1353 @prenotnull{range_begin}
1354 @prenotnull{range_end}
1355 @preisenumft{enum_field_type}
1356 @pre The wrapped @intft of \p enum_field_type is unsigned.
1357 @pre \p index is lesser than the number of mappings contained in the
1358         enumeration field type \p enum_field_type (see
1359         bt_ctf_field_type_enumeration_get_mapping_count()).
1360 @postrefcountsame{enum_field_type}
1361
1362 @sa bt_ctf_field_type_enumeration_get_mapping(): Returns the
1363         signed mapping contained by a given enumeration field type
1364         at a given index.
1365 */
1366 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1367                 struct bt_ctf_field_type *enum_field_type, int index,
1368                 const char **name, uint64_t *range_begin,
1369                 uint64_t *range_end);
1370
1371 /** @cond DOCUMENT */
1372 /*
1373  * TODO: Document once we know what to do with this function (return
1374  *       the first match?).
1375  */
1376 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
1377                 struct bt_ctf_field_type *enum_field_type, const char *name);
1378 /** @endcond */
1379
1380 /**
1381 @brief  Returns the index of the signed mapping of the @enumft
1382         \p field_type which contains the value \p value.
1383
1384 The @intft wrapped by \p enum_field_type, as returned by
1385 bt_ctf_field_type_enumeration_get_container_type(), must be
1386 \b signed to use this function.
1387
1388 @param[in] enum_field_type      Enumeration field type of which to get
1389                                 the index of the mapping which contains
1390                                 \p value.
1391 @param[in] value                Value of the mapping to find.
1392 @returns                        Index of the mapping of
1393                                 \p enum_field_type which contains
1394                                 \p value, or a negative value if the
1395                                 function cannot find such a mapping or
1396                                 on error.
1397
1398 @prenotnull{enum_field_type}
1399 @preisenumft{enum_field_type}
1400 @pre The wrapped @intft of \p enum_field_type is signed.
1401 @postrefcountsame{enum_field_type}
1402
1403 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1404         Finds the index of an unsigned mapping of a given enumeration
1405         field type by value.
1406 */
1407 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
1408                 struct bt_ctf_field_type *enum_field_type, int64_t value);
1409
1410 /**
1411 @brief  Returns the index of the unsigned mapping of the @enumft
1412         \p field_type which contains the value \p value.
1413
1414 The @intft wrapped by \p enum_field_type, as returned by
1415 bt_ctf_field_type_enumeration_get_container_type(), must be
1416 \b unsigned to use this function.
1417
1418 @param[in] enum_field_type      Enumeration field type of which to get
1419                                 the index of the mapping which contains
1420                                 \p value.
1421 @param[in] value                Value of the mapping to find.
1422 @returns                        Index of the mapping of
1423                                 \p enum_field_type which contains
1424                                 \p value, or a negative value if the
1425                                 function cannot find such a mapping or
1426                                 on error.
1427
1428 @prenotnull{enum_field_type}
1429 @preisenumft{enum_field_type}
1430 @pre The wrapped @intft of \p enum_field_type is unsigned.
1431 @postrefcountsame{enum_field_type}
1432
1433 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1434         Finds the index of a signed mapping of a given enumeration
1435         field type by value.
1436 */
1437 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
1438                 struct bt_ctf_field_type *enum_field_type, uint64_t value);
1439
1440 /**
1441 @brief  Adds a mapping to the @enumft \p enum_field_type which maps the
1442         name \p name to the signed range \p range_begin (included) to
1443         \p range_end (included).
1444
1445 Make \p range_begin and \p range_end the same value to add a mapping
1446 to a single value.
1447
1448 The @intft wrapped by \p enum_field_type, as returned by
1449 bt_ctf_field_type_enumeration_get_container_type(), must be
1450 \b signed to use this function.
1451
1452 A mapping in \p enum_field_type can exist with the name \p name, but
1453 there must be no overlap amongst all the ranges of
1454 \p enum_field_type.
1455
1456 @param[in] enum_field_type      Enumeration field type to which to add
1457                                 a mapping.
1458 @param[in] name                 Name of the mapping to add (copied
1459                                 on success).
1460 @param[in] range_begin          Beginning of the range of the mapping
1461                                 (included).
1462 @param[in] range_end            End of the range of the mapping
1463                                 (included).
1464 @returns                        0 on success, or a negative value on error.
1465
1466 @prenotnull{enum_field_type}
1467 @prenotnull{name}
1468 @preisenumft{enum_field_type}
1469 @pre The wrapped @intft of \p enum_field_type is signed.
1470 @pre \p range_end is greater than or equal to \p range_begin.
1471 @postrefcountsame{enum_field_type}
1472
1473 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1474         unsigned mapping to a given enumeration field type.
1475 */
1476 extern int bt_ctf_field_type_enumeration_add_mapping(
1477                 struct bt_ctf_field_type *enum_field_type, const char *name,
1478                 int64_t range_begin, int64_t range_end);
1479
1480 /**
1481 @brief  Adds a mapping to the @enumft \p enum_field_type which maps
1482         the name \p name to the unsigned
1483         range \p range_begin (included) to \p range_end (included).
1484
1485 Make \p range_begin and \p range_end the same value to add a mapping
1486 to a single value.
1487
1488 The @intft wrapped by \p enum_field_type, as returned by
1489 bt_ctf_field_type_enumeration_get_container_type(), must be
1490 \b unsigned to use this function.
1491
1492 A mapping in \p enum_field_type can exist with the name \p name, but
1493 there must be no overlap amongst all the ranges of
1494 \p enum_field_type.
1495
1496 @param[in] enum_field_type      Enumeration field type to which to add
1497                                 a mapping.
1498 @param[in] name                 Name of the mapping to add (copied
1499                                 on success).
1500 @param[in] range_begin          Beginning of the range of the mapping
1501                                 (included).
1502 @param[in] range_end            End of the range of the mapping
1503                                 (included).
1504 @returns                        0 on success, or a negative value on error.
1505
1506 @prenotnull{enum_field_type}
1507 @prenotnull{name}
1508 @preisenumft{enum_field_type}
1509 @pre The wrapped @intft of \p enum_field_type is unsigned.
1510 @pre \p range_end is greater than or equal to \p range_begin.
1511 @postrefcountsame{enum_field_type}
1512
1513 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1514         mapping to a given enumeration field type.
1515 */
1516 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1517                 struct bt_ctf_field_type *enum_field_type, const char *name,
1518                 uint64_t range_begin, uint64_t range_end);
1519
1520 /** @} */
1521
1522 /**
1523 @defgroup ctfirstringfieldtype CTF IR string field type
1524 @ingroup ctfirfieldtypes
1525 @brief CTF IR string field type.
1526
1527 @code
1528 #include <babeltrace/ctf-ir/field-types.h>
1529 @endcode
1530
1531 A CTF IR <strong><em>string field type</em></strong> is a field type that
1532 you can use to create concrete @stringfields.
1533
1534 You can create a string field type
1535 with bt_ctf_field_type_string_create().
1536
1537 A string field type has only one property: the \b encoding of its
1538 described @stringfields. By default, the encoding of the string fields
1539 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1540 can set the encoding of the string fields described by a string field
1541 type with bt_ctf_field_type_string_set_encoding().
1542
1543 @sa ctfirstringfield
1544 @sa ctfirfieldtypes
1545
1546 @addtogroup ctfirstringfieldtype
1547 @{
1548 */
1549
1550 /**
1551 @brief  Creates a default @stringft.
1552
1553 @returns        Created string field type, or \c NULL on error.
1554
1555 @postsuccessrefcountret1
1556 */
1557 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
1558
1559 /**
1560 @brief  Returns the encoding of the @stringfields described by
1561         the @stringft \p string_field_type.
1562
1563 @param[in] string_field_type    String field type which describes the
1564                                 string fields of which to get the
1565                                 encoding.
1566 @returns                        Encoding of the string
1567                                 fields described by \p string_field_type,
1568                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1569                                 error.
1570
1571 @prenotnull{string_field_type}
1572 @preisstringft{string_field_type}
1573 @postrefcountsame{string_field_type}
1574
1575 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1576         of the string fields described by a given string field type.
1577 */
1578 extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding(
1579                 struct bt_ctf_field_type *string_field_type);
1580
1581 /**
1582 @brief  Sets the encoding of the @stringfields described by the
1583         @stringft \p string_field_type to \p encoding.
1584
1585 @param[in] string_field_type    String field type which describes the
1586                                 string fields of which to set the
1587                                 encoding.
1588 @param[in] encoding             Encoding of the string fields described
1589                                 by \p string_field_type.
1590 @returns                        0 on success, or a negative value on error.
1591
1592 @prenotnull{string_field_type}
1593 @preisstringft{string_field_type}
1594 @prehot{string_field_type}
1595 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1596         #BT_CTF_STRING_ENCODING_UTF8.
1597 @postrefcountsame{string_field_type}
1598
1599 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1600         the string fields described by a given string field type.
1601 */
1602 extern int bt_ctf_field_type_string_set_encoding(
1603                 struct bt_ctf_field_type *string_field_type,
1604                 enum bt_ctf_string_encoding encoding);
1605
1606 /** @} */
1607
1608 /**
1609 @defgroup ctfirstructfieldtype CTF IR structure field type
1610 @ingroup ctfirfieldtypes
1611 @brief CTF IR structure field type.
1612
1613 @code
1614 #include <babeltrace/ctf-ir/field-types.h>
1615 @endcode
1616
1617 A CTF IR <strong><em>structure field type</em></strong> is
1618 a field type that you can use to create concrete @structfields.
1619
1620 You can create a structure field type
1621 with bt_ctf_field_type_structure_create(). This function creates
1622 an empty structure field type, with no fields.
1623
1624 You can add a field to a structure field type with
1625 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1626 field type cannot have the same name.
1627
1628 You can set the \em minimum alignment of the structure fields described
1629 by a structure field type with the common
1630 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1631 of the structure fields described by a structure field type, as per
1632 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1633 the effective alignments of all its fields. Note that the effective
1634 alignment of @varfields is always 1.
1635
1636 You can set the byte order of <em>all the contained fields</em>,
1637 recursively, of a structure field type with the common
1638 bt_ctf_field_type_set_byte_order() function.
1639
1640 @sa ctfirstructfield
1641 @sa ctfirfieldtypes
1642
1643 @addtogroup ctfirstructfieldtype
1644 @{
1645 */
1646
1647 /**
1648 @brief  Creates a default, empty @structft.
1649
1650 @returns                        Created structure field type,
1651                                 or \c NULL on error.
1652
1653 @postsuccessrefcountret1
1654 */
1655 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
1656
1657 /**
1658 @brief  Returns the number of fields contained in the
1659         @structft \p struct_field_type.
1660
1661 @param[in] struct_field_type    Structure field type of which to get
1662                                 the number of contained fields.
1663 @returns                        Number of fields contained in
1664                                 \p struct_field_type, or a negative
1665                                 value on error.
1666
1667 @prenotnull{struct_field_type}
1668 @preisstructft{struct_field_type}
1669 @postrefcountsame{struct_field_type}
1670 */
1671 extern int bt_ctf_field_type_structure_get_field_count(
1672                 struct bt_ctf_field_type *struct_field_type);
1673
1674 /**
1675 @brief  Returns the field of the @structft \p struct_field_type
1676         at index \p index.
1677
1678 On success, the field's type is placed in \p *field_type if
1679 \p field_type is not \c NULL. The field's name is placed in
1680 \p *field_name if \p field_name is not \c NULL.
1681 \p struct_field_type remains the sole owner of \p *field_name.
1682
1683 @param[in] struct_field_type    Structure field type of which to get
1684                                 the field at index \p index.
1685 @param[out] field_name          Returned name of the field at index
1686                                 \p index (can be \c NULL).
1687 @param[out] field_type          Returned field type of the field
1688                                 at index \p index (can be \c NULL).
1689 @param[in] index              Index of the field to get from
1690                                 \p struct_field_type.
1691 @returns                        0 on success, or a negative value on error.
1692
1693 @prenotnull{struct_field_type}
1694 @preisstructft{struct_field_type}
1695 @pre \p index is lesser than the number of fields contained in the
1696         structure field type \p struct_field_type (see
1697         bt_ctf_field_type_structure_get_field_count()).
1698 @postrefcountsame{struct_field_type}
1699 @post <strong>On success</strong>, the returned field's type is placed
1700         in \p *field_type and its reference count is incremented.
1701
1702 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1703         structure field type's field by name.
1704 */
1705 extern int bt_ctf_field_type_structure_get_field(
1706                 struct bt_ctf_field_type *struct_field_type,
1707                 const char **field_name, struct bt_ctf_field_type **field_type,
1708                 int index);
1709
1710 /**
1711 @brief  Returns the type of the field named \p field_name found in
1712         the @structft \p struct_field_type.
1713
1714 @param[in] struct_field_type    Structure field type of which to get
1715                                 a field's type.
1716 @param[in] field_name           Name of the field to find.
1717 @returns                        Type of the field named \p field_name in
1718                                 \p struct_field_type, or
1719                                 \c NULL on error.
1720
1721 @prenotnull{struct_field_type}
1722 @prenotnull{field_name}
1723 @preisstructft{struct_field_type}
1724 @postrefcountsame{struct_field_type}
1725 @postsuccessrefcountretinc
1726
1727 @sa bt_ctf_field_type_structure_get_field(): Finds a
1728         structure field type's field by index.
1729 */
1730 extern
1731 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
1732                 struct bt_ctf_field_type *struct_field_type,
1733                 const char *field_name);
1734
1735 /**
1736 @brief  Adds a field named \p field_name with the @ft
1737         \p field_type to the @structft \p struct_field_type.
1738
1739 On success, \p field_type becomes the child of \p struct_field_type.
1740
1741 This function adds the new field after the current last field of
1742 \p struct_field_type (append mode).
1743
1744 You \em cannot add a field named \p field_name if there's already a
1745 field named \p field_name in \p struct_field_type.
1746
1747 @param[in] struct_field_type    Structure field type to which to add
1748                                 a new field.
1749 @param[in] field_type           Field type of the field to add to
1750                                 \p struct_field_type.
1751 @param[in] field_name           Name of the field to add to
1752                                 \p struct_field_type
1753                                 (copied on success).
1754 @returns                        0 on success, or a negative value on error.
1755
1756 @prenotnull{struct_field_type}
1757 @prenotnull{field_type}
1758 @prenotnull{field_name}
1759 @preisstructft{struct_field_type}
1760 @pre \p field_type is not and does not contain \p struct_field_type,
1761         recursively, as a field's type.
1762 @prehot{struct_field_type}
1763 @postrefcountsame{struct_field_type}
1764 @postsuccessrefcountinc{field_type}
1765 */
1766 extern int bt_ctf_field_type_structure_add_field(
1767                 struct bt_ctf_field_type *struct_field_type,
1768                 struct bt_ctf_field_type *field_type,
1769                 const char *field_name);
1770
1771 /** @} */
1772
1773 /**
1774 @defgroup ctfirarrayfieldtype CTF IR array field type
1775 @ingroup ctfirfieldtypes
1776 @brief CTF IR array field type.
1777
1778 @code
1779 #include <babeltrace/ctf-ir/field-types.h>
1780 @endcode
1781
1782 A CTF IR <strong><em>array field type</em></strong> is a field type that
1783 you can use to create concrete @arrayfields.
1784
1785 You can create an array field type
1786 with bt_ctf_field_type_array_create(). This function needs
1787 the @ft of the fields contained by the array fields described by the
1788 array field type to create.
1789
1790 @sa ctfirarrayfield
1791 @sa ctfirfieldtypes
1792
1793 @addtogroup ctfirarrayfieldtype
1794 @{
1795 */
1796
1797 /**
1798 @brief  Creates a default @arrayft with
1799         \p element_field_type as the field type of the fields contained
1800         in its described @arrayfields of length \p length.
1801
1802 @param[in] element_field_type   Field type of the fields contained in
1803                                 the array fields described by the
1804                                 created array field type.
1805 @param[in] length               Length of the array fields described by
1806                                 the created array field type.
1807 @returns                        Created array field type, or
1808                                 \c NULL on error.
1809
1810 @prenotnull{element_field_type}
1811 @postsuccessrefcountinc{element_field_type}
1812 @postsuccessrefcountret1
1813 */
1814 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
1815                 struct bt_ctf_field_type *element_field_type,
1816                 unsigned int length);
1817
1818 /**
1819 @brief  Returns the @ft of the @fields contained in
1820         the @arrayfields described by the @arrayft \p array_field_type.
1821
1822 @param[in] array_field_type     Array field type of which to get
1823                                 the type of the fields contained in its
1824                                 described array fields.
1825 @returns                        Type of the fields contained in the
1826                                 array fields described by
1827                                 \p array_field_type, or \c NULL
1828                                 on error.
1829
1830 @prenotnull{array_field_type}
1831 @preisarrayft{array_field_type}
1832 @postrefcountsame{array_field_type}
1833 @postsuccessrefcountretinc
1834 */
1835 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
1836                 struct bt_ctf_field_type *array_field_type);
1837
1838 /**
1839 @brief  Returns the number of @fields contained in the
1840         @arrayfields described by the @arrayft \p array_field_type.
1841
1842 @param[in] array_field_type     Array field type of which to get
1843                                 the number of fields contained in its
1844                                 described array fields.
1845 @returns                        Number of fields contained in the
1846                                 array fields described by
1847                                 \p array_field_type, or a negative value
1848                                 on error.
1849
1850 @prenotnull{array_field_type}
1851 @preisarrayft{array_field_type}
1852 @postrefcountsame{array_field_type}
1853 */
1854 extern int64_t bt_ctf_field_type_array_get_length(
1855                 struct bt_ctf_field_type *array_field_type);
1856
1857 /** @} */
1858
1859 /**
1860 @defgroup ctfirseqfieldtype CTF IR sequence field type
1861 @ingroup ctfirfieldtypes
1862 @brief CTF IR sequence field type.
1863
1864 @code
1865 #include <babeltrace/ctf-ir/field-types.h>
1866 @endcode
1867
1868 A CTF IR <strong><em>sequence field type</em></strong> is
1869 a field type that you can use to create concrete @seqfields.
1870
1871 You can create a sequence field type with
1872 bt_ctf_field_type_sequence_create(). This function needs the @ft
1873 of the fields contained by the sequence fields described by the created
1874 sequence field type. This function also needs the length name of the
1875 sequence field type to create. The length name is used to automatically
1876 resolve the length's field type. See \ref ctfirfieldtypes to learn more
1877 about the automatic resolving.
1878
1879 @sa ctfirseqfield
1880 @sa ctfirfieldtypes
1881
1882 @addtogroup ctfirseqfieldtype
1883 @{
1884 */
1885
1886 /**
1887 @brief  Creates a default @seqft with \p element_field_type as the
1888         @ft of the @fields contained in its described @seqfields
1889         with the length name \p length_name.
1890
1891 \p length_name can be an absolute or relative reference. See
1892 <a href="http://diamon.org/ctf/">CTF</a> for more details.
1893
1894 @param[in] element_field_type   Field type of the fields contained in
1895                                 the sequence fields described by the
1896                                 created sequence field type.
1897 @param[in] length_name          Length name (copied on success).
1898 @returns                        Created array field type, or
1899                                 \c NULL on error.
1900
1901 @prenotnull{element_field_type}
1902 @prenotnull{length_name}
1903 @postsuccessrefcountinc{element_field_type}
1904 @postsuccessrefcountret1
1905 */
1906 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
1907                 struct bt_ctf_field_type *element_field_type,
1908                 const char *length_name);
1909
1910 /**
1911 @brief  Returns the @ft of the @fields contained in the @seqft
1912         described by the @seqft \p sequence_field_type.
1913
1914 @param[in] sequence_field_type  Sequence field type of which to get
1915                                 the type of the fields contained in its
1916                                 described sequence fields.
1917 @returns                        Type of the fields contained in the
1918                                 sequence fields described by
1919                                 \p sequence_field_type, or \c NULL
1920                                 on error.
1921
1922 @prenotnull{sequence_field_type}
1923 @preisseqft{sequence_field_type}
1924 @postrefcountsame{sequence_field_type}
1925 @postsuccessrefcountretinc
1926 */
1927 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
1928                 struct bt_ctf_field_type *sequence_field_type);
1929
1930 /**
1931 @brief  Returns the length name of the @seqft \p sequence_field_type.
1932
1933 On success, \p sequence_field_type remains the sole owner of
1934 the returned string.
1935
1936 @param[in] sequence_field_type  Sequence field type of which to get the
1937                                 length name.
1938 @returns                        Length name of \p sequence_field_type,
1939                                 or \c NULL on error.
1940
1941 @prenotnull{sequence_field_type}
1942 @preisseqft{sequence_field_type}
1943
1944 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
1945         length's CTF IR field path of a given sequence field type.
1946 */
1947 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
1948                 struct bt_ctf_field_type *sequence_field_type);
1949
1950 /**
1951 @brief  Returns the length's CTF IR field path of the @seqft
1952         \p sequence_field_type.
1953
1954 The length's field path of a sequence field type is set when automatic
1955 resolving is performed (see \ref ctfirfieldtypes).
1956
1957 @param[in] sequence_field_type  Sequence field type of which to get the
1958                                 length's field path.
1959 @returns                        Length's field path of
1960                                 \p sequence_field_type, or
1961                                 \c NULL if the length's field path is
1962                                 not set yet is not set or on error.
1963
1964 @prenotnull{sequence_field_type}
1965 @preisseqft{sequence_field_type}
1966 @postsuccessrefcountretinc
1967
1968 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
1969         length's name of a given sequence field type.
1970 */
1971 extern struct bt_ctf_field_path *bt_ctf_field_type_sequence_get_length_field_path(
1972                 struct bt_ctf_field_type *sequence_field_type);
1973
1974 /** @} */
1975
1976 /**
1977 @defgroup ctfirvarfieldtype CTF IR variant field type
1978 @ingroup ctfirfieldtypes
1979 @brief CTF IR variant field type.
1980
1981 @code
1982 #include <babeltrace/ctf-ir/field-types.h>
1983 @endcode
1984
1985 A CTF IR <strong><em>variant field type</em></strong> is
1986 a field type that you can use to create concrete @varfields.
1987
1988 You can create a variant field type with
1989 bt_ctf_field_type_variant_create(). This function expects you to pass
1990 both the tag's @enumft and the tag name of the variant field type to
1991 create. The tag's field type is optional, as the Babeltrace system can
1992 automatically resolve it using the tag name. You can leave the tag name
1993 to \c NULL initially, and set it later with
1994 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
1995 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
1996 about the automatic resolving and the conditions under which a field
1997 type can be frozen.
1998
1999 You can add a field to a variant field type with
2000 bt_ctf_field_type_variant_add_field(). All the field names of a
2001 variant field type \em must exist as mapping names in its tag's @enumft.
2002
2003 The effective alignment of the @varfields described by a
2004 variant field type is always 1, but the individual fields of a
2005 @varfield can have custom alignments.
2006
2007 You can set the byte order of <em>all the contained fields</em>,
2008 recursively, of a variant field type with the common
2009 bt_ctf_field_type_set_byte_order() function.
2010
2011 @sa ctfirvarfield
2012 @sa ctfirfieldtypes
2013
2014 @addtogroup ctfirvarfieldtype
2015 @{
2016 */
2017
2018 /**
2019 @brief  Creates a default, empty @varft with the tag's @enumft
2020         \p tag_field_type and the tag name \p tag_name.
2021
2022 \p tag_field_type can be \c NULL; the tag's field type can be
2023 automatically resolved from the variant field type's tag name (see
2024 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2025 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2026 field type is frozen.
2027
2028 \p tag_name can be an absolute or relative reference. See
2029 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2030
2031 @param[in] tag_field_type       Tag's enumeration field type
2032                                 (can be \c NULL).
2033 @param[in] tag_name             Tag name (copied on success,
2034                                 can be \c NULL).
2035 @returns                        Created variant field type, or
2036                                 \c NULL on error.
2037
2038 @pre \p tag_field_type is an enumeration field type or \c NULL.
2039 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2040         its reference count is incremented.
2041 @postsuccessrefcountret1
2042 */
2043 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
2044                 struct bt_ctf_field_type *tag_field_type,
2045                 const char *tag_name);
2046
2047 /**
2048 @brief  Returns the tag's @enumft of the @varft \p variant_field_type.
2049
2050 @param[in] variant_field_type   Variant field type of which to get
2051                                 the tag's enumeration field type.
2052 @returns                        Tag's enumeration field type of
2053                                 \p variant_field_type, or \c NULL if the
2054                                 tag's field type is not set or on
2055                                 error.
2056
2057 @prenotnull{variant_field_type}
2058 @preisvarft{variant_field_type}
2059 @postrefcountsame{variant_field_type}
2060 @postsuccessrefcountretinc
2061 */
2062 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
2063                 struct bt_ctf_field_type *variant_field_type);
2064
2065 /**
2066 @brief  Returns the tag name of the @varft \p variant_field_type.
2067
2068 On success, \p variant_field_type remains the sole owner of
2069 the returned string.
2070
2071 @param[in] variant_field_type   Variant field type of which to get the
2072                                 tag name.
2073 @returns                        Tag name of \p variant_field_type, or
2074                                 \c NULL if the tag name is not set or
2075                                 on error.
2076
2077 @prenotnull{variant_field_type}
2078 @preisvarft{variant_field_type}
2079
2080 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2081         a given variant field type.
2082 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2083         CTF IR field path of a given variant field type.
2084 */
2085 extern const char *bt_ctf_field_type_variant_get_tag_name(
2086                 struct bt_ctf_field_type *variant_field_type);
2087
2088 /**
2089 @brief  Sets the tag name of the @varft \p variant_field_type.
2090
2091 \p tag_name can be an absolute or relative reference. See
2092 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2093
2094 @param[in] variant_field_type   Variant field type of which to set
2095                                 the tag name.
2096 @param[in] tag_name             Tag name of \p variant_field_type
2097                                 (copied on success).
2098 @returns                        0 on success, or a negative value on error.
2099
2100 @prenotnull{variant_field_type}
2101 @prenotnull{name}
2102 @prehot{variant_field_type}
2103 @postrefcountsame{variant_field_type}
2104
2105 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2106         a given variant field type.
2107 */
2108 extern int bt_ctf_field_type_variant_set_tag_name(
2109                 struct bt_ctf_field_type *variant_field_type,
2110                 const char *tag_name);
2111
2112 /**
2113 @brief  Returns the tag's CTF IR field path of the @varft
2114         \p variant_field_type.
2115
2116 The tag's field path of a variant field type is set when automatic
2117 resolving is performed (see \ref ctfirfieldtypes).
2118
2119 @param[in] variant_field_type   Variant field type of which to get the
2120                                 tag's field path.
2121 @returns                        Tag's field path of
2122                                 \p variant_field_type, or
2123                                 \c NULL if the tag's field path is not
2124                                 set yet is not set or on error.
2125
2126 @prenotnull{variant_field_type}
2127 @preisvarft{variant_field_type}
2128 @postsuccessrefcountretinc
2129
2130 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2131         name of a given variant field type.
2132 */
2133 extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path(
2134                 struct bt_ctf_field_type *variant_field_type);
2135
2136 /**
2137 @brief  Returns the number of fields (choices) contained in the @varft
2138         \p variant_field_type.
2139
2140 @param[in] variant_field_type   Variant field type of which to get
2141                                 the number of contained fields.
2142 @returns                        Number of fields contained in
2143                                 \p variant_field_type, or a negative
2144                                 value on error.
2145
2146 @prenotnull{variant_field_type}
2147 @preisvarft{variant_field_type}
2148 @postrefcountsame{variant_field_type}
2149 */
2150 extern int bt_ctf_field_type_variant_get_field_count(
2151                 struct bt_ctf_field_type *variant_field_type);
2152
2153 /**
2154 @brief  Returns the field (choice) of the @varft \p variant_field_type
2155         at index \p index.
2156
2157 On success, the field's type is placed in \p *field_type if
2158 \p field_type is not \c NULL. The field's name is placed in
2159 \p *field_name if \p field_name is not \c NULL.
2160 \p variant_field_type remains the sole owner of \p *field_name.
2161
2162 @param[in] variant_field_type   Variant field type of which to get
2163                                 the field at index \p index.
2164 @param[out] field_name          Returned name of the field at index
2165                                 \p index (can be \c NULL).
2166 @param[out] field_type          Returned field type of the field
2167                                 at index \p index (can be \c NULL).
2168 @param[in] index              Index of the field to get from
2169                                 \p variant_field_type.
2170 @returns                        0 on success, or a negative value on error.
2171
2172 @prenotnull{variant_field_type}
2173 @preisvarft{variant_field_type}
2174 @pre \p index is lesser than the number of fields contained in the
2175         variant field type \p variant_field_type (see
2176         bt_ctf_field_type_variant_get_field_count()).
2177 @postrefcountsame{variant_field_type}
2178 @post <strong>On success</strong>, the returned field's type is placed
2179         in \p *field_type and its reference count is incremented.
2180
2181 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2182         field type's field by name.
2183 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2184         field type's field by current tag value.
2185 */
2186 extern int bt_ctf_field_type_variant_get_field(
2187                 struct bt_ctf_field_type *variant_field_type,
2188                 const char **field_name,
2189                 struct bt_ctf_field_type **field_type, int index);
2190
2191 /**
2192 @brief  Returns the type of the field (choice) named \p field_name
2193         found in the @varft \p variant_field_type.
2194
2195 @param[in] variant_field_type   Variant field type of which to get
2196                                 a field's type.
2197 @param[in] field_name           Name of the field to find.
2198 @returns                        Type of the field named \p field_name in
2199                                 \p variant_field_type, or
2200                                 \c NULL on error.
2201
2202 @prenotnull{variant_field_type}
2203 @prenotnull{field_name}
2204 @preisvarft{variant_field_type}
2205 @postrefcountsame{variant_field_type}
2206 @postsuccessrefcountretinc
2207
2208 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2209         field by index.
2210 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2211         field type's field by current tag value.
2212 */
2213 extern
2214 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
2215                 struct bt_ctf_field_type *variant_field_type,
2216                 const char *field_name);
2217
2218 /**
2219 @brief  Returns the type of the field (choice) selected by the value of
2220         the @enumfield \p tag_field in the @varft \p variant_field_type.
2221
2222 \p tag_field is the current tag value.
2223
2224 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2225 \em must be equivalent to the field type returned by
2226 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2227
2228 @param[in] variant_field_type   Variant field type of which to get
2229                                 a field's type.
2230 @param[in] tag_field            Current tag value (variant field type's
2231                                 selector).
2232 @returns                        Type of the field selected by
2233                                 \p tag_field in \p variant_field_type,
2234                                 or \c NULL on error.
2235
2236 @prenotnull{variant_field_type}
2237 @prenotnull{tag_field}
2238 @preisvarft{variant_field_type}
2239 @preisenumfield{tag_field}
2240 @postrefcountsame{variant_field_type}
2241 @postrefcountsame{tag_field}
2242 @postsuccessrefcountretinc
2243
2244 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2245         field by index.
2246 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2247         field type's field by name.
2248 */
2249 extern
2250 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
2251                 struct bt_ctf_field_type *variant_field_type,
2252                 struct bt_ctf_field *tag_field);
2253
2254 /**
2255 @brief  Adds a field (a choice) named \p field_name with the @ft
2256         \p field_type to the @varft \p variant_field_type.
2257
2258 On success, \p field_type becomes the child of \p variant_field_type.
2259
2260 You \em cannot add a field named \p field_name if there's already a
2261 field named \p field_name in \p variant_field_type.
2262
2263 \p field_name \em must name an existing mapping in the tag's
2264 enumeration field type of \p variant_field_type.
2265
2266 @param[in] variant_field_type   Variant field type to which to add
2267                                 a new field.
2268 @param[in] field_type           Field type of the field to add to
2269                                 \p variant_field_type.
2270 @param[in] field_name           Name of the field to add to
2271                                 \p variant_field_type
2272                                 (copied on success).
2273 @returns                        0 on success, or a negative value on error.
2274
2275 @prenotnull{variant_field_type}
2276 @prenotnull{field_type}
2277 @prenotnull{field_name}
2278 @preisvarft{variant_field_type}
2279 @pre \p field_type is not and does not contain \p variant_field_type,
2280         recursively, as a field's type.
2281 @prehot{variant_field_type}
2282 @postrefcountsame{variant_field_type}
2283 @postsuccessrefcountinc{field_type}
2284 */
2285 extern int bt_ctf_field_type_variant_add_field(
2286                 struct bt_ctf_field_type *variant_field_type,
2287                 struct bt_ctf_field_type *field_type,
2288                 const char *field_name);
2289
2290 /** @} */
2291
2292 #ifdef __cplusplus
2293 }
2294 #endif
2295
2296 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */