[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

struct lttng_event_expr;
struct lttng_event_field_value;

/*
 * TODO: overall desciption of an event rule condition.
 */

/*
 * Create a newly allocated event rule condition.
 *
 * Rule will be copied internally.
 *
 * 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);

/*
 * Sets `*field_val` to the array event field value of the event rule
 * condition evaluation `evaluation` which contains its captured values.
 *
 * Returns:
 *
 * `LTTNG_EVALUATION_STATUS_OK`:
 *     Success.
 *
 *     `*field_val` is an array event field value with a length of at
 *     least one.
 *
 * `LTTNG_EVALUATION_STATUS_INVALID`:
 *     * `evaluation` is `NULL`.
 *     * The type of the condition of `evaluation` is not
 *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 *     * The condition of `evaluation` has no capture descriptors.
 *     * `field_val` is `NULL`.
 */
extern enum lttng_evaluation_status
lttng_evaluation_get_captured_values(
		const struct lttng_evaluation *evaluation,
		const struct lttng_event_field_value **field_val);

/*
 * Appends (transfering the ownership) the capture descriptor `expr` to
 * the event rule condition `condition`.
 *
 * Returns:
 *
 * `LTTNG_CONDITION_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_CONDITION_STATUS_ERROR`:
 *     Memory error.
 *
 * `LTTNG_CONDITION_STATUS_INVALID`:
 *     * `condition` is `NULL`.
 *     * The type of `condition` is not
 *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 *     * `expr` is `NULL`.
 *     * `expr` is not a locator expression, that is, its type is not
 *       one of:
 *
 *       * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
 * `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
 *     * The associated event-rule does not support runtime capture.
 */
extern enum lttng_condition_status
lttng_condition_event_rule_append_capture_descriptor(
		struct lttng_condition *condition,
		struct lttng_event_expr *expr);

/*
 * Sets `*count` to the number of capture descriptors in the event rule
 * condition `condition`.
 *
 * Returns:
 *
 * `LTTNG_CONDITION_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_CONDITION_STATUS_INVALID`:
 *     * `condition` is `NULL`.
 *     * The type of `condition` is not
 *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 *     * `count` is `NULL`.
 */
extern enum lttng_condition_status
lttng_condition_event_rule_get_capture_descriptor_count(
		const struct lttng_condition *condition, unsigned int *count);

/*
 * Returns the capture descriptor (borrowed) of the event rule condition
 * `condition` at the index `index`, or `NULL` if:
 *
 * * `condition` is `NULL`.
 * * The type of `condition` is not
 *   `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 * * `index` is greater than or equal to the number of capture
 *   descriptors in `condition` (as returned by
 *   lttng_condition_event_rule_get_capture_descriptor_count()).
 */
extern const struct lttng_event_expr *
lttng_condition_event_rule_get_capture_descriptor_at_index(
		const struct lttng_condition *condition, unsigned int index);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_EVENT_RULE_H */
Commit	Line	Data
5024c2ac JR	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	struct lttng_event_expr;
	20	struct lttng_event_field_value;
	21
	22	/*
	23	* TODO: overall desciption of an event rule condition.
	24	*/
	25
	26	/*
	27	* Create a newly allocated event rule condition.
	28	*
	29	* Rule will be copied internally.
	30	*
	31	* Returns a new condition on success, NULL on failure. This condition must be
	32	* destroyed using lttng_condition_destroy().
	33	*/
	34	extern struct lttng_condition *lttng_condition_event_rule_create(
	35	struct lttng_event_rule *rule);
	36
	37	/*
	38	* Get the rule property of a event rule condition.
	39	*
	40	* The caller does not assume the ownership of the returned rule. The
	41	* rule shall only be used for the duration of the condition's
	42	* lifetime.
	43	*
	44	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
	45	* on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
	46	* parameter is passed. */
	47	extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
	48	const struct lttng_condition condition, const struct lttng_event_rule *rule);
	49
	50	/**
	51	* lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
	52	* allow users to query a number of properties resulting from the evaluation
	53	* of a condition which evaluated to true.
	54	*
	55	* The evaluation of a event rule hit yields two different results:
	56	* TEMPORARY - The name of the triggers associated with the condition.
	57	* TODO - The captured event payload if any
	58	*/
	59
	60	/*
	61	* Get the trigger name property of a event rule hit evaluation.
	62	*
	63	* Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
	64	* or LTTNG_EVALUATION_STATUS_INVALID if
65	* an invalid parameter is passed.
66	*/
67	extern enum lttng_evaluation_status
68	lttng_evaluation_event_rule_get_trigger_name(
69	const struct lttng_evaluation *evaluation,
70	const char **name);
71
72	/*
73	* Sets `*field_val` to the array event field value of the event rule
74	* condition evaluation `evaluation` which contains its captured values.
75	*
76	* Returns:
77	*
78	* `LTTNG_EVALUATION_STATUS_OK`:
79	* Success.
80	*
81	* `*field_val` is an array event field value with a length of at
82	* least one.
83	*
84	* `LTTNG_EVALUATION_STATUS_INVALID`:
85	* * `evaluation` is `NULL`.
86	* * The type of the condition of `evaluation` is not
87	* `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
88	* * The condition of `evaluation` has no capture descriptors.
89	* * `field_val` is `NULL`.
90	*/
91	extern enum lttng_evaluation_status
92	lttng_evaluation_get_captured_values(
93	const struct lttng_evaluation *evaluation,
94	const struct lttng_event_field_value **field_val);
95
96	/*
97	* Appends (transfering the ownership) the capture descriptor `expr` to
98	* the event rule condition `condition`.
99	*
100	* Returns:
101	*
102	* `LTTNG_CONDITION_STATUS_OK`:
103	* Success.
104	*
105	* `LTTNG_CONDITION_STATUS_ERROR`:
106	* Memory error.
107	*
108	* `LTTNG_CONDITION_STATUS_INVALID`:
109	* * `condition` is `NULL`.
110	* * The type of `condition` is not
111	* `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
112	* * `expr` is `NULL`.
113	* * `expr` is not a locator expression, that is, its type is not
114	* one of:
115	*
116	* * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
117	* * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
118	* * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
119	* * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
120	* `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
121	* * The associated event-rule does not support runtime capture.
122	*/
123	extern enum lttng_condition_status
124	lttng_condition_event_rule_append_capture_descriptor(
125	struct lttng_condition *condition,
126	struct lttng_event_expr *expr);
127
128	/*
129	* Sets `*count` to the number of capture descriptors in the event rule
130	* condition `condition`.
131	*
132	* Returns:
133	*
134	* `LTTNG_CONDITION_STATUS_OK`:
135	* Success.
136	*
137	* `LTTNG_CONDITION_STATUS_INVALID`:
138	* * `condition` is `NULL`.
139	* * The type of `condition` is not
140	* `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
141	* * `count` is `NULL`.
142	*/
143	extern enum lttng_condition_status
144	lttng_condition_event_rule_get_capture_descriptor_count(
145	const struct lttng_condition condition, unsigned int count);
146
147	/*
148	* Returns the capture descriptor (borrowed) of the event rule condition
149	* `condition` at the index `index`, or `NULL` if:
150	*
151	* * `condition` is `NULL`.
152	* * The type of `condition` is not
153	* `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
154	* * `index` is greater than or equal to the number of capture
155	* descriptors in `condition` (as returned by
156	* lttng_condition_event_rule_get_capture_descriptor_count()).
157	*/
158	extern const struct lttng_event_expr *
159	lttng_condition_event_rule_get_capture_descriptor_at_index(
160	const struct lttng_condition *condition, unsigned int index);
161
162	#ifdef __cplusplus
163	}
164	#endif
165
166	#endif /* LTTNG_CONDITION_EVENT_RULE_H */