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

#ifndef BABELTRACE_CTF_IR_STREAM_H
#define BABELTRACE_CTF_IR_STREAM_H

/*
 * BabelTrace - CTF IR: Stream
 *
 * 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 <babeltrace/ctf-ir/stream-class.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup ctfirstream CTF IR stream
@ingroup ctfir
@brief CTF IR stream.

@note
See \ref ctfirwriterstream which documents additional CTF IR stream
functions exclusive to the CTF IR writer mode.

A CTF IR <strong><em>stream</em></strong> is an instance of a
\link ctfirstreamclass CTF IR stream class\endlink.

You can obtain a CTF IR stream object in two different modes:

- <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream
  class having a \link ctfirtraceclass CTF IR trace class\endlink parent
  \em not created by a \link ctfirwriter CTF IR writer\endlink object to
  create a default stream.
- <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with
  a stream class having a trace class parent created by a CTF IR writer
  object, or use bt_ctf_writer_create_stream().

A CTF IR stream object represents a CTF stream, that is, a sequence of
packets containing events:

@imgtracestructure

A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
IR packet\endlink objects: it only acts as a common parent to identify
the original CTF stream of packet objects.

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

@sa ctfirstreamclass
@sa ctfirpacket
@sa ctfirwriterstream

@file
@brief CTF IR stream type and functions.
@sa ctfirstream

@addtogroup ctfirstream
@{
*/

/**
@struct bt_ctf_stream
@brief A CTF IR stream.
@sa ctfirstream
@sa ctfirwriterstream
*/
struct bt_ctf_stream;
struct bt_ctf_event;

/**
@brief  Creates a default CTF IR stream named \p name from the CTF IR
	stream class \p stream_class.

\p stream_class \em must have a parent
\link ctfirtraceclass CTF IR trace class\endlink.

If the parent \link ctfirtraceclass trace class\endlink of
\p stream_class was created by a \link ctfirwriter CTF IR writer\endlink
object, then the stream object is created in CTF IR writer mode, and
you can use the functions of \ref ctfirwriterstream on it.
Otherwise it is created in normal mode: you should only use the
functions documented in this module on it.

\p name can be \c NULL to create an unnamed stream object.

@param[in] stream_class	CTF IR stream class to use to create the
			CTF IR stream.
@param[in] name		Name of the stream object to create (copied on
			success) or \c NULL to create an unnamed stream.
@returns		Created stream object, or \c NULL on error.

@prenotnull{stream_class}
@pre \p stream_class has a parent trace class.
@postsuccessrefcountret1
*/
extern struct bt_ctf_stream *bt_ctf_stream_create(
		struct bt_ctf_stream_class *stream_class,
		const char *name);

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

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

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

@prenotnull{stream}
@postrefcountsame{stream}
*/
extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);

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

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

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

@prenotnull{stream}
@postsuccessrefcountretinc
*/
extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
		struct bt_ctf_stream *stream);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_STREAM_H */
Commit	Line	Data
3f043b05 JG	1	#ifndef BABELTRACE_CTF_IR_STREAM_H
	2	#define BABELTRACE_CTF_IR_STREAM_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Stream
	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 <babeltrace/ctf-ir/stream-class.h>
ffc6a64e	34	#include <stdint.h>
3f043b05 JG	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
54f61f03 PP	40	/**
	41	@defgroup ctfirstream CTF IR stream
	42	@ingroup ctfir
	43	@brief CTF IR stream.
	44
	45	@note
	46	See \ref ctfirwriterstream which documents additional CTF IR stream
	47	functions exclusive to the CTF IR writer mode.
	48
	49	A CTF IR <strong><em>stream</em></strong> is an instance of a
	50	\link ctfirstreamclass CTF IR stream class\endlink.
	51
	52	You can obtain a CTF IR stream object in two different modes:
	53
	54	- <strong>Normal mode</strong>: use bt_ctf_stream_create() with a stream
	55	class having a \link ctfirtraceclass CTF IR trace class\endlink parent
	56	\em not created by a \link ctfirwriter CTF IR writer\endlink object to
	57	create a default stream.
	58	- <strong>CTF IR writer mode</strong>: use bt_ctf_stream_create() with
	59	a stream class having a trace class parent created by a CTF IR writer
	60	object, or use bt_ctf_writer_create_stream().
	61
	62	A CTF IR stream object represents a CTF stream, that is, a sequence of
	63	packets containing events:
	64
	65	@imgtracestructure
	66
	67	A CTF IR stream does not contain, however, actual \link ctfirpacket CTF
	68	IR packet\endlink objects: it only acts as a common parent to identify
	69	the original CTF stream of packet objects.
	70
	71	As with any Babeltrace object, CTF IR stream 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	@sa ctfirstreamclass
	77	@sa ctfirpacket
	78	@sa ctfirwriterstream
	79
	80	@file
	81	@brief CTF IR stream type and functions.
	82	@sa ctfirstream
	83
	84	@addtogroup ctfirstream
	85	@{
	86	*/
	87
d0218df1 PP	88	/**
	89	@struct bt_ctf_stream
	90	@brief A CTF IR stream.
	91	@sa ctfirstream
	92	@sa ctfirwriterstream
	93	*/
3f043b05	94	struct bt_ctf_stream;
54f61f03 PP	95	struct bt_ctf_event;
	96
	97	/**
	98	@brief Creates a default CTF IR stream named \p name from the CTF IR
	99	stream class \p stream_class.
3f043b05	100
54f61f03 PP	101	\p stream_class \em must have a parent
	102	\link ctfirtraceclass CTF IR trace class\endlink.
	103
	104	If the parent \link ctfirtraceclass trace class\endlink of
	105	\p stream_class was created by a \link ctfirwriter CTF IR writer\endlink
	106	object, then the stream object is created in CTF IR writer mode, and
	107	you can use the functions of \ref ctfirwriterstream on it.
	108	Otherwise it is created in normal mode: you should only use the
	109	functions documented in this module on it.
	110
	111	\p name can be \c NULL to create an unnamed stream object.
	112
	113	@param[in] stream_class CTF IR stream class to use to create the
	114	CTF IR stream.
	115	@param[in] name Name of the stream object to create (copied on
	116	success) or \c NULL to create an unnamed stream.
	117	@returns Created stream object, or \c NULL on error.
	118
	119	@prenotnull{stream_class}
	120	@pre \p stream_class has a parent trace class.
	121	@postsuccessrefcountret1
	122	*/
319fd969	123	extern struct bt_ctf_stream *bt_ctf_stream_create(
b71d7298 PP	124	struct bt_ctf_stream_class *stream_class,
	125	const char *name);
	126
54f61f03 PP	127	/**
	128	@brief Returns the name of the CTF IR stream \p stream.
	129
	130	On success, \p stream remains the sole owner of the returned string.
	131
	132	@param[in] stream Stream object of which to get the name.
	133	@returns Name of stream \p stream, or \c NULL if
	134	\p stream is unnamed or on error.
	135
	136	@prenotnull{stream}
	137	@postrefcountsame{stream}
	138	*/
b71d7298	139	extern const char bt_ctf_stream_get_name(struct bt_ctf_stream stream);
319fd969	140
54f61f03 PP	141	/**
	142	@brief Returns the parent CTF IR stream class of the CTF IR
	143	stream \p stream.
	144
	145	This function returns a reference to the stream class which was used
	146	to create the stream object in the first place with
	147	bt_ctf_stream_create().
	148
	149	@param[in] stream Stream of which to get the parent stream class.
	150	@returns Parent stream class of \p stream,
	151	or \c NULL on error.
	152
	153	@prenotnull{stream}
	154	@postsuccessrefcountretinc
	155	*/
3baf0856 JG	156	extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
	157	struct bt_ctf_stream *stream);
	158
54f61f03 PP	159	/** @} */
54f61f03 PP	160
3f043b05 JG	161	#ifdef __cplusplus
	162	}
	163	#endif
	164
	165	#endif /* BABELTRACE_CTF_IR_STREAM_H */