[babeltrace.git] / include / babeltrace / ctf-ir / packet.h

#ifndef BABELTRACE_CTF_IR_PACKET_H
#define BABELTRACE_CTF_IR_PACKET_H

/*
 * BabelTrace - CTF IR: Stream packet
 *
 * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * The Common Trace Format (CTF) Specification is available at
 * http://www.efficios.com/ctf
 */

/* For bt_get() */
#include <babeltrace/ref.h>

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup ctfirpacket CTF IR packet
@ingroup ctfir
@brief CTF IR packet.

@code
#include <babeltrace/ctf-ir/packet.h>
@endcode

A CTF IR <strong><em>packet</em></strong> is a container of packet
fields, that is, of the <strong>trace packet header</strong> and
<strong>stream packet context</strong> fields.

As a reminder, here's the structure of a CTF packet:

@imgpacketstructure

You can create a CTF IR packet \em from a
\link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
stream you use to create a packet object becomes its parent.

When you set the trace packet header and stream packet context fields of
a packet with resp. bt_packet_set_header() and
bt_packet_set_context(), their field type \em must be equivalent to
the field types returned by resp. bt_trace_get_packet_header_type()
and bt_stream_class_get_packet_context_type() for its parent trace
class and stream class.

You can attach a packet object to a \link ctfirevent CTF IR
event\endlink object with bt_event_set_packet().

As with any Babeltrace object, CTF IR packet objects have
<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
counts</a>. See \ref refs to learn more about the reference counting
management of Babeltrace objects.

bt_notification_event_create() \em freezes its event parameter on
success, which in turns freezes the event's associated packet object.
This is the only way that a CTF IR packet object can be frozen.
You cannot modify a frozen packet: it is considered immutable,
except for \link refs reference counting\endlink.

@sa ctfirstream
@sa ctfirstreamclass
@sa ctfirtraceclass

@file
@brief CTF IR packet type and functions.
@sa ctfirpacket

@addtogroup ctfirpacket
@{
*/

/**
@struct bt_packet
@brief A CTF IR packet.
@sa ctfirpacket
*/
struct bt_packet;
struct bt_packet_header_field;
struct bt_packet_context_field;
struct bt_stream;

/**
@name Creation and parent access functions
@{
*/

/**
@brief	Creates a default CTF IR packet with \p stream as its parent
	CTF IR stream.

On success, the packet object's trace packet header and stream packet
context fields are not set. You can set them with resp.
bt_packet_set_header() and bt_packet_set_context().

@param[in] stream	Parent CTF IR stream of the packet to create.
@returns		Created packet, or \c NULL on error.

@prenotnull{stream}
@postsuccessrefcountret1
*/
extern struct bt_packet *bt_packet_create(struct bt_stream *stream);

extern struct bt_stream *bt_packet_borrow_stream(struct bt_packet *packet);

/**
@brief	Returns the parent CTF IR stream of the CTF IR packet \p packet.

This function returns a reference to the stream which was used to create
the packet object in the first place with bt_packet_create().

@param[in] packet	Packet of which to get the parent stream.
@returns		Parent stream of \p packet, or \c NULL on error.

@prenotnull{packet}
@postrefcountsame{packet}
@postsuccessrefcountretinc
*/
static inline
struct bt_stream *bt_packet_get_stream(
		struct bt_packet *packet)
{
	return bt_get(bt_packet_borrow_stream(packet));
}

/** @} */

/**
@name Contained fields functions
@{
*/

extern
struct bt_field *bt_packet_borrow_header(struct bt_packet *packet);

extern
int bt_packet_move_header(struct bt_packet *packet,
		struct bt_packet_header_field *header);

extern
struct bt_field *bt_packet_borrow_context(struct bt_packet *packet);

extern
int bt_packet_move_context(struct bt_packet *packet,
		struct bt_packet_context_field *context);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_PACKET_H */
Commit	Line	Data
	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	/* For bt_get() */
	32	#include <babeltrace/ref.h>
	33
	34	#include <stdint.h>
	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
	40	/**
	41	@defgroup ctfirpacket CTF IR packet
	42	@ingroup ctfir
	43	@brief CTF IR packet.
	44
	45	@code
	46	#include <babeltrace/ctf-ir/packet.h>
	47	@endcode
	48
	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.
	52
	53	As a reminder, here's the structure of a CTF packet:
	54
	55	@imgpacketstructure
	56
	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.
	60
	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.
	67
	68	You can attach a packet object to a \link ctfirevent CTF IR
	69	event\endlink object with bt_event_set_packet().
	70
	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.
	75
	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.
	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	/**
	95	@struct bt_packet
	96	@brief A CTF IR packet.
	97	@sa ctfirpacket
	98	*/
	99	struct bt_packet;
	100	struct bt_packet_header_field;
	101	struct bt_packet_context_field;
	102	struct bt_stream;
	103
	104	/**
	105	@name Creation and parent access functions
	106	@{
	107	*/
	108
	109	/**
	110	@brief Creates a default CTF IR packet with \p stream as its parent
	111	CTF IR stream.
	112
	113	On success, the packet object's trace packet header and stream packet
	114	context fields are not set. You can set them with resp.
	115	bt_packet_set_header() and bt_packet_set_context().
	116
	117	@param[in] stream Parent CTF IR stream of the packet to create.
	118	@returns Created packet, or \c NULL on error.
	119
	120	@prenotnull{stream}
	121	@postsuccessrefcountret1
	122	*/
	123	extern struct bt_packet bt_packet_create(struct bt_stream stream);
	124
	125	extern struct bt_stream bt_packet_borrow_stream(struct bt_packet packet);
	126
	127	/**
	128	@brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
	129
	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().
	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}
	137	@postrefcountsame{packet}
	138	@postsuccessrefcountretinc
	139	*/
	140	static inline
	141	struct bt_stream *bt_packet_get_stream(
	142	struct bt_packet *packet)
	143	{
	144	return bt_get(bt_packet_borrow_stream(packet));
	145	}
	146
	147	/** @} */
	148
	149	/**
	150	@name Contained fields functions
	151	@{
	152	*/
	153
	154	extern
	155	struct bt_field bt_packet_borrow_header(struct bt_packet packet);
	156
	157	extern
	158	int bt_packet_move_header(struct bt_packet *packet,
	159	struct bt_packet_header_field *header);
	160
	161	extern
	162	struct bt_field bt_packet_borrow_context(struct bt_packet packet);
	163
	164	extern
	165	int bt_packet_move_context(struct bt_packet *packet,
	166	struct bt_packet_context_field *context);
	167
	168	/** @} */
	169
	170	/** @} */
	171
	172	#ifdef __cplusplus
	173	}
	174	#endif
	175
	176	#endif /* BABELTRACE_CTF_IR_PACKET_H */