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 int64_t 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 int64_t bt_ctf_trace_get_clock_class_count(
 552                 struct bt_ctf_trace *trace_class);
 553
 554 /**
 555 @brief  Returns the CTF IR clock class at index \p index in the CTF
 556         IR trace class \p trace_class.
 557
 558 @param[in] trace_class  Trace class of which to get the clock class
 559                         contained at index \p index.
 560 @param[in] index        Index of the clock class to find in
 561                         \p trace_class.
 562 @returns                Clock class at index \p index in \p trace_class,
 563                         or \c NULL on error.
 564
 565 @prenotnull{trace_class}
 566 @pre \p index is lesser than the number of clock classes contained in
 567         the trace class \p trace_class (see
 568         bt_ctf_trace_get_clock_class_count()).
 569 @postrefcountsame{trace_class}
 570 @postsuccessrefcountretinc
 571
 572 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 573         in a given trace class.
 574 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 575 */
 576 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class(
 577                 struct bt_ctf_trace *trace_class, int index);
 578
 579 /**
 580 @brief  Returns the CTF IR clock class named \c name found in the CTF
 581         IR trace class \p trace_class.
 582
 583 @param[in] trace_class  Trace class of which to get the clock class
 584                         named \p name.
 585 @param[in] name         Name of the clock class to find in \p trace_class.
 586 @returns                Clock class named \p name in \p trace_class,
 587                         or \c NULL on error.
 588
 589 @prenotnull{trace_class}
 590 @prenotnull{name}
 591 @postrefcountsame{trace_class}
 592 @postsuccessrefcountretinc
 593
 594 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
 595         in a given trace class at a given index.
 596 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
 597 */
 598 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class_by_name(
 599                 struct bt_ctf_trace *trace_class, const char *name);
 600
 601 /**
 602 @brief  Adds the CTF IR clock class \p clock_class to the CTF IR
 603         trace class \p trace_class.
 604
 605 On success, \p trace_class contains \p clock_class.
 606
 607 You can call this function even if \p trace_class or \p clock_class
 608 are frozen.
 609
 610 @param[in] trace_class  Trace class to which to add \p clock_class.
 611 @param[in] clock_class  Clock class to add to \p trace_class.
 612 @returns                0 on success, or a negative value on error.
 613
 614 @prenotnull{trace_class}
 615 @prenotnull{clock_class}
 616 @postrefcountsame{trace_class}
 617 @postsuccessrefcountinc{clock_class}
 618 @post <strong>On success, if \p trace_class is frozen</strong>,
 619         \p clock_class is frozen.
 620
 621 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
 622         in a given trace class at a given index.
 623 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
 624         in a given trace class.
 625 */
 626 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace *trace_class,
 627                 struct bt_ctf_clock_class *clock_class);
 628
 629 /** @} */
 630
 631 /**
 632 @name Stream class children functions
 633 @{
 634 */
 635
 636 /**
 637 @brief  Returns the number of stream classes contained in the
 638         CTF IR trace class \p trace_class.
 639
 640 @param[in] trace_class  Trace class of which to get the number
 641                         of children stream classes.
 642 @returns                Number of children stream classes
 643                         contained in \p trace_class, or a negative
 644                         value on error.
 645
 646 @prenotnull{trace_class}
 647 @postrefcountsame{trace_class}
 648 */
 649 extern int64_t bt_ctf_trace_get_stream_class_count(
 650                 struct bt_ctf_trace *trace_class);
 651
 652 /**
 653 @brief  Returns the stream class at index \p index in the CTF IR trace
 654         class \p trace_class.
 655
 656 @param[in] trace_class  Trace class of which to get the stream class.
 657 @param[in] index        Index of the stream class to find.
 658 @returns                Stream class at index \p index, or \c NULL
 659                         on error.
 660
 661 @prenotnull{trace_class}
 662 @pre \p index is lesser than the number of stream classes contained in
 663         the trace class \p trace_class (see
 664         bt_ctf_trace_get_stream_class_count()).
 665 @postrefcountsame{trace_class}
 666
 667 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 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(
 671                 struct bt_ctf_trace *trace_class, int index);
 672
 673 /**
 674 @brief  Returns the stream class with ID \c id found in the CTF IR
 675         trace class \p trace_class.
 676
 677 @param[in] trace_class  Trace class of which to get the stream class.
 678 @param[in] id           ID of the stream class to find.
 679 @returns                Stream class with ID \p id, or \c NULL
 680                         on error.
 681
 682 @prenotnull{trace_class}
 683 @postrefcountsame{trace_class}
 684 @postsuccessrefcountretinc
 685
 686 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
 687         in a given trace class at a given index.
 688 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
 689 */
 690 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id(
 691                 struct bt_ctf_trace *trace_class, uint32_t id);
 692
 693 /**
 694 @brief  Adds the CTF IR stream class \p stream_class to the
 695         CTF IR trace class \p trace_class.
 696
 697 On success, \p stream_class becomes the child of \p trace_class.
 698
 699 You can only add a given stream class to one trace class.
 700
 701 You can call this function even if \p trace_class is frozen.
 702
 703 This function tries to resolve the needed
 704 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
 705 types that are found anywhere in the root field types of
 706 \p stream_class and of all its currently contained
 707 \link ctfireventclass CTF IR event classes\endlink. If any automatic
 708 resolving fails, then this function fails.
 709
 710 @param[in] trace_class  Trace class to which to add \p stream_class.
 711 @param[in] stream_class Stream class to add to \p trace_class.
 712 @returns                0 on success, or a negative value on error.
 713
 714 @prenotnull{trace_class}
 715 @prenotnull{stream_class}
 716 @postrefcountsame{trace_class}
 717 @postsuccessrefcountinc{stream_class}
 718 @postsuccessfrozen{stream_class}
 719
 720 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
 721         in a given trace class at a given index.
 722 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
 723 */
 724 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace_class,
 725                 struct bt_ctf_stream_class *stream_class);
 726
 727 /** @} */
 728
 729 /**
 730 @name Stream children functions
 731 @{
 732 */
 733
 734 /**
 735 @brief  Returns the number of streams contained in the CTF IR trace
 736         class \p trace_class.
 737
 738 @param[in] trace_class  Trace class of which to get the number
 739                         of children streams.
 740 @returns                Number of children streams
 741                         contained in \p trace_class, or a negative
 742                         value on error.
 743
 744 @prenotnull{trace_class}
 745 @postrefcountsame{trace_class}
 746 */
 747 extern int64_t bt_ctf_trace_get_stream_count(struct bt_ctf_trace *trace_class);
 748
 749 /**
 750 @brief  Returns the stream at index \p index in the CTF IR trace
 751         class \p trace_class.
 752
 753 @param[in] trace_class  Trace class of which to get the stream.
 754 @param[in] index        Index of the stream to find.
 755 @returns                Stream at index \p index, or \c NULL
 756                         on error.
 757
 758 @prenotnull{trace_class}
 759 @pre \p index is lesser than the number of streams contained in
 760         the trace class \p trace_class (see
 761         bt_ctf_trace_get_stream_count()).
 762 @postrefcountsame{trace_class}
 763 */
 764 extern struct bt_ctf_stream *bt_ctf_trace_get_stream(
 765                 struct bt_ctf_trace *trace_class, int index);
 766
 767 /** @} */
 768
 769 /**
 770 @name Misc. functions
 771 @{
 772 */
 773
 774 /**
 775 @brief  Returns whether or not the CTF IR trace class \p trace_class
 776         is static.
 777
 778 It is guaranteed that a static trace class will never contain new
 779 streams, stream classes, or clock classes. A static class is always
 780 frozen.
 781
 782 This function returns \c true if bt_ctf_trace_set_is_static() was
 783 previously called on it.
 784
 785 @param[in] trace_class  Trace class to check.
 786 @returns                \c true if \p trace_class is static,
 787
 788 @sa bt_ctf_trace_set_is_static(): Makes a trace class static.
 789 */
 790 extern bool bt_ctf_trace_is_static(struct bt_ctf_trace *trace_class);
 791
 792 /**
 793 @brief  Makes the CTF IR trace class \p trace_class static.
 794
 795 A static trace class is frozen and you cannot call any modifying
 796 function on it:
 797
 798 - bt_ctf_trace_add_stream_class()
 799 - bt_ctf_trace_add_clock_class()
 800
 801 You cannot create a stream with bt_ctf_stream_create() with any of the
 802 stream classes of a static trace class.
 803
 804 @param[in] trace_class  Trace class to make static.
 805 @returns                0 on success, or a negative value on error.
 806
 807 @prenotnull{trace_class}
 808 @postrefcountsame{trace_class}
 809 @postsuccessfrozen{trace_class}
 810
 811 @sa bt_ctf_trace_is_static(): Checks whether or not a given trace class
 812         is static.
 813 */
 814 extern int bt_ctf_trace_set_is_static(struct bt_ctf_trace *trace_class);
 815
 816 /**
 817 @brief  Accepts the visitor \p visitor to visit the hierarchy of the
 818         CTF IR trace class \p trace_class.
 819
 820 This function traverses the hierarchy of \p trace_class in pre-order
 821 and calls \p visitor on each element.
 822
 823 The trace class itself is visited first, then, for each children stream
 824 class, the stream class itself, and all its children event classes.
 825
 826 @param[in] trace_class  Trace class to visit.
 827 @param[in] visitor      Visiting function.
 828 @param[in] data         User data.
 829 @returns                0 on success, or a negative value on error.
 830
 831 @prenotnull{trace_class}
 832 @prenotnull{visitor}
 833 */
 834 extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class,
 835                 bt_ctf_visitor visitor, void *data);
 836
 837 /** @} */
 838
 839 /** @} */
 840
 841 /*
 842  * bt_ctf_trace_get_metadata_string: get metadata string.
 843  *
 844  * Get the trace's TSDL metadata. The caller assumes the ownership of the
 845  * returned string.
 846  *
 847  * @param trace Trace instance.
 848  *
 849  * Returns the metadata string on success, NULL on error.
 850  */
 851 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);
 852
 853 #ifdef __cplusplus
 854 }
 855 #endif
 856
 857 #endif /* BABELTRACE_CTF_IR_TRACE_H */