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