ctf plugin: notif iter: use "borrow" functions for metadata where possible
[babeltrace.git] / include / babeltrace / ctf-ir / packet.h
CommitLineData
f79cf0f0
PP
1#ifndef BABELTRACE_CTF_IR_PACKET_H
2#define BABELTRACE_CTF_IR_PACKET_H
3
4/*
5 * BabelTrace - CTF IR: Stream packet
6 *
7 * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
8 *
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:
15 *
16 * The above copyright notice and this permission notice shall be included in
17 * all copies or substantial portions of the Software.
18 *
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
25 * SOFTWARE.
26 *
27 * The Common Trace Format (CTF) Specification is available at
28 * http://www.efficios.com/ctf
29 */
30
094ff7c0
PP
31/* For bt_get() */
32#include <babeltrace/ref.h>
33
f79cf0f0
PP
34#include <stdint.h>
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
f5efa812
PP
40/**
41@defgroup ctfirpacket CTF IR packet
42@ingroup ctfir
43@brief CTF IR packet.
44
6dd2bd0c
PP
45@code
46#include <babeltrace/ctf-ir/packet.h>
47@endcode
48
f5efa812
PP
49A CTF IR <strong><em>packet</em></strong> is a container of packet
50fields, that is, of the <strong>trace packet header</strong> and
51<strong>stream packet context</strong> fields.
52
53As a reminder, here's the structure of a CTF packet:
54
55@imgpacketstructure
56
57You can create a CTF IR packet \em from a
50842bdc 58\link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
f5efa812
PP
59stream you use to create a packet object becomes its parent.
60
61When you set the trace packet header and stream packet context fields of
50842bdc
PP
62a packet with resp. bt_packet_set_header() and
63bt_packet_set_context(), their field type \em must be equivalent to
64the field types returned by resp. bt_trace_get_packet_header_type()
65and bt_stream_class_get_packet_context_type() for its parent trace
f5efa812
PP
66class and stream class.
67
68You can attach a packet object to a \link ctfirevent CTF IR
50842bdc 69event\endlink object with bt_event_set_packet().
f5efa812
PP
70
71As with any Babeltrace object, CTF IR packet objects have
72<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
73counts</a>. See \ref refs to learn more about the reference counting
74management of Babeltrace objects.
75
76bt_notification_event_create() \em freezes its event parameter on
77success, which in turns freezes the event's associated packet object.
78This is the only way that a CTF IR packet object can be frozen.
79You cannot modify a frozen packet: it is considered immutable,
80except for \link refs reference counting\endlink.
81
82@sa ctfirstream
83@sa ctfirstreamclass
84@sa ctfirtraceclass
85
86@file
87@brief CTF IR packet type and functions.
88@sa ctfirpacket
89
90@addtogroup ctfirpacket
91@{
92*/
93
94/**
50842bdc 95@struct bt_packet
f5efa812
PP
96@brief A CTF IR packet.
97@sa ctfirpacket
98*/
50842bdc
PP
99struct bt_packet;
100struct bt_stream;
f5efa812
PP
101
102/**
103@name Creation and parent access functions
104@{
105*/
f79cf0f0 106
f5efa812
PP
107/**
108@brief Creates a default CTF IR packet with \p stream as its parent
109 CTF IR stream.
110
111On success, the packet object's trace packet header and stream packet
112context fields are not set. You can set them with resp.
50842bdc 113bt_packet_set_header() and bt_packet_set_context().
f5efa812
PP
114
115@param[in] stream Parent CTF IR stream of the packet to create.
116@returns Created packet, or \c NULL on error.
117
118@prenotnull{stream}
119@postsuccessrefcountret1
120*/
50842bdc
PP
121extern struct bt_packet *bt_packet_create(
122 struct bt_stream *stream);
f79cf0f0 123
094ff7c0
PP
124extern struct bt_stream *bt_packet_borrow_stream(
125 struct bt_packet *packet);
126
f5efa812
PP
127/**
128@brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
129
130This function returns a reference to the stream which was used to create
50842bdc 131the packet object in the first place with bt_packet_create().
f5efa812
PP
132
133@param[in] packet Packet of which to get the parent stream.
134@returns Parent stream of \p packet, or \c NULL on error.
135
136@prenotnull{packet}
c2f29fb9 137@postrefcountsame{packet}
f5efa812
PP
138@postsuccessrefcountretinc
139*/
094ff7c0
PP
140static inline
141struct bt_stream *bt_packet_get_stream(
142 struct bt_packet *packet)
143{
144 return bt_get(bt_packet_borrow_stream(packet));
145}
f79cf0f0 146
f5efa812
PP
147/** @} */
148
149/**
150@name Contained fields functions
151@{
152*/
153
094ff7c0
PP
154extern
155struct bt_field *bt_packet_borrow_header(struct bt_packet *packet);
156
f5efa812
PP
157/**
158@brief Returns the trace packet header field of the CTF IR packet
159 \p packet.
160
161@param[in] packet Packet of which to get the trace packet header
162 field.
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.
166
167@prenotnull{packet}
c2f29fb9 168@postrefcountsame{packet}
f5efa812
PP
169@postsuccessrefcountretinc
170
50842bdc 171@sa bt_packet_set_header(): Sets the trace packet header
f5efa812
PP
172 field of a given packet.
173*/
094ff7c0
PP
174static inline
175struct bt_field *bt_packet_get_header(struct bt_packet *packet)
176{
177 return bt_get(bt_packet_borrow_header(packet));
178}
f79cf0f0 179
f5efa812 180/**
6b783f49
JG
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
183 \p packet.
f5efa812 184
6b783f49 185If \p header is not \c NULL, the field type of \p header, as returned by
50842bdc
PP
186bt_field_get_type(), \em must be equivalent to the field type returned by
187bt_trace_get_packet_header_type() for the parent trace class of
6b783f49 188\p packet.
f5efa812 189
6b783f49 190@param[in] packet Packet of which to set the trace packet header field.
f5efa812
PP
191@param[in] header Trace packet header field.
192@returns 0 on success, or a negative value on error.
193
194@prenotnull{packet}
f5efa812 195@prehot{packet}
6b783f49 196@pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
50842bdc 197 the field type returned by bt_trace_get_packet_header_type() for the
6b783f49
JG
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.
202
50842bdc 203@sa bt_packet_get_header(): Returns the trace packet header field of a given
6b783f49 204 packet.
f5efa812 205*/
094ff7c0
PP
206extern int bt_packet_set_header(struct bt_packet *packet,
207 struct bt_field *header);
208
209extern struct bt_field *bt_packet_borrow_context(
210 struct bt_packet *packet);
f79cf0f0 211
f5efa812
PP
212/**
213@brief Returns the stream packet context field of the CTF IR packet
214 \p packet.
215
216@param[in] packet Packet of which to get the stream packet context
217 field.
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.
221
222@prenotnull{packet}
c2f29fb9 223@postrefcountsame{packet}
f5efa812
PP
224@postsuccessrefcountretinc
225
50842bdc 226@sa bt_packet_set_context(): Sets the stream packet context
f5efa812
PP
227 field of a given packet.
228*/
094ff7c0
PP
229static inline
230struct bt_field *bt_packet_get_context(struct bt_packet *packet)
231{
232 return bt_get(bt_packet_borrow_context(packet));
233}
f5efa812
PP
234
235/**
6b783f49
JG
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.
f79cf0f0 238
6b783f49 239If \p context is not \c NULL, the field type of \p context, as returned by
50842bdc
PP
240bt_field_get_type(), \em must be equivalent to the field type returned by
241bt_stream_class_get_packet_context_type() for the parent stream class of
6b783f49 242\p packet.
f5efa812 243
6b783f49 244@param[in] packet Packet of which to set the stream packet context field.
f5efa812
PP
245@param[in] context Stream packet context field.
246@returns 0 on success, or a negative value on error.
247
248@prenotnull{packet}
f5efa812 249@prehot{packet}
6b783f49 250@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
50842bdc 251 the field type returned by bt_stream_class_get_packet_context_type()
6b783f49 252 for the parent stream class of \p packet.
f5efa812 253@postrefcountsame{packet}
6b783f49
JG
254@post <strong>On success, if \p context is not \c NULL</strong>, the reference
255 count of \p context is incremented.
f5efa812 256
50842bdc 257@sa bt_packet_get_context(): Returns the stream packet context field of a
6b783f49 258 given packet.
f5efa812 259*/
50842bdc
PP
260extern int bt_packet_set_context(
261 struct bt_packet *packet, struct bt_field *context);
f79cf0f0 262
f5efa812
PP
263/** @} */
264
a0491f93
PP
265/** @} */
266
f79cf0f0
PP
267#ifdef __cplusplus
268}
269#endif
270
271#endif /* BABELTRACE_CTF_IR_PACKET_H */
This page took 0.050373 seconds and 4 git commands to generate.