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