[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
 */

#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_ctf_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_ctf_packet_set_header() and
bt_ctf_packet_set_context(), their field type \em must be equivalent to
the field types returned by resp. bt_ctf_trace_get_packet_header_type()
and bt_ctf_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_ctf_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_ctf_packet
@brief A CTF IR packet.
@sa ctfirpacket
*/
struct bt_ctf_packet;
struct bt_ctf_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_ctf_packet_set_header() and bt_ctf_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_ctf_packet *bt_ctf_packet_create(
		struct bt_ctf_stream *stream);

/**
@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_ctf_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}
@postsuccessrefcountretinc
*/
extern struct bt_ctf_stream *bt_ctf_packet_get_stream(
		struct bt_ctf_packet *packet);

/** @} */

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

/**
@brief	Returns the trace packet header field of the CTF IR packet
	\p packet.

@param[in] packet	Packet of which to get the trace packet header
			field.
@returns		Trace packet header field of \p packet,
			or \c NULL if the trace packet header
			field is not set or on error.

@prenotnull{packet}
@postsuccessrefcountretinc

@sa bt_ctf_packet_set_header(): Sets the trace packet header
	field of a given packet.
*/
extern struct bt_ctf_field *bt_ctf_packet_get_header(
		struct bt_ctf_packet *packet);

/**
@brief	Sets the trace packet header field of the CTF IR packet
	\p packet to \p header.

The field type of \p header, as returned by bt_ctf_field_get_type(),
\em must be equivalent to the field type returned by
bt_ctf_trace_get_packet_header_type() for the parent trace class
of \p packet.

@param[in] packet	Packet of which to set the trace packet header
			field.
@param[in] header	Trace packet header field.
@returns		0 on success, or a negative value on error.

@prenotnull{packet}
@prenotnull{header}
@prehot{packet}
@pre \p header has a field type equivalent to the field type returned by
	bt_ctf_trace_get_packet_header_type() for the parent trace class
	of \p packet.
@postrefcountsame{packet}
@postsuccessrefcountinc{header}

@sa bt_ctf_packet_get_header(): Returns the trace packet header field
	of a given packet.
*/
extern int bt_ctf_packet_set_header(
		struct bt_ctf_packet *packet, struct bt_ctf_field *header);

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

@param[in] packet	Packet of which to get the stream packet context
			field.
@returns		Stream packet context field of \p packet,
			or \c NULL if the stream packet context
			field is not set or on error.

@prenotnull{packet}
@postsuccessrefcountretinc

@sa bt_ctf_packet_set_context(): Sets the stream packet context
	field of a given packet.
*/
extern struct bt_ctf_field *bt_ctf_packet_get_context(
		struct bt_ctf_packet *packet);

/**
@brief	Sets the stream packet context field of the CTF IR packet
	\p packet to \p context.

The field type of \p context, as returned by bt_ctf_field_get_type(),
\em must be equivalent to the field type returned by
bt_ctf_stream_class_get_packet_context_type() for the parent stream
class of \p packet.

@param[in] packet	Packet of which to set the stream packet context
			field.
@param[in] context	Stream packet context field.
@returns		0 on success, or a negative value on error.

@prenotnull{packet}
@prenotnull{context}
@prehot{packet}
@pre \p context has a field type equivalent to the field type returned
	by bt_ctf_stream_class_get_packet_context_type() for the parent
	stream class of \p packet.
@postrefcountsame{packet}
@postsuccessrefcountinc{context}

@sa bt_ctf_packet_get_context(): Returns the stream packet context field
	of a given packet.
*/
extern int bt_ctf_packet_set_context(
		struct bt_ctf_packet *packet, struct bt_ctf_field *context);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_PACKET_H */
Commit	Line	Data
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
	34	extern "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	46	A CTF IR <strong><em>packet</em></strong> is a container of packet
	47	fields, that is, of the <strong>trace packet header</strong> and
	48	<strong>stream packet context</strong> fields.
	49
	50	As a reminder, here's the structure of a CTF packet:
	51
	52	@imgpacketstructure
	53
	54	You can create a CTF IR packet \em from a
	55	\link ctfirstream CTF IR stream\endlink with bt_ctf_packet_create(). The
	56	stream you use to create a packet object becomes its parent.
	57
	58	When you set the trace packet header and stream packet context fields of
	59	a packet with resp. bt_ctf_packet_set_header() and
	60	bt_ctf_packet_set_context(), their field type \em must be equivalent to
	61	the field types returned by resp. bt_ctf_trace_get_packet_header_type()
	62	and bt_ctf_stream_class_get_packet_context_type() for its parent trace
	63	class and stream class.
	64
	65	You can attach a packet object to a \link ctfirevent CTF IR
	66	event\endlink object with bt_ctf_event_set_packet().
	67
	68	As with any Babeltrace object, CTF IR packet objects have
	69	<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
	70	counts</a>. See \ref refs to learn more about the reference counting
	71	management of Babeltrace objects.
	72
	73	bt_notification_event_create() \em freezes its event parameter on
	74	success, which in turns freezes the event's associated packet object.
	75	This is the only way that a CTF IR packet object can be frozen.
	76	You cannot modify a frozen packet: it is considered immutable,
	77	except 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	/**
	92	@struct bt_ctf_packet
	93	@brief A CTF IR packet.
	94	@sa ctfirpacket
	95	*/
f79cf0f0	96	struct bt_ctf_packet;
f5efa812 PP	97	struct bt_ctf_stream;
	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
	108	On success, the packet object's trace packet header and stream packet
	109	context fields are not set. You can set them with resp.
	110	bt_ctf_packet_set_header() and bt_ctf_packet_set_context().
	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	*/
f79cf0f0 PP	118	extern struct bt_ctf_packet *bt_ctf_packet_create(
	119	struct bt_ctf_stream *stream);
	120
f5efa812 PP	121	/**
	122	@brief Returns the parent CTF IR stream of the CTF IR packet \p packet.
	123
	124	This function returns a reference to the stream which was used to create
	125	the packet object in the first place with bt_ctf_packet_create().
	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}
	131	@postsuccessrefcountretinc
	132	*/
f79cf0f0 PP	133	extern struct bt_ctf_stream *bt_ctf_packet_get_stream(
	134	struct bt_ctf_packet *packet);
	135
f5efa812 PP	136	/** @} */
	137
	138	/**
	139	@name Contained fields functions
	140	@{
	141	*/
	142
	143	/**
	144	@brief Returns the trace packet header field of the CTF IR packet
	145	\p packet.
	146
	147	@param[in] packet Packet of which to get the trace packet header
	148	field.
	149	@returns Trace packet header field of \p packet,
	150	or \c NULL if the trace packet header
	151	field is not set or on error.
	152
	153	@prenotnull{packet}
	154	@postsuccessrefcountretinc
	155
	156	@sa bt_ctf_packet_set_header(): Sets the trace packet header
	157	field of a given packet.
	158	*/
f79cf0f0 PP	159	extern struct bt_ctf_field *bt_ctf_packet_get_header(
	160	struct bt_ctf_packet *packet);
	161
f5efa812 PP	162	/**
	163	@brief Sets the trace packet header field of the CTF IR packet
	164	\p packet to \p header.
	165
	166	The field type of \p header, as returned by bt_ctf_field_get_type(),
	167	\em must be equivalent to the field type returned by
	168	bt_ctf_trace_get_packet_header_type() for the parent trace class
	169	of \p packet.
	170
	171	@param[in] packet Packet of which to set the trace packet header
	172	field.
	173	@param[in] header Trace packet header field.
	174	@returns 0 on success, or a negative value on error.
	175
	176	@prenotnull{packet}
	177	@prenotnull{header}
	178	@prehot{packet}
	179	@pre \p header has a field type equivalent to the field type returned by
	180	bt_ctf_trace_get_packet_header_type() for the parent trace class
	181	of \p packet.
	182	@postrefcountsame{packet}
	183	@postsuccessrefcountinc{header}
	184
	185	@sa bt_ctf_packet_get_header(): Returns the trace packet header field
	186	of a given packet.
	187	*/
f79cf0f0 PP	188	extern int bt_ctf_packet_set_header(
	189	struct bt_ctf_packet packet, struct bt_ctf_field header);
	190
f5efa812 PP	191	/**
	192	@brief Returns the stream packet context field of the CTF IR packet
	193	\p packet.
	194
	195	@param[in] packet Packet of which to get the stream packet context
	196	field.
	197	@returns Stream packet context field of \p packet,
	198	or \c NULL if the stream packet context
	199	field is not set or on error.
	200
	201	@prenotnull{packet}
	202	@postsuccessrefcountretinc
	203
	204	@sa bt_ctf_packet_set_context(): Sets the stream packet context
	205	field of a given packet.
	206	*/
f79cf0f0	207	extern struct bt_ctf_field *bt_ctf_packet_get_context(
f5efa812 PP	208	struct bt_ctf_packet *packet);
	209
	210	/**
	211	@brief Sets the stream packet context field of the CTF IR packet
	212	\p packet to \p context.
f79cf0f0	213
f5efa812 PP	214	The field type of \p context, as returned by bt_ctf_field_get_type(),
	215	\em must be equivalent to the field type returned by
	216	bt_ctf_stream_class_get_packet_context_type() for the parent stream
	217	class of \p packet.
	218
	219	@param[in] packet Packet of which to set the stream packet context
	220	field.
	221	@param[in] context Stream packet context field.
	222	@returns 0 on success, or a negative value on error.
	223
	224	@prenotnull{packet}
	225	@prenotnull{context}
	226	@prehot{packet}
	227	@pre \p context has a field type equivalent to the field type returned
	228	by bt_ctf_stream_class_get_packet_context_type() for the parent
	229	stream class of \p packet.
	230	@postrefcountsame{packet}
	231	@postsuccessrefcountinc{context}
	232
	233	@sa bt_ctf_packet_get_context(): Returns the stream packet context field
	234	of a given packet.
	235	*/
f79cf0f0 PP	236	extern int bt_ctf_packet_set_context(
	237	struct bt_ctf_packet packet, struct bt_ctf_field context);
	238
f5efa812 PP	239	/** @} */
f5efa812 PP	240
f79cf0f0 PP	241	#ifdef __cplusplus
	242	}
	243	#endif
	244
	245	#endif /* BABELTRACE_CTF_IR_PACKET_H */