[babeltrace.git] / include / babeltrace / plugin / plugin-system.h

#ifndef BABELTRACE_PLUGIN_SYSTEM_H
#define BABELTRACE_PLUGIN_SYSTEM_H

/*
 * BabelTrace - Babeltrace Plug-in System Interface
 *
 * This interface is provided for plug-ins to use the Babeltrace
 * plug-in system facilities.
 *
 * Copyright 2015 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.
 */

#include <babeltrace/plugin/notification/notification.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_notification;
struct bt_notification_iterator;
struct bt_component;
struct bt_component_factory;
struct bt_value;

typedef enum bt_component_status (*bt_plugin_init_func)(
		struct bt_component_factory *factory);
typedef void (*bt_plugin_exit_func)(void);

/**
 * Component private data deallocation function type.
 *
 * @param component	Component instance
 */
typedef void (*bt_component_destroy_cb)(struct bt_component *component);

/**
 * Component initialization function type.
 *
 * A component's private data and required callbacks must be set by this
 * function.
 *
 * @param component	Component instance
 * @param params	A dictionary of component parameters
 * @returns		One of #bt_component_status values
 */
typedef enum bt_component_status (*bt_component_init_cb)(
		struct bt_component *component, struct bt_value *params);

/**
 * Get a component's private data.
 *
 * @param component	Component of which to get the private data
 * @returns		Component's private data
 */
extern void *bt_component_get_private_data(struct bt_component *component);

/**
 * Set a component's private data.
 *
 * @param component	Component of which to set the private data
 * @param data		Component private data
 * @returns		One of #bt_component_status values
 */
extern enum bt_component_status bt_component_set_private_data(
		struct bt_component *component, void *data);

/**
 * Set a component's private data cleanup function.
 *
 * @param component	Component of which to set the private data destruction
 *			function
 * @param data		Component private data clean-up function
 * @returns		One of #bt_component_status values
 */
extern enum bt_component_status bt_component_set_destroy_cb(
		struct bt_component *component,
		bt_component_destroy_cb destroy);

/** bt_component_souce */
/**
 * Iterator initialization function type.
 *
 * A notification iterator's private data, deinitialization, next, and get
 * callbacks must be set by this function.
 *
 * @param source	Source component instance
 * @param iterator	Notification iterator instance
 */
typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
		struct bt_component *, struct bt_notification_iterator *);

/**
 * Set a source component's iterator initialization function.
 *
 * @param source	Source component instance
 * @param init_iterator	Notification iterator initialization callback
 */
extern enum bt_component_status
bt_component_source_set_iterator_init_cb(struct bt_component *source,
		bt_component_source_init_iterator_cb init_iterator);

/** bt_component_sink */
/**
 * Notification consumption function type.
 *
 * @param sink		Sink component instance
 * @returns		One of #bt_component_status values
 */
typedef enum bt_component_status (*bt_component_sink_consume_cb)(
		struct bt_component *);

/**
 * Iterator addition function type.
 *
 * A sink component may choose to refuse the addition of an iterator
 * by not returning BT_COMPONENT_STATUS_OK.
 *
 * @param sink		Sink component instance
 * @returns		One of #bt_component_status values
 */
typedef enum bt_component_status (*bt_component_sink_add_iterator_cb)(
		struct bt_component *, struct bt_notification_iterator *);

/**
 * Set a sink component's consumption callback.
 *
 * @param sink		Sink component instance
 * @param consume	Consumption callback
 * @returns		One of #bt_component_status values
 */
extern enum bt_component_status
bt_component_sink_set_consume_cb(struct bt_component *sink,
		bt_component_sink_consume_cb consume);

/**
 * Set a sink component's iterator addition callback.
 *
 * @param sink		Sink component instance
 * @param add_iterator	Iterator addition callback
 * @returns		One of #bt_component_status values
 */
extern enum bt_component_status
bt_component_sink_set_add_iterator_cb(struct bt_component *sink,
		bt_component_sink_add_iterator_cb add_iterator);

/* Defaults to 1. */
extern enum bt_component_status
bt_component_sink_set_minimum_input_count(struct bt_component *sink,
		unsigned int minimum);

/* Defaults to 1. */
extern enum bt_component_status
bt_component_sink_set_maximum_input_count(struct bt_component *sink,
		unsigned int maximum);

extern enum bt_component_status
bt_component_sink_get_input_count(struct bt_component *sink,
		unsigned int *count);

/* May return NULL after an interator has reached its end. */
extern enum bt_component_status
bt_component_sink_get_input_iterator(struct bt_component *sink,
		unsigned int input, struct bt_notification_iterator **iterator);

/** bt_component_filter */
/**
 * Iterator initialization function type.
 *
 * A notification iterator's private data, deinitialization, next, and get
 * callbacks must be set by this function.
 *
 * @param filter	Filter component instance
 * @param iterator	Notification iterator instance
 */
typedef enum bt_component_status (*bt_component_filter_init_iterator_cb)(
		struct bt_component *, struct bt_notification_iterator *);

/**
 * Iterator addition function type.
 *
 * A filter component may choose to refuse the addition of an iterator
 * by not returning BT_COMPONENT_STATUS_OK.
 *
 * @param filter	Filter component instance
 * @returns		One of #bt_component_status values
 */
typedef enum bt_component_status (*bt_component_filter_add_iterator_cb)(
		struct bt_component *, struct bt_notification_iterator *);

/**
 * Set a filter component's iterator initialization function.
 *
 * @param filter	Filter component instance
 * @param init_iterator	Notification iterator initialization callback
 */
extern enum bt_component_status
bt_component_filter_set_iterator_init_cb(struct bt_component *filter,
		bt_component_filter_init_iterator_cb init_iterator);

/**
 * Set a filter component's iterator addition callback.
 *
 * @param filter	Filter component instance
 * @param add_iterator	Iterator addition callback
 * @returns		One of #bt_component_status values
 */
extern enum bt_component_status
bt_component_filter_set_add_iterator_cb(struct bt_component *filter,
		bt_component_filter_add_iterator_cb add_iterator);

/* Defaults to 1. */
extern enum bt_component_status
bt_component_filter_set_minimum_input_count(struct bt_component *filter,
		unsigned int minimum);

/* Defaults to 1. */
extern enum bt_component_status
bt_component_filter_set_maximum_input_count(struct bt_component *filter,
		unsigned int maximum);

extern enum bt_component_status
bt_component_filter_get_input_count(struct bt_component *filter,
		unsigned int *count);

/* May return NULL after an interator has reached its end. */
extern enum bt_component_status
bt_component_filter_get_input_iterator(struct bt_component *filter,
		unsigned int input, struct bt_notification_iterator **iterator);

/** bt_notification_iterator */
/**
 * Function returning an iterator's current notification.
 *
 * @param iterator	Notification iterator instance
 * @returns 		A notification instance
 */
typedef struct bt_notification *(*bt_notification_iterator_get_cb)(
		struct bt_notification_iterator *iterator);

/**
 * Function advancing an iterator's position of one element.
 *
 * @param iterator	Notification iterator instance
 * @returns 		One of #bt_notification_iterator_status values
 */
typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
		struct bt_notification_iterator *iterator);

/**
 * Function cleaning-up an iterator's private data on destruction.
 *
 * @param iterator	Notification iterator instance
 */
typedef void (*bt_notification_iterator_destroy_cb)(
		struct bt_notification_iterator *iterator);

/**
 * Set an iterator's "get" callback which return the current notification.
 *
 * @param iterator	Notification iterator instance
 * @param get		Notification return callback
 * @returns		One of #bt_notification_iterator_status values
 */
extern enum bt_notification_iterator_status
bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
		bt_notification_iterator_get_cb get);

/**
 * Set an iterator's "next" callback which advances the iterator's position.
 *
 * @param iterator	Notification iterator instance
 * @param next		Iterator "next" callback
 * @returns		One of #bt_notification_iterator_status values
 */
extern enum bt_notification_iterator_status
bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
		bt_notification_iterator_next_cb next);

/**
 * Set an iterator's "destroy" callback.
 *
 * @param iterator	Notification iterator instance
 * @param next		Iterator destruction callback
 * @returns		One of #bt_notification_iterator_status values
 */
extern enum bt_notification_iterator_status
bt_notification_iterator_set_destroy_cb(
		struct bt_notification_iterator *iterator,
		bt_notification_iterator_destroy_cb destroy);

/**
 * Set an iterator's private data.
 *
 * @param iterator	Notification iterator instance
 * @param data		Iterator private data
 * @returns		One of #bt_notification_iterator_status values
 */
extern enum bt_notification_iterator_status
bt_notification_iterator_set_private_data(
		struct bt_notification_iterator *iterator, void *data);

/**
 * Get an iterator's private data.
 *
 * @param iterator	Notification iterator instance
 * @returns		Iterator instance private data
 */
extern void *bt_notification_iterator_get_private_data(
		struct bt_notification_iterator *iterator);

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_PLUGIN_SYSTEM_H */
Commit	Line	Data
	1	#ifndef BABELTRACE_PLUGIN_SYSTEM_H
	2	#define BABELTRACE_PLUGIN_SYSTEM_H
	3
	4	/*
	5	* BabelTrace - Babeltrace Plug-in System Interface
	6	*
	7	* This interface is provided for plug-ins to use the Babeltrace
	8	* plug-in system facilities.
	9	*
	10	* Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	11	*
	12	* Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
	13	*
	14	* Permission is hereby granted, free of charge, to any person obtaining a copy
	15	* of this software and associated documentation files (the "Software"), to deal
	16	* in the Software without restriction, including without limitation the rights
	17	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	18	* copies of the Software, and to permit persons to whom the Software is
	19	* furnished to do so, subject to the following conditions:
	20	*
	21	* The above copyright notice and this permission notice shall be included in
	22	* all copies or substantial portions of the Software.
	23	*
	24	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	25	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	26	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	27	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	28	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	29	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	30	* SOFTWARE.
	31	*/
	32
	33	#include <babeltrace/plugin/notification/notification.h>
	34	#include <stdint.h>
	35
	36	#ifdef __cplusplus
	37	extern "C" {
	38	#endif
	39
	40	struct bt_notification;
	41	struct bt_notification_iterator;
	42	struct bt_component;
	43	struct bt_component_factory;
	44	struct bt_value;
	45
	46	typedef enum bt_component_status (*bt_plugin_init_func)(
	47	struct bt_component_factory *factory);
	48	typedef void (*bt_plugin_exit_func)(void);
	49
	50	/**
	51	* Component private data deallocation function type.
	52	*
	53	* @param component Component instance
	54	*/
	55	typedef void (bt_component_destroy_cb)(struct bt_component component);
	56
	57	/**
	58	* Component initialization function type.
	59	*
	60	* A component's private data and required callbacks must be set by this
	61	* function.
	62	*
	63	* @param component Component instance
	64	* @param params A dictionary of component parameters
	65	* @returns One of #bt_component_status values
	66	*/
	67	typedef enum bt_component_status (*bt_component_init_cb)(
	68	struct bt_component component, struct bt_value params);
	69
	70	/**
	71	* Get a component's private data.
	72	*
	73	* @param component Component of which to get the private data
	74	* @returns Component's private data
	75	*/
	76	extern void bt_component_get_private_data(struct bt_component component);
	77
	78	/**
	79	* Set a component's private data.
	80	*
	81	* @param component Component of which to set the private data
	82	* @param data Component private data
	83	* @returns One of #bt_component_status values
	84	*/
	85	extern enum bt_component_status bt_component_set_private_data(
	86	struct bt_component component, void data);
	87
	88	/**
	89	* Set a component's private data cleanup function.
	90	*
	91	* @param component Component of which to set the private data destruction
	92	* function
	93	* @param data Component private data clean-up function
	94	* @returns One of #bt_component_status values
	95	*/
	96	extern enum bt_component_status bt_component_set_destroy_cb(
	97	struct bt_component *component,
	98	bt_component_destroy_cb destroy);
	99
	100	/** bt_component_souce */
	101	/**
	102	* Iterator initialization function type.
	103	*
	104	* A notification iterator's private data, deinitialization, next, and get
	105	* callbacks must be set by this function.
	106	*
	107	* @param source Source component instance
	108	* @param iterator Notification iterator instance
	109	*/
	110	typedef enum bt_component_status (*bt_component_source_init_iterator_cb)(
	111	struct bt_component , struct bt_notification_iterator );
	112
	113	/**
	114	* Set a source component's iterator initialization function.
	115	*
	116	* @param source Source component instance
	117	* @param init_iterator Notification iterator initialization callback
	118	*/
	119	extern enum bt_component_status
	120	bt_component_source_set_iterator_init_cb(struct bt_component *source,
	121	bt_component_source_init_iterator_cb init_iterator);
	122
	123	/** bt_component_sink */
	124	/**
	125	* Notification consumption function type.
	126	*
	127	* @param sink Sink component instance
	128	* @returns One of #bt_component_status values
	129	*/
	130	typedef enum bt_component_status (*bt_component_sink_consume_cb)(
	131	struct bt_component *);
	132
	133	/**
	134	* Iterator addition function type.
	135	*
	136	* A sink component may choose to refuse the addition of an iterator
	137	* by not returning BT_COMPONENT_STATUS_OK.
	138	*
	139	* @param sink Sink component instance
	140	* @returns One of #bt_component_status values
	141	*/
	142	typedef enum bt_component_status (*bt_component_sink_add_iterator_cb)(
	143	struct bt_component , struct bt_notification_iterator );
	144
	145	/**
	146	* Set a sink component's consumption callback.
	147	*
	148	* @param sink Sink component instance
	149	* @param consume Consumption callback
	150	* @returns One of #bt_component_status values
	151	*/
	152	extern enum bt_component_status
	153	bt_component_sink_set_consume_cb(struct bt_component *sink,
	154	bt_component_sink_consume_cb consume);
	155
	156	/**
	157	* Set a sink component's iterator addition callback.
	158	*
	159	* @param sink Sink component instance
	160	* @param add_iterator Iterator addition callback
	161	* @returns One of #bt_component_status values
	162	*/
	163	extern enum bt_component_status
	164	bt_component_sink_set_add_iterator_cb(struct bt_component *sink,
	165	bt_component_sink_add_iterator_cb add_iterator);
	166
	167	/* Defaults to 1. */
	168	extern enum bt_component_status
	169	bt_component_sink_set_minimum_input_count(struct bt_component *sink,
	170	unsigned int minimum);
	171
	172	/* Defaults to 1. */
	173	extern enum bt_component_status
	174	bt_component_sink_set_maximum_input_count(struct bt_component *sink,
	175	unsigned int maximum);
	176
	177	extern enum bt_component_status
	178	bt_component_sink_get_input_count(struct bt_component *sink,
	179	unsigned int *count);
	180
	181	/* May return NULL after an interator has reached its end. */
	182	extern enum bt_component_status
	183	bt_component_sink_get_input_iterator(struct bt_component *sink,
	184	unsigned int input, struct bt_notification_iterator **iterator);
	185
	186	/** bt_component_filter */
	187	/**
	188	* Iterator initialization function type.
	189	*
	190	* A notification iterator's private data, deinitialization, next, and get
	191	* callbacks must be set by this function.
	192	*
	193	* @param filter Filter component instance
	194	* @param iterator Notification iterator instance
	195	*/
	196	typedef enum bt_component_status (*bt_component_filter_init_iterator_cb)(
	197	struct bt_component , struct bt_notification_iterator );
	198
	199	/**
	200	* Iterator addition function type.
	201	*
	202	* A filter component may choose to refuse the addition of an iterator
	203	* by not returning BT_COMPONENT_STATUS_OK.
	204	*
	205	* @param filter Filter component instance
	206	* @returns One of #bt_component_status values
	207	*/
	208	typedef enum bt_component_status (*bt_component_filter_add_iterator_cb)(
	209	struct bt_component , struct bt_notification_iterator );
	210
	211	/**
	212	* Set a filter component's iterator initialization function.
	213	*
	214	* @param filter Filter component instance
	215	* @param init_iterator Notification iterator initialization callback
	216	*/
	217	extern enum bt_component_status
	218	bt_component_filter_set_iterator_init_cb(struct bt_component *filter,
	219	bt_component_filter_init_iterator_cb init_iterator);
	220
	221	/**
	222	* Set a filter component's iterator addition callback.
	223	*
	224	* @param filter Filter component instance
	225	* @param add_iterator Iterator addition callback
	226	* @returns One of #bt_component_status values
	227	*/
	228	extern enum bt_component_status
	229	bt_component_filter_set_add_iterator_cb(struct bt_component *filter,
	230	bt_component_filter_add_iterator_cb add_iterator);
	231
	232	/* Defaults to 1. */
	233	extern enum bt_component_status
	234	bt_component_filter_set_minimum_input_count(struct bt_component *filter,
	235	unsigned int minimum);
	236
	237	/* Defaults to 1. */
	238	extern enum bt_component_status
	239	bt_component_filter_set_maximum_input_count(struct bt_component *filter,
	240	unsigned int maximum);
	241
	242	extern enum bt_component_status
	243	bt_component_filter_get_input_count(struct bt_component *filter,
	244	unsigned int *count);
	245
	246	/* May return NULL after an interator has reached its end. */
	247	extern enum bt_component_status
	248	bt_component_filter_get_input_iterator(struct bt_component *filter,
	249	unsigned int input, struct bt_notification_iterator **iterator);
	250
	251	/** bt_notification_iterator */
	252	/**
	253	* Function returning an iterator's current notification.
	254	*
	255	* @param iterator Notification iterator instance
	256	* @returns A notification instance
	257	*/
	258	typedef struct bt_notification (bt_notification_iterator_get_cb)(
	259	struct bt_notification_iterator *iterator);
	260
	261	/**
	262	* Function advancing an iterator's position of one element.
	263	*
	264	* @param iterator Notification iterator instance
	265	* @returns One of #bt_notification_iterator_status values
	266	*/
	267	typedef enum bt_notification_iterator_status (*bt_notification_iterator_next_cb)(
	268	struct bt_notification_iterator *iterator);
	269
	270	/**
	271	* Function cleaning-up an iterator's private data on destruction.
	272	*
	273	* @param iterator Notification iterator instance
	274	*/
	275	typedef void (*bt_notification_iterator_destroy_cb)(
	276	struct bt_notification_iterator *iterator);
	277
	278	/**
	279	* Set an iterator's "get" callback which return the current notification.
	280	*
	281	* @param iterator Notification iterator instance
	282	* @param get Notification return callback
	283	* @returns One of #bt_notification_iterator_status values
	284	*/
	285	extern enum bt_notification_iterator_status
	286	bt_notification_iterator_set_get_cb(struct bt_notification_iterator *iterator,
	287	bt_notification_iterator_get_cb get);
	288
	289	/**
	290	* Set an iterator's "next" callback which advances the iterator's position.
	291	*
	292	* @param iterator Notification iterator instance
	293	* @param next Iterator "next" callback
	294	* @returns One of #bt_notification_iterator_status values
	295	*/
	296	extern enum bt_notification_iterator_status
	297	bt_notification_iterator_set_next_cb(struct bt_notification_iterator *iterator,
	298	bt_notification_iterator_next_cb next);
	299
	300	/**
	301	* Set an iterator's "destroy" callback.
	302	*
	303	* @param iterator Notification iterator instance
	304	* @param next Iterator destruction callback
	305	* @returns One of #bt_notification_iterator_status values
	306	*/
	307	extern enum bt_notification_iterator_status
	308	bt_notification_iterator_set_destroy_cb(
	309	struct bt_notification_iterator *iterator,
	310	bt_notification_iterator_destroy_cb destroy);
	311
	312	/**
	313	* Set an iterator's private data.
	314	*
	315	* @param iterator Notification iterator instance
	316	* @param data Iterator private data
	317	* @returns One of #bt_notification_iterator_status values
	318	*/
	319	extern enum bt_notification_iterator_status
	320	bt_notification_iterator_set_private_data(
	321	struct bt_notification_iterator iterator, void data);
	322
	323	/**
	324	* Get an iterator's private data.
	325	*
	326	* @param iterator Notification iterator instance
	327	* @returns Iterator instance private data
	328	*/
	329	extern void *bt_notification_iterator_get_private_data(
	330	struct bt_notification_iterator *iterator);
	331
	332	#ifdef __cplusplus
	333	}
	334	#endif
	335
	336	#endif /* BABELTRACE_PLUGIN_SYSTEM_H */