[babeltrace.git] / include / babeltrace / ctf-ir / stream-class.h

#ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
#define BABELTRACE_CTF_IR_STREAM_CLASS_H

/*
 * BabelTrace - CTF IR: Stream Class
 *
 * Copyright 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 <babeltrace/ctf-ir/visitor.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup ctfirstreamclass CTF IR stream class
@ingroup ctfir
@brief CTF IR stream class.

A CTF IR <strong><em>stream class</em></strong> is a template that you
can use to create concrete \link ctfirstream CTF IR streams\endlink.

A stream class has the following properties, both of which \em must
be unique amongst all the stream classes contained in the same
\link ctfirtraceclass CTF IR trace class\endlink:

- A \b name.
- A numeric \b ID.

In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
contains zero or more stream classes,
and a stream class contains zero or more
\link ctfireventclass event classes\endlink.
You can add an event class
to a stream class with bt_ctf_stream_class_add_event_class().
You can add a stream class to a trace class with
bt_ctf_trace_add_stream_class().

A stream class owns three \link ctfirfieldtypes field types\endlink:

- An optional <strong>stream packet context</strong> field type, which
  represents the \c stream.packet.context CTF scope.
- An optional <strong>stream event header</strong> field type, which
  represents the \c stream.event.header CTF scope.
- An optional <strong>stream event context</strong> field type, which
  represents the \c stream.event.context CTF scope.

Those three field types \em must be structure field types as of
Babeltrace \btversion.

As per the CTF specification, the event header field type \em must
contain a field named \c id if the stream class contains more than one
event class.

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

@imgpacketstructure

Before you can create a stream from a stream class with
bt_ctf_stream_create(), you \em must add the prepared stream class to a
trace class by calling bt_ctf_trace_add_stream_class().

As with any Babeltrace object, CTF IR stream class 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.

The following functions \em freeze their stream class parameter on
success:

- bt_ctf_trace_add_stream_class()
- bt_ctf_event_create()
- bt_ctf_writer_create_stream()
  (\link ctfirwriter CTF writer\endlink mode only)

You cannot modify a frozen stream class: it is considered immutable,
except for:

- Adding an event class to it with
  bt_ctf_stream_class_add_event_class().
- \link refs Reference counting\endlink.

@sa ctfirstream
@sa ctfireventclass
@sa ctfirtraceclass

@file
@brief CTF IR stream class type and functions.
@sa ctfirstreamclass

@addtogroup ctfirstreamclass
@{
*/

/**
@struct bt_ctf_stream_class
@brief A CTF IR stream class.
@sa ctfirstreamclass
*/
struct bt_ctf_stream_class;
struct bt_ctf_event_class;
struct bt_ctf_clock;

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

/**
@brief	Creates a default CTF IR stream class named \p name, or a
	default unnamed stream class if \p name is \c NULL.

On success, the packet context field type of the created stream class
has the following fields:

- <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
- <code>timestamp_end</code>: a 64-bit unsigned integer field type.
- <code>content_size</code>: a 64-bit unsigned integer field type.
- <code>packet_size</code>: a 64-bit unsigned integer field type.
- <code>events_discarded</code>: a 64-bit unsigned integer field type.

On success, the event header field type of the created stream class
has the following fields:

- <code>code</code>: a 32-bit unsigned integer field type.
- <code>timestamp</code>: a 64-bit unsigned integer field type.

You can modify those default field types after the stream class is
created with bt_ctf_stream_class_set_packet_context_type() and
bt_ctf_stream_class_set_event_header_type().

@param[in] name	Name of the stream class to create (can be \c NULL to
		create an unnamed stream class).
@returns	Created stream class, or \c NULL on error.

@postsuccessrefcountret1
*/
extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name);

/**
@brief	Returns the parent CTF IR trace class of the CTF IR stream
	class \p stream_class.

It is possible that the stream class was not added to a trace class
yet, in which case this function returns \c NULL. You can add a
stream class to a trace class with
bt_ctf_trace_add_stream_class().

@param[in] stream_class	Stream class of which to get the parent
			trace class.
@returns		Parent trace class of \p stream_class,
			or \c NULL if \p stream_class was not
			added to a trace class yet or on error.

@prenotnull{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_trace_add_stream_class(): Add a stream class to
	a trace class.
*/
extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace(
		struct bt_ctf_stream_class *stream_class);

/** @} */

/**
@name Properties functions
@{
*/

/**
@brief	Returns the name of the CTF IR stream class \p stream_class.

On success, \p stream_class remains the sole owner of the returned
string.

@param[in] stream_class	Stream class of which to get the name.
@returns		Name of stream class \p stream_class, or
			\c NULL if \p stream_class is unnamed or
			on error.

@prenotnull{stream_class}
@postrefcountsame{stream_class}

@sa bt_ctf_stream_class_set_name(): Sets the name of a given
	stream class.
*/
extern const char *bt_ctf_stream_class_get_name(
		struct bt_ctf_stream_class *stream_class);

/**
@brief	Sets the name of the CTF IR stream class
	\p stream_class to \p name.

\p name must be unique amongst the names of all the stream classes
of the trace class to which you eventually add \p stream_class.

@param[in] stream_class	Stream class of which to set the name.
@param[in] name		Name of the stream class (copied on success).
@returns		0 on success, or a negative value on error.

@prenotnull{stream_class}
@prenotnull{name}
@prehot{stream_class}
@postrefcountsame{stream_class}

@sa bt_ctf_stream_class_get_name(): Returns the name of a given
	stream class.
*/
extern int bt_ctf_stream_class_set_name(
		struct bt_ctf_stream_class *stream_class, const char *name);

/**
@brief	Returns the numeric ID of the CTF IR stream class \p stream_class.

@param[in] stream_class	Stream class of which to get the numeric ID.
@returns		ID of stream class \p stream_class, or a
			negative value on error.

@prenotnull{stream_class}
@postrefcountsame{stream_class}

@sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
	stream class.
*/
extern int64_t bt_ctf_stream_class_get_id(
		struct bt_ctf_stream_class *stream_class);

/**
@brief	Sets the numeric ID of the CTF IR stream class
	\p stream_class to \p id.

\p id must be unique amongst the IDs of all the stream classes
of the trace class to which you eventually add \p stream_class.

@param[in] stream_class	Stream class of which to set the numeric ID.
@param[in] id		ID of the stream class.
@returns		0 on success, or a negative value on error.

@prenotnull{stream_class}
@prehot{stream_class}
@postrefcountsame{stream_class}

@sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
	stream class.
*/
extern int bt_ctf_stream_class_set_id(
		struct bt_ctf_stream_class *stream_class, uint32_t id);

/** @} */

/**
@name Contained field types functions
@{
*/

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

@param[in] stream_class	Stream class of which to get the packet
			context field type.
@returns		Packet context field type of \p stream_class,
			or \c NULL on error.

@prenotnull{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
	context field type of a given stream class.
*/
extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(
		struct bt_ctf_stream_class *stream_class);

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

As of Babeltrace \btversion, \p packet_context_type \em must be a
CTF IR structure field type object.

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

@prenotnull{stream_class}
@prenotnull{packet_context_type}
@prehot{stream_class}
@preisstructft{packet_context_type}
@postrefcountsame{stream_class}
@postsuccessrefcountinc{packet_context_type}

@sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
	context field type of a given stream class.
*/
extern int bt_ctf_stream_class_set_packet_context_type(
		struct bt_ctf_stream_class *stream_class,
		struct bt_ctf_field_type *packet_context_type);

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

@param[in] stream_class	Stream class of which to get the event header
			field type.
@returns		Event header field type of \p stream_class,
			or \c NULL on error.

@prenotnull{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_set_event_header_type(): Sets the event
	header field type of a given stream class.
*/
extern struct bt_ctf_field_type *
bt_ctf_stream_class_get_event_header_type(
		struct bt_ctf_stream_class *stream_class);

/**
@brief	Sets the event header field type of the CTF IR stream class
	\p stream_class to \p event_header_type.

As of Babeltrace \btversion, \p event_header_type \em must be a
CTF IR structure field type object.

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

@prenotnull{stream_class}
@prenotnull{event_header_type}
@prehot{stream_class}
@preisstructft{event_header_type}
@postrefcountsame{stream_class}
@postsuccessrefcountinc{event_header_type}

@sa bt_ctf_stream_class_get_event_header_type(): Returns the event
	header field type of a given stream class.
*/
extern int bt_ctf_stream_class_set_event_header_type(
		struct bt_ctf_stream_class *stream_class,
		struct bt_ctf_field_type *event_header_type);

/**
@brief	Returns the per-stream class event context field type of the
	CTF IR stream class \p stream_class.

@param[in] stream_class	Stream class of which to get the per-stream
			class event context field type.
@returns		Per-stream class event context field type of
			\p stream_class, or \c NULL on error.

@prenotnull{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
	class event context field type of a given stream class.
*/
extern struct bt_ctf_field_type *
bt_ctf_stream_class_get_event_context_type(
		struct bt_ctf_stream_class *stream_class);

/**
@brief	Sets the per-stream class event context field type of the CTF
	IR stream class \p stream_class to \p event_context_type.

As of Babeltrace \btversion, \p event_context_type \em must be a
CTF IR structure field type object.

@param[in] stream_class		Stream class of which to set the
				per-stream class event context
				field type.
@param[in] event_context_type	Per-stream class event context context
				field type.
@returns			0 on success, or a negative value on error.

@prenotnull{stream_class}
@prenotnull{event_context_type}
@prehot{stream_class}
@preisstructft{event_context_type}
@postrefcountsame{stream_class}
@postsuccessrefcountinc{event_context_type}

@sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
	class event context field type of a given stream class.
*/
extern int bt_ctf_stream_class_set_event_context_type(
		struct bt_ctf_stream_class *stream_class,
		struct bt_ctf_field_type *event_context_type);

/** @} */

/**
@name Event class children functions
@{
*/

/**
@brief	Returns the number of event classes contained in the
	CTF IR stream class \p stream_class.

@param[in] stream_class	Stream class of which to get the number
			of children event classes.
@returns		Number of children event classes
			contained in \p stream_class, or
			a negative value on error.

@prenotnull{stream_class}
@postrefcountsame{stream_class}
*/
extern int bt_ctf_stream_class_get_event_class_count(
		struct bt_ctf_stream_class *stream_class);

/**
@brief  Returns the event class at index \p index in the CTF IR stream
	class \p stream_class.

@param[in] stream_class	Stream class of which to get the event class.
@param[in] index	Index of the event class to find.
@returns		Event class at index \p index, or \c NULL
			on error.

@prenotnull{stream_class}
@pre \p index is lesser than the number of event classes contained in the
	stream class \p stream_class (see
	bt_ctf_stream_class_get_event_class_count()).
@postrefcountsame{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
	by ID.
@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
	by name.
*/
extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
		struct bt_ctf_stream_class *stream_class, int index);

/**
@brief  Returns the event class named \c name found in the CTF IR stream
	class \p stream_class.

@param[in] stream_class	Stream class of which to get the event class.
@param[in] name		Name of the event class to find.
@returns		Event class named \p name, or \c NULL
			on error.

@prenotnull{stream_class}
@prenotnull{name}
@postrefcountsame{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
	by ID.
*/
extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
		struct bt_ctf_stream_class *stream_class, const char *name);

/**
@brief  Returns the event class with ID \c id found in the CTF IR stream
	class \p stream_class.

@param[in] stream_class	Stream class of which to get the event class.
@param[in] id		ID of the event class to find.
@returns		Event class with ID \p id, or \c NULL
			on error.

@prenotnull{stream_class}
@postrefcountsame{stream_class}
@postsuccessrefcountretinc

@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
	by name.
*/
extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
		struct bt_ctf_stream_class *stream_class, uint32_t id);

/**
@brief	Adds the CTF IR event class \p event_class to the
	CTF IR stream class \p stream_class.

On success, \p event_class becomes the child of \p stream_class.

You can only add a given event class to one stream class.

You can call this function even if \p stream_class is frozen. Adding
event classes is the only operation that is permitted
on a frozen stream class.

@param[in] stream_class	Stream class to which to add \p event_class.
@param[in] event_class	Event class to add to \p stream_class.
@returns		0 on success, or a negative value on error.

@prenotnull{stream_class}
@prenotnull{event_class}
@prehot{event_class}
@postrefcountsame{stream_class}
@postsuccessrefcountinc{event_class}
*/
extern int bt_ctf_stream_class_add_event_class(
		struct bt_ctf_stream_class *stream_class,
		struct bt_ctf_event_class *event_class);

/** @} */

/**
@name Misc. function
@{
*/

/**
@brief	Accepts the visitor \p visitor to visit the hierarchy of the
	CTF IR stream class \p stream_class.

This function traverses the hierarchy of \p stream_class in pre-order
and calls \p visitor on each element.

The stream class itself is visited first, and then all its children
event classes.

@param[in] stream_class	Stream class to visit.
@param[in] visitor	Visiting function.
@param[in] data		User data.
@returns		0 on success, or a negative value on error.

@prenotnull{stream_class}
@prenotnull{visitor}
*/
extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class,
		bt_ctf_visitor visitor, void *data);

/** @} */

/** @} */

// TODO: document for writer
extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
		struct bt_ctf_stream_class *stream_class);

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */
Commit	Line	Data
adc315b8 JG	1	#ifndef BABELTRACE_CTF_IR_STREAM_CLASS_H
	2	#define BABELTRACE_CTF_IR_STREAM_CLASS_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Stream Class
	6	*
de9dd397	7	* Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
adc315b8 JG	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
48d711a2	33	#include <stdint.h>
8bf65fbd	34	#include <babeltrace/ctf-ir/visitor.h>
48d711a2	35
adc315b8 JG	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
594a3fb7 PP	40	/**
	41	@defgroup ctfirstreamclass CTF IR stream class
	42	@ingroup ctfir
	43	@brief CTF IR stream class.
	44
	45	A CTF IR <strong><em>stream class</em></strong> is a template that you
	46	can use to create concrete \link ctfirstream CTF IR streams\endlink.
	47
	48	A stream class has the following properties, both of which \em must
	49	be unique amongst all the stream classes contained in the same
	50	\link ctfirtraceclass CTF IR trace class\endlink:
	51
	52	- A \b name.
	53	- A numeric \b ID.
	54
	55	In the Babeltrace CTF IR system, a \link ctfirtraceclass trace class\endlink
	56	contains zero or more stream classes,
	57	and a stream class contains zero or more
	58	\link ctfireventclass event classes\endlink.
	59	You can add an event class
	60	to a stream class with bt_ctf_stream_class_add_event_class().
	61	You can add a stream class to a trace class with
	62	bt_ctf_trace_add_stream_class().
	63
	64	A stream class owns three \link ctfirfieldtypes field types\endlink:
	65
	66	- An optional <strong>stream packet context</strong> field type, which
	67	represents the \c stream.packet.context CTF scope.
	68	- An optional <strong>stream event header</strong> field type, which
	69	represents the \c stream.event.header CTF scope.
	70	- An optional <strong>stream event context</strong> field type, which
	71	represents the \c stream.event.context CTF scope.
	72
	73	Those three field types \em must be structure field types as of
	74	Babeltrace \btversion.
	75
	76	As per the CTF specification, the event header field type \em must
	77	contain a field named \c id if the stream class contains more than one
	78	event class.
	79
	80	As a reminder, here's the structure of a CTF packet:
	81
	82	@imgpacketstructure
	83
	84	Before you can create a stream from a stream class with
	85	bt_ctf_stream_create(), you \em must add the prepared stream class to a
	86	trace class by calling bt_ctf_trace_add_stream_class().
	87
	88	As with any Babeltrace object, CTF IR stream class objects have
	89	<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
	90	counts</a>. See \ref refs to learn more about the reference counting
	91	management of Babeltrace objects.
	92
	93	The following functions \em freeze their stream class parameter on
	94	success:
	95
	96	- bt_ctf_trace_add_stream_class()
	97	- bt_ctf_event_create()
	98	- bt_ctf_writer_create_stream()
	99	(\link ctfirwriter CTF writer\endlink mode only)
	100
	101	You cannot modify a frozen stream class: it is considered immutable,
	102	except for:
	103
104	- Adding an event class to it with
105	bt_ctf_stream_class_add_event_class().
106	- \link refs Reference counting\endlink.
107
108	@sa ctfirstream
109	@sa ctfireventclass
110	@sa ctfirtraceclass
111
112	@file
113	@brief CTF IR stream class type and functions.
114	@sa ctfirstreamclass
115
116	@addtogroup ctfirstreamclass
117	@{
118	*/
119
120	/**
121	@struct bt_ctf_stream_class
122	@brief A CTF IR stream class.
123	@sa ctfirstreamclass
124	*/
adc315b8	125	struct bt_ctf_stream_class;
594a3fb7	126	struct bt_ctf_event_class;
adc315b8 JG	127	struct bt_ctf_clock;
adc315b8 JG	128
594a3fb7 PP	129	/**
	130	@name Creation and parent access functions
	131	@{
	132	*/
	133
	134	/**
	135	@brief Creates a default CTF IR stream class named \p name, or a
	136	default unnamed stream class if \p name is \c NULL.
	137
	138	On success, the packet context field type of the created stream class
	139	has the following fields:
	140
	141	- <code>timestamp_begin</code>: a 64-bit unsigned integer field type.
	142	- <code>timestamp_end</code>: a 64-bit unsigned integer field type.
	143	- <code>content_size</code>: a 64-bit unsigned integer field type.
	144	- <code>packet_size</code>: a 64-bit unsigned integer field type.
	145	- <code>events_discarded</code>: a 64-bit unsigned integer field type.
	146
	147	On success, the event header field type of the created stream class
	148	has the following fields:
	149
	150	- <code>code</code>: a 32-bit unsigned integer field type.
	151	- <code>timestamp</code>: a 64-bit unsigned integer field type.
	152
	153	You can modify those default field types after the stream class is
	154	created with bt_ctf_stream_class_set_packet_context_type() and
	155	bt_ctf_stream_class_set_event_header_type().
	156
	157	@param[in] name Name of the stream class to create (can be \c NULL to
	158	create an unnamed stream class).
	159	@returns Created stream class, or \c NULL on error.
	160
	161	@postsuccessrefcountret1
	162	*/
adc315b8 JG	163	extern struct bt_ctf_stream_class bt_ctf_stream_class_create(const char name);
adc315b8 JG	164
594a3fb7 PP	165	/**
	166	@brief Returns the parent CTF IR trace class of the CTF IR stream
	167	class \p stream_class.
	168
	169	It is possible that the stream class was not added to a trace class
	170	yet, in which case this function returns \c NULL. You can add a
	171	stream class to a trace class with
	172	bt_ctf_trace_add_stream_class().
	173
	174	@param[in] stream_class Stream class of which to get the parent
	175	trace class.
	176	@returns Parent trace class of \p stream_class,
	177	or \c NULL if \p stream_class was not
	178	added to a trace class yet or on error.
	179
	180	@prenotnull{stream_class}
	181	@postsuccessrefcountretinc
	182
	183	@sa bt_ctf_trace_add_stream_class(): Add a stream class to
	184	a trace class.
	185	*/
142c5610 JG	186	extern struct bt_ctf_trace *bt_ctf_stream_class_get_trace(
	187	struct bt_ctf_stream_class *stream_class);
	188
594a3fb7 PP	189	/** @} */
	190
	191	/**
	192	@name Properties functions
	193	@{
	194	*/
	195
	196	/**
	197	@brief Returns the name of the CTF IR stream class \p stream_class.
	198
	199	On success, \p stream_class remains the sole owner of the returned
	200	string.
	201
	202	@param[in] stream_class Stream class of which to get the name.
	203	@returns Name of stream class \p stream_class, or
	204	\c NULL if \p stream_class is unnamed or
	205	on error.
	206
	207	@prenotnull{stream_class}
	208	@postrefcountsame{stream_class}
	209
	210	@sa bt_ctf_stream_class_set_name(): Sets the name of a given
	211	stream class.
	212	*/
69dc4535 JG	213	extern const char *bt_ctf_stream_class_get_name(
	214	struct bt_ctf_stream_class *stream_class);
	215
594a3fb7 PP	216	/**
	217	@brief Sets the name of the CTF IR stream class
	218	\p stream_class to \p name.
	219
	220	\p name must be unique amongst the names of all the stream classes
	221	of the trace class to which you eventually add \p stream_class.
	222
	223	@param[in] stream_class Stream class of which to set the name.
	224	@param[in] name Name of the stream class (copied on success).
	225	@returns 0 on success, or a negative value on error.
	226
	227	@prenotnull{stream_class}
	228	@prenotnull{name}
	229	@prehot{stream_class}
	230	@postrefcountsame{stream_class}
	231
	232	@sa bt_ctf_stream_class_get_name(): Returns the name of a given
	233	stream class.
	234	*/
3ea33115 JG	235	extern int bt_ctf_stream_class_set_name(
	236	struct bt_ctf_stream_class stream_class, const char name);
	237
594a3fb7 PP	238	/**
594a3fb7 PP	239	@brief Returns the numeric ID of the CTF IR stream class \p stream_class.
2f100782	240
594a3fb7 PP	241	@param[in] stream_class Stream class of which to get the numeric ID.
	242	@returns ID of stream class \p stream_class, or a
	243	negative value on error.
	244
	245	@prenotnull{stream_class}
	246	@postrefcountsame{stream_class}
	247
	248	@sa bt_ctf_stream_class_set_id(): Sets the numeric ID of a given
	249	stream class.
	250	*/
2f100782 JG	251	extern int64_t bt_ctf_stream_class_get_id(
	252	struct bt_ctf_stream_class *stream_class);
	253
594a3fb7 PP	254	/**
	255	@brief Sets the numeric ID of the CTF IR stream class
	256	\p stream_class to \p id.
	257
	258	\p id must be unique amongst the IDs of all the stream classes
	259	of the trace class to which you eventually add \p stream_class.
	260
	261	@param[in] stream_class Stream class of which to set the numeric ID.
	262	@param[in] id ID of the stream class.
	263	@returns 0 on success, or a negative value on error.
	264
	265	@prenotnull{stream_class}
	266	@prehot{stream_class}
	267	@postrefcountsame{stream_class}
	268
	269	@sa bt_ctf_stream_class_get_id(): Returns the numeric ID of a given
	270	stream class.
	271	*/
2f100782 JG	272	extern int bt_ctf_stream_class_set_id(
	273	struct bt_ctf_stream_class *stream_class, uint32_t id);
	274
594a3fb7	275	/** @} */
adc315b8	276
594a3fb7 PP	277	/**
	278	@name Contained field types functions
	279	@{
	280	*/
69dc4535	281
594a3fb7 PP	282	/**
	283	@brief Returns the packet context field type of the CTF IR stream class
	284	\p stream_class.
69dc4535	285
594a3fb7 PP	286	@param[in] stream_class Stream class of which to get the packet
	287	context field type.
	288	@returns Packet context field type of \p stream_class,
	289	or \c NULL on error.
69dc4535	290
594a3fb7 PP	291	@prenotnull{stream_class}
594a3fb7 PP	292	@postsuccessrefcountretinc
0863f950	293
594a3fb7 PP	294	@sa bt_ctf_stream_class_set_packet_context_type(): Sets the packet
	295	context field type of a given stream class.
	296	*/
12c8a1a3 JG	297	extern struct bt_ctf_field_type *bt_ctf_stream_class_get_packet_context_type(
	298	struct bt_ctf_stream_class *stream_class);
	299
594a3fb7 PP	300	/**
	301	@brief Sets the packet context field type of the CTF IR stream class
	302	\p stream_class to \p packet_context_type.
	303
	304	As of Babeltrace \btversion, \p packet_context_type \em must be a
	305	CTF IR structure field type object.
	306
	307	@param[in] stream_class Stream class of which to set the packet
	308	context field type.
	309	@param[in] packet_context_type Packet context field type.
	310	@returns 0 on success, or a negative value on error.
	311
	312	@prenotnull{stream_class}
	313	@prenotnull{packet_context_type}
	314	@prehot{stream_class}
	315	@preisstructft{packet_context_type}
	316	@postrefcountsame{stream_class}
	317	@postsuccessrefcountinc{packet_context_type}
	318
	319	@sa bt_ctf_stream_class_get_packet_context_type(): Returns the packet
	320	context field type of a given stream class.
	321	*/
12c8a1a3 JG	322	extern int bt_ctf_stream_class_set_packet_context_type(
	323	struct bt_ctf_stream_class *stream_class,
	324	struct bt_ctf_field_type *packet_context_type);
	325
594a3fb7 PP	326	/**
	327	@brief Returns the event header field type of the CTF IR stream class
	328	\p stream_class.
	329
	330	@param[in] stream_class Stream class of which to get the event header
	331	field type.
	332	@returns Event header field type of \p stream_class,
	333	or \c NULL on error.
	334
	335	@prenotnull{stream_class}
	336	@postsuccessrefcountretinc
	337
	338	@sa bt_ctf_stream_class_set_event_header_type(): Sets the event
	339	header field type of a given stream class.
	340	*/
662e778c JG	341	extern struct bt_ctf_field_type *
	342	bt_ctf_stream_class_get_event_header_type(
	343	struct bt_ctf_stream_class *stream_class);
	344
594a3fb7 PP	345	/**
	346	@brief Sets the event header field type of the CTF IR stream class
	347	\p stream_class to \p event_header_type.
	348
	349	As of Babeltrace \btversion, \p event_header_type \em must be a
	350	CTF IR structure field type object.
	351
	352	@param[in] stream_class Stream class of which to set the event
	353	header field type.
	354	@param[in] event_header_type Event header field type.
	355	@returns 0 on success, or a negative value on error.
	356
	357	@prenotnull{stream_class}
	358	@prenotnull{event_header_type}
	359	@prehot{stream_class}
	360	@preisstructft{event_header_type}
	361	@postrefcountsame{stream_class}
	362	@postsuccessrefcountinc{event_header_type}
	363
	364	@sa bt_ctf_stream_class_get_event_header_type(): Returns the event
	365	header field type of a given stream class.
	366	*/
662e778c JG	367	extern int bt_ctf_stream_class_set_event_header_type(
	368	struct bt_ctf_stream_class *stream_class,
	369	struct bt_ctf_field_type *event_header_type);
	370
594a3fb7 PP	371	/**
	372	@brief Returns the per-stream class event context field type of the
	373	CTF IR stream class \p stream_class.
	374
	375	@param[in] stream_class Stream class of which to get the per-stream
	376	class event context field type.
	377	@returns Per-stream class event context field type of
	378	\p stream_class, or \c NULL on error.
	379
	380	@prenotnull{stream_class}
	381	@postsuccessrefcountretinc
	382
	383	@sa bt_ctf_stream_class_set_event_context_type(): Sets the per-stream
	384	class event context field type of a given stream class.
	385	*/
af181248 JG	386	extern struct bt_ctf_field_type *
	387	bt_ctf_stream_class_get_event_context_type(
	388	struct bt_ctf_stream_class *stream_class);
	389
594a3fb7 PP	390	/**
	391	@brief Sets the per-stream class event context field type of the CTF
	392	IR stream class \p stream_class to \p event_context_type.
	393
	394	As of Babeltrace \btversion, \p event_context_type \em must be a
	395	CTF IR structure field type object.
	396
	397	@param[in] stream_class Stream class of which to set the
	398	per-stream class event context
	399	field type.
	400	@param[in] event_context_type Per-stream class event context context
	401	field type.
	402	@returns 0 on success, or a negative value on error.
	403
	404	@prenotnull{stream_class}
	405	@prenotnull{event_context_type}
	406	@prehot{stream_class}
	407	@preisstructft{event_context_type}
	408	@postrefcountsame{stream_class}
	409	@postsuccessrefcountinc{event_context_type}
	410
	411	@sa bt_ctf_stream_class_get_event_context_type(): Returns the per-stream
	412	class event context field type of a given stream class.
	413	*/
af181248 JG	414	extern int bt_ctf_stream_class_set_event_context_type(
	415	struct bt_ctf_stream_class *stream_class,
	416	struct bt_ctf_field_type *event_context_type);
	417
594a3fb7 PP	418	/** @} */
	419
	420	/**
	421	@name Event class children functions
	422	@{
	423	*/
	424
	425	/**
	426	@brief Returns the number of event classes contained in the
	427	CTF IR stream class \p stream_class.
	428
	429	@param[in] stream_class Stream class of which to get the number
	430	of children event classes.
	431	@returns Number of children event classes
	432	contained in \p stream_class, or
	433	a negative value on error.
	434
	435	@prenotnull{stream_class}
	436	@postrefcountsame{stream_class}
	437	*/
	438	extern int bt_ctf_stream_class_get_event_class_count(
	439	struct bt_ctf_stream_class *stream_class);
	440
	441	/**
	442	@brief Returns the event class at index \p index in the CTF IR stream
	443	class \p stream_class.
	444
	445	@param[in] stream_class Stream class of which to get the event class.
	446	@param[in] index Index of the event class to find.
	447	@returns Event class at index \p index, or \c NULL
	448	on error.
	449
	450	@prenotnull{stream_class}
	451	@pre \p index is lesser than the number of event classes contained in the
	452	stream class \p stream_class (see
	453	bt_ctf_stream_class_get_event_class_count()).
	454	@postrefcountsame{stream_class}
	455	@postsuccessrefcountretinc
	456
	457	@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
	458	by ID.
	459	@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
	460	by name.
	461	*/
	462	extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class(
	463	struct bt_ctf_stream_class *stream_class, int index);
	464
	465	/**
	466	@brief Returns the event class named \c name found in the CTF IR stream
	467	class \p stream_class.
	468
	469	@param[in] stream_class Stream class of which to get the event class.
	470	@param[in] name Name of the event class to find.
	471	@returns Event class named \p name, or \c NULL
	472	on error.
	473
	474	@prenotnull{stream_class}
	475	@prenotnull{name}
	476	@postrefcountsame{stream_class}
	477	@postsuccessrefcountretinc
	478
	479	@sa bt_ctf_stream_class_get_event_class_by_id(): Finds an event class
	480	by ID.
	481	*/
482	extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_name(
483	struct bt_ctf_stream_class stream_class, const char name);
484
485	/**
486	@brief Returns the event class with ID \c id found in the CTF IR stream
487	class \p stream_class.
488
489	@param[in] stream_class Stream class of which to get the event class.
490	@param[in] id ID of the event class to find.
491	@returns Event class with ID \p id, or \c NULL
492	on error.
493
494	@prenotnull{stream_class}
495	@postrefcountsame{stream_class}
496	@postsuccessrefcountretinc
497
498	@sa bt_ctf_stream_class_get_event_class_by_name(): Finds an event class
499	by name.
500	*/
501	extern struct bt_ctf_event_class *bt_ctf_stream_class_get_event_class_by_id(
502	struct bt_ctf_stream_class *stream_class, uint32_t id);
503
504	/**
505	@brief Adds the CTF IR event class \p event_class to the
506	CTF IR stream class \p stream_class.
507
508	On success, \p event_class becomes the child of \p stream_class.
509
510	You can only add a given event class to one stream class.
511
512	You can call this function even if \p stream_class is frozen. Adding
513	event classes is the only operation that is permitted
514	on a frozen stream class.
515
516	@param[in] stream_class Stream class to which to add \p event_class.
517	@param[in] event_class Event class to add to \p stream_class.
518	@returns 0 on success, or a negative value on error.
519
520	@prenotnull{stream_class}
521	@prenotnull{event_class}
522	@prehot{event_class}
523	@postrefcountsame{stream_class}
524	@postsuccessrefcountinc{event_class}
525	*/
526	extern int bt_ctf_stream_class_add_event_class(
527	struct bt_ctf_stream_class *stream_class,
528	struct bt_ctf_event_class *event_class);
529
530	/** @} */
531
532	/**
533	@name Misc. function
534	@{
535	*/
536
537	/**
538	@brief Accepts the visitor \p visitor to visit the hierarchy of the
539	CTF IR stream class \p stream_class.
540
541	This function traverses the hierarchy of \p stream_class in pre-order
542	and calls \p visitor on each element.
543
544	The stream class itself is visited first, and then all its children
545	event classes.
546
547	@param[in] stream_class Stream class to visit.
548	@param[in] visitor Visiting function.
549	@param[in] data User data.
550	@returns 0 on success, or a negative value on error.
551
552	@prenotnull{stream_class}
553	@prenotnull{visitor}
554	*/
8bf65fbd	555	extern int bt_ctf_stream_class_visit(struct bt_ctf_stream_class *stream_class,
d9a13d86	556	bt_ctf_visitor visitor, void *data);
8bf65fbd	557
594a3fb7 PP	558	/** @} */
	559
	560	/** @} */
	561
	562	// TODO: document for writer
	563	extern struct bt_ctf_clock *bt_ctf_stream_class_get_clock(
	564	struct bt_ctf_stream_class *stream_class);
	565
adc315b8 JG	566	#ifdef __cplusplus
	567	}
	568	#endif
	569
	570	#endif /* BABELTRACE_CTF_IR_STREAM_CLASS_H */