trace.h: update API doc
[babeltrace.git] / include / babeltrace / ctf-ir / trace.h
1 #ifndef BABELTRACE_CTF_IR_TRACE_H
2 #define BABELTRACE_CTF_IR_TRACE_H
3
4 /*
5 * BabelTrace - CTF IR: Trace
6 *
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
8 *
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
10 *
11 * Permission is hereby granted, free of charge, to any person obtaining a copy
12 * of this software and associated documentation files (the "Software"), to deal
13 * in the Software without restriction, including without limitation the rights
14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 * copies of the Software, and to permit persons to whom the Software is
16 * furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 *
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
31 */
32
33 #include <babeltrace/ctf-ir/field-types.h>
34 #include <babeltrace/ctf-ir/visitor.h>
35 #include <babeltrace/values.h>
36 #include <babeltrace/graph/notification.h>
37 #include <stdint.h>
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 @defgroup ctfirtraceclass CTF IR trace class
45 @ingroup ctfir
46 @brief CTF IR trace class.
47
48 @code
49 #include <babeltrace/ctf-ir/trace.h>
50 @endcode
51
52 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
53 traces.
54
55 You can obtain a trace class in two different modes:
56
57 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
58 default, empty trace class.
59 - <strong>CTF writer mode</strong>: use bt_ctf_writer_get_trace() to
60 get the trace class created by a given CTF writer object.
61
62 A trace class has the following properties:
63
64 - A \b name.
65 - A <strong>default byte order</strong>: all the
66 \link ctfirfieldtypes field types\endlink eventually part of the trace
67 class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
68 "real" byte order.
69 - An \b environment, which is a custom key-value mapping. Keys are
70 strings and values can be strings or integers.
71
72 In the Babeltrace CTF IR system, a trace class contains zero or more
73 \link ctfirstreamclass stream classes\endlink, and a stream class
74 contains zero or more \link ctfireventclass event classes\endlink. You
75 can add an event class to a stream class with
76 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
77 trace class with bt_ctf_trace_add_stream_class().
78
79 A trace class owns the <strong>trace packet header</strong>
80 \link ctfirfieldtypes field type\endlink, which represents the
81 \c trace.packet.header CTF scope. This field type describes the
82 trace packet header fields of the traces that this trace class
83 describes.
84
85 The trace packet header field type \em must be a structure field type as
86 of Babeltrace \btversion.
87
88 As per the CTF specification, the trace packet header field type \em
89 must contain a field named \c stream_id if the trace class contains more
90 than one stream class.
91
92 As a reminder, here's the structure of a CTF packet:
93
94 @imgpacketstructure
95
96 A trace class also contains zero or more
97 \link ctfirclockclass CTF IR clock classes\endlink.
98
99 @todo
100 Elaborate about clock classes irt clock values.
101
102 As with any Babeltrace object, CTF IR trace class objects have
103 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
104 counts</a>. See \ref refs to learn more about the reference counting
105 management of Babeltrace objects.
106
107 The following functions \em freeze their trace class parameter on
108 success:
109
110 - bt_ctf_trace_add_stream_class()
111 - bt_ctf_writer_create_stream()
112 (\link ctfwriter CTF writer\endlink mode only)
113
114 You cannot modify a frozen trace class: it is considered immutable,
115 except for:
116
117 - Adding a stream class to it with
118 bt_ctf_trace_add_stream_class().
119 - Adding a CTF IR clock class to it with bt_ctf_trace_add_clock_class().
120 - \link refs Reference counting\endlink.
121
122 You can add a custom listener with bt_ctf_trace_add_listener() to get
123 notified if anything changes in a trace class, that is, if an event
124 class is added to one of its stream class, if a stream class is added,
125 or if a clock class is added.
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 default byte order with bt_ctf_trace_set_byte_order().
174
175 Note that you \em must set the default 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 default 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 trace class
240 \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN
241 on error.
242
243 @prenotnull{trace_class}
244 @postrefcountsame{trace_class}
245
246 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
247 */
248 extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order(
249 struct bt_ctf_trace *trace_class);
250
251 /**
252 @brief Sets the default byte order of the CTF IR trace class
253 \p trace_class to \p name.
254
255 \p 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 default byte
262 order.
263 @param[in] 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 @prenotnull{name}
268 @prehot{trace_class}
269 @pre \p byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
270 #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
271 #BT_CTF_BYTE_ORDER_NETWORK.
272 @postrefcountsame{trace_class}
273
274 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
275 */
276 extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace_class,
277 enum bt_ctf_byte_order byte_order);
278
279 /**
280 @brief Returns the number of entries contained in the environment of
281 the CTF IR trace class \p trace_class.
282
283 @param[in] trace_class Trace class of which to get the number
284 of environment entries.
285 @returns Number of environment entries
286 contained in \p trace_class, or
287 a negative value on error.
288
289 @prenotnull{trace_class}
290 @postrefcountsame{trace_class}
291 */
292 extern int bt_ctf_trace_get_environment_field_count(
293 struct bt_ctf_trace *trace_class);
294
295 /**
296 @brief Returns the field name of the environment entry at index
297 \p index in the CTF IR trace class \p trace_class.
298
299 On success, the returned string is valid as long as this trace class
300 exists and is \em not modified. \p trace_class remains the sole owner of
301 the returned string.
302
303 @param[in] trace_class Trace class of which to get the name of the
304 environment entry at index \p index.
305 @param[in] index Index of environment entry to find.
306 @returns Name of the environment entry at index \p index
307 in \p trace_class, or \c NULL on error.
308
309 @prenotnull{trace_class}
310 @pre \p index is lesser than the number of environment entries in
311 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
312 @postrefcountsame{trace_class}
313
314 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
315 environment entry by index.
316 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
317 class's environment entry by name.
318 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
319 class's environment entry.
320 */
321 extern const char *
322 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace_class,
323 int index);
324
325 /**
326 @brief Returns the value of the environment entry at index
327 \p index in the CTF IR trace class \p trace_class.
328
329 @param[in] trace_class Trace class of which to get the value of the
330 environment entry at index \p index.
331 @param[in] index Index of the environment entry to find.
332 @returns Value of the environment entry at index \p index
333 in \p trace_class, or \c NULL on error.
334
335 @prenotnull{trace_class}
336 @pre \p index is lesser than the number of environment entries in
337 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
338 @postrefcountsame{trace_class}
339 @postsuccessrefcountretinc
340
341 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
342 class's environment entry by name.
343 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
344 class's environment entry.
345 */
346 extern struct bt_value *
347 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace_class,
348 int index);
349
350 /**
351 @brief Returns the value of the environment entry named \p name
352 in the CTF IR trace class \p trace_class.
353
354 @param[in] trace_class Trace class of which to get the value of the
355 environment entry named \p name.
356 @param[in] name Name of the environment entry to find.
357 @returns Value of the environment entry named \p name
358 in \p trace_class, or \c NULL if there's no such
359 entry or on error.
360
361 @prenotnull{trace_class}
362 @prenotnull{name}
363 @postrefcountsame{trace_class}
364 @postsuccessrefcountretinc
365
366 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
367 environment entry by index.
368 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
369 class's environment entry.
370 */
371 extern struct bt_value *
372 bt_ctf_trace_get_environment_field_value_by_name(
373 struct bt_ctf_trace *trace_class, const char *name);
374
375 /**
376 @brief Sets the environment entry named \p name in the
377 CTF IR trace class \p trace_class to \p value.
378
379 If an environment entry named \p name exists in \p trace_class, its
380 value is first put, and then replaced by \p value.
381
382 @param[in] trace_class Trace class of which to set the environment
383 entry.
384 @param[in] name Name of the environment entry to set (copied
385 on success).
386 @param[in] value Value of the environment entry named \p name.
387 @returns 0 on success, or a negative value on error.
388
389 @prenotnull{trace_class}
390 @prenotnull{name}
391 @prenotnull{value}
392 @prehot{trace_class}
393 @pre \p value is an
394 \link bt_value_integer_create() integer value object\endlink
395 or a
396 \link bt_value_string_create() string value object\endlink.
397 @postrefcountsame{trace_class}
398 @postsuccessrefcountinc{value}
399
400 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
401 environment entry by index.
402 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
403 class's environment entry by name.
404 */
405 extern int bt_ctf_trace_set_environment_field(
406 struct bt_ctf_trace *trace_class, const char *name,
407 struct bt_value *value);
408
409 /**
410 @brief Sets the environment entry named \p name in the
411 CTF IR trace class \p trace_class to \p value.
412
413 If an environment entry named \p name exists in \p trace_class, its
414 value is first put, and then replaced by a new
415 \link bt_value_integer_create() integer value object\endlink
416 containing \p value.
417
418 @param[in] trace_class Trace class of which to set the environment
419 entry.
420 @param[in] name Name of the environment entry to set (copied
421 on success).
422 @param[in] value Value of the environment entry named \p name.
423 @returns 0 on success, or a negative value on error.
424
425 @prenotnull{trace_class}
426 @prenotnull{name}
427 @prehot{trace_class}
428 @postrefcountsame{trace_class}
429
430 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
431 class's environment entry.
432 */
433 extern int bt_ctf_trace_set_environment_field_integer(
434 struct bt_ctf_trace *trace_class, const char *name,
435 int64_t value);
436
437 /**
438 @brief Sets the environment entry named \p name in the
439 CTF IR trace class \p trace_class to \p value.
440
441 If an environment entry named \p name exists in \p trace_class, its
442 value is first put, and then replaced by a new
443 \link bt_value_string_create() string value object\endlink
444 containing \p value.
445
446 @param[in] trace_class Trace class of which to set the environment
447 entry.
448 @param[in] name Name of the environment entry to set (copied
449 on success).
450 @param[in] value Value of the environment entry named \p name
451 (copied on success).
452 @returns 0 on success, or a negative value on error.
453
454 @prenotnull{trace_class}
455 @prenotnull{name}
456 @prenotnull{value}
457 @prehot{trace_class}
458 @postrefcountsame{trace_class}
459
460 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
461 class's environment entry.
462 */
463 extern int bt_ctf_trace_set_environment_field_string(
464 struct bt_ctf_trace *trace_class, const char *name,
465 const char *value);
466
467 /** @} */
468
469 /**
470 @name Contained field types functions
471 @{
472 */
473
474 /**
475 @brief Returns the packet header field type of the CTF IR trace class
476 \p trace_class.
477
478 @param[in] trace_class Trace class of which to get the packet
479 header field type.
480 @returns Packet header field type of \p trace_class,
481 or \c NULL if \p trace_class has no packet header field
482 type or on error.
483
484 @prenotnull{trace_class}
485 @postrefcountsame{trace_class}
486 @post <strong>On success, if the return value is a field type</strong>, its
487 reference count is incremented.
488
489 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
490 header field type of a given trace class.
491 */
492 extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
493 struct bt_ctf_trace *trace_class);
494
495 /**
496 @brief Sets the packet header field type of the CTF IR trace class
497 \p trace_class to \p packet_header_type, or unsets the current packet
498 header field type from \p trace_class.
499
500 If \p packet_header_type is \c NULL, then this function unsets the current
501 packet header field type from \p trace_class, effectively making \p trace_class
502 a trace without a packet header field type.
503
504 As of Babeltrace \btversion, if \p packet_header_type is not \c NULL,
505 \p packet_header_type \em must be a CTF IR structure field type object.
506
507 @param[in] trace_class Trace class of which to set the packet
508 header field type.
509 @param[in] packet_header_type Packet header field type, or \c NULL to unset
510 the current packet header field type.
511 @returns 0 on success, or a negative value on error.
512
513 @prenotnull{trace_class}
514 @prehot{trace_class}
515 @pre <strong>\p packet_header_type, if not \c NULL</strong>, is a CTF IR
516 structure field type.
517 @postrefcountsame{trace_class}
518 @post <strong>On success, if \p packet_header_type is not \c NULL</strong>,
519 the reference count of \p packet_header_type is incremented.
520
521 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
522 header field type of a given trace class.
523 */
524 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace_class,
525 struct bt_ctf_field_type *packet_header_type);
526
527 /** @} */
528
529 /**
530 @name Contained clock classes functions
531 @{
532 */
533
534 /**
535 @brief Returns the number of CTF IR clock classes contained in the
536 CTF IR trace class \p trace_class.
537
538 @param[in] trace_class Trace class of which to get the number
539 of contained clock classes.
540 @returns Number of contained clock classes
541 contained in \p trace_class, or a negative
542 value on error.
543
544 @prenotnull{trace_class}
545 @postrefcountsame{trace_class}
546 */
547 extern int bt_ctf_trace_get_clock_class_count(struct bt_ctf_trace *trace_class);
548
549 /**
550 @brief Returns the CTF IR clock class at index \p index in the CTF
551 IR trace class \p trace_class.
552
553 @param[in] trace_class Trace class of which to get the clock class
554 contained at index \p index.
555 @param[in] index Index of the clock class to find in
556 \p trace_class.
557 @returns Clock class at index \p index in \p trace_class,
558 or \c NULL on error.
559
560 @prenotnull{trace_class}
561 @pre \p index is lesser than the number of clock classes contained in
562 the trace class \p trace_class (see
563 bt_ctf_trace_get_clock_class_count()).
564 @postrefcountsame{trace_class}
565 @postsuccessrefcountretinc
566
567 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
568 in a given trace class.
569 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
570 */
571 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class(
572 struct bt_ctf_trace *trace_class, int index);
573
574 /**
575 @brief Returns the CTF IR clock class named \c name found in the CTF
576 IR trace class \p trace_class.
577
578 @param[in] trace_class Trace class of which to get the clock class
579 named \p name.
580 @param[in] name Name of the clock class to find in \p trace_class.
581 @returns Clock class named \p name in \p trace_class,
582 or \c NULL on error.
583
584 @prenotnull{trace_class}
585 @prenotnull{name}
586 @postrefcountsame{trace_class}
587 @postsuccessrefcountretinc
588
589 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
590 in a given trace class at a given index.
591 @sa bt_ctf_trace_add_clock_class(): Adds a clock class to a trace class.
592 */
593 extern struct bt_ctf_clock_class *bt_ctf_trace_get_clock_class_by_name(
594 struct bt_ctf_trace *trace_class, const char *name);
595
596 /**
597 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
598 trace class \p trace_class.
599
600 On success, \p trace_class contains \p clock_class.
601
602 You can call this function even if \p trace_class or \p clock_class
603 are frozen.
604
605 @param[in] trace_class Trace class to which to add \p clock_class.
606 @param[in] clock_class Clock class to add to \p trace_class.
607 @returns 0 on success, or a negative value on error.
608
609 @prenotnull{trace_class}
610 @prenotnull{clock_class}
611 @postrefcountsame{trace_class}
612 @postsuccessrefcountinc{clock_class}
613 @post <strong>On success, if \p trace_class is frozen</strong>,
614 \p clock_class is frozen.
615
616 @sa bt_ctf_trace_get_clock_class(): Returns the clock class contained
617 in a given trace class at a given index.
618 @sa bt_ctf_trace_get_clock_class_by_name(): Finds a clock class by name
619 in a given trace class.
620 */
621 extern int bt_ctf_trace_add_clock_class(struct bt_ctf_trace *trace_class,
622 struct bt_ctf_clock_class *clock_class);
623
624 /** @} */
625
626 /**
627 @name Stream class children functions
628 @{
629 */
630
631 /**
632 @brief Returns the number of stream classes contained in the
633 CTF IR trace class \p trace_class.
634
635 @param[in] trace_class Trace class of which to get the number
636 of children stream classes.
637 @returns Number of children stream classes
638 contained in \p trace_class, or a negative
639 value on error.
640
641 @prenotnull{trace_class}
642 @postrefcountsame{trace_class}
643 */
644 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace_class);
645
646 /**
647 @brief Returns the stream class at index \p index in the CTF IR trace
648 class \p trace_class.
649
650 @param[in] trace_class Trace class of which to get the stream class.
651 @param[in] index Index of the stream class to find.
652 @returns Stream class at index \p index, or \c NULL
653 on error.
654
655 @prenotnull{trace_class}
656 @pre \p index is lesser than the number of stream classes contained in
657 the trace class \p trace_class (see
658 bt_ctf_trace_get_stream_class_count()).
659 @postrefcountsame{trace_class}
660
661 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
662 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
663 */
664 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class(
665 struct bt_ctf_trace *trace_class, int index);
666
667 /**
668 @brief Returns the stream class with ID \c id found in the CTF IR
669 trace class \p trace_class.
670
671 @param[in] trace_class Trace class of which to get the stream class.
672 @param[in] id ID of the stream class to find.
673 @returns Stream class with ID \p id, or \c NULL
674 on error.
675
676 @prenotnull{trace_class}
677 @postrefcountsame{trace_class}
678 @postsuccessrefcountretinc
679
680 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
681 in a given trace class at a given index.
682 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
683 */
684 extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id(
685 struct bt_ctf_trace *trace_class, uint32_t id);
686
687 /**
688 @brief Adds the CTF IR stream class \p stream_class to the
689 CTF IR trace class \p trace_class.
690
691 On success, \p stream_class becomes the child of \p trace_class.
692
693 You can only add a given stream class to one trace class.
694
695 You can call this function even if \p trace_class is frozen.
696
697 This function tries to resolve the needed
698 \link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
699 types that are found anywhere in the root field types of
700 \p stream_class and of all its currently contained
701 \link ctfireventclass CTF IR event classes\endlink. If any automatic
702 resolving fails, then this function fails.
703
704 @param[in] trace_class Trace class to which to add \p stream_class.
705 @param[in] stream_class Stream class to add to \p trace_class.
706 @returns 0 on success, or a negative value on error.
707
708 @prenotnull{trace_class}
709 @prenotnull{stream_class}
710 @postrefcountsame{trace_class}
711 @postsuccessrefcountinc{stream_class}
712 @postsuccessfrozen{stream_class}
713
714 @sa bt_ctf_trace_get_stream_class(): Returns the stream class contained
715 in a given trace class at a given index.
716 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
717 */
718 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace_class,
719 struct bt_ctf_stream_class *stream_class);
720
721 /** @} */
722
723 /**
724 @name Misc. functions
725 @{
726 */
727
728 /**
729 @brief User function type to use with bt_ctf_trace_add_listener().
730
731 @param[in] obj New CTF IR object which is part of the trace
732 class hierarchy.
733 @param[in] data User data.
734
735 @prenotnull{obj}
736 */
737 typedef void (*bt_ctf_listener_cb)(struct bt_ctf_object *obj, void *data);
738
739 /**
740 @brief Adds the trace class modification listener \p listener to
741 the CTF IR trace class \p trace_class.
742
743 Once you add \p listener to \p trace_class, whenever \p trace_class
744 is modified, \p listener is called with the new element and with
745 \p data (user data).
746
747 @param[in] trace_class Trace class to which to add \p listener.
748 @param[in] listener Modification listener function.
749 @param[in] data User data.
750 @returns 0 on success, or a negative value on error.
751
752 @prenotnull{trace_class}
753 @prenotnull{listener}
754 @postrefcountsame{trace_class}
755 */
756 extern int bt_ctf_trace_add_listener(struct bt_ctf_trace *trace_class,
757 bt_ctf_listener_cb listener, void *data);
758
759 /**
760 @brief Accepts the visitor \p visitor to visit the hierarchy of the
761 CTF IR trace class \p trace_class.
762
763 This function traverses the hierarchy of \p trace_class in pre-order
764 and calls \p visitor on each element.
765
766 The trace class itself is visited first, then, for each children stream
767 class, the stream class itself, and all its children event classes.
768
769 @param[in] trace_class Trace class to visit.
770 @param[in] visitor Visiting function.
771 @param[in] data User data.
772 @returns 0 on success, or a negative value on error.
773
774 @prenotnull{trace_class}
775 @prenotnull{visitor}
776 */
777 extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class,
778 bt_ctf_visitor visitor, void *data);
779
780 /** @} */
781
782 /** @} */
783
784 /*
785 * bt_ctf_trace_get_metadata_string: get metadata string.
786 *
787 * Get the trace's TSDL metadata. The caller assumes the ownership of the
788 * returned string.
789 *
790 * @param trace Trace instance.
791 *
792 * Returns the metadata string on success, NULL on error.
793 */
794 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);
795
796 #ifdef __cplusplus
797 }
798 #endif
799
800 #endif /* BABELTRACE_CTF_IR_TRACE_H */
This page took 0.04747 seconds and 5 git commands to generate.