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