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 type 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 */
 654 extern struct bt_ctf_field_type *bt_ctf_field_type_copy(
 655                 struct bt_ctf_field_type *field_type);
 656
 657 /** @} */
 658
 659 /** @} */
 660
 661 /**
 662 @defgroup ctfirintfieldtype CTF IR integer field type
 663 @ingroup ctfirfieldtypes
 664 @brief CTF IR integer field type.
 665
 666 @code
 667 #include <babeltrace/ctf-ir/field-types.h>
 668 @endcode
 669
 670 A CTF IR <strong><em>integer field type</em></strong> is a field type that
 671 you can use to create concrete @intfield objects.
 672
 673 You can create an integer field type
 674 with bt_ctf_field_type_integer_create().
 675
 676 An integer field type has the following properties:
 677
 678 <table>
 679   <tr>
 680     <th>Property
 681     <th>Value at creation
 682     <th>Getter
 683     <th>Setter
 684   </tr>
 685   <tr>
 686     <td>\b Alignment (bits) of the described integer fields
 687     <td>1
 688     <td>bt_ctf_field_type_get_alignment()
 689     <td>bt_ctf_field_type_set_alignment()
 690   </tr>
 691   <tr>
 692     <td><strong>Byte order</strong> of the described integer fields
 693     <td>#BT_CTF_BYTE_ORDER_NATIVE
 694     <td>bt_ctf_field_type_get_byte_order()
 695     <td>bt_ctf_field_type_set_byte_order()
 696   </tr>
 697   <tr>
 698     <td><strong>Storage size</strong> (bits) of the described
 699         integer fields
 700     <td>Specified at creation
 701     <td>bt_ctf_field_type_integer_get_size()
 702     <td>None: specified at creation (bt_ctf_field_type_integer_create())
 703   </tr>
 704   <tr>
 705     <td><strong>Signedness</strong> of the described integer fields
 706     <td>Unsigned
 707     <td>bt_ctf_field_type_integer_get_signed()
 708     <td>bt_ctf_field_type_integer_set_signed()
 709   </tr>
 710   <tr>
 711     <td><strong>Preferred display base</strong> of the described
 712         integer fields
 713     <td>#BT_CTF_INTEGER_BASE_DECIMAL
 714     <td>bt_ctf_field_type_integer_get_base()
 715     <td>bt_ctf_field_type_integer_set_base()
 716   </tr>
 717   <tr>
 718     <td>\b Encoding of the described integer fields
 719     <td>#BT_CTF_STRING_ENCODING_NONE
 720     <td>bt_ctf_field_type_integer_get_encoding()
 721     <td>bt_ctf_field_type_integer_set_encoding()
 722   </tr>
 723   <tr>
 724     <td><strong>Mapped
 725         \link ctfirclockclass CTF IR clock class\endlink</strong>
 726     <td>None
 727     <td>bt_ctf_field_type_integer_get_mapped_clock_class()
 728     <td>bt_ctf_field_type_integer_set_mapped_clock_class()
 729   </tr>
 730 </table>
 731
 732 @sa ctfirintfield
 733 @sa ctfirfieldtypes
 734
 735 @addtogroup ctfirintfieldtype
 736 @{
 737 */
 738
 739 /**
 740 @brief  Preferred display base (radix) of a @intft.
 741 */
 742 enum bt_ctf_integer_base {
 743         /// Unknown, used for errors.
 744         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
 745
 746         /// Binary.
 747         BT_CTF_INTEGER_BASE_BINARY = 2,
 748
 749         /// Octal.
 750         BT_CTF_INTEGER_BASE_OCTAL = 8,
 751
 752         /// Decimal.
 753         BT_CTF_INTEGER_BASE_DECIMAL = 10,
 754
 755         /// Hexadecimal.
 756         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
 757 };
 758
 759 /**
 760 @brief  Creates a default @intft with \p size bits as the storage size
 761         of the @intfields it describes.
 762
 763 @param[in] size Storage size (bits) of the described integer fields.
 764 @returns        Created integer field type, or \c NULL on error.
 765
 766 @pre \p size is greater than 0 and lesser than or equal to 64.
 767 @postsuccessrefcountret1
 768 */
 769 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
 770                 unsigned int size);
 771
 772 /**
 773 @brief  Returns the storage size, in bits, of the @intfields
 774         described by the @intft \p int_field_type.
 775
 776 @param[in] int_field_type       Integer field type which describes the
 777                                 integer fields of which to get the
 778                                 storage size.
 779 @returns                        Storage size (bits) of the integer
 780                                 fields described by \p int_field_type,
 781                                 or a negative value on error.
 782
 783 @prenotnull{int_field_type}
 784 @preisintft{int_field_type}
 785 @postrefcountsame{int_field_type}
 786 */
 787 extern int bt_ctf_field_type_integer_get_size(
 788                 struct bt_ctf_field_type *int_field_type);
 789
 790 /**
 791 @brief  Returns whether or not the @intfields described by the @intft
 792         \p int_field_type are signed.
 793
 794 @param[in] int_field_type       Integer field type which describes the
 795                                 integer fields of which to get the
 796                                 signedness.
 797 @returns                        1 if the integer fields described by
 798                                 \p int_field_type are signed, 0 if they
 799                                 are unsigned, or a negative value on
 800                                 error.
 801
 802 @prenotnull{int_field_type}
 803 @preisintft{int_field_type}
 804 @postrefcountsame{int_field_type}
 805
 806 @sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the
 807         integer fields described by a given integer field type.
 808 */
 809 extern int bt_ctf_field_type_integer_get_signed(
 810                 struct bt_ctf_field_type *int_field_type);
 811
 812 /**
 813 @brief  Sets whether or not the @intfields described by
 814         the @intft \p int_field_type are signed.
 815
 816 @param[in] int_field_type       Integer field type which describes the
 817                                 integer fields of which to set the
 818                                 signedness.
 819 @param[in] is_signed            Signedness of the integer fields
 820                                 described by \p int_field_type; 0 means
 821                                 \em unsigned, 1 means \em signed.
 822 @returns                        0 on success, or a negative value on error.
 823
 824 @prenotnull{int_field_type}
 825 @preisintft{int_field_type}
 826 @prehot{int_field_type}
 827 @pre \p is_signed is 0 or 1.
 828 @postrefcountsame{event_class}
 829
 830 @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of
 831         the integer fields described by a given integer field type.
 832 */
 833 extern int bt_ctf_field_type_integer_set_signed(
 834                 struct bt_ctf_field_type *int_field_type, int is_signed);
 835
 836 /**
 837 @brief  Returns the preferred display base (radix) of the @intfields
 838         described by the @intft \p int_field_type.
 839
 840 @param[in] int_field_type       Integer field type which describes the
 841                                 integer fields of which to get the
 842                                 preferred display base.
 843 @returns                        Preferred display base of the integer
 844                                 fields described by \p int_field_type,
 845                                 or #BT_CTF_INTEGER_BASE_UNKNOWN on
 846                                 error.
 847
 848 @prenotnull{int_field_type}
 849 @preisintft{int_field_type}
 850 @postrefcountsame{int_field_type}
 851
 852 @sa bt_ctf_field_type_integer_set_base(): Sets the preferred display
 853         base of the integer fields described by a given integer field
 854         type.
 855 */
 856 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 857                 struct bt_ctf_field_type *int_field_type);
 858
 859 /**
 860 @brief  Sets the preferred display base (radix) of the @intfields
 861         described by the @intft \p int_field_type to \p base.
 862
 863 @param[in] int_field_type       Integer field type which describes the
 864                                 integer fields of which to set the
 865                                 preferred display base.
 866 @param[in] base                 Preferred display base of the integer
 867                                 fields described by \p int_field_type.
 868 @returns                        0 on success, or a negative value on error.
 869
 870 @prenotnull{int_field_type}
 871 @preisintft{int_field_type}
 872 @prehot{int_field_type}
 873 @pre \p base is #BT_CTF_INTEGER_BASE_BINARY, #BT_CTF_INTEGER_BASE_OCTAL,
 874         #BT_CTF_INTEGER_BASE_DECIMAL, or
 875         #BT_CTF_INTEGER_BASE_HEXADECIMAL.
 876 @postrefcountsame{int_field_type}
 877
 878 @sa bt_ctf_field_type_integer_get_base(): Returns the preferred display
 879         base of the integer fields described by a given
 880         integer field type.
 881 */
 882 extern int bt_ctf_field_type_integer_set_base(
 883                 struct bt_ctf_field_type *int_field_type,
 884                 enum bt_ctf_integer_base base);
 885
 886 /**
 887 @brief  Returns the encoding of the @intfields described by
 888         the @intft \p int_field_type.
 889
 890 @param[in] int_field_type       Integer field type which describes the
 891                                 integer fields of which to get the
 892                                 encoding.
 893 @returns                        Encoding of the integer
 894                                 fields described by \p int_field_type,
 895                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
 896                                 error.
 897
 898 @prenotnull{int_field_type}
 899 @preisintft{int_field_type}
 900 @postrefcountsame{int_field_type}
 901
 902 @sa bt_ctf_field_type_integer_set_encoding(): Sets the encoding
 903         of the integer fields described by a given integer field type.
 904 */
 905 extern enum bt_ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 906                 struct bt_ctf_field_type *int_field_type);
 907
 908 /**
 909 @brief  Sets the encoding of the @intfields described by the @intft
 910         \p int_field_type to \p encoding.
 911
 912 You can use this property, in CTF IR, to create "text" @arrayfts or
 913 @seqfts. A text array field type is array field type with an unsigned,
 914 8-bit integer field type having an encoding as its element field type.
 915
 916 @param[in] int_field_type       Integer field type which describes the
 917                                 integer fields of which to set the
 918                                 encoding.
 919 @param[in] encoding             Encoding of the integer
 920                                 fields described by \p int_field_type.
 921 @returns                        0 on success, or a negative value on error.
 922
 923 @prenotnull{int_field_type}
 924 @preisintft{int_field_type}
 925 @prehot{int_field_type}
 926 @pre \p encoding is #BT_CTF_STRING_ENCODING_NONE,
 927         #BT_CTF_STRING_ENCODING_ASCII, or
 928         #BT_CTF_STRING_ENCODING_UTF8.
 929 @postrefcountsame{int_field_type}
 930
 931 @sa bt_ctf_field_type_integer_get_encoding(): Returns the encoding of
 932         the integer fields described by a given integer field type.
 933 */
 934 extern int bt_ctf_field_type_integer_set_encoding(
 935                 struct bt_ctf_field_type *int_field_type,
 936                 enum bt_ctf_string_encoding encoding);
 937
 938 /**
 939 @brief  Returns the \link ctfirclockclass CTF IR clock class\endlink
 940         mapped to the @intft \p int_field_type.
 941
 942 The mapped clock class, if any, indicates the class of the clock which
 943 an @intfield described by \p int_field_type should sample or update.
 944 This mapped clock class is only indicative.
 945
 946 @param[in] int_field_type       Integer field type of which to get the
 947                                 mapped clock class.
 948 @returns                        Mapped clock class of \p int_field_type,
 949                                 or \c NULL if there's no mapped clock
 950                                 class or on error.
 951
 952 @prenotnull{int_field_type}
 953 @preisintft{int_field_type}
 954 @postrefcountsame{int_field_type}
 955 @postsuccessrefcountretinc
 956
 957 @sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped
 958         clock class of a given integer field type.
 959 */
 960 extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class(
 961                 struct bt_ctf_field_type *int_field_type);
 962
 963 /**
 964 @brief  Sets the \link ctfirclockclass CTF IR clock class\endlink mapped
 965         to the @intft \p int_field_type to \p clock_class.
 966
 967 The mapped clock class, if any, indicates the class of the clock which
 968 an integer field described by \p int_field_type should sample or update.
 969 This mapped clock class is only indicative.
 970
 971 @param[in] int_field_type       Integer field type of which to set the
 972                                 mapped clock class.
 973 @param[in] clock_class          Mapped clock class of \p int_field_type.
 974 @returns                        0 on success, or a negative value on error.
 975
 976 @prenotnull{int_field_type}
 977 @prenotnull{clock_class}
 978 @preisintft{int_field_type}
 979 @prehot{int_field_type}
 980 @postrefcountsame{int_field_type}
 981 @postsuccessrefcountinc{clock_class}
 982
 983 @sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped
 984         clock class of a given integer field type.
 985 */
 986 extern int bt_ctf_field_type_integer_set_mapped_clock_class(
 987                 struct bt_ctf_field_type *int_field_type,
 988                 struct bt_ctf_clock_class *clock_class);
 989
 990 /** @} */
 991
 992 /**
 993 @defgroup ctfirfloatfieldtype CTF IR floating point number field type
 994 @ingroup ctfirfieldtypes
 995 @brief CTF IR floating point number field type.
 996
 997 @code
 998 #include <babeltrace/ctf-ir/field-types.h>
 999 @endcode
1000
1001 A CTF IR <strong><em>floating point number field type</em></strong> is
1002 a field type that you can use to create concrete @floatfields.
1003
1004 You can create a floating point number field type
1005 with bt_ctf_field_type_floating_point_create().
1006
1007 A floating point number field type has the following properties:
1008
1009 <table>
1010   <tr>
1011     <th>Property
1012     <th>Value at creation
1013     <th>Getter
1014     <th>Setter
1015   </tr>
1016   <tr>
1017     <td>\b Alignment (bits) of the described floating point
1018         number fields
1019     <td>1
1020     <td>bt_ctf_field_type_get_alignment()
1021     <td>bt_ctf_field_type_set_alignment()
1022   </tr>
1023   <tr>
1024     <td><strong>Byte order</strong> of the described floating point
1025         number fields
1026     <td>#BT_CTF_BYTE_ORDER_NATIVE
1027     <td>bt_ctf_field_type_get_byte_order()
1028     <td>bt_ctf_field_type_set_byte_order()
1029   </tr>
1030   <tr>
1031     <td><strong>Exponent storage size</strong> (bits) of the described
1032         floating point number fields
1033     <td>8
1034     <td>bt_ctf_field_type_floating_point_get_exponent_digits()
1035     <td>bt_ctf_field_type_floating_point_set_exponent_digits()
1036   </tr>
1037   <tr>
1038     <td><strong>Mantissa and sign storage size</strong> (bits) of the
1039         described floating point number fields
1040     <td>24 (23-bit mantissa, 1-bit sign)
1041     <td>bt_ctf_field_type_floating_point_get_mantissa_digits()
1042     <td>bt_ctf_field_type_floating_point_set_mantissa_digits()
1043   </tr>
1044 </table>
1045
1046 @sa ctfirfloatfield
1047 @sa ctfirfieldtypes
1048
1049 @addtogroup ctfirfloatfieldtype
1050 @{
1051 */
1052
1053 /**
1054 @brief  Creates a default @floatft.
1055
1056 @returns        Created floating point number field type,
1057                 or \c NULL on error.
1058
1059 @postsuccessrefcountret1
1060 */
1061 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
1062
1063 /**
1064 @brief  Returns the exponent storage size of the @floatfields
1065         described by the @floatft \p float_field_type.
1066
1067 @param[in] float_field_type     Floating point number field type which
1068                                 describes the floating point number
1069                                 fields of which to get the exponent
1070                                 storage size.
1071 @returns                        Exponent storage size of the
1072                                 floating point number fields
1073                                 described by \p float_field_type,
1074                                 or a negative value on error.
1075
1076 @prenotnull{float_field_type}
1077 @preisfloatft{float_field_type}
1078 @postrefcountsame{float_field_type}
1079
1080 @sa bt_ctf_field_type_floating_point_set_exponent_digits(): Sets the
1081         exponent storage size of the floating point number fields
1082         described by a given floating point number field type.
1083 */
1084 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
1085                 struct bt_ctf_field_type *float_field_type);
1086
1087 /**
1088 @brief  Sets the exponent storage size of the @floatfields described by
1089         the @floatft \p float_field_type to \p exponent_size.
1090
1091 As of Babeltrace \btversion, \p exponent_size can only be 8 or 11.
1092
1093 @param[in] float_field_type     Floating point number field type which
1094                                 describes the floating point number
1095                                 fields of which to set the exponent
1096                                 storage size.
1097 @param[in] exponent_size        Exponent storage size of the floating
1098                                 point number fields described by \p
1099                                 float_field_type.
1100 @returns                        0 on success, or a negative value on error.
1101
1102 @prenotnull{float_field_type}
1103 @preisfloatft{float_field_type}
1104 @prehot{float_field_type}
1105 @pre \p exponent_size is 8 or 11.
1106 @postrefcountsame{float_field_type}
1107
1108 @sa bt_ctf_field_type_floating_point_get_exponent_digits(): Returns the
1109         exponent storage size of the floating point number fields
1110         described by a given floating point number field type.
1111 */
1112 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
1113                 struct bt_ctf_field_type *float_field_type,
1114                 unsigned int exponent_size);
1115
1116 /**
1117 @brief  Returns the mantissa and sign storage size of the @floatfields
1118         described by the @floatft \p float_field_type.
1119
1120 On success, the returned value is the sum of the mantissa \em and
1121 sign storage sizes.
1122
1123 @param[in] float_field_type     Floating point number field type which
1124                                 describes the floating point number
1125                                 fields of which to get the mantissa and
1126                                 sign storage size.
1127 @returns                        Mantissa and sign storage size of the
1128                                 floating point number fields
1129                                 described by \p float_field_type,
1130                                 or a negative value on error.
1131
1132 @prenotnull{float_field_type}
1133 @preisfloatft{float_field_type}
1134 @postrefcountsame{float_field_type}
1135
1136 @sa bt_ctf_field_type_floating_point_set_mantissa_digits(): Sets the
1137         mantissa and size storage size of the floating point number
1138         fields described by a given floating point number field type.
1139 */
1140 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
1141                 struct bt_ctf_field_type *float_field_type);
1142
1143 /**
1144 @brief  Sets the mantissa and sign storage size of the @floatfields
1145         described by the @floatft \p float_field_type to \p
1146         mantissa_sign_size.
1147
1148 As of Babeltrace \btversion, \p mantissa_sign_size can only be 24 or 53.
1149
1150 @param[in] float_field_type     Floating point number field type which
1151                                 describes the floating point number
1152                                 fields of which to set the mantissa and
1153                                 sign storage size.
1154 @param[in] mantissa_sign_size   Mantissa and sign storage size of the
1155                                 floating point number fields described
1156                                 by \p float_field_type.
1157 @returns                        0 on success, or a negative value on error.
1158
1159 @prenotnull{float_field_type}
1160 @preisfloatft{float_field_type}
1161 @prehot{float_field_type}
1162 @pre \p mantissa_sign_size is 24 or 53.
1163 @postrefcountsame{float_field_type}
1164
1165 @sa bt_ctf_field_type_floating_point_get_mantissa_digits(): Returns the
1166         mantissa and sign storage size of the floating point number
1167         fields described by a given floating point number field type.
1168 */
1169 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
1170                 struct bt_ctf_field_type *float_field_type,
1171                 unsigned int mantissa_sign_size);
1172
1173 /** @} */
1174
1175 /**
1176 @defgroup ctfirenumfieldtype CTF IR enumeration field type
1177 @ingroup ctfirfieldtypes
1178 @brief CTF IR enumeration field type.
1179
1180 @code
1181 #include <babeltrace/ctf-ir/field-types.h>
1182 @endcode
1183
1184 A CTF IR <strong><em>enumeration field type</em></strong> is
1185 a field type that you can use to create concrete @enumfields.
1186
1187 You can create an enumeration field type with
1188 bt_ctf_field_type_enumeration_create(). This function needs a @intft
1189 which represents the storage field type of the created enumeration field
1190 type. In other words, an enumeration field type wraps an integer field
1191 type and adds label-value mappings to it.
1192
1193 An enumeration mapping has:
1194
1195 - A <strong>name</strong>.
1196 - A <strong>range of values</strong> given by a beginning and an ending
1197   value, both included in the range.
1198
1199 You can add a mapping to an enumeration field type with
1200 bt_ctf_field_type_enumeration_add_mapping() or
1201 bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the
1202 signedness of the wrapped @intft.
1203
1204 Many mappings can share the same name, but the ranges of a given
1205 enumeration field type <strong>must not overlap</strong>. For example,
1206 this is a valid set of mappings:
1207
1208 @verbatim
1209 APPLE  -> [  3, 19]
1210 BANANA -> [-15,  1]
1211 CHERRY -> [ 25, 34]
1212 APPLE  -> [ 55, 55]
1213 @endverbatim
1214
1215 The following set of mappings is \em not valid, however:
1216
1217 @verbatim
1218 APPLE  -> [  3, 19]
1219 BANANA -> [-15,  1]
1220 CHERRY -> [ 25, 34]
1221 APPLE  -> [ 30, 55]
1222 @endverbatim
1223
1224 Here, the range of the second \c APPLE mapping overlaps the range of
1225 the \c CHERRY mapping.
1226
1227 @sa ctfirenumfield
1228 @sa ctfirfieldtypes
1229
1230 @addtogroup ctfirenumfieldtype
1231 @{
1232 */
1233
1234 /**
1235 @brief  Creates a default @enumft wrapping the @intft \p int_field_type.
1236
1237 @param[in] int_field_type       Integer field type wrapped by the
1238                                 created enumeration field type.
1239 @returns                        Created enumeration field type,
1240                                 or \c NULL on error.
1241
1242 @prenotnull{int_field_type}
1243 @preisintft{int_field_type}
1244 @postsuccessrefcountinc{int_field_type}
1245 @postsuccessrefcountret1
1246 */
1247 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
1248                 struct bt_ctf_field_type *int_field_type);
1249
1250 /**
1251 @brief  Returns the @intft wrapped by the @enumft \p enum_field_type.
1252
1253 @param[in] enum_field_type      Enumeration field type of which to get
1254                                 the wrapped integer field type.
1255 @returns                        Integer field type wrapped by
1256                                 \p enum_field_type, or \c NULL on
1257                                 error.
1258
1259 @prenotnull{enum_field_type}
1260 @preisenumft{enum_field_type}
1261 @postrefcountsame{enum_field_type}
1262 @postsuccessrefcountretinc
1263 */
1264 extern
1265 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
1266                 struct bt_ctf_field_type *enum_field_type);
1267
1268 /**
1269 @brief  Returns the number of mappings contained in the
1270         @enumft \p enum_field_type.
1271
1272 @param[in] enum_field_type      Enumeration field type of which to get
1273                                 the number of contained mappings.
1274 @returns                        Number of mappings contained in
1275                                 \p enum_field_type, or a negative
1276                                 value on error.
1277
1278 @prenotnull{enum_field_type}
1279 @preisenumft{enum_field_type}
1280 @postrefcountsame{enum_field_type}
1281 */
1282 extern int bt_ctf_field_type_enumeration_get_mapping_count(
1283                 struct bt_ctf_field_type *enum_field_type);
1284
1285 /**
1286 @brief  Returns the signed mapping of the @enumft
1287         \p enum_field_type at index \p index.
1288
1289 The @intft wrapped by \p enum_field_type, as returned by
1290 bt_ctf_field_type_enumeration_get_container_type(), must be \b signed
1291 to use this function.
1292
1293 On success, \p enum_field_type remains the sole owner of \p *name.
1294
1295 @param[in] enum_field_type      Enumeration field type of which to get
1296                                 the mapping at index \p index.
1297 @param[in] index              Index of the mapping to get from
1298                                 \p enum_field_type.
1299 @param[out] name                Returned name of the mapping at index
1300                                 \p index.
1301 @param[out] range_begin         Returned beginning of the range
1302                                 (included) of the mapping at index \p
1303                                 index.
1304 @param[out] range_end           Returned end of the range (included) of
1305                                 the mapping at index \p index.
1306 @returns                        0 on success, or a negative value on error.
1307
1308 @prenotnull{enum_field_type}
1309 @prenotnull{name}
1310 @prenotnull{range_begin}
1311 @prenotnull{range_end}
1312 @preisenumft{enum_field_type}
1313 @pre The wrapped @intft of \p enum_field_type is signed.
1314 @pre \p index is lesser than the number of mappings contained in the
1315         enumeration field type \p enum_field_type (see
1316         bt_ctf_field_type_enumeration_get_mapping_count()).
1317 @postrefcountsame{enum_field_type}
1318
1319 @sa bt_ctf_field_type_enumeration_get_mapping_unsigned(): Returns the
1320         unsigned mapping contained by a given enumeration field type
1321         at a given index.
1322 */
1323 extern int bt_ctf_field_type_enumeration_get_mapping(
1324                 struct bt_ctf_field_type *enum_field_type, int index,
1325                 const char **name, int64_t *range_begin, int64_t *range_end);
1326
1327 /**
1328 @brief  Returns the unsigned mapping of the @enumft
1329         \p enum_field_type at index \p index.
1330
1331 The @intft wrapped by \p enum_field_type, as returned by
1332 bt_ctf_field_type_enumeration_get_container_type(), must be
1333 \b unsigned to use this function.
1334
1335 On success, \p enum_field_type remains the sole owner of \p *name.
1336
1337 @param[in] enum_field_type      Enumeration field type of which to get
1338                                 the mapping at index \p index.
1339 @param[in] index              Index of the mapping to get from
1340                                 \p enum_field_type.
1341 @param[out] name                Returned name of the mapping at index
1342                                 \p index.
1343 @param[out] range_begin         Returned beginning of the range
1344                                 (included) of the mapping at index \p
1345                                 index.
1346 @param[out] range_end           Returned end of the range (included) of
1347                                 the mapping at index \p index.
1348 @returns                        0 on success, or a negative value on error.
1349
1350 @prenotnull{enum_field_type}
1351 @prenotnull{name}
1352 @prenotnull{range_begin}
1353 @prenotnull{range_end}
1354 @preisenumft{enum_field_type}
1355 @pre The wrapped @intft of \p enum_field_type is unsigned.
1356 @pre \p index is lesser than the number of mappings contained in the
1357         enumeration field type \p enum_field_type (see
1358         bt_ctf_field_type_enumeration_get_mapping_count()).
1359 @postrefcountsame{enum_field_type}
1360
1361 @sa bt_ctf_field_type_enumeration_get_mapping(): Returns the
1362         signed mapping contained by a given enumeration field type
1363         at a given index.
1364 */
1365 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
1366                 struct bt_ctf_field_type *enum_field_type, int index,
1367                 const char **name, uint64_t *range_begin,
1368                 uint64_t *range_end);
1369
1370 /** @cond DOCUMENT */
1371 /*
1372  * TODO: Document once we know what to do with this function (return
1373  *       the first match?).
1374  */
1375 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
1376                 struct bt_ctf_field_type *enum_field_type, const char *name);
1377 /** @endcond */
1378
1379 /**
1380 @brief  Returns the index of the signed mapping of the @enumft
1381         \p field_type which contains the value \p value.
1382
1383 The @intft wrapped by \p enum_field_type, as returned by
1384 bt_ctf_field_type_enumeration_get_container_type(), must be
1385 \b signed to use this function.
1386
1387 @param[in] enum_field_type      Enumeration field type of which to get
1388                                 the index of the mapping which contains
1389                                 \p value.
1390 @param[in] value                Value of the mapping to find.
1391 @returns                        Index of the mapping of
1392                                 \p enum_field_type which contains
1393                                 \p value, or a negative value if the
1394                                 function cannot find such a mapping or
1395                                 on error.
1396
1397 @prenotnull{enum_field_type}
1398 @preisenumft{enum_field_type}
1399 @pre The wrapped @intft of \p enum_field_type is signed.
1400 @postrefcountsame{enum_field_type}
1401
1402 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1403         Finds the index of an unsigned mapping of a given enumeration
1404         field type by value.
1405 */
1406 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
1407                 struct bt_ctf_field_type *enum_field_type, int64_t value);
1408
1409 /**
1410 @brief  Returns the index of the unsigned mapping of the @enumft
1411         \p field_type which contains the value \p value.
1412
1413 The @intft wrapped by \p enum_field_type, as returned by
1414 bt_ctf_field_type_enumeration_get_container_type(), must be
1415 \b unsigned to use this function.
1416
1417 @param[in] enum_field_type      Enumeration field type of which to get
1418                                 the index of the mapping which contains
1419                                 \p value.
1420 @param[in] value                Value of the mapping to find.
1421 @returns                        Index of the mapping of
1422                                 \p enum_field_type which contains
1423                                 \p value, or a negative value if the
1424                                 function cannot find such a mapping or
1425                                 on error.
1426
1427 @prenotnull{enum_field_type}
1428 @preisenumft{enum_field_type}
1429 @pre The wrapped @intft of \p enum_field_type is unsigned.
1430 @postrefcountsame{enum_field_type}
1431
1432 @sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value():
1433         Finds the index of a signed mapping of a given enumeration
1434         field type by value.
1435 */
1436 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
1437                 struct bt_ctf_field_type *enum_field_type, uint64_t value);
1438
1439 /**
1440 @brief  Adds a mapping to the @enumft \p enum_field_type which maps the
1441         name \p name to the signed range \p range_begin (included) to
1442         \p range_end (included).
1443
1444 Make \p range_begin and \p range_end the same value to add a mapping
1445 to a single value.
1446
1447 The @intft wrapped by \p enum_field_type, as returned by
1448 bt_ctf_field_type_enumeration_get_container_type(), must be
1449 \b signed to use this function.
1450
1451 A mapping in \p enum_field_type can exist with the name \p name, but
1452 there must be no overlap amongst all the ranges of
1453 \p enum_field_type.
1454
1455 @param[in] enum_field_type      Enumeration field type to which to add
1456                                 a mapping.
1457 @param[in] name                 Name of the mapping to add (copied
1458                                 on success).
1459 @param[in] range_begin          Beginning of the range of the mapping
1460                                 (included).
1461 @param[in] range_end            End of the range of the mapping
1462                                 (included).
1463 @returns                        0 on success, or a negative value on error.
1464
1465 @prenotnull{enum_field_type}
1466 @prenotnull{name}
1467 @preisenumft{enum_field_type}
1468 @pre The wrapped @intft of \p enum_field_type is signed.
1469 @pre \p range_end is greater than or equal to \p range_begin.
1470 @postrefcountsame{enum_field_type}
1471
1472 @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an
1473         unsigned mapping to a given enumeration field type.
1474 */
1475 extern int bt_ctf_field_type_enumeration_add_mapping(
1476                 struct bt_ctf_field_type *enum_field_type, const char *name,
1477                 int64_t range_begin, int64_t range_end);
1478
1479 /**
1480 @brief  Adds a mapping to the @enumft \p enum_field_type which maps
1481         the name \p name to the unsigned
1482         range \p range_begin (included) to \p range_end (included).
1483
1484 Make \p range_begin and \p range_end the same value to add a mapping
1485 to a single value.
1486
1487 The @intft wrapped by \p enum_field_type, as returned by
1488 bt_ctf_field_type_enumeration_get_container_type(), must be
1489 \b unsigned to use this function.
1490
1491 A mapping in \p enum_field_type can exist with the name \p name, but
1492 there must be no overlap amongst all the ranges of
1493 \p enum_field_type.
1494
1495 @param[in] enum_field_type      Enumeration field type to which to add
1496                                 a mapping.
1497 @param[in] name                 Name of the mapping to add (copied
1498                                 on success).
1499 @param[in] range_begin          Beginning of the range of the mapping
1500                                 (included).
1501 @param[in] range_end            End of the range of the mapping
1502                                 (included).
1503 @returns                        0 on success, or a negative value on error.
1504
1505 @prenotnull{enum_field_type}
1506 @prenotnull{name}
1507 @preisenumft{enum_field_type}
1508 @pre The wrapped @intft of \p enum_field_type is unsigned.
1509 @pre \p range_end is greater than or equal to \p range_begin.
1510 @postrefcountsame{enum_field_type}
1511
1512 @sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed
1513         mapping to a given enumeration field type.
1514 */
1515 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
1516                 struct bt_ctf_field_type *enum_field_type, const char *name,
1517                 uint64_t range_begin, uint64_t range_end);
1518
1519 /** @} */
1520
1521 /**
1522 @defgroup ctfirstringfieldtype CTF IR string field type
1523 @ingroup ctfirfieldtypes
1524 @brief CTF IR string field type.
1525
1526 @code
1527 #include <babeltrace/ctf-ir/field-types.h>
1528 @endcode
1529
1530 A CTF IR <strong><em>string field type</em></strong> is a field type that
1531 you can use to create concrete @stringfields.
1532
1533 You can create a string field type
1534 with bt_ctf_field_type_string_create().
1535
1536 A string field type has only one property: the \b encoding of its
1537 described @stringfields. By default, the encoding of the string fields
1538 described by a string field type is #BT_CTF_STRING_ENCODING_UTF8. You
1539 can set the encoding of the string fields described by a string field
1540 type with bt_ctf_field_type_string_set_encoding().
1541
1542 @sa ctfirstringfield
1543 @sa ctfirfieldtypes
1544
1545 @addtogroup ctfirstringfieldtype
1546 @{
1547 */
1548
1549 /**
1550 @brief  Creates a default @stringft.
1551
1552 @returns        Created string field type, or \c NULL on error.
1553
1554 @postsuccessrefcountret1
1555 */
1556 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
1557
1558 /**
1559 @brief  Returns the encoding of the @stringfields described by
1560         the @stringft \p string_field_type.
1561
1562 @param[in] string_field_type    String field type which describes the
1563                                 string fields of which to get the
1564                                 encoding.
1565 @returns                        Encoding of the string
1566                                 fields described by \p string_field_type,
1567                                 or #BT_CTF_STRING_ENCODING_UNKNOWN on
1568                                 error.
1569
1570 @prenotnull{string_field_type}
1571 @preisstringft{string_field_type}
1572 @postrefcountsame{string_field_type}
1573
1574 @sa bt_ctf_field_type_string_set_encoding(): Sets the encoding
1575         of the string fields described by a given string field type.
1576 */
1577 extern enum bt_ctf_string_encoding bt_ctf_field_type_string_get_encoding(
1578                 struct bt_ctf_field_type *string_field_type);
1579
1580 /**
1581 @brief  Sets the encoding of the @stringfields described by the
1582         @stringft \p string_field_type to \p encoding.
1583
1584 @param[in] string_field_type    String field type which describes the
1585                                 string fields of which to set the
1586                                 encoding.
1587 @param[in] encoding             Encoding of the string fields described
1588                                 by \p string_field_type.
1589 @returns                        0 on success, or a negative value on error.
1590
1591 @prenotnull{string_field_type}
1592 @preisstringft{string_field_type}
1593 @prehot{string_field_type}
1594 @pre \p encoding is #BT_CTF_STRING_ENCODING_ASCII or
1595         #BT_CTF_STRING_ENCODING_UTF8.
1596 @postrefcountsame{string_field_type}
1597
1598 @sa bt_ctf_field_type_string_get_encoding(): Returns the encoding of
1599         the string fields described by a given string field type.
1600 */
1601 extern int bt_ctf_field_type_string_set_encoding(
1602                 struct bt_ctf_field_type *string_field_type,
1603                 enum bt_ctf_string_encoding encoding);
1604
1605 /** @} */
1606
1607 /**
1608 @defgroup ctfirstructfieldtype CTF IR structure field type
1609 @ingroup ctfirfieldtypes
1610 @brief CTF IR structure field type.
1611
1612 @code
1613 #include <babeltrace/ctf-ir/field-types.h>
1614 @endcode
1615
1616 A CTF IR <strong><em>structure field type</em></strong> is
1617 a field type that you can use to create concrete @structfields.
1618
1619 You can create a structure field type
1620 with bt_ctf_field_type_structure_create(). This function creates
1621 an empty structure field type, with no fields.
1622
1623 You can add a field to a structure field type with
1624 bt_ctf_field_type_structure_add_field(). Two fields in a structure
1625 field type cannot have the same name.
1626
1627 You can set the \em minimum alignment of the structure fields described
1628 by a structure field type with the common
1629 bt_ctf_field_type_set_alignment() function. The \em effective alignment
1630 of the structure fields described by a structure field type, as per
1631 <a href="http://diamon.org/ctf/">CTF</a>, is the \em maximum value amongst
1632 the effective alignments of all its fields. Note that the effective
1633 alignment of @varfields is always 1.
1634
1635 You can set the byte order of <em>all the contained fields</em>,
1636 recursively, of a structure field type with the common
1637 bt_ctf_field_type_set_byte_order() function.
1638
1639 @sa ctfirstructfield
1640 @sa ctfirfieldtypes
1641
1642 @addtogroup ctfirstructfieldtype
1643 @{
1644 */
1645
1646 /**
1647 @brief  Creates a default, empty @structft.
1648
1649 @returns                        Created structure field type,
1650                                 or \c NULL on error.
1651
1652 @postsuccessrefcountret1
1653 */
1654 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
1655
1656 /**
1657 @brief  Returns the number of fields contained in the
1658         @structft \p struct_field_type.
1659
1660 @param[in] struct_field_type    Structure field type of which to get
1661                                 the number of contained fields.
1662 @returns                        Number of fields contained in
1663                                 \p struct_field_type, or a negative
1664                                 value on error.
1665
1666 @prenotnull{struct_field_type}
1667 @preisstructft{struct_field_type}
1668 @postrefcountsame{struct_field_type}
1669 */
1670 extern int bt_ctf_field_type_structure_get_field_count(
1671                 struct bt_ctf_field_type *struct_field_type);
1672
1673 /**
1674 @brief  Returns the field of the @structft \p struct_field_type
1675         at index \p index.
1676
1677 On success, the field's type is placed in \p *field_type if
1678 \p field_type is not \c NULL. The field's name is placed in
1679 \p *field_name if \p field_name is not \c NULL.
1680 \p struct_field_type remains the sole owner of \p *field_name.
1681
1682 @param[in] struct_field_type    Structure field type of which to get
1683                                 the field at index \p index.
1684 @param[out] field_name          Returned name of the field at index
1685                                 \p index (can be \c NULL).
1686 @param[out] field_type          Returned field type of the field
1687                                 at index \p index (can be \c NULL).
1688 @param[in] index              Index of the field to get from
1689                                 \p struct_field_type.
1690 @returns                        0 on success, or a negative value on error.
1691
1692 @prenotnull{struct_field_type}
1693 @preisstructft{struct_field_type}
1694 @pre \p index is lesser than the number of fields contained in the
1695         structure field type \p struct_field_type (see
1696         bt_ctf_field_type_structure_get_field_count()).
1697 @postrefcountsame{struct_field_type}
1698 @post <strong>On success</strong>, the returned field's type is placed
1699         in \p *field_type and its reference count is incremented.
1700
1701 @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a
1702         structure field type's field by name.
1703 */
1704 extern int bt_ctf_field_type_structure_get_field(
1705                 struct bt_ctf_field_type *struct_field_type,
1706                 const char **field_name, struct bt_ctf_field_type **field_type,
1707                 int index);
1708
1709 /**
1710 @brief  Returns the type of the field named \p field_name found in
1711         the @structft \p struct_field_type.
1712
1713 @param[in] struct_field_type    Structure field type of which to get
1714                                 a field's type.
1715 @param[in] field_name           Name of the field to find.
1716 @returns                        Type of the field named \p field_name in
1717                                 \p struct_field_type, or
1718                                 \c NULL on error.
1719
1720 @prenotnull{struct_field_type}
1721 @prenotnull{field_name}
1722 @preisstructft{struct_field_type}
1723 @postrefcountsame{struct_field_type}
1724 @postsuccessrefcountretinc
1725
1726 @sa bt_ctf_field_type_structure_get_field(): Finds a
1727         structure field type's field by index.
1728 */
1729 extern
1730 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
1731                 struct bt_ctf_field_type *struct_field_type,
1732                 const char *field_name);
1733
1734 /**
1735 @brief  Adds a field named \p field_name with the @ft
1736         \p field_type to the @structft \p struct_field_type.
1737
1738 On success, \p field_type becomes the child of \p struct_field_type.
1739
1740 This function adds the new field after the current last field of
1741 \p struct_field_type (append mode).
1742
1743 You \em cannot add a field named \p field_name if there's already a
1744 field named \p field_name in \p struct_field_type.
1745
1746 @param[in] struct_field_type    Structure field type to which to add
1747                                 a new field.
1748 @param[in] field_type           Field type of the field to add to
1749                                 \p struct_field_type.
1750 @param[in] field_name           Name of the field to add to
1751                                 \p struct_field_type
1752                                 (copied on success).
1753 @returns                        0 on success, or a negative value on error.
1754
1755 @prenotnull{struct_field_type}
1756 @prenotnull{field_type}
1757 @prenotnull{field_name}
1758 @preisstructft{struct_field_type}
1759 @pre \p field_type is not and does not contain \p struct_field_type,
1760         recursively, as a field's type.
1761 @prehot{struct_field_type}
1762 @postrefcountsame{struct_field_type}
1763 @postsuccessrefcountinc{field_type}
1764 */
1765 extern int bt_ctf_field_type_structure_add_field(
1766                 struct bt_ctf_field_type *struct_field_type,
1767                 struct bt_ctf_field_type *field_type,
1768                 const char *field_name);
1769
1770 /** @} */
1771
1772 /**
1773 @defgroup ctfirarrayfieldtype CTF IR array field type
1774 @ingroup ctfirfieldtypes
1775 @brief CTF IR array field type.
1776
1777 @code
1778 #include <babeltrace/ctf-ir/field-types.h>
1779 @endcode
1780
1781 A CTF IR <strong><em>array field type</em></strong> is a field type that
1782 you can use to create concrete @arrayfields.
1783
1784 You can create an array field type
1785 with bt_ctf_field_type_array_create(). This function needs
1786 the @ft of the fields contained by the array fields described by the
1787 array field type to create.
1788
1789 @sa ctfirarrayfield
1790 @sa ctfirfieldtypes
1791
1792 @addtogroup ctfirarrayfieldtype
1793 @{
1794 */
1795
1796 /**
1797 @brief  Creates a default @arrayft with
1798         \p element_field_type as the field type of the fields contained
1799         in its described @arrayfields of length \p length.
1800
1801 @param[in] element_field_type   Field type of the fields contained in
1802                                 the array fields described by the
1803                                 created array field type.
1804 @param[in] length               Length of the array fields described by
1805                                 the created array field type.
1806 @returns                        Created array field type, or
1807                                 \c NULL on error.
1808
1809 @prenotnull{element_field_type}
1810 @postsuccessrefcountinc{element_field_type}
1811 @postsuccessrefcountret1
1812 */
1813 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
1814                 struct bt_ctf_field_type *element_field_type,
1815                 unsigned int length);
1816
1817 /**
1818 @brief  Returns the @ft of the @fields contained in
1819         the @arrayfields described by the @arrayft \p array_field_type.
1820
1821 @param[in] array_field_type     Array field type of which to get
1822                                 the type of the fields contained in its
1823                                 described array fields.
1824 @returns                        Type of the fields contained in the
1825                                 array fields described by
1826                                 \p array_field_type, or \c NULL
1827                                 on error.
1828
1829 @prenotnull{array_field_type}
1830 @preisarrayft{array_field_type}
1831 @postrefcountsame{array_field_type}
1832 @postsuccessrefcountretinc
1833 */
1834 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
1835                 struct bt_ctf_field_type *array_field_type);
1836
1837 /**
1838 @brief  Returns the number of @fields contained in the
1839         @arrayfields described by the @arrayft \p array_field_type.
1840
1841 @param[in] array_field_type     Array field type of which to get
1842                                 the number of fields contained in its
1843                                 described array fields.
1844 @returns                        Number of fields contained in the
1845                                 array fields described by
1846                                 \p array_field_type, or a negative value
1847                                 on error.
1848
1849 @prenotnull{array_field_type}
1850 @preisarrayft{array_field_type}
1851 @postrefcountsame{array_field_type}
1852 */
1853 extern int64_t bt_ctf_field_type_array_get_length(
1854                 struct bt_ctf_field_type *array_field_type);
1855
1856 /** @} */
1857
1858 /**
1859 @defgroup ctfirseqfieldtype CTF IR sequence field type
1860 @ingroup ctfirfieldtypes
1861 @brief CTF IR sequence field type.
1862
1863 @code
1864 #include <babeltrace/ctf-ir/field-types.h>
1865 @endcode
1866
1867 A CTF IR <strong><em>sequence field type</em></strong> is
1868 a field type that you can use to create concrete @seqfields.
1869
1870 You can create a sequence field type with
1871 bt_ctf_field_type_sequence_create(). This function needs the @ft
1872 of the fields contained by the sequence fields described by the created
1873 sequence field type. This function also needs the length name of the
1874 sequence field type to create. The length name is used to automatically
1875 resolve the length's field type. See \ref ctfirfieldtypes to learn more
1876 about the automatic resolving.
1877
1878 @sa ctfirseqfield
1879 @sa ctfirfieldtypes
1880
1881 @addtogroup ctfirseqfieldtype
1882 @{
1883 */
1884
1885 /**
1886 @brief  Creates a default @seqft with \p element_field_type as the
1887         @ft of the @fields contained in its described @seqfields
1888         with the length name \p length_name.
1889
1890 \p length_name can be an absolute or relative reference. See
1891 <a href="http://diamon.org/ctf/">CTF</a> for more details.
1892
1893 @param[in] element_field_type   Field type of the fields contained in
1894                                 the sequence fields described by the
1895                                 created sequence field type.
1896 @param[in] length_name          Length name (copied on success).
1897 @returns                        Created array field type, or
1898                                 \c NULL on error.
1899
1900 @prenotnull{element_field_type}
1901 @prenotnull{length_name}
1902 @postsuccessrefcountinc{element_field_type}
1903 @postsuccessrefcountret1
1904 */
1905 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
1906                 struct bt_ctf_field_type *element_field_type,
1907                 const char *length_name);
1908
1909 /**
1910 @brief  Returns the @ft of the @fields contained in the @seqft
1911         described by the @seqft \p sequence_field_type.
1912
1913 @param[in] sequence_field_type  Sequence field type of which to get
1914                                 the type of the fields contained in its
1915                                 described sequence fields.
1916 @returns                        Type of the fields contained in the
1917                                 sequence fields described by
1918                                 \p sequence_field_type, or \c NULL
1919                                 on error.
1920
1921 @prenotnull{sequence_field_type}
1922 @preisseqft{sequence_field_type}
1923 @postrefcountsame{sequence_field_type}
1924 @postsuccessrefcountretinc
1925 */
1926 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
1927                 struct bt_ctf_field_type *sequence_field_type);
1928
1929 /**
1930 @brief  Returns the length name of the @seqft \p sequence_field_type.
1931
1932 On success, \p sequence_field_type remains the sole owner of
1933 the returned string.
1934
1935 @param[in] sequence_field_type  Sequence field type of which to get the
1936                                 length name.
1937 @returns                        Length name of \p sequence_field_type,
1938                                 or \c NULL on error.
1939
1940 @prenotnull{sequence_field_type}
1941 @preisseqft{sequence_field_type}
1942
1943 @sa bt_ctf_field_type_sequence_get_length_field_path(): Returns the
1944         length's CTF IR field path of a given sequence field type.
1945 */
1946 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
1947                 struct bt_ctf_field_type *sequence_field_type);
1948
1949 /**
1950 @brief  Returns the length's CTF IR field path of the @seqft
1951         \p sequence_field_type.
1952
1953 The length's field path of a sequence field type is set when automatic
1954 resolving is performed (see \ref ctfirfieldtypes).
1955
1956 @param[in] sequence_field_type  Sequence field type of which to get the
1957                                 length's field path.
1958 @returns                        Length's field path of
1959                                 \p sequence_field_type, or
1960                                 \c NULL if the length's field path is
1961                                 not set yet is not set or on error.
1962
1963 @prenotnull{sequence_field_type}
1964 @preisseqft{sequence_field_type}
1965 @postsuccessrefcountretinc
1966
1967 @sa bt_ctf_field_type_sequence_get_length_field_name(): Returns the
1968         length's name of a given sequence field type.
1969 */
1970 extern struct bt_ctf_field_path *bt_ctf_field_type_sequence_get_length_field_path(
1971                 struct bt_ctf_field_type *sequence_field_type);
1972
1973 /** @} */
1974
1975 /**
1976 @defgroup ctfirvarfieldtype CTF IR variant field type
1977 @ingroup ctfirfieldtypes
1978 @brief CTF IR variant field type.
1979
1980 @code
1981 #include <babeltrace/ctf-ir/field-types.h>
1982 @endcode
1983
1984 A CTF IR <strong><em>variant field type</em></strong> is
1985 a field type that you can use to create concrete @varfields.
1986
1987 You can create a variant field type with
1988 bt_ctf_field_type_variant_create(). This function expects you to pass
1989 both the tag's @enumft and the tag name of the variant field type to
1990 create. The tag's field type is optional, as the Babeltrace system can
1991 automatically resolve it using the tag name. You can leave the tag name
1992 to \c NULL initially, and set it later with
1993 bt_ctf_field_type_variant_set_tag_name(). The tag name must be set when
1994 the variant field type is frozen. See \ref ctfirfieldtypes to learn more
1995 about the automatic resolving and the conditions under which a field
1996 type can be frozen.
1997
1998 You can add a field to a variant field type with
1999 bt_ctf_field_type_variant_add_field(). All the field names of a
2000 variant field type \em must exist as mapping names in its tag's @enumft.
2001
2002 The effective alignment of the @varfields described by a
2003 variant field type is always 1, but the individual fields of a
2004 @varfield can have custom alignments.
2005
2006 You can set the byte order of <em>all the contained fields</em>,
2007 recursively, of a variant field type with the common
2008 bt_ctf_field_type_set_byte_order() function.
2009
2010 @sa ctfirvarfield
2011 @sa ctfirfieldtypes
2012
2013 @addtogroup ctfirvarfieldtype
2014 @{
2015 */
2016
2017 /**
2018 @brief  Creates a default, empty @varft with the tag's @enumft
2019         \p tag_field_type and the tag name \p tag_name.
2020
2021 \p tag_field_type can be \c NULL; the tag's field type can be
2022 automatically resolved from the variant field type's tag name (see
2023 \ref ctfirfieldtypes). If \p tag_name is \c NULL, it \em must be set
2024 with bt_ctf_field_type_variant_set_tag_name() \em before the variant
2025 field type is frozen.
2026
2027 \p tag_name can be an absolute or relative reference. See
2028 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2029
2030 @param[in] tag_field_type       Tag's enumeration field type
2031                                 (can be \c NULL).
2032 @param[in] tag_name             Tag name (copied on success,
2033                                 can be \c NULL).
2034 @returns                        Created variant field type, or
2035                                 \c NULL on error.
2036
2037 @pre \p tag_field_type is an enumeration field type or \c NULL.
2038 @post <strong>On success, if \p tag_field_type is not \c NULL</strong>,
2039         its reference count is incremented.
2040 @postsuccessrefcountret1
2041 */
2042 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
2043                 struct bt_ctf_field_type *tag_field_type,
2044                 const char *tag_name);
2045
2046 /**
2047 @brief  Returns the tag's @enumft of the @varft \p variant_field_type.
2048
2049 @param[in] variant_field_type   Variant field type of which to get
2050                                 the tag's enumeration field type.
2051 @returns                        Tag's enumeration field type of
2052                                 \p variant_field_type, or \c NULL if the
2053                                 tag's field type is not set or on
2054                                 error.
2055
2056 @prenotnull{variant_field_type}
2057 @preisvarft{variant_field_type}
2058 @postrefcountsame{variant_field_type}
2059 @postsuccessrefcountretinc
2060 */
2061 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
2062                 struct bt_ctf_field_type *variant_field_type);
2063
2064 /**
2065 @brief  Returns the tag name of the @varft \p variant_field_type.
2066
2067 On success, \p variant_field_type remains the sole owner of
2068 the returned string.
2069
2070 @param[in] variant_field_type   Variant field type of which to get the
2071                                 tag name.
2072 @returns                        Tag name of \p variant_field_type, or
2073                                 \c NULL if the tag name is not set or
2074                                 on error.
2075
2076 @prenotnull{variant_field_type}
2077 @preisvarft{variant_field_type}
2078
2079 @sa bt_ctf_field_type_variant_set_tag_name(): Sets the tag name of
2080         a given variant field type.
2081 @sa bt_ctf_field_type_variant_get_tag_field_path(): Returns the tag's
2082         CTF IR field path of a given variant field type.
2083 */
2084 extern const char *bt_ctf_field_type_variant_get_tag_name(
2085                 struct bt_ctf_field_type *variant_field_type);
2086
2087 /**
2088 @brief  Sets the tag name of the @varft \p variant_field_type.
2089
2090 \p tag_name can be an absolute or relative reference. See
2091 <a href="http://diamon.org/ctf/">CTF</a> for more details.
2092
2093 @param[in] variant_field_type   Variant field type of which to set
2094                                 the tag name.
2095 @param[in] tag_name             Tag name of \p variant_field_type
2096                                 (copied on success).
2097 @returns                        0 on success, or a negative value on error.
2098
2099 @prenotnull{variant_field_type}
2100 @prenotnull{name}
2101 @prehot{variant_field_type}
2102 @postrefcountsame{variant_field_type}
2103
2104 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag name of
2105         a given variant field type.
2106 */
2107 extern int bt_ctf_field_type_variant_set_tag_name(
2108                 struct bt_ctf_field_type *variant_field_type,
2109                 const char *tag_name);
2110
2111 /**
2112 @brief  Returns the tag's CTF IR field path of the @varft
2113         \p variant_field_type.
2114
2115 The tag's field path of a variant field type is set when automatic
2116 resolving is performed (see \ref ctfirfieldtypes).
2117
2118 @param[in] variant_field_type   Variant field type of which to get the
2119                                 tag's field path.
2120 @returns                        Tag's field path of
2121                                 \p variant_field_type, or
2122                                 \c NULL if the tag's field path is not
2123                                 set yet is not set or on error.
2124
2125 @prenotnull{variant_field_type}
2126 @preisvarft{variant_field_type}
2127 @postsuccessrefcountretinc
2128
2129 @sa bt_ctf_field_type_variant_get_tag_name(): Returns the tag's
2130         name of a given variant field type.
2131 */
2132 extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path(
2133                 struct bt_ctf_field_type *variant_field_type);
2134
2135 /**
2136 @brief  Returns the number of fields (choices) contained in the @varft
2137         \p variant_field_type.
2138
2139 @param[in] variant_field_type   Variant field type of which to get
2140                                 the number of contained fields.
2141 @returns                        Number of fields contained in
2142                                 \p variant_field_type, or a negative
2143                                 value on error.
2144
2145 @prenotnull{variant_field_type}
2146 @preisvarft{variant_field_type}
2147 @postrefcountsame{variant_field_type}
2148 */
2149 extern int bt_ctf_field_type_variant_get_field_count(
2150                 struct bt_ctf_field_type *variant_field_type);
2151
2152 /**
2153 @brief  Returns the field (choice) of the @varft \p variant_field_type
2154         at index \p index.
2155
2156 On success, the field's type is placed in \p *field_type if
2157 \p field_type is not \c NULL. The field's name is placed in
2158 \p *field_name if \p field_name is not \c NULL.
2159 \p variant_field_type remains the sole owner of \p *field_name.
2160
2161 @param[in] variant_field_type   Variant field type of which to get
2162                                 the field at index \p index.
2163 @param[out] field_name          Returned name of the field at index
2164                                 \p index (can be \c NULL).
2165 @param[out] field_type          Returned field type of the field
2166                                 at index \p index (can be \c NULL).
2167 @param[in] index              Index of the field to get from
2168                                 \p variant_field_type.
2169 @returns                        0 on success, or a negative value on error.
2170
2171 @prenotnull{variant_field_type}
2172 @preisvarft{variant_field_type}
2173 @pre \p index is lesser than the number of fields contained in the
2174         variant field type \p variant_field_type (see
2175         bt_ctf_field_type_variant_get_field_count()).
2176 @postrefcountsame{variant_field_type}
2177 @post <strong>On success</strong>, the returned field's type is placed
2178         in \p *field_type and its reference count is incremented.
2179
2180 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2181         field type's field by name.
2182 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2183         field type's field by current tag value.
2184 */
2185 extern int bt_ctf_field_type_variant_get_field(
2186                 struct bt_ctf_field_type *variant_field_type,
2187                 const char **field_name,
2188                 struct bt_ctf_field_type **field_type, int index);
2189
2190 /**
2191 @brief  Returns the type of the field (choice) named \p field_name
2192         found in the @varft \p variant_field_type.
2193
2194 @param[in] variant_field_type   Variant field type of which to get
2195                                 a field's type.
2196 @param[in] field_name           Name of the field to find.
2197 @returns                        Type of the field named \p field_name in
2198                                 \p variant_field_type, or
2199                                 \c NULL on error.
2200
2201 @prenotnull{variant_field_type}
2202 @prenotnull{field_name}
2203 @preisvarft{variant_field_type}
2204 @postrefcountsame{variant_field_type}
2205 @postsuccessrefcountretinc
2206
2207 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2208         field by index.
2209 @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant
2210         field type's field by current tag value.
2211 */
2212 extern
2213 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
2214                 struct bt_ctf_field_type *variant_field_type,
2215                 const char *field_name);
2216
2217 /**
2218 @brief  Returns the type of the field (choice) selected by the value of
2219         the @enumfield \p tag_field in the @varft \p variant_field_type.
2220
2221 \p tag_field is the current tag value.
2222
2223 The field type of \p tag_field, as returned by bt_ctf_field_get_type(),
2224 \em must be equivalent to the field type returned by
2225 bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type.
2226
2227 @param[in] variant_field_type   Variant field type of which to get
2228                                 a field's type.
2229 @param[in] tag_field            Current tag value (variant field type's
2230                                 selector).
2231 @returns                        Type of the field selected by
2232                                 \p tag_field in \p variant_field_type,
2233                                 or \c NULL on error.
2234
2235 @prenotnull{variant_field_type}
2236 @prenotnull{tag_field}
2237 @preisvarft{variant_field_type}
2238 @preisenumfield{tag_field}
2239 @postrefcountsame{variant_field_type}
2240 @postrefcountsame{tag_field}
2241 @postsuccessrefcountretinc
2242
2243 @sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's
2244         field by index.
2245 @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant
2246         field type's field by name.
2247 */
2248 extern
2249 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
2250                 struct bt_ctf_field_type *variant_field_type,
2251                 struct bt_ctf_field *tag_field);
2252
2253 /**
2254 @brief  Adds a field (a choice) named \p field_name with the @ft
2255         \p field_type to the @varft \p variant_field_type.
2256
2257 On success, \p field_type becomes the child of \p variant_field_type.
2258
2259 You \em cannot add a field named \p field_name if there's already a
2260 field named \p field_name in \p variant_field_type.
2261
2262 \p field_name \em must name an existing mapping in the tag's
2263 enumeration field type of \p variant_field_type.
2264
2265 @param[in] variant_field_type   Variant field type to which to add
2266                                 a new field.
2267 @param[in] field_type           Field type of the field to add to
2268                                 \p variant_field_type.
2269 @param[in] field_name           Name of the field to add to
2270                                 \p variant_field_type
2271                                 (copied on success).
2272 @returns                        0 on success, or a negative value on error.
2273
2274 @prenotnull{variant_field_type}
2275 @prenotnull{field_type}
2276 @prenotnull{field_name}
2277 @preisvarft{variant_field_type}
2278 @pre \p field_type is not and does not contain \p variant_field_type,
2279         recursively, as a field's type.
2280 @prehot{variant_field_type}
2281 @postrefcountsame{variant_field_type}
2282 @postsuccessrefcountinc{field_type}
2283 */
2284 extern int bt_ctf_field_type_variant_add_field(
2285                 struct bt_ctf_field_type *variant_field_type,
2286                 struct bt_ctf_field_type *field_type,
2287                 const char *field_name);
2288
2289 /** @} */
2290
2291 #ifdef __cplusplus
2292 }
2293 #endif
2294
2295 #endif /* BABELTRACE_CTF_IR_FIELD_TYPES_H */