75d1c88af7e6c00b0cf0ce4217633b43bfa7db14
[lttng-tools.git] / include / lttng / condition / event-rule-matches.h
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_MATCHES_H
9 #define LTTNG_CONDITION_EVENT_RULE_MATCHES_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 enum lttng_evaluation_event_rule_matches_status {
23 LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE = 1,
24 LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK = 0,
25 LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID = -1,
26 };
27
28 /**
29 * Event Rule Matches conditions allows an action to be taken whenever an event
30 * matching the Event Rule Matches is hit by the tracers.
31 *
32 * An Event Rule Matches condition can also specify a payload to be captured at
33 * runtime. This is done via the capture descriptor.
34 *
35 * Note: the dynamic runtime capture of payload is only available for the
36 * trigger notification subsystem.
37 */
38
39 /*
40 * Create a newly allocated Event Rule Matches condition.
41 *
42 * Returns a new condition on success, NULL on failure. This condition must be
43 * destroyed using lttng_condition_destroy().
44 */
45 extern struct lttng_condition *lttng_condition_event_rule_matches_create(
46 struct lttng_event_rule *rule);
47
48 /*
49 * Get the rule property of an Event Rule Matches condition.
50 *
51 * The caller does not assume the ownership of the returned rule. The
52 * rule shall only be used for the duration of the condition's
53 * lifetime.
54 *
55 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
56 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
57 * parameter is passed. */
58 extern enum lttng_condition_status lttng_condition_event_rule_matches_get_rule(
59 const struct lttng_condition *condition,
60 const struct lttng_event_rule **rule);
61
62 /**
63 * lttng_evaluation_event_rule_matches_hit are specialised lttng_evaluations
64 * which allow users to query a number of properties resulting from the
65 * evaluation of a condition which evaluated to true.
66 *
67 * The evaluation of an Event Rule Matches condition contains the captured event
68 * payload fields that were specified by the condition.
69 */
70
71 /*
72 * Sets `*field_val` to the array event field value of the Event Rule Matches
73 * condition evaluation `evaluation` which contains its captured values.
74 *
75 * Returns:
76 *
77 * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK`:
78 * Success.
79 *
80 * `*field_val` is an array event field value with a length of at
81 * least one.
82 *
83 * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID`:
84 * * `evaluation` is `NULL`.
85 * * The type of the condition of `evaluation` is not
86 * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
87 * * `field_val` is `NULL`.
88 *
89 * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE`:
90 * * The condition of `evaluation` has no capture descriptors.
91 */
92 extern enum lttng_evaluation_event_rule_matches_status
93 lttng_evaluation_event_rule_matches_get_captured_values(
94 const struct lttng_evaluation *evaluation,
95 const struct lttng_event_field_value **field_val);
96
97 /*
98 * Appends (transfering the ownership) the capture descriptor `expr` to
99 * the Event Rule Matches condition `condition`.
100 *
101 * Returns:
102 *
103 * `LTTNG_CONDITION_STATUS_OK`:
104 * Success.
105 *
106 * `LTTNG_CONDITION_STATUS_ERROR`:
107 * Memory error.
108 *
109 * `LTTNG_CONDITION_STATUS_INVALID`:
110 * * `condition` is `NULL`.
111 * * The type of `condition` is not
112 * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
113 * * `expr` is `NULL`.
114 * * `expr` is not a locator expression, that is, its type is not
115 * one of:
116 *
117 * * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
118 * * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
119 * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
120 * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
121 *
122 * `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
123 * * The associated event-rule does not support runtime capture.
124 */
125 extern enum lttng_condition_status
126 lttng_condition_event_rule_matches_append_capture_descriptor(
127 struct lttng_condition *condition,
128 struct lttng_event_expr *expr);
129
130 /*
131 * Sets `*count` to the number of capture descriptors in the Event Rule Matches
132 * condition `condition`.
133 *
134 * Returns:
135 *
136 * `LTTNG_CONDITION_STATUS_OK`:
137 * Success.
138 *
139 * `LTTNG_CONDITION_STATUS_INVALID`:
140 * * `condition` is `NULL`.
141 * * The type of `condition` is not
142 * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
143 * * `count` is `NULL`.
144 */
145 extern enum lttng_condition_status
146 lttng_condition_event_rule_matches_get_capture_descriptor_count(
147 const struct lttng_condition *condition, unsigned int *count);
148
149 /*
150 * Returns the capture descriptor (borrowed) of the Event Rule Matches condition
151 * `condition` at the index `index`, or `NULL` if:
152 *
153 * * `condition` is `NULL`.
154 * * The type of `condition` is not
155 * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`.
156 * * `index` is greater than or equal to the number of capture
157 * descriptors in `condition` (as returned by
158 * lttng_condition_event_rule_matches_get_capture_descriptor_count()).
159 */
160 extern const struct lttng_event_expr *
161 lttng_condition_event_rule_matches_get_capture_descriptor_at_index(
162 const struct lttng_condition *condition, unsigned int index);
163
164 #ifdef __cplusplus
165 }
166 #endif
167
168 #endif /* LTTNG_CONDITION_EVENT_RULE_MATCHES_H */
This page took 0.033485 seconds and 4 git commands to generate.