1 #ifndef BABELTRACE_CTF_IR_PACKET_H
2 #define BABELTRACE_CTF_IR_PACKET_H
5 * BabelTrace - CTF IR: Stream packet
7 * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
9 * Permission is hereby granted, free of charge, to any person obtaining a copy
10 * of this software and associated documentation files (the "Software"), to deal
11 * in the Software without restriction, including without limitation the rights
12 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 * copies of the Software, and to permit persons to whom the Software is
14 * furnished to do so, subject to the following conditions:
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * The Common Trace Format (CTF) Specification is available at
28 * http://www.efficios.com/ctf
32 #include <babeltrace/ref.h>
41 @defgroup ctfirpacket CTF IR packet
46 #include <babeltrace/ctf-ir/packet.h>
49 A CTF IR <strong><em>packet</em></strong> is a container of packet
50 fields, that is, of the <strong>trace packet header</strong> and
51 <strong>stream packet context</strong> fields.
53 As a reminder, here's the structure of a CTF packet:
57 You can create a CTF IR packet \em from a
58 \link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
59 stream you use to create a packet object becomes its parent.
61 When you set the trace packet header and stream packet context fields of
62 a packet with resp. bt_packet_set_header() and
63 bt_packet_set_context(), their field type \em must be equivalent to
64 the field types returned by resp. bt_trace_get_packet_header_type()
65 and bt_stream_class_get_packet_context_type() for its parent trace
66 class and stream class.
68 You can attach a packet object to a \link ctfirevent CTF IR
69 event\endlink object with bt_event_set_packet().
71 As with any Babeltrace object, CTF IR packet 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.
76 bt_notification_event_create() \em freezes its event parameter on
77 success, which in turns freezes the event's associated packet object.
78 This is the only way that a CTF IR packet object can be frozen.
79 You cannot modify a frozen packet: it is considered immutable,
80 except for \link refs reference counting\endlink.
87 @brief CTF IR packet type and functions.
90 @addtogroup ctfirpacket
96 @brief A CTF IR packet.
103 @name Creation and parent access functions
108 @brief Creates a default CTF IR packet with \p stream as its parent
111 On success, the packet object's trace packet header and stream packet
112 context fields are not set. You can set them with resp.
113 bt_packet_set_header() and bt_packet_set_context().
115 @param[in] stream Parent CTF IR stream of the packet to create.
116 @returns Created packet, or \c NULL on error.
119 @postsuccessrefcountret1
121 extern struct bt_packet
*bt_packet_create(
122 struct bt_stream
*stream
);
124 extern struct bt_stream
*bt_packet_borrow_stream(
125 struct bt_packet
*packet
);
128 @brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
130 This function returns a reference to the stream which was used to create
131 the packet object in the first place with bt_packet_create().
133 @param[in] packet Packet of which to get the parent stream.
134 @returns Parent stream of \p packet, or \c NULL on error.
137 @postrefcountsame{packet}
138 @postsuccessrefcountretinc
141 struct bt_stream
*bt_packet_get_stream(
142 struct bt_packet
*packet
)
144 return bt_get(bt_packet_borrow_stream(packet
));
150 @name Contained fields functions
155 struct bt_field
*bt_packet_borrow_header(struct bt_packet
*packet
);
158 @brief Returns the trace packet header field of the CTF IR packet
161 @param[in] packet Packet of which to get the trace packet header
163 @returns Trace packet header field of \p packet,
164 or \c NULL if the trace packet header
165 field is not set or on error.
168 @postrefcountsame{packet}
169 @postsuccessrefcountretinc
171 @sa bt_packet_set_header(): Sets the trace packet header
172 field of a given packet.
175 struct bt_field
*bt_packet_get_header(struct bt_packet
*packet
)
177 return bt_get(bt_packet_borrow_header(packet
));
181 @brief Sets the trace packet header field of the CTF IR packet \p packet to
182 \p header, or unsets the current trace packet header field from
185 If \p header is not \c NULL, the field type of \p header, as returned by
186 bt_field_get_type(), \em must be equivalent to the field type returned by
187 bt_trace_get_packet_header_type() for the parent trace class of
190 @param[in] packet Packet of which to set the trace packet header field.
191 @param[in] header Trace packet header field.
192 @returns 0 on success, or a negative value on error.
196 @pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
197 the field type returned by bt_trace_get_packet_header_type() for the
198 parent trace class of \p packet.
199 @postrefcountsame{event}
200 @post <strong>On success, if \p header is not \c NULL</strong>, the reference
201 count of \p header is incremented.
203 @sa bt_packet_get_header(): Returns the trace packet header field of a given
206 extern int bt_packet_set_header(struct bt_packet
*packet
,
207 struct bt_field
*header
);
209 extern struct bt_field
*bt_packet_borrow_context(
210 struct bt_packet
*packet
);
213 @brief Returns the stream packet context field of the CTF IR packet
216 @param[in] packet Packet of which to get the stream packet context
218 @returns Stream packet context field of \p packet,
219 or \c NULL if the stream packet context
220 field is not set or on error.
223 @postrefcountsame{packet}
224 @postsuccessrefcountretinc
226 @sa bt_packet_set_context(): Sets the stream packet context
227 field of a given packet.
230 struct bt_field
*bt_packet_get_context(struct bt_packet
*packet
)
232 return bt_get(bt_packet_borrow_context(packet
));
236 @brief Sets the stream packet context field of the CTF IR packet \p packet to
237 \p context, or unsets the current packet context field from \p packet.
239 If \p context is not \c NULL, the field type of \p context, as returned by
240 bt_field_get_type(), \em must be equivalent to the field type returned by
241 bt_stream_class_get_packet_context_type() for the parent stream class of
244 @param[in] packet Packet of which to set the stream packet context field.
245 @param[in] context Stream packet context field.
246 @returns 0 on success, or a negative value on error.
250 @pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
251 the field type returned by bt_stream_class_get_packet_context_type()
252 for the parent stream class of \p packet.
253 @postrefcountsame{packet}
254 @post <strong>On success, if \p context is not \c NULL</strong>, the reference
255 count of \p context is incremented.
257 @sa bt_packet_get_context(): Returns the stream packet context field of a
260 extern int bt_packet_set_context(
261 struct bt_packet
*packet
, struct bt_field
*context
);
271 #endif /* BABELTRACE_CTF_IR_PACKET_H */
This page took 0.053321 seconds and 5 git commands to generate.