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
34 #include <babeltrace/ref.h>
37 #include <babeltrace/types.h>
44 @defgroup ctfirpacket CTF IR packet
49 #include <babeltrace/ctf-ir/packet.h>
52 A CTF IR <strong><em>packet</em></strong> is a container of packet
53 fields, that is, of the <strong>trace packet header</strong> and
54 <strong>stream packet context</strong> fields.
56 As a reminder, here's the structure of a CTF packet:
60 You can create a CTF IR packet \em from a
61 \link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
62 stream you use to create a packet object becomes its parent.
64 When you set the trace packet header and stream packet context fields of
65 a packet with resp. bt_packet_set_header() and
66 bt_packet_set_context(), their field type \em must be equivalent to
67 the field types returned by resp. bt_trace_get_packet_header_type()
68 and bt_stream_class_get_packet_context_type() for its parent trace
69 class and stream class.
71 You can attach a packet object to a \link ctfirevent CTF IR
72 event\endlink object with bt_event_set_packet().
74 As with any Babeltrace object, CTF IR packet objects have
75 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
76 counts</a>. See \ref refs to learn more about the reference counting
77 management of Babeltrace objects.
79 bt_notification_event_create() \em freezes its event parameter on
80 success, which in turns freezes the event's associated packet object.
81 This is the only way that a CTF IR packet object can be frozen.
82 You cannot modify a frozen packet: it is considered immutable,
83 except for \link refs reference counting\endlink.
90 @brief CTF IR packet type and functions.
93 @addtogroup ctfirpacket
99 @brief A CTF IR packet.
103 struct bt_packet_header_field
;
104 struct bt_packet_context_field
;
106 struct bt_clock_value
;
107 struct bt_clock_class
;
109 enum bt_packet_previous_packet_availability
{
110 BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_ERROR
= -1,
111 BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_AVAILABLE
,
112 BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_NOT_AVAILABLE
,
113 BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_NONE
,
116 enum bt_packet_property_availability
{
117 BT_PACKET_PROPERTY_AVAILABILITY_ERROR
= -1,
118 BT_PACKET_PROPERTY_AVAILABILITY_AVAILABLE
,
119 BT_PACKET_PROPERTY_AVAILABILITY_NOT_AVAILABLE
,
123 @name Creation and parent access functions
128 @brief Creates a default CTF IR packet with \p stream as its parent
131 On success, the packet object's trace packet header and stream packet
132 context fields are not set. You can set them with resp.
133 bt_packet_set_header() and bt_packet_set_context().
135 @param[in] stream Parent CTF IR stream of the packet to create.
136 @returns Created packet, or \c NULL on error.
139 @postsuccessrefcountret1
141 extern struct bt_packet
*bt_packet_create(struct bt_stream
*stream
,
142 enum bt_packet_previous_packet_availability previous_packet_availability
,
143 struct bt_packet
*previous_packet
);
145 extern struct bt_stream
*bt_packet_borrow_stream(struct bt_packet
*packet
);
148 @brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
150 This function returns a reference to the stream which was used to create
151 the packet object in the first place with bt_packet_create().
153 @param[in] packet Packet of which to get the parent stream.
154 @returns Parent stream of \p packet, or \c NULL on error.
157 @postrefcountsame{packet}
158 @postsuccessrefcountretinc
161 struct bt_stream
*bt_packet_get_stream(
162 struct bt_packet
*packet
)
164 return bt_get(bt_packet_borrow_stream(packet
));
170 @name Contained fields functions
175 struct bt_field
*bt_packet_borrow_header(struct bt_packet
*packet
);
178 int bt_packet_move_header(struct bt_packet
*packet
,
179 struct bt_packet_header_field
*header
);
182 struct bt_field
*bt_packet_borrow_context(struct bt_packet
*packet
);
185 int bt_packet_move_context(struct bt_packet
*packet
,
186 struct bt_packet_context_field
*context
);
191 enum bt_packet_property_availability
192 bt_packet_borrow_default_beginning_clock_value(struct bt_packet
*packet
,
193 struct bt_clock_value
**clock_value
);
196 enum bt_packet_property_availability
197 bt_packet_borrow_default_end_clock_value(struct bt_packet
*packet
,
198 struct bt_clock_value
**clock_value
);
201 enum bt_packet_previous_packet_availability
202 bt_packet_get_previous_packet_availability(struct bt_packet
*packet
);
205 enum bt_packet_property_availability
206 bt_packet_borrow_previous_packet_default_end_clock_value(
207 struct bt_packet
*packet
, struct bt_clock_value
**clock_value
);
210 enum bt_packet_property_availability
bt_packet_get_discarded_event_counter(
211 struct bt_packet
*packet
, uint64_t *counter
);
214 enum bt_packet_property_availability
bt_packet_get_sequence_number(
215 struct bt_packet
*packet
, uint64_t *sequence_number
);
218 enum bt_packet_property_availability
bt_packet_get_discarded_event_count(
219 struct bt_packet
*packet
, uint64_t *count
);
222 enum bt_packet_property_availability
bt_packet_get_discarded_packet_count(
223 struct bt_packet
*packet
, uint64_t *count
);
231 #endif /* BABELTRACE_CTF_IR_PACKET_H */