Commit | Line | Data |
---|---|---|
683d081a 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 | ||
8dbb86b8 JR |
8 | #ifndef LTTNG_CONDITION_EVENT_RULE_MATCHES_H |
9 | #define LTTNG_CONDITION_EVENT_RULE_MATCHES_H | |
683d081a JR |
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 | ||
38114013 | 19 | struct lttng_event_expr; |
7c920b63 | 20 | struct lttng_event_field_value; |
38114013 | 21 | |
8dbb86b8 JR |
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, | |
3ce811ee JG |
26 | }; |
27 | ||
683d081a | 28 | /** |
8dbb86b8 JR |
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. | |
683d081a | 31 | * |
8dbb86b8 JR |
32 | * An Event Rule Matches condition can also specify a payload to be captured at |
33 | * runtime. This is done via the capture descriptor. | |
683d081a JR |
34 | * |
35 | * Note: the dynamic runtime capture of payload is only available for the | |
36 | * trigger notification subsystem. | |
37 | */ | |
38 | ||
39 | /* | |
8dbb86b8 | 40 | * Create a newly allocated Event Rule Matches condition. |
683d081a JR |
41 | * |
42 | * Returns a new condition on success, NULL on failure. This condition must be | |
43 | * destroyed using lttng_condition_destroy(). | |
44 | */ | |
8dbb86b8 | 45 | extern struct lttng_condition *lttng_condition_event_rule_matches_create( |
683d081a JR |
46 | struct lttng_event_rule *rule); |
47 | ||
48 | /* | |
8dbb86b8 | 49 | * Get the rule property of an Event Rule Matches condition. |
683d081a JR |
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. */ | |
8dbb86b8 | 58 | extern enum lttng_condition_status lttng_condition_event_rule_matches_get_rule( |
d602bd6a | 59 | const struct lttng_condition *condition, |
683d081a JR |
60 | const struct lttng_event_rule **rule); |
61 | ||
62 | /** | |
8dbb86b8 JR |
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. | |
683d081a | 66 | * |
8dbb86b8 | 67 | * The evaluation of an Event Rule Matches condition contains the captured event |
65f64978 | 68 | * payload fields that were specified by the condition. |
683d081a JR |
69 | */ |
70 | ||
7c920b63 | 71 | /* |
8dbb86b8 | 72 | * Sets `*field_val` to the array event field value of the Event Rule Matches |
7c920b63 PP |
73 | * condition evaluation `evaluation` which contains its captured values. |
74 | * | |
75 | * Returns: | |
76 | * | |
8dbb86b8 | 77 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK`: |
7c920b63 PP |
78 | * Success. |
79 | * | |
80 | * `*field_val` is an array event field value with a length of at | |
81 | * least one. | |
82 | * | |
8dbb86b8 | 83 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID`: |
7c920b63 PP |
84 | * * `evaluation` is `NULL`. |
85 | * * The type of the condition of `evaluation` is not | |
8dbb86b8 | 86 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
7c920b63 | 87 | * * `field_val` is `NULL`. |
3ce811ee | 88 | * |
8dbb86b8 | 89 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE`: |
3ce811ee | 90 | * * The condition of `evaluation` has no capture descriptors. |
7c920b63 | 91 | */ |
8dbb86b8 JR |
92 | extern enum lttng_evaluation_event_rule_matches_status |
93 | lttng_evaluation_event_rule_matches_get_captured_values( | |
7c920b63 PP |
94 | const struct lttng_evaluation *evaluation, |
95 | const struct lttng_event_field_value **field_val); | |
96 | ||
38114013 PP |
97 | /* |
98 | * Appends (transfering the ownership) the capture descriptor `expr` to | |
8dbb86b8 | 99 | * the Event Rule Matches condition `condition`. |
38114013 PP |
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 | |
8dbb86b8 | 112 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
38114013 PP |
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` | |
81d566c9 JR |
121 | * |
122 | * `LTTNG_CONDITION_STATUS_UNSUPPORTED`: | |
123 | * * The associated event-rule does not support runtime capture. | |
38114013 PP |
124 | */ |
125 | extern enum lttng_condition_status | |
8dbb86b8 | 126 | lttng_condition_event_rule_matches_append_capture_descriptor( |
38114013 PP |
127 | struct lttng_condition *condition, |
128 | struct lttng_event_expr *expr); | |
129 | ||
130 | /* | |
8dbb86b8 | 131 | * Sets `*count` to the number of capture descriptors in the Event Rule Matches |
38114013 PP |
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 | |
8dbb86b8 | 142 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
38114013 PP |
143 | * * `count` is `NULL`. |
144 | */ | |
145 | extern enum lttng_condition_status | |
8dbb86b8 | 146 | lttng_condition_event_rule_matches_get_capture_descriptor_count( |
38114013 PP |
147 | const struct lttng_condition *condition, unsigned int *count); |
148 | ||
149 | /* | |
8dbb86b8 | 150 | * Returns the capture descriptor (borrowed) of the Event Rule Matches condition |
38114013 PP |
151 | * `condition` at the index `index`, or `NULL` if: |
152 | * | |
153 | * * `condition` is `NULL`. | |
154 | * * The type of `condition` is not | |
8dbb86b8 | 155 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
38114013 PP |
156 | * * `index` is greater than or equal to the number of capture |
157 | * descriptors in `condition` (as returned by | |
8dbb86b8 | 158 | * lttng_condition_event_rule_matches_get_capture_descriptor_count()). |
38114013 PP |
159 | */ |
160 | extern const struct lttng_event_expr * | |
8dbb86b8 | 161 | lttng_condition_event_rule_matches_get_capture_descriptor_at_index( |
38114013 PP |
162 | const struct lttng_condition *condition, unsigned int index); |
163 | ||
683d081a JR |
164 | #ifdef __cplusplus |
165 | } | |
166 | #endif | |
167 | ||
8dbb86b8 | 168 | #endif /* LTTNG_CONDITION_EVENT_RULE_MATCHES_H */ |