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

#ifndef BABELTRACE_CTF_IR_TRACE_H
#define BABELTRACE_CTF_IR_TRACE_H

/*
 * BabelTrace - CTF IR: Trace
 *
 * 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 <babeltrace/ctf-ir/event-types.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_ctf_trace;
struct bt_ctf_stream;
struct bt_ctf_stream_class;
struct bt_ctf_clock;

/*
 * bt_ctf_trace_create: create a trace instance.
 *
 * Allocate a new trace
 *
 * Returns a new trace on success, NULL on error.
 */
extern struct bt_ctf_trace *bt_ctf_trace_create(void);

/*
 * bt_ctf_trace_create_stream: create a stream instance.
 *
 * Allocate a new stream instance and register it to the trace. The creation of
 * a stream sets its reference count to 1.
 *
 * @param trace Trace instance.
 * @param stream_class Stream class to instantiate.
 *
 * Returns a new stream on success, NULL on error.
 */
extern struct bt_ctf_stream *bt_ctf_trace_create_stream(
		struct bt_ctf_trace *trace,
		struct bt_ctf_stream_class *stream_class);

/*
 * bt_ctf_trace_add_environment_field: add an environment field to the trace.
 *
 * Add an environment field to the trace. The name and value parameters are
 * copied.
 *
 * @param trace Trace instance.
 * @param name Name of the environment field (will be copied).
 * @param value Value of the environment field (will be copied).
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace,
		const char *name,
		const char *value);

/*
 * bt_ctf_trace_add_clock: add a clock to the trace.
 *
 * Add a clock to the trace. Clocks assigned to stream classes must be
 * added to the trace beforehand.
 *
 * @param trace Trace instance.
 * @param clock Clock to add to the trace.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace,
		struct bt_ctf_clock *clock);

/*
 * bt_ctf_trace_get_clock_count: get the number of clocks
 *	associated to the trace.
 *
 * @param trace Trace instance.
 *
 * Returns the clock count on success, a negative value on error.
 */
extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace);

/*
 * bt_ctf_trace_get_clock: get a trace's clock at index.
 *
 * @param trace Trace instance.
 * @param index Index of the clock in the given trace.
 *
 * Return a clock instance on success, NULL on error.
 */
extern struct bt_ctf_clock *bt_ctf_trace_get_clock(
		struct bt_ctf_trace *trace, int index);

/*
 * bt_ctf_trace_get_metadata_string: get metadata string.
 *
 * Get the trace's TSDL metadata. The caller assumes the ownership of the
 * returned string.
 *
 * @param trace Trace instance.
 *
 * Returns the metadata string on success, NULL on error.
 */
extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);

/*
 * bt_ctf_trace_set_byte_order: set a field type's byte order.
 *
 * Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE,
 * the host machine's endianness.
 *
 * @param trace Trace instance.
 * @param byte_order Trace's byte order.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace,
		enum bt_ctf_byte_order byte_order);

/*
 * bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the
 * trace's reference count.
 *
 * These functions ensure that the trace won't be destroyed while it
 * is in use. The same number of get and put (plus one extra put to
 * release the initial reference done at creation) have to be done to
 * destroy a trace.
 *
 * When the trace's reference count is decremented to 0 by a
 * bt_ctf_trace_put, the trace is freed.
 *
 * @param trace Trace instance.
 */
extern void bt_ctf_trace_get(struct bt_ctf_trace *trace);
extern void bt_ctf_trace_put(struct bt_ctf_trace *trace);

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_TRACE_H */
Commit	Line	Data
bc37ae52 JG	1	#ifndef BABELTRACE_CTF_IR_TRACE_H
	2	#define BABELTRACE_CTF_IR_TRACE_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Trace
	6	*
	7	* Copyright 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/event-types.h>
	34
	35	#ifdef __cplusplus
	36	extern "C" {
	37	#endif
	38
	39	struct bt_ctf_trace;
	40	struct bt_ctf_stream;
	41	struct bt_ctf_stream_class;
	42	struct bt_ctf_clock;
	43
	44	/*
	45	* bt_ctf_trace_create: create a trace instance.
	46	*
	47	* Allocate a new trace
	48	*
	49	* Returns a new trace on success, NULL on error.
	50	*/
	51	extern struct bt_ctf_trace *bt_ctf_trace_create(void);
	52
	53	/*
	54	* bt_ctf_trace_create_stream: create a stream instance.
	55	*
	56	* Allocate a new stream instance and register it to the trace. The creation of
	57	* a stream sets its reference count to 1.
	58	*
	59	* @param trace Trace instance.
	60	* @param stream_class Stream class to instantiate.
	61	*
	62	* Returns a new stream on success, NULL on error.
	63	*/
	64	extern struct bt_ctf_stream *bt_ctf_trace_create_stream(
65	struct bt_ctf_trace *trace,
66	struct bt_ctf_stream_class *stream_class);
67
68	/*
69	* bt_ctf_trace_add_environment_field: add an environment field to the trace.
70	*
71	* Add an environment field to the trace. The name and value parameters are
72	* copied.
73	*
74	* @param trace Trace instance.
75	* @param name Name of the environment field (will be copied).
76	* @param value Value of the environment field (will be copied).
77	*
78	* Returns 0 on success, a negative value on error.
79	*/
80	extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace,
81	const char *name,
82	const char *value);
83
84	/*
85	* bt_ctf_trace_add_clock: add a clock to the trace.
86	*
87	* Add a clock to the trace. Clocks assigned to stream classes must be
88	* added to the trace beforehand.
89	*
90	* @param trace Trace instance.
91	* @param clock Clock to add to the trace.
92	*
93	* Returns 0 on success, a negative value on error.
94	*/
95	extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace,
96	struct bt_ctf_clock *clock);
97
884cd6c3 JG	98	/*
	99	* bt_ctf_trace_get_clock_count: get the number of clocks
	100	* associated to the trace.
	101	*
	102	* @param trace Trace instance.
	103	*
	104	* Returns the clock count on success, a negative value on error.
	105	*/
	106	extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace);
	107
	108	/*
	109	* bt_ctf_trace_get_clock: get a trace's clock at index.
	110	*
	111	* @param trace Trace instance.
	112	* @param index Index of the clock in the given trace.
	113	*
	114	* Return a clock instance on success, NULL on error.
	115	*/
	116	extern struct bt_ctf_clock *bt_ctf_trace_get_clock(
	117	struct bt_ctf_trace *trace, int index);
	118
bc37ae52 JG	119	/*
	120	* bt_ctf_trace_get_metadata_string: get metadata string.
	121	*
	122	* Get the trace's TSDL metadata. The caller assumes the ownership of the
	123	* returned string.
	124	*
	125	* @param trace Trace instance.
	126	*
	127	* Returns the metadata string on success, NULL on error.
	128	*/
	129	extern char bt_ctf_trace_get_metadata_string(struct bt_ctf_trace trace);
	130
	131	/*
	132	* bt_ctf_trace_set_byte_order: set a field type's byte order.
	133	*
	134	* Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE,
	135	* the host machine's endianness.
	136	*
	137	* @param trace Trace instance.
	138	* @param byte_order Trace's byte order.
	139	*
	140	* Returns 0 on success, a negative value on error.
	141	*/
	142	extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace,
	143	enum bt_ctf_byte_order byte_order);
	144
	145	/*
	146	* bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the
	147	* trace's reference count.
	148	*
	149	* These functions ensure that the trace won't be destroyed while it
	150	* is in use. The same number of get and put (plus one extra put to
	151	* release the initial reference done at creation) have to be done to
	152	* destroy a trace.
	153	*
	154	* When the trace's reference count is decremented to 0 by a
	155	* bt_ctf_trace_put, the trace is freed.
	156	*
	157	* @param trace Trace instance.
	158	*/
	159	extern void bt_ctf_trace_get(struct bt_ctf_trace *trace);
	160	extern void bt_ctf_trace_put(struct bt_ctf_trace *trace);
	161
	162	#ifdef __cplusplus
	163	}
	164	#endif
	165
	166	#endif /* BABELTRACE_CTF_IR_TRACE_H */