Commit | Line | Data |
---|---|---|
3f043b05 JG |
1 | #ifndef BABELTRACE_CTF_IR_STREAM_H |
2 | #define BABELTRACE_CTF_IR_STREAM_H | |
3 | ||
4 | /* | |
5 | * BabelTrace - CTF IR: Stream | |
6 | * | |
7 | * Copyright 2013, 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/stream-class.h> | |
ffc6a64e | 34 | #include <stdint.h> |
3f043b05 JG |
35 | |
36 | #ifdef __cplusplus | |
37 | extern "C" { | |
38 | #endif | |
39 | ||
54f61f03 PP |
40 | /** |
41 | @defgroup ctfirstream CTF IR stream | |
42 | @ingroup ctfir | |
43 | @brief CTF IR stream. | |
44 | ||
45 | @note | |
46 | See \ref ctfirwriterstream which documents additional CTF IR stream | |
47 | functions exclusive to the CTF IR writer mode. | |
48 | ||
49 | A CTF IR <strong><em>stream</em></strong> is an instance of a | |
50 | \link ctfirstreamclass CTF IR stream class\endlink. | |
51 | ||
52 | You can obtain a CTF IR stream object in two different modes: | |
53 | ||
54 | - <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream | |
55 | class having a \link ctfirtraceclass CTF IR trace class\endlink parent | |
56 | \em not created by a \link ctfirwriter CTF IR writer\endlink object to | |
57 | create a default stream. | |
58 | - <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with | |
59 | a stream class having a trace class parent created by a CTF IR writer | |
60 | object, or use bt_ctf_writer_create_stream(). | |
61 | ||
62 | A CTF IR stream object represents a CTF stream, that is, a sequence of | |
63 | packets containing events: | |
64 | ||
65 | @imgtracestructure | |
66 | ||
67 | A CTF IR stream does not contain, however, actual \link ctfirpacket CTF | |
68 | IR packet\endlink objects: it only acts as a common parent to identify | |
69 | the original CTF stream of packet objects. | |
70 | ||
71 | As with any Babeltrace object, CTF IR stream objects have | |
72 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference | |
73 | counts</a>. See \ref refs to learn more about the reference counting | |
74 | management of Babeltrace objects. | |
75 | ||
76 | @sa ctfirstreamclass | |
77 | @sa ctfirpacket | |
78 | @sa ctfirwriterstream | |
79 | ||
80 | @file | |
81 | @brief CTF IR stream type and functions. | |
82 | @sa ctfirstream | |
83 | ||
84 | @addtogroup ctfirstream | |
85 | @{ | |
86 | */ | |
87 | ||
d0218df1 PP |
88 | /** |
89 | @struct bt_ctf_stream | |
90 | @brief A CTF IR stream. | |
91 | @sa ctfirstream | |
92 | @sa ctfirwriterstream | |
93 | */ | |
3f043b05 | 94 | struct bt_ctf_stream; |
54f61f03 PP |
95 | struct bt_ctf_event; |
96 | ||
97 | /** | |
98 | @brief Creates a default CTF IR stream named \p name from the CTF IR | |
99 | stream class \p stream_class. | |
3f043b05 | 100 | |
54f61f03 PP |
101 | \p stream_class \em must have a parent |
102 | \link ctfirtraceclass CTF IR trace class\endlink. | |
103 | ||
104 | If the parent \link ctfirtraceclass trace class\endlink of | |
105 | \p stream_class was created by a \link ctfirwriter CTF IR writer\endlink | |
106 | object, then the stream object is created in CTF IR writer mode, and | |
107 | you can use the functions of \ref ctfirwriterstream on it. | |
108 | Otherwise it is created in normal mode: you should only use the | |
109 | functions documented in this module on it. | |
110 | ||
111 | \p name can be \c NULL to create an unnamed stream object. | |
112 | ||
113 | @param[in] stream_class CTF IR stream class to use to create the | |
114 | CTF IR stream. | |
115 | @param[in] name Name of the stream object to create (copied on | |
116 | success) or \c NULL to create an unnamed stream. | |
117 | @returns Created stream object, or \c NULL on error. | |
118 | ||
119 | @prenotnull{stream_class} | |
120 | @pre \p stream_class has a parent trace class. | |
121 | @postsuccessrefcountret1 | |
122 | */ | |
319fd969 | 123 | extern struct bt_ctf_stream *bt_ctf_stream_create( |
b71d7298 PP |
124 | struct bt_ctf_stream_class *stream_class, |
125 | const char *name); | |
126 | ||
54f61f03 PP |
127 | /** |
128 | @brief Returns the name of the CTF IR stream \p stream. | |
129 | ||
130 | On success, \p stream remains the sole owner of the returned string. | |
131 | ||
132 | @param[in] stream Stream object of which to get the name. | |
133 | @returns Name of stream \p stream, or \c NULL if | |
134 | \p stream is unnamed or on error. | |
135 | ||
136 | @prenotnull{stream} | |
137 | @postrefcountsame{stream} | |
138 | */ | |
b71d7298 | 139 | extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream); |
319fd969 | 140 | |
54f61f03 PP |
141 | /** |
142 | @brief Returns the parent CTF IR stream class of the CTF IR | |
143 | stream \p stream. | |
144 | ||
145 | This function returns a reference to the stream class which was used | |
146 | to create the stream object in the first place with | |
147 | bt_ctf_stream_create(). | |
148 | ||
149 | @param[in] stream Stream of which to get the parent stream class. | |
150 | @returns Parent stream class of \p stream, | |
151 | or \c NULL on error. | |
152 | ||
153 | @prenotnull{stream} | |
154 | @postsuccessrefcountretinc | |
155 | */ | |
3baf0856 JG |
156 | extern struct bt_ctf_stream_class *bt_ctf_stream_get_class( |
157 | struct bt_ctf_stream *stream); | |
158 | ||
54f61f03 PP |
159 | /** @} */ |
160 | ||
3f043b05 JG |
161 | #ifdef __cplusplus |
162 | } | |
163 | #endif | |
164 | ||
165 | #endif /* BABELTRACE_CTF_IR_STREAM_H */ |