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