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