include/babeltrace/ctf-ir/trace.h

   1 #ifndef BABELTRACE_CTF_IR_TRACE_H
   2 #define BABELTRACE_CTF_IR_TRACE_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Trace
   6  *
   7  * Copyright 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-ir/field-types.h>
  34 #include <babeltrace/ctf-ir/visitor.h>
  35 #include <babeltrace/values.h>
  36 #include <babeltrace/graph/notification.h>
  37 #include <stdint.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44 @defgroup ctfirtraceclass CTF IR trace class
  45 @ingroup ctfir
  46 @brief CTF IR trace class.
  47
  48 @code
  49 #include <babeltrace/ctf-ir/trace.h>
  50 @endcode
  51
  52 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
  53 traces.
  54
  55 You can obtain a trace class in two different modes:
  56
  57 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
  58   default, empty trace class.
  59 - <strong>CTF writer mode</strong>: use bt_ctf_writer_get_trace() to
  60   get the trace class created by a given CTF writer object.
  61
  62 A trace class has the following properties:
  63
  64 - A \b name.
  65 - A <strong>default byte order</strong>: all the
  66   \link ctfirfieldtypes field types\endlink eventually part of the trace
  67   class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
  68   "real" byte order.
  69 - An \b environment, which is a custom key-value mapping. Keys are
  70   strings and values can be strings or integers.
  71
  72 In the Babeltrace CTF IR system, a trace class contains zero or more
  73 \link ctfirstreamclass stream classes\endlink, and a stream class
  74 contains zero or more \link ctfireventclass event classes\endlink. You
  75 can add an event class to a stream class with
  76 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
  77 trace class with bt_ctf_trace_add_stream_class().
  78
  79 You can access the streams of a trace, that is, the streams which were
  80 created from the trace's stream classes with bt_ctf_stream_create(),
  81 with bt_ctf_trace_get_stream().
  82
  83 A trace class owns the <strong>trace packet header</strong>
  84 \link ctfirfieldtypes field type\endlink, which represents the
  85 \c trace.packet.header CTF scope. This field type describes the
  86 trace packet header fields of the traces that this trace class
  87 describes.
  88
  89 The trace packet header field type \em must be a structure field type as
  90 of Babeltrace \btversion.
  91
  92 As per the CTF specification, the trace packet header field type \em
  93 must contain a field named \c stream_id if the trace class contains more
  94 than one stream class.
  95
  96 As a reminder, here's the structure of a CTF packet:
  97
  98 @imgpacketstructure
  99
 100 A trace class also contains zero or more
 101 \link ctfirclockclass CTF IR clock classes\endlink.
 102
 103 @todo
 104 Elaborate about clock classes irt clock values.
 105
 106 As with any Babeltrace object, CTF IR trace class objects have
 107 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
 108 counts</a>. See \ref refs to learn more about the reference counting
 109 management of Babeltrace objects.
 110
 111 The following functions \em freeze their trace class parameter on
 112 success:
 113
 114 - bt_ctf_trace_add_stream_class()
 115 - bt_ctf_writer_create_stream()
 116   (\link ctfwriter CTF writer\endlink mode only)
 117
 118 You cannot modify a frozen trace class: it is considered immutable,
 119 except for:
 120
 121 - Adding a stream class to it with
 122   bt_ctf_trace_add_stream_class().
 123 - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class().
 124 - \link refs Reference counting\endlink.
 125
 126 You can add a custom listener with bt_ctf_trace_add_listener() to get
 127 notified if anything changes in a trace class, that is, if an event
 128 class is added to one of its stream class, if a stream class is added,
 129 or if a clock class is added.
 130
 131 @sa ctfirstreamclass
 132 @sa ctfireventclass
 133 @sa ctfirclockclass
 134
 135 @file
 136 @brief CTF IR trace class type and functions.
 137 @sa ctfirtraceclass
 138
 139 @addtogroup ctfirtraceclass
 140 @{
 141 */
 142
 143 /**
 144 @struct bt_ctf_trace
 145 @brief A CTF IR trace class.
 146 @sa ctfirtraceclass
 147 */
 148 struct bt_ctf_trace;
 149 struct bt_ctf_stream;
 150 struct bt_ctf_stream_class;
 151 struct bt_ctf_clock_class;
 152
 153 /**
 154 @name Creation function
 155 @{
 156 */
 157
 158 /**
 159 @brief  Creates a default CTF IR trace class.
 160
 161 On success, the trace packet header field type of the created trace
 162 class has the following fields:
 163
 164 - <code>magic</code>: a 32-bit unsigned integer field type.
 165 - <code>uuid</code>: an array field type of 16 8-bit unsigned integer
 166   field types.
 167 - <code>stream_id</code>: a 32-bit unsigned integer field type.
 168
 169 You can modify this default trace packet header field type after the
 170 trace class is created with bt_ctf_trace_set_packet_header_type().
 171
 172 The created trace class has the following initial properties:
 173
 174 - <strong>Name</strong>: none. You can set a name
 175   with bt_ctf_trace_set_name().
 176 - <strong>Default byte order</strong>: #BT_CTF_BYTE_ORDER_NATIVE. You
 177   can set a default byte order with bt_ctf_trace_set_native_byte_order().
 178
 179   Note that you \em must set the default byte order if any field type
 180   contained in the created trace class, in its stream classes, or in
 181   its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE.
 182 - <strong>Environment</strong>: empty. You can add environment entries
 183   with bt_ctf_trace_set_environment_field(),
 184   bt_ctf_trace_set_environment_field_integer(), and
 185   bt_ctf_trace_set_environment_field_string().
 186
 187 @returns        Created trace class, or \c NULL on error.
 188
 189 @postsuccessrefcountret1
 190 */
 191 extern struct bt_ctf_trace *bt_ctf_trace_create(void);
 192
 193 /** @} */
 194
 195 /**
 196 @name Properties functions
 197 @{
 198 */
 199
 200 /**
 201 @brief  Returns the name of the CTF IR trace class \p trace_class.
 202
 203 On success, \p trace_class remains the sole owner of the returned
 204 string. The returned string is valid as long as \p trace_class exists
 205 and is not modified.
 206
 207 @param[in] trace_class  Trace class of which to get the name.
 208 @returns                Name of trace class \p trace_class, or
 209                         \c NULL if \p trace_class is unnamed or
 210                         on error.
 211
 212 @prenotnull{trace_class}
 213 @postrefcountsame{trace_class}
 214
 215 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
 216 */
 217 extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace *trace_class);
 218
 219 /**
 220 @brief  Sets the name of the CTF IR trace class \p trace_class
 221         to \p name.
 222
 223 @param[in] trace_class  Trace class of which to set the name.
 224 @param[in] name         Name of the trace class (copied on success).
 225 @returns                0 on success, or a negative value on error.
 226
 227 @prenotnull{trace_class}
 228 @prenotnull{name}
 229 @prehot{trace_class}
 230 @postrefcountsame{trace_class}
 231
 232 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
 233 */
 234 extern int bt_ctf_trace_set_name(struct bt_ctf_trace *trace_class,
 235                 const char *name);
 236
 237 /**
 238 @brief  Returns the default byte order of the CTF IR trace class
 239         \p trace_class.
 240
 241 @param[in] trace_class  Trace class of which to get the default byte
 242                         order.
 243 @returns                Default byte order of trace class
 244                         \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN
 245                         on error.
 246
 247 @prenotnull{trace_class}
 248 @postrefcountsame{trace_class}
 249
 250 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
 251 */
 252 extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order(
 253                 struct bt_ctf_trace *trace_class);
 254
 255 /**
 256 @brief  Sets the default byte order of the CTF IR trace class
 257         \p trace_class to \p native_byte_order.
 258
 259 \p native_byte_order \em must be one of:
 260
 261 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
 262 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
 263 - #BT_CTF_BYTE_ORDER_NETWORK
 264
 265 @param[in] trace_class          Trace class of which to set the default byte
 266                                 order.
 267 @param[in] native_byte_order    Default byte order of the trace class.
 268 @returns                        0 on success, or a negative value on error.
 269
 270 @prenotnull{trace_class}
 271 @prenotnull{name}
 272 @prehot{trace_class}
 273 @pre \p native_byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
 274         #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
 275         #BT_CTF_BYTE_ORDER_NETWORK.
 276 @postrefcountsame{trace_class}
 277
 278 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
 279 */
 280 extern int bt_ctf_trace_set_native_byte_order(struct bt_ctf_trace *trace_class,
 281                 enum bt_ctf_byte_order native_byte_order);
 282
 283 /**
 284 @brief  Returns the number of entries contained in the environment of
 285         the CTF IR trace class \p trace_class.
 286
 287 @param[in] trace_class  Trace class of which to get the number
 288                         of environment entries.
 289 @returns                Number of environment entries
 290                         contained in \p trace_class, or
 291                         a negative value on error.
 292
 293 @prenotnull{trace_class}
 294 @postrefcountsame{trace_class}
 295 */
 296 extern int bt_ctf_trace_get_environment_field_count(
 297                 struct bt_ctf_trace *trace_class);
 298
 299 /**
 300 @brief  Returns the field name of the environment entry at index
 301         \p index in the CTF IR trace class \p trace_class.
 302
 303 On success, the returned string is valid as long as this trace class
 304 exists and is \em not modified. \p trace_class remains the sole owner of
 305 the returned string.
 306
 307 @param[in] trace_class  Trace class of which to get the name of the
 308                         environment entry at index \p index.
 309 @param[in] index        Index of environment entry to find.
 310 @returns                Name of the environment entry at index \p index
 311                         in \p trace_class, or \c NULL on error.
 312
 313 @prenotnull{trace_class}
 314 @pre \p index is lesser than the number of environment entries in
 315         \p trace_class (see bt_ctf_trace_get_environment_field_count()).
 316 @postrefcountsame{trace_class}
 317
 318 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
 319         environment entry by index.
 320 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 321         class's environment entry by name.
 322 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 323         class's environment entry.
 324 */
 325 extern const char *
 326 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace_class,
 327                 int index);
 328
 329 /**
 330 @brief  Returns the value of the environment entry at index
 331         \p index in the CTF IR trace class \p trace_class.
 332
 333 @param[in] trace_class  Trace class of which to get the value of the
 334                         environment entry at index \p index.
 335 @param[in] index        Index of the environment entry to find.
 336 @returns                Value of the environment entry at index \p index
 337                         in \p trace_class, or \c NULL on error.
 338
 339 @prenotnull{trace_class}
 340 @pre \p index is lesser than the number of environment entries in
 341         \p trace_class (see bt_ctf_trace_get_environment_field_count()).
 342 @postrefcountsame{trace_class}
 343 @postsuccessrefcountretinc
 344
 345 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 346         class's environment entry by name.
 347 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 348         class's environment entry.
 349 */
 350 extern struct bt_value *
 351 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace_class,
 352                 int index);
 353
 354 /**
 355 @brief  Returns the value of the environment entry named \p name
 356         in the CTF IR trace class \p trace_class.
 357
 358 @param[in] trace_class  Trace class of which to get the value of the
 359                         environment entry named \p name.
 360 @param[in] name         Name of the environment entry to find.
 361 @returns                Value of the environment entry named \p name
 362                         in \p trace_class, or \c NULL if there's no such
 363                         entry or on error.
 364
 365 @prenotnull{trace_class}
 366 @prenotnull{name}
 367 @postrefcountsame{trace_class}
 368 @postsuccessrefcountretinc
 369
 370 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
 371         environment entry by index.
 372 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 373         class's environment entry.
 374 */
 375 extern struct bt_value *
 376 bt_ctf_trace_get_environment_field_value_by_name(
 377                 struct bt_ctf_trace *trace_class, const char *name);
 378
 379 /**
 380 @brief  Sets the environment entry named \p name in the
 381         CTF IR trace class \p trace_class to \p value.
 382
 383 If an environment entry named \p name exists in \p trace_class, its
 384 value is first put, and then replaced by \p value.
 385
 386 @param[in] trace_class  Trace class of which to set the environment
 387                         entry.
 388 @param[in] name         Name of the environment entry to set (copied
 389                         on success).
 390 @param[in] value        Value of the environment entry named \p name.
 391 @returns                0 on success, or a negative value on error.
 392
 393 @prenotnull{trace_class}
 394 @prenotnull{name}
 395 @prenotnull{value}
 396 @prehot{trace_class}
 397 @pre \p value is an
 398         \link bt_value_integer_create() integer value object\endlink
 399         or a
 400         \link bt_value_string_create() string value object\endlink.
 401 @postrefcountsame{trace_class}
 402 @postsuccessrefcountinc{value}
 403
 404 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
 405         environment entry by index.
 406 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
 407         class's environment entry by name.
 408 */
 409 extern int bt_ctf_trace_set_environment_field(
 410                 struct bt_ctf_trace *trace_class, const char *name,
 411                 struct bt_value *value);
 412
 413 /**
 414 @brief  Sets the environment entry named \p name in the
 415         CTF IR trace class \p trace_class to \p value.
 416
 417 If an environment entry named \p name exists in \p trace_class, its
 418 value is first put, and then replaced by a new
 419 \link bt_value_integer_create() integer value object\endlink
 420 containing \p value.
 421
 422 @param[in] trace_class  Trace class of which to set the environment
 423                         entry.
 424 @param[in] name         Name of the environment entry to set (copied
 425                         on success).
 426 @param[in] value        Value of the environment entry named \p name.
 427 @returns                0 on success, or a negative value on error.
 428
 429 @prenotnull{trace_class}
 430 @prenotnull{name}
 431 @prehot{trace_class}
 432 @postrefcountsame{trace_class}
 433
 434 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 435         class's environment entry.
 436 */
 437 extern int bt_ctf_trace_set_environment_field_integer(
 438                 struct bt_ctf_trace *trace_class, const char *name,
 439                 int64_t value);
 440
 441 /**
 442 @brief  Sets the environment entry named \p name in the
 443         CTF IR trace class \p trace_class to \p value.
 444
 445 If an environment entry named \p name exists in \p trace_class, its
 446 value is first put, and then replaced by a new
 447 \link bt_value_string_create() string value object\endlink
 448 containing \p value.
 449
 450 @param[in] trace_class  Trace class of which to set the environment
 451                         entry.
 452 @param[in] name         Name of the environment entry to set (copied
 453                         on success).
 454 @param[in] value        Value of the environment entry named \p name
 455                         (copied on success).
 456 @returns                0 on success, or a negative value on error.
 457
 458 @prenotnull{trace_class}
 459 @prenotnull{name}
 460 @prenotnull{value}
 461 @prehot{trace_class}
 462 @postrefcountsame{trace_class}
 463
 464 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
 465         class's environment entry.
 466 */
 467 extern int bt_ctf_trace_set_environment_field_string(
 468                 struct bt_ctf_trace *trace_class, const char *name,
 469                 const char *value);
 470
 471 /** @} */
 472
 473 /**
 474 @name Contained field types functions
 475 @{
 476 */
 477
 478 /**
 479 @brief  Returns the packet header field type of the CTF IR trace class
 480         \p trace_class.
 481
 482 @param[in] trace_class  Trace class of which to get the packet
 483                         header field type.
 484 @returns                Packet header field type of \p trace_class,
 485                         or \c NULL if \p trace_class has no packet header field
 486                         type or on error.
 487
 488 @prenotnull{trace_class}
 489 @postrefcountsame{trace_class}
 490 @post <strong>On success, if the return value is a field type</strong>, its
 491         reference count is incremented.
 492
 493 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
 494         header field type of a given trace class.
 495 */
 496 extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
 497                 struct bt_ctf_trace *trace_class);
 498
 499 /**
 500 @brief  Sets the packet header field type of the CTF IR trace class
 501         \p trace_class to \p packet_header_type, or unsets the current packet
 502         header field type from \p trace_class.
 503
 504 If \p packet_header_type is \c NULL, then this function unsets the current
 505 packet header field type from \p trace_class, effectively making \p trace_class
 506 a trace without a packet header field type.
 507
 508 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
 509 \p packet_header_type \em must be a CTF IR structure field type object.
 510
 511 @param[in] trace_class          Trace class of which to set the packet
 512                                 header field type.
 513 @param[in] packet_header_type   Packet header field type, or \c NULL to unset
 514                                 the current packet header field type.
 515 @returns                        0 on success, or a negative value on error.
 516
 517 @prenotnull{trace_class}
 518 @prehot{trace_class}
 519 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
 520         structure field type.
 521 @postrefcountsame{trace_class}
 522 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
 523         the reference count of \p packet_header_type is incremented.
 524
 525 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
 526         header field type of a given trace class.
 527 */
 528 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace_class,
 529                 struct bt_ctf_field_type *packet_header_type);
 530
 531 /** @} */
 532
 533 /**
 534 @name Contained clock classes functions
 535 @{
 536 */
 537
 538 /**
 539 @brief  Returns the number of CTF IR clock classes contained in the
 540         CTF IR trace class \p trace_class.
 541
 542 @param[in] trace_class  Trace class of which to get the number
 543                         of contained clock classes.
 544 @returns                Number of contained clock classes
 545                         contained in \p trace_class, or a negative
 546                         value on error.
 547
 548 @prenotnull{trace_class}
 549 @postrefcountsame{trace_class}
 550 */
 551 extern int bt_ctf_trace_get_clock_class_count(struct bt_ctf_trace *trace_class);
 552
 553 /**
 554 @brief  Returns the CTF IR clock class at index \p index in the CTF
 555         IR trace class \p trace_class.
 556
 557 @param[in] trace_class  Trace class of which to get the clock class
 558                         contained at index \p index.
 559 @param[in] index        Index of the clock class to find in
 560                         \p trace_class.
 561 @returns                Clock class at index \p index in \p trace_class,
 562                         or \c NULL on error.
 563
 564 @prenotnull{trace_class}
 565 @pre \p index is lesser than the number of clock classes contained in
 566         the trace class \p trace_class (see
 567         bt_ctf_trace_get_clock_class_count()).
 568 @postrefcountsame{trace_class}
 569 @postsuccessrefcountretinc
 570
 571 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 572         in a given trace class.
 573 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 574 */
 575 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class(
 576                 struct bt_ctf_trace *trace_class, int index);
 577
 578 /**
 579 @brief  Returns the CTF IR clock class named \c name found in the CTF
 580         IR trace class \p trace_class.
 581
 582 @param[in] trace_class  Trace class of which to get the clock class
 583                         named \p name.
 584 @param[in] name         Name of the clock class to find in \p trace_class.
 585 @returns                Clock class named \p name in \p trace_class,
 586                         or \c NULL on error.
 587
 588 @prenotnull{trace_class}
 589 @prenotnull{name}
 590 @postrefcountsame{trace_class}
 591 @postsuccessrefcountretinc
 592
 593 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
 594         in a given trace class at a given index.
 595 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 596 */
 597 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class_by_name(
 598                 struct bt_ctf_trace *trace_class, const char *name);
 599
 600 /**
 601 @brief  Adds the CTF IR clock class \p clock_class to the CTF IR
 602         trace class \p trace_class.
 603
 604 On success, \p trace_class contains \p clock_class.
 605
 606 You can call this function even if \p trace_class or \p clock_class
 607 are frozen.
 608
 609 @param[in] trace_class  Trace class to which to add \p clock_class.
 610 @param[in] clock_class  Clock class to add to \p trace_class.
 611 @returns                0 on success, or a negative value on error.
 612
 613 @prenotnull{trace_class}
 614 @prenotnull{clock_class}
 615 @postrefcountsame{trace_class}
 616 @postsuccessrefcountinc{clock_class}
 617 @post <strong>On success, if \p trace_class is frozen</strong>,
 618         \p clock_class is frozen.
 619
 620 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
 621         in a given trace class at a given index.
 622 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 623         in a given trace class.
 624 */
 625 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace *trace_class,
 626                 struct bt_ctf_clock_class *clock_class);
 627
 628 /** @} */
 629
 630 /**
 631 @name Stream class children functions
 632 @{
 633 */
 634
 635 /**
 636 @brief  Returns the number of stream classes contained in the
 637         CTF IR trace class \p trace_class.
 638
 639 @param[in] trace_class  Trace class of which to get the number
 640                         of children stream classes.
 641 @returns                Number of children stream classes
 642                         contained in \p trace_class, or a negative
 643                         value on error.
 644
 645 @prenotnull{trace_class}
 646 @postrefcountsame{trace_class}
 647 */
 648 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace_class);
 649
 650 /**
 651 @brief  Returns the stream class at index \p index in the CTF IR trace
 652         class \p trace_class.
 653
 654 @param[in] trace_class  Trace class of which to get the stream class.
 655 @param[in] index        Index of the stream class to find.
 656 @returns                Stream class at index \p index, or \c NULL
 657                         on error.
 658
 659 @prenotnull{trace_class}
 660 @pre \p index is lesser than the number of stream classes contained in
 661         the trace class \p trace_class (see
 662         bt_ctf_trace_get_stream_class_count()).
 663 @postrefcountsame{trace_class}
 664
 665 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 666 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
 667 */
 668 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class(
 669                 struct bt_ctf_trace *trace_class, int index);
 670
 671 /**
 672 @brief  Returns the stream class with ID \c id found in the CTF IR
 673         trace class \p trace_class.
 674
 675 @param[in] trace_class  Trace class of which to get the stream class.
 676 @param[in] id           ID of the stream class to find.
 677 @returns                Stream class with ID \p id, or \c NULL
 678                         on error.
 679
 680 @prenotnull{trace_class}
 681 @postrefcountsame{trace_class}
 682 @postsuccessrefcountretinc
 683
 684 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
 685         in a given trace class at a given index.
 686 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
 687 */
 688 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id(
 689                 struct bt_ctf_trace *trace_class, uint32_t id);
 690
 691 /**
 692 @brief  Adds the CTF IR stream class \p stream_class to the
 693         CTF IR trace class \p trace_class.
 694
 695 On success, \p stream_class becomes the child of \p trace_class.
 696
 697 You can only add a given stream class to one trace class.
 698
 699 You can call this function even if \p trace_class is frozen.
 700
 701 This function tries to resolve the needed
 702 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 703 types that are found anywhere in the root field types of
 704 \p stream_class and of all its currently contained
 705 \link ctfireventclass CTF IR event classes\endlink. If any automatic
 706 resolving fails, then this function fails.
 707
 708 @param[in] trace_class  Trace class to which to add \p stream_class.
 709 @param[in] stream_class Stream class to add to \p trace_class.
 710 @returns                0 on success, or a negative value on error.
 711
 712 @prenotnull{trace_class}
 713 @prenotnull{stream_class}
 714 @postrefcountsame{trace_class}
 715 @postsuccessrefcountinc{stream_class}
 716 @postsuccessfrozen{stream_class}
 717
 718 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
 719         in a given trace class at a given index.
 720 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 721 */
 722 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace_class,
 723                 struct bt_ctf_stream_class *stream_class);
 724
 725 /** @} */
 726
 727 /**
 728 @name Stream children functions
 729 @{
 730 */
 731
 732 /**
 733 @brief  Returns the number of streams contained in the CTF IR trace
 734         class \p trace_class.
 735
 736 @param[in] trace_class  Trace class of which to get the number
 737                         of children streams.
 738 @returns                Number of children streams
 739                         contained in \p trace_class, or a negative
 740                         value on error.
 741
 742 @prenotnull{trace_class}
 743 @postrefcountsame{trace_class}
 744 */
 745 extern int bt_ctf_trace_get_stream_count(struct bt_ctf_trace *trace_class);
 746
 747 /**
 748 @brief  Returns the stream at index \p index in the CTF IR trace
 749         class \p trace_class.
 750
 751 @param[in] trace_class  Trace class of which to get the stream.
 752 @param[in] index        Index of the stream to find.
 753 @returns                Stream at index \p index, or \c NULL
 754                         on error.
 755
 756 @prenotnull{trace_class}
 757 @pre \p index is lesser than the number of streams contained in
 758         the trace class \p trace_class (see
 759         bt_ctf_trace_get_stream_count()).
 760 @postrefcountsame{trace_class}
 761 */
 762 extern struct bt_ctf_stream *bt_ctf_trace_get_stream(
 763                 struct bt_ctf_trace *trace_class, int index);
 764
 765 /** @} */
 766
 767 /**
 768 @name Misc. functions
 769 @{
 770 */
 771
 772 /**
 773 @brief  Returns whether or not the CTF IR trace class \p trace_class
 774         is static.
 775
 776 It is guaranteed that a static trace class will never contain new
 777 streams, stream classes, or clock classes. A static class is always
 778 frozen.
 779
 780 This function returns \c true if bt_ctf_trace_set_is_static() was
 781 previously called on it.
 782
 783 @param[in] trace_class  Trace class to check.
 784 @returns                \c true if \p trace_class is static,
 785
 786 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
 787 */
 788 extern bool bt_ctf_trace_is_static(struct bt_ctf_trace *trace_class);
 789
 790 /**
 791 @brief  Makes the CTF IR trace class \p trace_class static.
 792
 793 A static trace class is frozen and you cannot call any modifying
 794 function on it:
 795
 796 - bt_ctf_trace_add_stream_class()
 797 - bt_ctf_trace_add_clock_class()
 798
 799 You cannot create a stream with bt_ctf_stream_create() with any of the
 800 stream classes of a static trace class.
 801
 802 @param[in] trace_class  Trace class to make static.
 803 @returns                0 on success, or a negative value on error.
 804
 805 @prenotnull{trace_class}
 806 @postrefcountsame{trace_class}
 807 @postsuccessfrozen{trace_class}
 808
 809 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
 810         is static.
 811 */
 812 extern int bt_ctf_trace_set_is_static(struct bt_ctf_trace *trace_class);
 813
 814 /**
 815 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 816         CTF IR trace class \p trace_class.
 817
 818 This function traverses the hierarchy of \p trace_class in pre-order
 819 and calls \p visitor on each element.
 820
 821 The trace class itself is visited first, then, for each children stream
 822 class, the stream class itself, and all its children event classes.
 823
 824 @param[in] trace_class  Trace class to visit.
 825 @param[in] visitor      Visiting function.
 826 @param[in] data         User data.
 827 @returns                0 on success, or a negative value on error.
 828
 829 @prenotnull{trace_class}
 830 @prenotnull{visitor}
 831 */
 832 extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class,
 833                 bt_ctf_visitor visitor, void *data);
 834
 835 /** @} */
 836
 837 /** @} */
 838
 839 /*
 840  * bt_ctf_trace_get_metadata_string: get metadata string.
 841  *
 842  * Get the trace's TSDL metadata. The caller assumes the ownership of the
 843  * returned string.
 844  *
 845  * @param trace Trace instance.
 846  *
 847  * Returns the metadata string on success, NULL on error.
 848  */
 849 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);
 850
 851 #ifdef __cplusplus
 852 }
 853 #endif
 854
 855 #endif /* BABELTRACE_CTF_IR_TRACE_H */