[lttng-tools.git] / include / lttng / condition / event-rule.h

/*
 * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_CONDITION_EVENT_RULE_H
#define LTTNG_CONDITION_EVENT_RULE_H

#include <lttng/event-rule/event-rule.h>
#include <lttng/condition/condition.h>
#include <lttng/condition/evaluation.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Event rule conditions allows an action to be taken whenever an event matching
 * the event rule is hit by the tracers.
 *
 * An event rule condition can also specify a payload to be captured at runtime.
 * This is done via the capture descriptor.
 *
 * Note: the dynamic runtime capture of payload is only available for the
 *       trigger notification subsystem.
 */

/*
 * Create a newly allocated event rule condition.
 *
 * Returns a new condition on success, NULL on failure. This condition must be
 * destroyed using lttng_condition_destroy().
 */
extern struct lttng_condition *lttng_condition_event_rule_create(
		struct lttng_event_rule *rule);

/*
 * Get the rule property of a event rule condition.
 *
 * The caller does not assume the ownership of the returned rule. The
 * rule shall only be used for the duration of the condition's
 * lifetime.
 *
 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 * parameter is passed. */
extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
		 const struct lttng_condition *condition,
		const struct lttng_event_rule **rule);

/**
 * lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
 * allow users to query a number of properties resulting from the evaluation
 * of a condition which evaluated to true.
 *
 * The evaluation of a event rule hit yields two different results:
 *    TEMPORARY - The name of the triggers associated with the condition.
 *    TODO - The captured event payload if any
 */

/*
 * Get the trigger name property of a event rule hit evaluation.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
 * or LTTNG_EVALUATION_STATUS_INVALID if
 * an invalid parameter is passed.
 */
extern enum lttng_evaluation_status
lttng_evaluation_event_rule_get_trigger_name(
		const struct lttng_evaluation *evaluation,
		const char **name);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_EVENT_RULE_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef LTTNG_CONDITION_EVENT_RULE_H
	9	#define LTTNG_CONDITION_EVENT_RULE_H
	10
	11	#include <lttng/event-rule/event-rule.h>
	12	#include <lttng/condition/condition.h>
	13	#include <lttng/condition/evaluation.h>
	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
	19	/**
	20	* Event rule conditions allows an action to be taken whenever an event matching
	21	* the event rule is hit by the tracers.
	22	*
	23	* An event rule condition can also specify a payload to be captured at runtime.
	24	* This is done via the capture descriptor.
	25	*
	26	* Note: the dynamic runtime capture of payload is only available for the
	27	* trigger notification subsystem.
	28	*/
	29
	30	/*
	31	* Create a newly allocated event rule condition.
	32	*
	33	* Returns a new condition on success, NULL on failure. This condition must be
	34	* destroyed using lttng_condition_destroy().
	35	*/
	36	extern struct lttng_condition *lttng_condition_event_rule_create(
	37	struct lttng_event_rule *rule);
	38
	39	/*
	40	* Get the rule property of a event rule condition.
	41	*
	42	* The caller does not assume the ownership of the returned rule. The
	43	* rule shall only be used for the duration of the condition's
	44	* lifetime.
	45	*
	46	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
	47	* on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
	48	* parameter is passed. */
	49	extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
	50	const struct lttng_condition *condition,
	51	const struct lttng_event_rule **rule);
	52
	53	/**
	54	* lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
	55	* allow users to query a number of properties resulting from the evaluation
	56	* of a condition which evaluated to true.
	57	*
	58	* The evaluation of a event rule hit yields two different results:
	59	* TEMPORARY - The name of the triggers associated with the condition.
	60	* TODO - The captured event payload if any
	61	*/
	62
	63	/*
	64	* Get the trigger name property of a event rule hit evaluation.
	65	*
	66	* Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
	67	* or LTTNG_EVALUATION_STATUS_INVALID if
	68	* an invalid parameter is passed.
	69	*/
	70	extern enum lttng_evaluation_status
	71	lttng_evaluation_event_rule_get_trigger_name(
	72	const struct lttng_evaluation *evaluation,
	73	const char **name);
	74
	75	#ifdef __cplusplus
	76	}
	77	#endif
	78
	79	#endif /* LTTNG_CONDITION_EVENT_RULE_H */