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