lib/babeltrace/ctf-ir/event-types.h

   1 #ifndef BABELTRACE_CTF_IR_EVENT_TYPES_H
   2 #define BABELTRACE_CTF_IR_EVENT_TYPES_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event 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 <babeltrace/ctf/events.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_ctf_event_class;
  41 struct bt_ctf_event;
  42 struct bt_ctf_field_type;
  43 struct bt_ctf_field;
  44
  45 enum bt_ctf_integer_base {
  46         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
  47         BT_CTF_INTEGER_BASE_BINARY = 2,
  48         BT_CTF_INTEGER_BASE_OCTAL = 8,
  49         BT_CTF_INTEGER_BASE_DECIMAL = 10,
  50         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
  51 };
  52
  53 enum bt_ctf_byte_order {
  54         BT_CTF_BYTE_ORDER_UNKNOWN = -1,
  55         BT_CTF_BYTE_ORDER_NATIVE = 0,
  56         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
  57         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
  58         BT_CTF_BYTE_ORDER_NETWORK,
  59 };
  60
  61 /*
  62  * bt_ctf_field_type_integer_create: create an integer field type.
  63  *
  64  * Allocate a new integer field type of the given size. The creation of a field
  65  * type sets its reference countto 1.
  66  *
  67  * @param size Integer field type size/length in bits.
  68  *
  69  * Returns an allocated field type on success, NULL on error.
  70  */
  71 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
  72                 unsigned int size);
  73
  74 /*
  75  * bt_ctf_field_type_integer_get_size: get an integer type's size.
  76  *
  77  * Get an integer type's size.
  78  *
  79  * @param integer Integer type.
  80  *
  81  * Returns the integer type's size, a negative value on error.
  82  */
  83 extern int bt_ctf_field_type_integer_get_size(
  84                 struct bt_ctf_field_type *integer);
  85
  86 /*
  87  * bt_ctf_field_type_integer_get_signed: get an integer type's signedness.
  88  *
  89  * Get an integer type's signedness attribute.
  90  *
  91  * @param integer Integer type.
  92  *
  93  * Returns the integer's signedness, a negative value on error.
  94  */
  95 extern int bt_ctf_field_type_integer_get_signed(
  96                 struct bt_ctf_field_type *integer);
  97
  98 /*
  99  * bt_ctf_field_type_integer_set_signed: set an integer type's signedness.
 100  *
 101  * Set an integer type's signedness attribute.
 102  *
 103  * @param integer Integer type.
 104  * @param is_signed Integer's signedness, defaults to FALSE.
 105  *
 106  * Returns 0 on success, a negative value on error.
 107  */
 108 extern int bt_ctf_field_type_integer_set_signed(
 109                 struct bt_ctf_field_type *integer, int is_signed);
 110
 111 /*
 112  * bt_ctf_field_type_integer_get_base: get an integer type's base.
 113  *
 114  * Get an integer type's base used to pretty-print the resulting trace.
 115  *
 116  * @param integer Integer type.
 117  *
 118  * Returns the integer type's base on success, BT_CTF_INTEGER_BASE_UNKNOWN on
 119  *      error.
 120  */
 121 extern enum bt_ctf_integer_base bt_ctf_field_type_integer_get_base(
 122                 struct bt_ctf_field_type *integer);
 123
 124 /*
 125  * bt_ctf_field_type_integer_set_base: set an integer type's base.
 126  *
 127  * Set an integer type's base used to pretty-print the resulting trace.
 128  *
 129  * @param integer Integer type.
 130  * @param base Integer base, defaults to BT_CTF_INTEGER_BASE_DECIMAL.
 131  *
 132  * Returns 0 on success, a negative value on error.
 133  */
 134 extern int bt_ctf_field_type_integer_set_base(struct bt_ctf_field_type *integer,
 135                 enum bt_ctf_integer_base base);
 136
 137 /*
 138  * bt_ctf_field_type_integer_get_encoding: get an integer type's encoding.
 139  *
 140  * @param integer Integer type.
 141  *
 142  * Returns the string field's encoding on success, CTF_STRING_UNKNOWN on error.
 143  */
 144 extern enum ctf_string_encoding bt_ctf_field_type_integer_get_encoding(
 145                 struct bt_ctf_field_type *integer);
 146
 147 /*
 148  * bt_ctf_field_type_integer_set_encoding: set an integer type's encoding.
 149  *
 150  * An integer encoding may be set to signal that the integer must be printed as
 151  * a text character.
 152  *
 153  * @param integer Integer type.
 154  * @param encoding Integer output encoding, defaults to CTF_STRING_ENCODING_NONE
 155  *
 156  * Returns 0 on success, a negative value on error.
 157  */
 158 extern int bt_ctf_field_type_integer_set_encoding(
 159                 struct bt_ctf_field_type *integer,
 160                 enum ctf_string_encoding encoding);
 161
 162 /*
 163  * bt_ctf_field_type_enumeration_create: create an enumeration field type.
 164  *
 165  * Allocate a new enumeration field type with the given underlying type. The
 166  * creation of a field type sets its reference count to 1.
 167  * The resulting enumeration will share the integer_container_type's ownership
 168  * by increasing its reference count.
 169  *
 170  * @param integer_container_type Underlying integer type of the enumeration
 171  *      type.
 172  *
 173  * Returns an allocated field type on success, NULL on error.
 174  */
 175 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
 176                 struct bt_ctf_field_type *integer_container_type);
 177
 178 /*
 179  * bt_ctf_field_type_enumeration_get_container_type: get underlying container.
 180  *
 181  * Get the enumeration type's underlying integer container type.
 182  *
 183  * @param enumeration Enumeration type.
 184  *
 185  * Returns an allocated field type on success, NULL on error.
 186  */
 187 extern
 188 struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type(
 189                 struct bt_ctf_field_type *enumeration);
 190
 191 /*
 192  * bt_ctf_field_type_enumeration_add_mapping: add an enumeration mapping.
 193  *
 194  * Add a mapping to the enumeration. The range's values are inclusive.
 195  *
 196  * @param enumeration Enumeration type.
 197  * @param name Enumeration mapping name (will be copied).
 198  * @param range_start Enumeration mapping range start.
 199  * @param range_end Enumeration mapping range end.
 200  *
 201  * Returns 0 on success, a negative value on error.
 202  */
 203 extern int bt_ctf_field_type_enumeration_add_mapping(
 204                 struct bt_ctf_field_type *enumeration, const char *name,
 205                 int64_t range_start, int64_t range_end);
 206
 207 /*
 208  * bt_ctf_field_type_enumeration_add_mapping_unsigned: add an enumeration
 209  *      mapping.
 210  *
 211  * Add a mapping to the enumeration. The range's values are inclusive.
 212  *
 213  * @param enumeration Enumeration type.
 214  * @param name Enumeration mapping name (will be copied).
 215  * @param range_start Enumeration mapping range start.
 216  * @param range_end Enumeration mapping range end.
 217  *
 218  * Returns 0 on success, a negative value on error.
 219  */
 220 extern int bt_ctf_field_type_enumeration_add_mapping_unsigned(
 221                 struct bt_ctf_field_type *enumeration, const char *name,
 222                 uint64_t range_start, uint64_t range_end);
 223
 224 /*
 225  * bt_ctf_field_type_enumeration_get_mapping_count: Get the number of mappings
 226  *      defined in the enumeration.
 227  *
 228  * @param enumeration Enumeration type.
 229  *
 230  * Returns the mapping count on success, a negative value on error.
 231  */
 232 extern int64_t bt_ctf_field_type_enumeration_get_mapping_count(
 233                 struct bt_ctf_field_type *enumeration);
 234
 235 /*
 236  * bt_ctf_field_type_enumeration_get_mapping: get an enumeration mapping.
 237  *
 238  * @param enumeration Enumeration type.
 239  * @param index Index of mapping.
 240  * @param name Pointer where the mapping's name will be returned (valid for
 241  *      the lifetime of the enumeration).
 242  * @param range_start Pointer where the enumeration mapping's range start will
 243  *      be returned.
 244  * @param range_end Pointer where the enumeration mapping's range end will
 245  *      be returned.
 246  *
 247  * Returns 0 on success, a negative value on error.
 248  */
 249 extern int bt_ctf_field_type_enumeration_get_mapping(
 250                 struct bt_ctf_field_type *enumeration, size_t index,
 251                 const char **name, int64_t *range_start, int64_t *range_end);
 252
 253 /*
 254  * bt_ctf_field_type_enumeration_get_mapping_unsigned: get a mapping.
 255  *
 256  * @param enumeration Enumeration type.
 257  * @param index Index of mapping.
 258  * @param name Pointer where the mapping's name will be returned (valid for
 259  *      the lifetime of the enumeration).
 260  * @param range_start Pointer where the enumeration mapping's range start will
 261  *      be returned.
 262  * @param range_end Pointer where the enumeration mapping's range end will
 263  *      be returned.
 264  *
 265  * Returns 0 on success, a negative value on error.
 266  */
 267 extern int bt_ctf_field_type_enumeration_get_mapping_unsigned(
 268                 struct bt_ctf_field_type *enumeration, size_t index,
 269                 const char **name, uint64_t *range_start,
 270                 uint64_t *range_end);
 271
 272 /*
 273  * bt_ctf_field_type_enumeration_get_mapping_index_by_name: get an enumerations'
 274  *      mapping index by name.
 275  *
 276  * @param enumeration Enumeration type.
 277  * @param name Mapping name.
 278  * @param index Pointer where the enumeration's mapping index will be returned.
 279  *
 280  * Returns 0 on success, a negative value on error.
 281  */
 282 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name(
 283                 struct bt_ctf_field_type *enumeration, const char *name,
 284                 size_t *index);
 285
 286 /*
 287  * bt_ctf_field_type_enumeration_get_mapping_index_by_value: get an
 288  *      enumerations' mapping index by value.
 289  *
 290  * @param enumeration Enumeration type.
 291  * @param value Value.
 292  * @param index Pointer where the enumeration's mapping index will be returned.
 293  *
 294  * Returns 0 on success, a negative value on error.
 295  */
 296 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value(
 297                 struct bt_ctf_field_type *enumeration, int64_t value,
 298                 size_t *index);
 299
 300 /*
 301  * bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value: get an
 302  *      enumerations' mapping index by value.
 303  *
 304  * @param enumeration Enumeration type.
 305  * @param value Value.
 306  * @param index Pointer where the enumeration's mapping index will be returned.
 307  *
 308  * Returns 0 on success, a negative value on error.
 309  */
 310 extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(
 311                 struct bt_ctf_field_type *enumeration, uint64_t value,
 312                 size_t *index);
 313
 314 /*
 315  * bt_ctf_field_type_floating_point_create: create a floating point field type.
 316  *
 317  * Allocate a new floating point field type. The creation of a field type sets
 318  * its reference count to 1.
 319  *
 320  * Returns an allocated field type on success, NULL on error.
 321  */
 322 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
 323
 324 /*
 325  * bt_ctf_field_type_floating_point_get_exponent_digits: get exponent digit
 326  *      count.
 327  *
 328  * @param floating_point Floating point type.
 329  *
 330  * Returns the exponent digit count on success, a negative value on error.
 331  */
 332 extern int bt_ctf_field_type_floating_point_get_exponent_digits(
 333                 struct bt_ctf_field_type *floating_point);
 334
 335 /*
 336  * bt_ctf_field_type_floating_point_set_exponent_digits: set exponent digit
 337  *      count.
 338  *
 339  * Set the number of exponent digits to use to store the floating point field.
 340  * The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG.
 341  *
 342  * @param floating_point Floating point type.
 343  * @param exponent_digits Number of digits to allocate to the exponent (defaults
 344  *      to FLT_EXP_DIG).
 345  *
 346  * Returns 0 on success, a negative value on error.
 347  */
 348 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
 349                 struct bt_ctf_field_type *floating_point,
 350                 unsigned int exponent_digits);
 351
 352 /*
 353  * bt_ctf_field_type_floating_point_get_mantissa_digits: get mantissa digit
 354  * count.
 355  *
 356  * @param floating_point Floating point type.
 357  *
 358  * Returns the mantissa digit count on success, a negative value on error.
 359  */
 360 extern int bt_ctf_field_type_floating_point_get_mantissa_digits(
 361                 struct bt_ctf_field_type *floating_point);
 362
 363 /*
 364  * bt_ctf_field_type_floating_point_set_mantissa_digits: set mantissa digit
 365  *      count.
 366  *
 367  * Set the number of mantissa digits to use to store the floating point field.
 368  * The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG.
 369  *
 370  * @param floating_point Floating point type.
 371  * @param mantissa_digits Number of digits to allocate to the mantissa (defaults
 372  *      to FLT_MANT_DIG).
 373  *
 374  * Returns 0 on success, a negative value on error.
 375  */
 376 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
 377                 struct bt_ctf_field_type *floating_point,
 378                 unsigned int mantissa_digits);
 379
 380 /*
 381  * bt_ctf_field_type_structure_create: create a structure field type.
 382  *
 383  * Allocate a new structure field type. The creation of a field type sets
 384  * its reference count to 1.
 385  *
 386  * Returns an allocated field type on success, NULL on error.
 387  */
 388 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
 389
 390 /*
 391  * bt_ctf_field_type_structure_add_field: add a field to a structure.
 392  *
 393  * Add a field of type "field_type" to the structure. The structure will share
 394  * field_type's ownership by increasing its reference count.
 395  *
 396  * @param structure Structure type.
 397  * @param field_type Type of the field to add to the structure type.
 398  * @param field_name Name of the structure's new field (will be copied).
 399  *
 400  * Returns 0 on success, a negative value on error.
 401  */
 402 extern int bt_ctf_field_type_structure_add_field(
 403                 struct bt_ctf_field_type *structure,
 404                 struct bt_ctf_field_type *field_type,
 405                 const char *field_name);
 406
 407 /*
 408  * bt_ctf_field_type_structure_get_field_count: Get the number of fields defined
 409  *      in the structure.
 410  *
 411  * @param structure Structure type.
 412  *
 413  * Returns the field count on success, a negative value on error.
 414  */
 415 extern int64_t bt_ctf_field_type_structure_get_field_count(
 416                 struct bt_ctf_field_type *structure);
 417
 418 /*
 419  * bt_ctf_field_type_structure_get_field: get a structure's field type and name.
 420  *
 421  * @param structure Structure type.
 422  * @param field_type Pointer to a const char* where the field's name will
 423  *      be returned.
 424  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 425  *      be returned.
 426  * @param index Index of field.
 427  *
 428  * Returns 0 on success, a negative value on error.
 429  */
 430 extern int bt_ctf_field_type_structure_get_field(
 431                 struct bt_ctf_field_type *structure,
 432                 const char **field_name, struct bt_ctf_field_type **field_type,
 433                 size_t index);
 434
 435 /*
 436  * bt_ctf_field_type_structure_get_field_type_by_name: get a structure field's
 437  *      type by name.
 438  *
 439  * @param structure Structure type.
 440  * @param field_name Name of the structure's field.
 441  *
 442  * Returns a field type instance on success, NULL on error.
 443  */
 444 extern
 445 struct bt_ctf_field_type *bt_ctf_field_type_structure_get_field_type_by_name(
 446                 struct bt_ctf_field_type *structure, const char *field_name);
 447
 448 /*
 449  * bt_ctf_field_type_variant_create: create a variant field type.
 450  *
 451  * Allocate a new variant field type. The creation of a field type sets
 452  * its reference count to 1. tag_name must be the name of an enumeration
 453  * field declared in the same scope as this variant.
 454  *
 455  * @param enum_tag Type of the variant's tag/selector (must be an enumeration).
 456  * @param tag_name Name of the variant's tag/selector field (will be copied).
 457  *
 458  * Returns an allocated field type on success, NULL on error.
 459  */
 460 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
 461                 struct bt_ctf_field_type *enum_tag, const char *tag_name);
 462
 463 /*
 464  * bt_ctf_field_type_variant_get_tag_type: get a variant's tag type.
 465  *
 466  * @param variant Variant type.
 467  *
 468  * Returns a field type instance on success, NULL on error.
 469  */
 470 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_get_tag_type(
 471                 struct bt_ctf_field_type *variant);
 472
 473 /*
 474  * bt_ctf_field_type_variant_get_tag_name: get a variant's tag name.
 475  *
 476  * @param variant Variant type.
 477  *
 478  * Returns the tag field's name, NULL on error.
 479  */
 480 extern const char *bt_ctf_field_type_variant_get_tag_name(
 481                 struct bt_ctf_field_type *variant);
 482
 483 /*
 484  * bt_ctf_field_type_variant_add_field: add a field to a variant.
 485  *
 486  * Add a field of type "field_type" to the variant. The variant will share
 487  * field_type's ownership by increasing its reference count. The "field_name"
 488  * will be copied. field_name must match a mapping in the tag/selector
 489  * enumeration.
 490  *
 491  * @param variant Variant type.
 492  * @param field_type Type of the variant type's new field.
 493  * @param field_name Name of the variant type's new field (will be copied).
 494  *
 495  * Returns 0 on success, a negative value on error.
 496  */
 497 extern int bt_ctf_field_type_variant_add_field(
 498                 struct bt_ctf_field_type *variant,
 499                 struct bt_ctf_field_type *field_type,
 500                 const char *field_name);
 501
 502 /*
 503  * bt_ctf_field_type_variant_get_field_type_by_name: get variant field's type.
 504  *
 505  * @param structure Variant type.
 506  * @param field_name Name of the variant's field.
 507  *
 508  * Returns a field type instance on success, NULL on error.
 509  */
 510 extern
 511 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_by_name(
 512                 struct bt_ctf_field_type *variant, const char *field_name);
 513
 514 /*
 515  * bt_ctf_field_type_variant_get_field_type_from_tag: get variant field's type.
 516  *
 517  * @param variant Variant type.
 518  * @param tag Type tag (enum).
 519  *
 520  * Returns a field type instance on success, NULL on error.
 521  */
 522 extern
 523 struct bt_ctf_field_type *bt_ctf_field_type_variant_get_field_type_from_tag(
 524                 struct bt_ctf_field_type *variant, struct bt_ctf_field *tag);
 525
 526 /*
 527  * bt_ctf_field_type_variant_get_field_count: Get the number of fields defined
 528  *      in the variant.
 529  *
 530  * @param variant Variant type.
 531  *
 532  * Returns the field count on success, a negative value on error.
 533  */
 534 extern int64_t bt_ctf_field_type_variant_get_field_count(
 535                 struct bt_ctf_field_type *variant);
 536
 537 /*
 538  * bt_ctf_field_type_variant_get_field: get a variant's field name and type.
 539  *
 540  * @param variant Variant type.
 541  * @param field_type Pointer to a const char* where the field's name will
 542  *      be returned.
 543  * @param field_type Pointer to a bt_ctf_field_type* where the field's type will
 544  *      be returned.
 545  * @param index Index of field.
 546  *
 547  * Returns 0 on success, a negative value on error.
 548  */
 549 extern int bt_ctf_field_type_variant_get_field(
 550                 struct bt_ctf_field_type *variant, const char **field_name,
 551                 struct bt_ctf_field_type **field_type, size_t index);
 552
 553 /*
 554  * bt_ctf_field_type_array_create: create an array field type.
 555  *
 556  * Allocate a new array field type. The creation of a field type sets
 557  * its reference count to 1.
 558  *
 559  * @param element_type Array's element type.
 560  * @oaram length Array type's length.
 561  *
 562  * Returns an allocated field type on success, NULL on error.
 563  */
 564 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
 565                 struct bt_ctf_field_type *element_type, unsigned int length);
 566
 567 /*
 568  * bt_ctf_field_type_array_get_element_type: get an array's element type.
 569  *
 570  * @param array Array type.
 571  *
 572  * Returns a field type instance on success, NULL on error.
 573  */
 574 extern struct bt_ctf_field_type *bt_ctf_field_type_array_get_element_type(
 575                 struct bt_ctf_field_type *array);
 576
 577 /*
 578  * bt_ctf_field_type_array_get_length: get an array's length.
 579  *
 580  * @param array Array type.
 581  *
 582  * Returns the array's length on success, a negative value on error.
 583  */
 584 extern int64_t bt_ctf_field_type_array_get_length(
 585                 struct bt_ctf_field_type *array);
 586
 587 /*
 588  * bt_ctf_field_type_sequence_create: create a sequence field type.
 589  *
 590  * Allocate a new sequence field type. The creation of a field type sets
 591  * its reference count to 1. "length_field_name" must match an integer field
 592  * declared in the same scope.
 593  *
 594  * @param element_type Sequence's element type.
 595  * @param length_field_name Name of the sequence's length field (will be
 596  *      copied).
 597  *
 598  * Returns an allocated field type on success, NULL on error.
 599  */
 600 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
 601                 struct bt_ctf_field_type *element_type,
 602                 const char *length_field_name);
 603
 604 /*
 605  * bt_ctf_field_type_sequence_get_element_type: get a sequence's element type.
 606  *
 607  * @param sequence Sequence type.
 608  *
 609  * Returns a field type instance on success, NULL on error.
 610  */
 611 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_get_element_type(
 612                 struct bt_ctf_field_type *sequence);
 613
 614 /*
 615  * bt_ctf_field_type_sequence_get_length_field_name: get length field name.
 616  *
 617  * @param sequence Sequence type.
 618  *
 619  * Returns the sequence's length field on success, NULL on error.
 620  */
 621 extern const char *bt_ctf_field_type_sequence_get_length_field_name(
 622                 struct bt_ctf_field_type *sequence);
 623
 624 /*
 625  * bt_ctf_field_type_string_create: create a string field type.
 626  *
 627  * Allocate a new string field type. The creation of a field type sets
 628  * its reference count to 1.
 629  *
 630  * Returns an allocated field type on success, NULL on error.
 631  */
 632 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
 633
 634 /*
 635  * bt_ctf_field_type_string_get_encoding: get a string type's encoding.
 636  *
 637  * Get the string type's encoding.
 638  *
 639  * @param string_type String type.
 640  *
 641  * Returns the string's encoding on success, a CTF_STRING_UNKNOWN on error.
 642  */
 643 extern enum ctf_string_encoding bt_ctf_field_type_string_get_encoding(
 644                 struct bt_ctf_field_type *string_type);
 645
 646 /*
 647  * bt_ctf_field_type_string_set_encoding: set a string type's encoding.
 648  *
 649  * Set the string type's encoding.
 650  *
 651  * @param string_type String type.
 652  * @param encoding String field encoding, default CTF_STRING_ENCODING_ASCII.
 653  *      Valid values are CTF_STRING_ENCODING_ASCII and CTF_STRING_ENCODING_UTF8.
 654  *
 655  * Returns 0 on success, a negative value on error.
 656  */
 657 extern int bt_ctf_field_type_string_set_encoding(
 658                 struct bt_ctf_field_type *string_type,
 659                 enum ctf_string_encoding encoding);
 660
 661 /*
 662  * bt_ctf_field_type_get_alignment: get a field type's alignment.
 663  *
 664  * Get the field type's alignment.
 665  *
 666  * @param type Field type.
 667  *
 668  * Returns the field type's alignment on success, a negative value on error.
 669  */
 670 extern int bt_ctf_field_type_get_alignment(struct bt_ctf_field_type *type);
 671
 672 /*
 673  * bt_ctf_field_type_set_alignment: set a field type's alignment.
 674  *
 675  * Set the field type's alignment.
 676  *
 677  * @param type Field type.
 678  * @param alignment Type's alignment. Defaults to 1 (bit-aligned). However,
 679  *      some types, such as structures and string, may impose other alignment
 680  *      constraints.
 681  *
 682  * Returns 0 on success, a negative value on error.
 683  */
 684 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *type,
 685                 unsigned int alignment);
 686
 687 /*
 688  * bt_ctf_field_type_get_byte_order: get a field type's byte order.
 689  *
 690  * @param type Field type.
 691  *
 692  * Returns the field type's byte order on success, a negative value on error.
 693  */
 694 extern enum bt_ctf_byte_order bt_ctf_field_type_get_byte_order(
 695                 struct bt_ctf_field_type *type);
 696
 697 /*
 698  * bt_ctf_field_type_set_byte_order: set a field type's byte order.
 699  *
 700  * Set the field type's byte order.
 701  *
 702  * @param type Field type.
 703  * @param byte_order Field type's byte order. Defaults to
 704  * BT_CTF_BYTE_ORDER_NATIVE, the host machine's endianness.
 705  *
 706  * Returns 0 on success, a negative value on error.
 707  */
 708 extern int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type,
 709                 enum bt_ctf_byte_order byte_order);
 710
 711 /*
 712  * bt_ctf_field_type_get_type_id: get a field type's ctf_type_id.
 713  *
 714  * @param type Field type.
 715  *
 716  * Returns the field type's ctf_type_id, CTF_TYPE_UNKNOWN on error.
 717  */
 718 extern enum ctf_type_id bt_ctf_field_type_get_type_id(
 719                 struct bt_ctf_field_type *type);
 720
 721 /*
 722  * bt_ctf_field_type_get and bt_ctf_field_type_put: increment and decrement
 723  * the field type's reference count.
 724  *
 725  * These functions ensure that the field type won't be destroyed while it
 726  * is in use. The same number of get and put (plus one extra put to
 727  * release the initial reference done at creation) have to be done to
 728  * destroy a field type.
 729  *
 730  * When the field type's reference count is decremented to 0 by a
 731  * bt_ctf_field_type_put, the field type is freed.
 732  *
 733  * @param type Field type.
 734  */
 735 extern void bt_ctf_field_type_get(struct bt_ctf_field_type *type);
 736 extern void bt_ctf_field_type_put(struct bt_ctf_field_type *type);
 737
 738 #ifdef __cplusplus
 739 }
 740 #endif
 741
 742 #endif /* BABELTRACE_CTF_IR_EVENT_TYPES_H */