[babeltrace.git] / include / babeltrace / ctf / events.h

#ifndef _BABELTRACE_CTF_EVENTS_H
#define _BABELTRACE_CTF_EVENTS_H

/*
 * BabelTrace
 *
 * CTF events API
 *
 * Copyright 2011-2012 EfficiOS Inc. and Linux Foundation
 *
 * Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 *         Julien Desfossez <julien.desfossez@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.
 */

#include <stdint.h>

struct ctf_stream;
struct ctf_stream_event;
struct definition;

/*
 * the top-level scopes in CTF
 */
enum bt_ctf_scope {
	BT_TRACE_PACKET_HEADER          = 0,
	BT_STREAM_PACKET_CONTEXT        = 1,
	BT_STREAM_EVENT_HEADER          = 2,
	BT_STREAM_EVENT_CONTEXT         = 3,
	BT_EVENT_CONTEXT                = 4,
	BT_EVENT_FIELDS                 = 5,
};

/*
 * the supported CTF types
 */
enum ctf_type_id {
	CTF_TYPE_UNKNOWN = 0,
	CTF_TYPE_INTEGER,
	CTF_TYPE_FLOAT,
	CTF_TYPE_ENUM,
	CTF_TYPE_STRING,
	CTF_TYPE_STRUCT,
	CTF_TYPE_UNTAGGED_VARIANT,
	CTF_TYPE_VARIANT,
	CTF_TYPE_ARRAY,
	CTF_TYPE_SEQUENCE,
	NR_CTF_TYPES,
};

/*
 * the structure to manipulate events
 */
struct bt_ctf_event {
	struct ctf_stream *stream;
	struct ctf_stream_event *event;
};

/*
 * bt_ctf_get_top_level_scope: return a definition of the top-level scope
 *
 * Top-level scopes are defined in the bt_ctf_scope enum.
 * In order to get a field or a field list, the user needs to pass a
 * scope as argument, this scope can be a top-level scope or a scope
 * relative to an arbitrary field. This function provides the mapping
 * between the enum and the actual definition of top-level scopes.
 * On error return NULL.
 */
struct definition *bt_ctf_get_top_level_scope(struct bt_ctf_event *event,
		enum bt_ctf_scope scope);

/*
 * bt_ctf_event_get_name: returns the name of the event or NULL on error
 */
const char *bt_ctf_event_name(struct bt_ctf_event *event);

/*
 * bt_ctf_get_timestamp: returns the timestamp of the event or -1ULL on error
 */
uint64_t bt_ctf_get_timestamp(struct bt_ctf_event *event);

/*
 * bt_ctf_get_field_list: set list pointer to an array of definition
 * pointers and set count to the number of elements in the array.
 * Return 0 on success and a negative value on error.
 */
int bt_ctf_get_field_list(struct bt_ctf_event *event,
		struct definition *scope,
		struct definition const * const **list,
		unsigned int *count);

/*
 * bt_ctf_get_field: returns the definition of a specific field
 */
struct definition *bt_ctf_get_field(struct bt_ctf_event *event,
		struct definition *scope,
		const char *field);

/*
 * bt_ctf_get_index: if the field is an array or a sequence, return the element
 * at position index, otherwise return NULL;
 */
struct definition *bt_ctf_get_index(struct bt_ctf_event *event,
		struct definition *field,
		unsigned int index);

/*
 * bt_ctf_field_name: returns the name of a field or NULL on error
 */
const char *bt_ctf_field_name(const struct definition *def);

/*
 * bt_ctf_field_type: returns the type of a field or -1 if unknown
 */
enum ctf_type_id bt_ctf_field_type(struct definition *def);

/*
 * Field access functions
 *
 * These functions return the value associated with the field passed in
 * parameter.
 *
 * If the field does not exist or is not of the type requested, the value
 * returned is undefined. To check if an error occured, use the
 * bt_ctf_field_error() function after accessing a field.
 */
uint64_t bt_ctf_get_uint64(struct definition *field);
int64_t bt_ctf_get_int64(struct definition *field);
char *bt_ctf_get_char_array(struct definition *field);
char *bt_ctf_get_string(struct definition *field);

/*
 * bt_ctf_field_error: returns the last error code encountered while
 * accessing a field and reset the error flag.
 * Return 0 if no error, a negative value otherwise.
 */
int bt_ctf_field_get_error(void);

#endif /* _BABELTRACE_CTF_EVENTS_H */
Commit	Line	Data
9843982d JD	1	#ifndef _BABELTRACE_CTF_EVENTS_H
	2	#define _BABELTRACE_CTF_EVENTS_H
	3
	4	/*
	5	* BabelTrace
	6	*
	7	* CTF events API
	8	*
	9	* Copyright 2011-2012 EfficiOS Inc. and Linux Foundation
	10	*
	11	* Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	12	* Julien Desfossez <julien.desfossez@efficios.com>
	13	*
	14	* Permission is hereby granted, free of charge, to any person obtaining
	15	* a copy of this software and associated documentation files (the
	16	* "Software"), to deal in the Software without restriction, including
	17	* without limitation the rights to use, copy, modify, merge, publish,
	18	* distribute, sublicense, and/or sell copies of the Software, and to
	19	* permit persons to whom the Software is furnished to do so, subject to
	20	* the following conditions:
	21	*
	22	* The above copyright notice and this permission notice shall be
	23	* included in all copies or substantial portions of the Software.
	24	*/
	25
	26	#include <stdint.h>
	27
	28	struct ctf_stream;
	29	struct ctf_stream_event;
	30	struct definition;
	31
	32	/*
	33	* the top-level scopes in CTF
	34	*/
	35	enum bt_ctf_scope {
	36	BT_TRACE_PACKET_HEADER = 0,
	37	BT_STREAM_PACKET_CONTEXT = 1,
	38	BT_STREAM_EVENT_HEADER = 2,
	39	BT_STREAM_EVENT_CONTEXT = 3,
	40	BT_EVENT_CONTEXT = 4,
	41	BT_EVENT_FIELDS = 5,
	42	};
	43
	44	/*
	45	* the supported CTF types
	46	*/
	47	enum ctf_type_id {
	48	CTF_TYPE_UNKNOWN = 0,
	49	CTF_TYPE_INTEGER,
	50	CTF_TYPE_FLOAT,
	51	CTF_TYPE_ENUM,
	52	CTF_TYPE_STRING,
	53	CTF_TYPE_STRUCT,
	54	CTF_TYPE_UNTAGGED_VARIANT,
	55	CTF_TYPE_VARIANT,
	56	CTF_TYPE_ARRAY,
	57	CTF_TYPE_SEQUENCE,
	58	NR_CTF_TYPES,
	59	};
	60
	61	/*
	62	* the structure to manipulate events
	63	*/
	64	struct bt_ctf_event {
65	struct ctf_stream *stream;
66	struct ctf_stream_event *event;
67	};
68
69	/*
70	* bt_ctf_get_top_level_scope: return a definition of the top-level scope
71	*
72	* Top-level scopes are defined in the bt_ctf_scope enum.
73	* In order to get a field or a field list, the user needs to pass a
74	* scope as argument, this scope can be a top-level scope or a scope
75	* relative to an arbitrary field. This function provides the mapping
76	* between the enum and the actual definition of top-level scopes.
77	* On error return NULL.
78	*/
79	struct definition bt_ctf_get_top_level_scope(struct bt_ctf_event event,
80	enum bt_ctf_scope scope);
81
82	/*
83	* bt_ctf_event_get_name: returns the name of the event or NULL on error
84	*/
85	const char bt_ctf_event_name(struct bt_ctf_event event);
86
87	/*
88	* bt_ctf_get_timestamp: returns the timestamp of the event or -1ULL on error
89	*/
90	uint64_t bt_ctf_get_timestamp(struct bt_ctf_event *event);
91
92	/*
aacd0c69 JD	93	* bt_ctf_get_field_list: set list pointer to an array of definition
	94	* pointers and set count to the number of elements in the array.
	95	* Return 0 on success and a negative value on error.
9843982d JD	96	*/
	97	int bt_ctf_get_field_list(struct bt_ctf_event *event,
	98	struct definition *scope,
	99	struct definition const * const **list,
	100	unsigned int *count);
	101
	102	/*
	103	* bt_ctf_get_field: returns the definition of a specific field
	104	*/
	105	struct definition bt_ctf_get_field(struct bt_ctf_event event,
	106	struct definition *scope,
	107	const char *field);
	108
	109	/*
	110	* bt_ctf_get_index: if the field is an array or a sequence, return the element
	111	* at position index, otherwise return NULL;
	112	*/
	113	struct definition bt_ctf_get_index(struct bt_ctf_event event,
	114	struct definition *field,
	115	unsigned int index);
	116
	117	/*
	118	* bt_ctf_field_name: returns the name of a field or NULL on error
	119	*/
	120	const char bt_ctf_field_name(const struct definition def);
	121
	122	/*
	123	* bt_ctf_field_type: returns the type of a field or -1 if unknown
	124	*/
	125	enum ctf_type_id bt_ctf_field_type(struct definition *def);
	126
	127	/*
	128	* Field access functions
	129	*
	130	* These functions return the value associated with the field passed in
	131	* parameter.
	132	*
	133	* If the field does not exist or is not of the type requested, the value
	134	* returned is undefined. To check if an error occured, use the
	135	* bt_ctf_field_error() function after accessing a field.
	136	*/
	137	uint64_t bt_ctf_get_uint64(struct definition *field);
	138	int64_t bt_ctf_get_int64(struct definition *field);
	139	char bt_ctf_get_char_array(struct definition field);
	140	char bt_ctf_get_string(struct definition field);
	141
	142	/*
	143	* bt_ctf_field_error: returns the last error code encountered while
	144	* accessing a field and reset the error flag.
	145	* Return 0 if no error, a negative value otherwise.
	146	*/
	147	int bt_ctf_field_get_error(void);
	148
	149	#endif /* _BABELTRACE_CTF_EVENTS_H */