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

#ifndef BABELTRACE_CTF_IR_EVENT_H
#define BABELTRACE_CTF_IR_EVENT_H

/*
 * BabelTrace - CTF IR: Event
 *
 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Author: Jérémie Galarneau <jeremie.galarneau@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>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_value;
struct bt_clock_class;

/**
@defgroup ctfirevent CTF IR event
@ingroup ctfir
@brief CTF IR event.

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

A CTF IR <strong><em>event</em></strong> is a container of event
fields:

- <strong>Stream event header</strong> field, described by the
  <em>stream event header field type</em> of a
  \link ctfirstreamclass CTF IR stream class\endlink.
- <strong>Stream event context</strong> field, described by the
  <em>stream event context field type</em> of a stream class.
- <strong>Event context</strong> field, described by the
  <em>event context field type</em> of a
  \link ctfireventclass CTF IR event class\endlink.
- <strong>Event payload</strong>, described by the
  <em>event payload field type</em> of an event class.

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

@imgpacketstructure

You can create a CTF IR event \em from a
\link ctfireventclass CTF IR event class\endlink with
bt_event_create(). The event class you use to create an event
object becomes its parent.

If the \link ctfirtraceclass CTF IR trace class\endlink of an event
object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
which is the parent of its event class) was created by a
\link ctfwriter CTF writer\endlink object, then the only possible
action you can do with this event object is to append it to a
\link ctfirstream CTF IR stream\endlink with
bt_stream_append_event(). Otherwise, you can create an event
notification with bt_notification_event_create(). The event you pass
to this function \em must have an attached packet object first.

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

A CTF IR event has a mapping of
\link ctfirclockvalue CTF IR clock values\endlink. A clock value is
an instance of a specific
\link ctfirclockclass CTF IR clock class\endlink when the event is
emitted. You can set an event object's clock value with
bt_event_set_clock_value().

As with any Babeltrace object, CTF IR event 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. You cannot modify a frozen event object: it is considered
immutable, except for \link refs reference counting\endlink.

@sa ctfireventclass
@sa ctfirpacket

@file
@brief CTF IR event type and functions.
@sa ctfirevent

@addtogroup ctfirevent
@{
*/

/**
@struct bt_event
@brief A CTF IR event.
@sa ctfirevent
*/
struct bt_event;
struct bt_clock;
struct bt_clock_value;
struct bt_event_class;
struct bt_field;
struct bt_field_type;
struct bt_stream_class;
struct bt_packet;

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

/**
@brief  Creates a default CTF IR event from the CTF IR event class
	\p event_class.

\p event_class \em must have a parent
\link ctfirstreamclass CTF IR stream class\endlink.

On success, the four fields of the created event object are not set. You
can set them with bt_event_set_header(),
bt_event_set_stream_event_context(),
bt_event_set_context(), and bt_event_set_payload().

This function tries to resolve the needed
\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
types that are found anywhere in the context or payload field
types of \p event_class and in the root field types of the
parent stream class of \p event_class. If any automatic resolving fails,
this function fails. This means that, if any dynamic field type need
a field type which should be found in the trace packet header root
field type, and if the parent stream class of \p event_class was not
added to a \link ctfirtraceclass CTF IR trace class\endlink yet
with bt_trace_add_stream_class(), then this function fails.

@param[in] event_class	CTF IR event class to use to create the
			CTF IR event.
@returns		Created event object, or \c NULL on error.

@prenotnull{event_class}
@pre \p event_class has a parent stream class.
@postsuccessrefcountret1
*/
extern struct bt_event *bt_event_create(struct bt_event_class *event_class);

/**
@brief	Returns the parent CTF IR event class of the CTF IR event
	\p event.

This function returns a reference to the event class which was used to
create the event object in the first place with bt_event_create().

@param[in] event	Event of which to get the parent event class.
@returns		Parent event class of \p event,
			or \c NULL on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
*/
extern struct bt_event_class *bt_event_get_class(struct bt_event *event);

/**
@brief	Returns the CTF IR packet associated to the CTF IR event
	\p event.

This function returns a reference to the event class which was set to
\p event in the first place with bt_event_set_packet().

@param[in] event	Event of which to get the associated packet.
@returns		Packet associated to \p event,
			or \c NULL if no packet is associated to
			\p event or on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_set_packet(): Associates a given event to a given
	packet.
*/
extern struct bt_packet *bt_event_get_packet(struct bt_event *event);

/**
@brief	Associates the CTF IR event \p event to the CTF IR packet
	\p packet.

The \link ctfirstreamclass CTF IR stream class\endlink of the
parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
be the same as the parent stream class of the
\link ctfireventclass CTF IR event class\endlink returned
by bt_event_get_class() for \p event.

You \em must call this function to create an event-packet association
before you call bt_notification_event_create() with \p event.

On success, this function also sets the parent stream object of
\p event to the parent stream of \p packet.

@param[in] event	Event to which to associate \p packet.
@param[in] packet	Packet to associate to \p event.
@returns		0 on success, or a negative value on error.

@prenotnull{event}
@prenotnull{packet}
@prehot{event}
@pre The parent stream class of \p packet is the same as the parent
	stream class of \p event.
@postsuccessrefcountretinc

@sa bt_event_get_packet(): Returns the associated packet of a
	given event object.
*/
extern int bt_event_set_packet(struct bt_event *event,
		struct bt_packet *packet);

/**
@brief	Returns the parent CTF IR stream associated to the CTF IR event
	\p event.

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

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
*/
extern struct bt_stream *bt_event_get_stream(struct bt_event *event);

/** @} */

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

/**
@brief	Returns the stream event header field of the CTF IR event
	\p event.

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

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_get_header(): Sets the stream event header
	field of a given event.
*/
extern struct bt_field *bt_event_get_header(struct bt_event *event);

/**
@brief	Sets the stream event header field of the CTF IR event
	\p event to \p header, or unsets the current stream event header field
	from \p event.

If \p header is not \c NULL, the field type of \p header, as returned by
bt_field_get_type(), \em must be equivalent to the field type returned by
bt_stream_class_get_event_header_type() for the parent stream class
of \p event.

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

@prenotnull{event}
@prehot{event}
@pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
	the field type returned by bt_stream_class_get_event_header_type()
	for the parent stream class of \p event.
@postrefcountsame{event}
@post <strong>On success, if \p header is not \c NULL</strong>,
	the reference count of \p header is incremented.

@sa bt_event_get_header(): Returns the stream event header field
	of a given event.
*/
extern int bt_event_set_header(struct bt_event *event,
		struct bt_field *header);

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

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

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_set_stream_event_context(): Sets the stream event context
	field of a given event.
*/
extern struct bt_field *bt_event_get_stream_event_context(
		struct bt_event *event);

/**
@brief	Sets the stream event context field of the CTF IR event
	\p event to \p context, or unsets the current stream event context field
	from \p event.

If \p context is not \c NULL, the field type of \p context, as returned by
bt_field_get_type(), \em must be equivalent to the field type returned by
bt_stream_class_get_event_context_type() for the parent stream class
of \p event.

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

@prenotnull{event}
@prehot{event}
@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
	the field type returned by bt_stream_class_get_event_context_type()
	for the parent stream class of \p event.
@postrefcountsame{event}
@post <strong>On success, if \p context is not \c NULL</strong>, the reference
	count of \p context is incremented.

@sa bt_event_get_stream_event_context(): Returns the stream event context
	field of a given event.
*/
extern int bt_event_set_stream_event_context(struct bt_event *event,
		struct bt_field *context);

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

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

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_set_context(): Sets the event context field of a given
	event.
*/
extern struct bt_field *bt_event_get_context(struct bt_event *event);

/**
@brief	Sets the event context field of the CTF IR event \p event to \p context,
	or unsets the current event context field from \p event.

If \p context is not \c NULL, the field type of \p context, as returned by
bt_field_get_type(), \em must be equivalent to the field type returned by
bt_event_class_get_context_type() for the parent class of \p event.

@param[in] event	Event of which to set the context field.
@param[in] context	Event context field.
@returns		0 on success, or a negative value on error.

@prenotnull{event}
@prehot{event}
@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
	the field type returned by bt_event_class_get_context_type() for the
	parent class of \p event.
@postrefcountsame{event}
@post <strong>On success, if \p context is not \c NULL</strong>, the reference
	count of \p context is incremented.

@sa bt_event_get_context(): Returns the context field of a given event.
*/
extern int bt_event_set_context(struct bt_event *event,
		struct bt_field *context);

/**
@brief	Returns the payload field of the CTF IR event \p event.

@param[in] event	Event of which to get the payload field.
@returns		Payload field of \p event, or \c NULL if the payload
			field is not set or on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_set_payload(): Sets the payload field of a given
	event.
*/
extern struct bt_field *bt_event_get_payload(struct bt_event *event);

/**
@brief	Sets the payload field of the CTF IR event \p event to \p payload,
	or unsets the current event payload field from \p event.

If \p payload is not \c NULL, the field type of \p payload, as returned by
bt_field_get_type(), \em must be equivalent to the field type returned by
bt_event_class_get_payload_type() for the parent class of \p event.

@param[in] event	Event of which to set the payload field.
@param[in] payload	Event payload field.
@returns		0 on success, or a negative value on error.

@prenotnull{event}
@prehot{event}
@pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
	the field typereturned by bt_event_class_get_payload_type() for the
	parent class of \p event.
@postrefcountsame{event}
@post <strong>On success, if \p payload is not \c NULL</strong>, the reference
	count of \p payload is incremented.

@sa bt_event_get_payload(): Returns the payload field of a given event.
*/
extern int bt_event_set_payload(struct bt_event *event,
		struct bt_field *payload);

/** @} */

/**
@name Clock value functions
@{
*/

/**
@brief	Returns the value, as of the CTF IR event \p event, of the
	clock described by the
	\link ctfirclockclass CTF IR clock class\endlink \p clock_class.

@param[in] event	Event of which to get the value of the clock
			described by \p clock_class.
@param[in] clock_class	Class of the clock of which to get the value.
@returns		Value of the clock described by \p clock_class
			as of \p event.

@prenotnull{event}
@prenotnull{clock_class}
@postrefcountsame{event}
@postrefcountsame{clock_class}
@postsuccessrefcountretinc

@sa bt_event_set_clock_value(): Sets the clock value of a given event.
*/
extern struct bt_clock_value *bt_event_get_clock_value(
		struct bt_event *event,
		struct bt_clock_class *clock_class);

/**
@brief	Sets the value, as of the CTF IR event \p event, of the
	clock described by its \link ctfirclockclass CTF IR
	clock class\endlink.

@param[in] event	Event of which to set the value of the clock
			described by the clock class of \p clock_value.
@param[in] clock_value	Value of the clock described by its clock class
			as of \p event.
@returns		0 on success, or a negative value on error.

@prenotnull{event}
@prenotnull{clock_value}
@prehot{event}
@postrefcountsame{event}

@sa bt_event_get_clock_value(): Returns the clock value of
	a given event.
*/
extern int bt_event_set_clock_value(
		struct bt_event *event,
		struct bt_clock_value *clock_value);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_EVENT_H */
Commit	Line	Data
	1	#ifndef BABELTRACE_CTF_IR_EVENT_H
	2	#define BABELTRACE_CTF_IR_EVENT_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Event
	6	*
	7	* Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	8	*
	9	* Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
	10	*
	11	* Permission is hereby granted, free of charge, to any person obtaining a copy
	12	* of this software and associated documentation files (the "Software"), to deal
	13	* in the Software without restriction, including without limitation the rights
	14	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	15	* copies of the Software, and to permit persons to whom the Software is
	16	* furnished to do so, subject to the following conditions:
	17	*
	18	* The above copyright notice and this permission notice shall be included in
	19	* all copies or substantial portions of the Software.
	20	*
	21	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	22	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	23	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	24	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	25	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	26	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	27	* SOFTWARE.
	28	*
	29	* The Common Trace Format (CTF) Specification is available at
	30	* http://www.efficios.com/ctf
	31	*/
	32
	33	#include <stdint.h>
	34	#include <stddef.h>
	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
	40	struct bt_value;
	41	struct bt_clock_class;
	42
	43	/**
	44	@defgroup ctfirevent CTF IR event
	45	@ingroup ctfir
	46	@brief CTF IR event.
	47
	48	@code
	49	#include <babeltrace/ctf-ir/event.h>
	50	@endcode
	51
	52	A CTF IR <strong><em>event</em></strong> is a container of event
	53	fields:
	54
	55	- <strong>Stream event header</strong> field, described by the
	56	<em>stream event header field type</em> of a
	57	\link ctfirstreamclass CTF IR stream class\endlink.
	58	- <strong>Stream event context</strong> field, described by the
	59	<em>stream event context field type</em> of a stream class.
	60	- <strong>Event context</strong> field, described by the
	61	<em>event context field type</em> of a
	62	\link ctfireventclass CTF IR event class\endlink.
	63	- <strong>Event payload</strong>, described by the
	64	<em>event payload field type</em> of an event class.
	65
	66	As a reminder, here's the structure of a CTF packet:
	67
	68	@imgpacketstructure
	69
	70	You can create a CTF IR event \em from a
	71	\link ctfireventclass CTF IR event class\endlink with
	72	bt_event_create(). The event class you use to create an event
	73	object becomes its parent.
	74
	75	If the \link ctfirtraceclass CTF IR trace class\endlink of an event
	76	object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
	77	which is the parent of its event class) was created by a
	78	\link ctfwriter CTF writer\endlink object, then the only possible
	79	action you can do with this event object is to append it to a
	80	\link ctfirstream CTF IR stream\endlink with
	81	bt_stream_append_event(). Otherwise, you can create an event
	82	notification with bt_notification_event_create(). The event you pass
	83	to this function \em must have an attached packet object first.
	84
	85	You can attach a \link ctfirpacket CTF IR packet object\endlink to an
	86	event object with bt_event_set_packet().
	87
	88	A CTF IR event has a mapping of
	89	\link ctfirclockvalue CTF IR clock values\endlink. A clock value is
	90	an instance of a specific
	91	\link ctfirclockclass CTF IR clock class\endlink when the event is
	92	emitted. You can set an event object's clock value with
	93	bt_event_set_clock_value().
	94
	95	As with any Babeltrace object, CTF IR event objects have
	96	<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
	97	counts</a>. See \ref refs to learn more about the reference counting
	98	management of Babeltrace objects.
	99
	100	bt_notification_event_create() \em freezes its event parameter on
	101	success. You cannot modify a frozen event object: it is considered
	102	immutable, except for \link refs reference counting\endlink.
	103
	104	@sa ctfireventclass
	105	@sa ctfirpacket
	106
	107	@file
	108	@brief CTF IR event type and functions.
	109	@sa ctfirevent
	110
	111	@addtogroup ctfirevent
	112	@{
	113	*/
	114
	115	/**
	116	@struct bt_event
	117	@brief A CTF IR event.
	118	@sa ctfirevent
	119	*/
	120	struct bt_event;
	121	struct bt_clock;
	122	struct bt_clock_value;
	123	struct bt_event_class;
	124	struct bt_field;
	125	struct bt_field_type;
	126	struct bt_stream_class;
	127	struct bt_packet;
	128
	129	/**
	130	@name Creation and parent access functions
	131	@{
	132	*/
	133
	134	/**
	135	@brief Creates a default CTF IR event from the CTF IR event class
	136	\p event_class.
	137
	138	\p event_class \em must have a parent
	139	\link ctfirstreamclass CTF IR stream class\endlink.
	140
	141	On success, the four fields of the created event object are not set. You
	142	can set them with bt_event_set_header(),
	143	bt_event_set_stream_event_context(),
	144	bt_event_set_context(), and bt_event_set_payload().
	145
	146	This function tries to resolve the needed
	147	\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
	148	types that are found anywhere in the context or payload field
	149	types of \p event_class and in the root field types of the
	150	parent stream class of \p event_class. If any automatic resolving fails,
	151	this function fails. This means that, if any dynamic field type need
	152	a field type which should be found in the trace packet header root
	153	field type, and if the parent stream class of \p event_class was not
	154	added to a \link ctfirtraceclass CTF IR trace class\endlink yet
	155	with bt_trace_add_stream_class(), then this function fails.
	156
	157	@param[in] event_class CTF IR event class to use to create the
	158	CTF IR event.
	159	@returns Created event object, or \c NULL on error.
	160
	161	@prenotnull{event_class}
	162	@pre \p event_class has a parent stream class.
	163	@postsuccessrefcountret1
	164	*/
	165	extern struct bt_event bt_event_create(struct bt_event_class event_class);
	166
	167	/**
	168	@brief Returns the parent CTF IR event class of the CTF IR event
	169	\p event.
	170
	171	This function returns a reference to the event class which was used to
	172	create the event object in the first place with bt_event_create().
	173
	174	@param[in] event Event of which to get the parent event class.
	175	@returns Parent event class of \p event,
	176	or \c NULL on error.
	177
	178	@prenotnull{event}
	179	@postrefcountsame{event}
	180	@postsuccessrefcountretinc
	181	*/
	182	extern struct bt_event_class bt_event_get_class(struct bt_event event);
	183
	184	/**
	185	@brief Returns the CTF IR packet associated to the CTF IR event
	186	\p event.
	187
	188	This function returns a reference to the event class which was set to
	189	\p event in the first place with bt_event_set_packet().
	190
	191	@param[in] event Event of which to get the associated packet.
	192	@returns Packet associated to \p event,
	193	or \c NULL if no packet is associated to
	194	\p event or on error.
	195
	196	@prenotnull{event}
	197	@postrefcountsame{event}
	198	@postsuccessrefcountretinc
	199
	200	@sa bt_event_set_packet(): Associates a given event to a given
	201	packet.
	202	*/
	203	extern struct bt_packet bt_event_get_packet(struct bt_event event);
	204
	205	/**
	206	@brief Associates the CTF IR event \p event to the CTF IR packet
	207	\p packet.
	208
	209	The \link ctfirstreamclass CTF IR stream class\endlink of the
	210	parent \link ctfirstream CTF IR stream\endlink of \p packet \em must
	211	be the same as the parent stream class of the
	212	\link ctfireventclass CTF IR event class\endlink returned
	213	by bt_event_get_class() for \p event.
	214
	215	You \em must call this function to create an event-packet association
	216	before you call bt_notification_event_create() with \p event.
	217
	218	On success, this function also sets the parent stream object of
	219	\p event to the parent stream of \p packet.
	220
	221	@param[in] event Event to which to associate \p packet.
	222	@param[in] packet Packet to associate to \p event.
	223	@returns 0 on success, or a negative value on error.
	224
	225	@prenotnull{event}
	226	@prenotnull{packet}
	227	@prehot{event}
	228	@pre The parent stream class of \p packet is the same as the parent
	229	stream class of \p event.
	230	@postsuccessrefcountretinc
	231
	232	@sa bt_event_get_packet(): Returns the associated packet of a
	233	given event object.
	234	*/
	235	extern int bt_event_set_packet(struct bt_event *event,
	236	struct bt_packet *packet);
	237
	238	/**
	239	@brief Returns the parent CTF IR stream associated to the CTF IR event
	240	\p event.
	241
	242	@param[in] event Event of which to get the parent stream.
	243	@returns Parent stream of \p event, or \c NULL on error.
	244
	245	@prenotnull{event}
	246	@postrefcountsame{event}
	247	@postsuccessrefcountretinc
	248	*/
	249	extern struct bt_stream bt_event_get_stream(struct bt_event event);
	250
	251	/** @} */
	252
	253	/**
	254	@name Contained fields functions
	255	@{
	256	*/
	257
	258	/**
	259	@brief Returns the stream event header field of the CTF IR event
	260	\p event.
	261
	262	@param[in] event Event of which to get the stream event header
	263	field.
	264	@returns Stream event header field of \p event,
	265	or \c NULL if the stream event header
	266	field is not set or on error.
	267
	268	@prenotnull{event}
	269	@postrefcountsame{event}
	270	@postsuccessrefcountretinc
	271
	272	@sa bt_event_get_header(): Sets the stream event header
	273	field of a given event.
	274	*/
	275	extern struct bt_field bt_event_get_header(struct bt_event event);
	276
	277	/**
	278	@brief Sets the stream event header field of the CTF IR event
	279	\p event to \p header, or unsets the current stream event header field
	280	from \p event.
	281
	282	If \p header is not \c NULL, the field type of \p header, as returned by
	283	bt_field_get_type(), \em must be equivalent to the field type returned by
	284	bt_stream_class_get_event_header_type() for the parent stream class
	285	of \p event.
	286
	287	@param[in] event Event of which to set the stream event header
	288	field.
	289	@param[in] header Stream event header field.
	290	@returns 0 on success, or a negative value on error.
	291
	292	@prenotnull{event}
	293	@prehot{event}
	294	@pre <strong>\p header, if not \c NULL</strong>, has a field type equivalent to
	295	the field type returned by bt_stream_class_get_event_header_type()
	296	for the parent stream class of \p event.
	297	@postrefcountsame{event}
	298	@post <strong>On success, if \p header is not \c NULL</strong>,
	299	the reference count of \p header is incremented.
	300
	301	@sa bt_event_get_header(): Returns the stream event header field
	302	of a given event.
	303	*/
	304	extern int bt_event_set_header(struct bt_event *event,
	305	struct bt_field *header);
	306
	307	/**
	308	@brief Returns the stream event context field of the CTF IR event
	309	\p event.
	310
	311	@param[in] event Event of which to get the stream event context
	312	field.
	313	@returns Stream event context field of \p event,
	314	or \c NULL if the stream event context
	315	field is not set or on error.
	316
	317	@prenotnull{event}
	318	@postrefcountsame{event}
	319	@postsuccessrefcountretinc
	320
	321	@sa bt_event_set_stream_event_context(): Sets the stream event context
	322	field of a given event.
	323	*/
	324	extern struct bt_field *bt_event_get_stream_event_context(
	325	struct bt_event *event);
	326
	327	/**
	328	@brief Sets the stream event context field of the CTF IR event
	329	\p event to \p context, or unsets the current stream event context field
	330	from \p event.
	331
	332	If \p context is not \c NULL, the field type of \p context, as returned by
	333	bt_field_get_type(), \em must be equivalent to the field type returned by
	334	bt_stream_class_get_event_context_type() for the parent stream class
	335	of \p event.
	336
	337	@param[in] event Event of which to set the stream event context field.
	338	@param[in] context Stream event context field.
	339	@returns 0 on success, or a negative value on error.
	340
	341	@prenotnull{event}
	342	@prehot{event}
	343	@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
	344	the field type returned by bt_stream_class_get_event_context_type()
	345	for the parent stream class of \p event.
	346	@postrefcountsame{event}
	347	@post <strong>On success, if \p context is not \c NULL</strong>, the reference
	348	count of \p context is incremented.
	349
	350	@sa bt_event_get_stream_event_context(): Returns the stream event context
	351	field of a given event.
	352	*/
	353	extern int bt_event_set_stream_event_context(struct bt_event *event,
	354	struct bt_field *context);
	355
	356	/**
	357	@brief Returns the event context field of the CTF IR event \p event.
	358
	359	@param[in] event Event of which to get the context field.
	360	@returns Event context field of \p event, or \c NULL if the
	361	event context field is not set or on error.
	362
	363	@prenotnull{event}
	364	@postrefcountsame{event}
	365	@postsuccessrefcountretinc
	366
	367	@sa bt_event_set_context(): Sets the event context field of a given
	368	event.
	369	*/
	370	extern struct bt_field bt_event_get_context(struct bt_event event);
	371
	372	/**
	373	@brief Sets the event context field of the CTF IR event \p event to \p context,
	374	or unsets the current event context field from \p event.
	375
	376	If \p context is not \c NULL, the field type of \p context, as returned by
	377	bt_field_get_type(), \em must be equivalent to the field type returned by
	378	bt_event_class_get_context_type() for the parent class of \p event.
	379
	380	@param[in] event Event of which to set the context field.
	381	@param[in] context Event context field.
	382	@returns 0 on success, or a negative value on error.
	383
	384	@prenotnull{event}
	385	@prehot{event}
	386	@pre <strong>\p context, if not \c NULL</strong>, has a field type equivalent to
	387	the field type returned by bt_event_class_get_context_type() for the
	388	parent class of \p event.
	389	@postrefcountsame{event}
	390	@post <strong>On success, if \p context is not \c NULL</strong>, the reference
	391	count of \p context is incremented.
	392
	393	@sa bt_event_get_context(): Returns the context field of a given event.
	394	*/
	395	extern int bt_event_set_context(struct bt_event *event,
	396	struct bt_field *context);
	397
	398	/**
	399	@brief Returns the payload field of the CTF IR event \p event.
	400
	401	@param[in] event Event of which to get the payload field.
	402	@returns Payload field of \p event, or \c NULL if the payload
	403	field is not set or on error.
	404
	405	@prenotnull{event}
	406	@postrefcountsame{event}
	407	@postsuccessrefcountretinc
	408
	409	@sa bt_event_set_payload(): Sets the payload field of a given
	410	event.
	411	*/
	412	extern struct bt_field bt_event_get_payload(struct bt_event event);
	413
	414	/**
	415	@brief Sets the payload field of the CTF IR event \p event to \p payload,
	416	or unsets the current event payload field from \p event.
	417
	418	If \p payload is not \c NULL, the field type of \p payload, as returned by
	419	bt_field_get_type(), \em must be equivalent to the field type returned by
	420	bt_event_class_get_payload_type() for the parent class of \p event.
	421
	422	@param[in] event Event of which to set the payload field.
	423	@param[in] payload Event payload field.
	424	@returns 0 on success, or a negative value on error.
	425
	426	@prenotnull{event}
	427	@prehot{event}
	428	@pre <strong>\p payload, if not \c NULL</strong>, has a field type equivalent to
	429	the field typereturned by bt_event_class_get_payload_type() for the
	430	parent class of \p event.
	431	@postrefcountsame{event}
	432	@post <strong>On success, if \p payload is not \c NULL</strong>, the reference
	433	count of \p payload is incremented.
	434
	435	@sa bt_event_get_payload(): Returns the payload field of a given event.
	436	*/
	437	extern int bt_event_set_payload(struct bt_event *event,
	438	struct bt_field *payload);
	439
	440	/** @} */
	441
	442	/**
	443	@name Clock value functions
	444	@{
	445	*/
	446
	447	/**
	448	@brief Returns the value, as of the CTF IR event \p event, of the
	449	clock described by the
	450	\link ctfirclockclass CTF IR clock class\endlink \p clock_class.
	451
	452	@param[in] event Event of which to get the value of the clock
	453	described by \p clock_class.
	454	@param[in] clock_class Class of the clock of which to get the value.
	455	@returns Value of the clock described by \p clock_class
	456	as of \p event.
	457
	458	@prenotnull{event}
	459	@prenotnull{clock_class}
	460	@postrefcountsame{event}
	461	@postrefcountsame{clock_class}
	462	@postsuccessrefcountretinc
	463
	464	@sa bt_event_set_clock_value(): Sets the clock value of a given event.
	465	*/
	466	extern struct bt_clock_value *bt_event_get_clock_value(
	467	struct bt_event *event,
	468	struct bt_clock_class *clock_class);
	469
	470	/**
	471	@brief Sets the value, as of the CTF IR event \p event, of the
	472	clock described by its \link ctfirclockclass CTF IR
	473	clock class\endlink.
	474
	475	@param[in] event Event of which to set the value of the clock
	476	described by the clock class of \p clock_value.
	477	@param[in] clock_value Value of the clock described by its clock class
	478	as of \p event.
	479	@returns 0 on success, or a negative value on error.
	480
	481	@prenotnull{event}
	482	@prenotnull{clock_value}
	483	@prehot{event}
	484	@postrefcountsame{event}
	485
	486	@sa bt_event_get_clock_value(): Returns the clock value of
	487	a given event.
	488	*/
	489	extern int bt_event_set_clock_value(
	490	struct bt_event *event,
	491	struct bt_clock_value *clock_value);
	492
	493	/** @} */
	494
	495	/** @} */
	496
	497	#ifdef __cplusplus
	498	}
	499	#endif
	500
	501	#endif /* BABELTRACE_CTF_IR_EVENT_H */