[lttng-tools.git] / include / lttng / trigger / trigger.h

/*
 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef LTTNG_TRIGGER_H
#define LTTNG_TRIGGER_H

struct lttng_action;
struct lttng_condition;
struct lttng_trigger;

#ifdef __cplusplus
extern "C" {
#endif

enum lttng_register_trigger_status {
	LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
	LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
};

/*
 * Create a trigger object associating a condition and an action.
 *
 * A trigger associates a condition and an action to take whenever the
 * condition evaluates to true. Such actions can, for example, consist
 * in the emission of a notification to clients listening through
 * notification channels.
 *
 * The caller retains the ownership of both the condition and action
 * and both must be kept alive for the lifetime of the trigger object.
 *
 * A trigger must be registered in order to become activate and can
 * be destroyed after its registration.
 *
 * Returns a trigger object on success, NULL on error.
 * Trigger objects must be destroyed using the lttng_trigger_destroy()
 * function.
 */
extern struct lttng_trigger *lttng_trigger_create(
		struct lttng_condition *condition, struct lttng_action *action);

/*
 * Get the condition of a trigger.
 *
 * The caller acquires no ownership of the returned condition.
 *
 * Returns a condition on success, NULL on error.
 */
extern struct lttng_condition *lttng_trigger_get_condition(
		struct lttng_trigger *trigger);

/*
 * Get the action of a trigger.
 *
 * The caller acquires no ownership of the returned action.
 *
 * Returns an action on success, NULL on error.
 */
extern struct lttng_action *lttng_trigger_get_action(
		struct lttng_trigger *trigger);

/*
 * Destroy (frees) a trigger object.
 */
extern void lttng_trigger_destroy(struct lttng_trigger *trigger);

/*
 * Register a trigger to the session daemon.
 *
 * The trigger can be destroyed after this call.
 *
 * Return 0 on success, a negative LTTng error code on error.
 */
extern int lttng_register_trigger(struct lttng_trigger *trigger);

/*
 * Unregister a trigger from the session daemon.
 *
 * The trigger can be destroyed after this call.
 *
 * Return 0 on success, a negative LTTng error code on error.
 */
extern int lttng_unregister_trigger(struct lttng_trigger *trigger);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_TRIGGER_H */
Commit	Line	Data
a58c490f JG	1	/*
	2	* Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	*
	4	* This library is free software; you can redistribute it and/or modify it
	5	* under the terms of the GNU Lesser General Public License, version 2.1 only,
	6	* as published by the Free Software Foundation.
	7	*
	8	* This library is distributed in the hope that it will be useful, but WITHOUT
	9	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	10	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
	11	* for more details.
	12	*
	13	* You should have received a copy of the GNU Lesser General Public License
	14	* along with this library; if not, write to the Free Software Foundation,
	15	* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
	16	*/
	17
	18	#ifndef LTTNG_TRIGGER_H
	19	#define LTTNG_TRIGGER_H
	20
	21	struct lttng_action;
	22	struct lttng_condition;
	23	struct lttng_trigger;
	24
	25	#ifdef __cplusplus
	26	extern "C" {
	27	#endif
	28
	29	enum lttng_register_trigger_status {
	30	LTTNG_REGISTER_TRIGGER_STATUS_OK = 0,
	31	LTTNG_REGISTER_TRIGGER_STATUS_INVALID = -1,
	32	};
	33
75984389 JG	34	/*
	35	* Create a trigger object associating a condition and an action.
	36	*
	37	* A trigger associates a condition and an action to take whenever the
	38	* condition evaluates to true. Such actions can, for example, consist
	39	* in the emission of a notification to clients listening through
	40	* notification channels.
	41	*
	42	* The caller retains the ownership of both the condition and action
	43	* and both must be kept alive for the lifetime of the trigger object.
	44	*
	45	* A trigger must be registered in order to become activate and can
	46	* be destroyed after its registration.
	47	*
	48	* Returns a trigger object on success, NULL on error.
	49	* Trigger objects must be destroyed using the lttng_trigger_destroy()
	50	* function.
	51	*/
a58c490f JG	52	extern struct lttng_trigger *lttng_trigger_create(
	53	struct lttng_condition condition, struct lttng_action action);
	54
75984389 JG	55	/*
	56	* Get the condition of a trigger.
	57	*
	58	* The caller acquires no ownership of the returned condition.
	59	*
	60	* Returns a condition on success, NULL on error.
	61	*/
a58c490f JG	62	extern struct lttng_condition *lttng_trigger_get_condition(
	63	struct lttng_trigger *trigger);
	64
75984389 JG	65	/*
	66	* Get the action of a trigger.
	67	*
	68	* The caller acquires no ownership of the returned action.
	69	*
	70	* Returns an action on success, NULL on error.
	71	*/
a58c490f JG	72	extern struct lttng_action *lttng_trigger_get_action(
	73	struct lttng_trigger *trigger);
	74
75984389 JG	75	/*
	76	* Destroy (frees) a trigger object.
	77	*/
a58c490f JG	78	extern void lttng_trigger_destroy(struct lttng_trigger *trigger);
a58c490f JG	79
75984389 JG	80	/*
	81	* Register a trigger to the session daemon.
	82	*
	83	* The trigger can be destroyed after this call.
	84	*
	85	* Return 0 on success, a negative LTTng error code on error.
	86	*/
a58c490f JG	87	extern int lttng_register_trigger(struct lttng_trigger *trigger);
a58c490f JG	88
75984389 JG	89	/*
	90	* Unregister a trigger from the session daemon.
	91	*
	92	* The trigger can be destroyed after this call.
	93	*
	94	* Return 0 on success, a negative LTTng error code on error.
	95	*/
a58c490f JG	96	extern int lttng_unregister_trigger(struct lttng_trigger *trigger);
	97
	98	#ifdef __cplusplus
	99	}
	100	#endif
	101
	102	#endif /* LTTNG_TRIGGER_H */