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 | 10 | |
683d081a JR |
11 | #include <lttng/condition/condition.h> |
12 | #include <lttng/condition/evaluation.h> | |
28f23191 | 13 | #include <lttng/event-rule/event-rule.h> |
4bd69c5f | 14 | #include <lttng/lttng-export.h> |
683d081a JR |
15 | |
16 | #ifdef __cplusplus | |
17 | extern "C" { | |
18 | #endif | |
19 | ||
38114013 | 20 | struct lttng_event_expr; |
7c920b63 | 21 | struct lttng_event_field_value; |
38114013 | 22 | |
8dbb86b8 JR |
23 | enum lttng_evaluation_event_rule_matches_status { |
24 | LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE = 1, | |
25 | LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK = 0, | |
26 | LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID = -1, | |
3ce811ee JG |
27 | }; |
28 | ||
683d081a | 29 | /** |
8dbb86b8 JR |
30 | * Event Rule Matches conditions allows an action to be taken whenever an event |
31 | * matching the Event Rule Matches is hit by the tracers. | |
683d081a | 32 | * |
8dbb86b8 JR |
33 | * An Event Rule Matches condition can also specify a payload to be captured at |
34 | * runtime. This is done via the capture descriptor. | |
683d081a JR |
35 | * |
36 | * Note: the dynamic runtime capture of payload is only available for the | |
37 | * trigger notification subsystem. | |
38 | */ | |
39 | ||
40 | /* | |
8dbb86b8 | 41 | * Create a newly allocated Event Rule Matches condition. |
683d081a JR |
42 | * |
43 | * Returns a new condition on success, NULL on failure. This condition must be | |
44 | * destroyed using lttng_condition_destroy(). | |
45 | */ | |
28f23191 JG |
46 | LTTNG_EXPORT extern struct lttng_condition * |
47 | lttng_condition_event_rule_matches_create(struct lttng_event_rule *rule); | |
683d081a JR |
48 | |
49 | /* | |
8dbb86b8 | 50 | * Get the rule property of an Event Rule Matches condition. |
683d081a JR |
51 | * |
52 | * The caller does not assume the ownership of the returned rule. The | |
53 | * rule shall only be used for the duration of the condition's | |
54 | * lifetime. | |
55 | * | |
56 | * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule | |
57 | * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid | |
58 | * parameter is passed. */ | |
28f23191 JG |
59 | LTTNG_EXPORT extern enum lttng_condition_status |
60 | lttng_condition_event_rule_matches_get_rule(const struct lttng_condition *condition, | |
61 | const struct lttng_event_rule **rule); | |
683d081a JR |
62 | |
63 | /** | |
8dbb86b8 JR |
64 | * lttng_evaluation_event_rule_matches_hit are specialised lttng_evaluations |
65 | * which allow users to query a number of properties resulting from the | |
66 | * evaluation of a condition which evaluated to true. | |
683d081a | 67 | * |
8dbb86b8 | 68 | * The evaluation of an Event Rule Matches condition contains the captured event |
65f64978 | 69 | * payload fields that were specified by the condition. |
683d081a JR |
70 | */ |
71 | ||
7c920b63 | 72 | /* |
8dbb86b8 | 73 | * Sets `*field_val` to the array event field value of the Event Rule Matches |
7c920b63 PP |
74 | * condition evaluation `evaluation` which contains its captured values. |
75 | * | |
76 | * Returns: | |
77 | * | |
8dbb86b8 | 78 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK`: |
7c920b63 PP |
79 | * Success. |
80 | * | |
81 | * `*field_val` is an array event field value with a length of at | |
82 | * least one. | |
83 | * | |
8dbb86b8 | 84 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_INVALID`: |
7c920b63 PP |
85 | * * `evaluation` is `NULL`. |
86 | * * The type of the condition of `evaluation` is not | |
8dbb86b8 | 87 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
7c920b63 | 88 | * * `field_val` is `NULL`. |
3ce811ee | 89 | * |
8dbb86b8 | 90 | * `LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_NONE`: |
3ce811ee | 91 | * * The condition of `evaluation` has no capture descriptors. |
7c920b63 | 92 | */ |
4bd69c5f | 93 | LTTNG_EXPORT extern enum lttng_evaluation_event_rule_matches_status |
8dbb86b8 | 94 | lttng_evaluation_event_rule_matches_get_captured_values( |
28f23191 JG |
95 | const struct lttng_evaluation *evaluation, |
96 | const struct lttng_event_field_value **field_val); | |
7c920b63 | 97 | |
38114013 PP |
98 | /* |
99 | * Appends (transfering the ownership) the capture descriptor `expr` to | |
8dbb86b8 | 100 | * the Event Rule Matches condition `condition`. |
38114013 PP |
101 | * |
102 | * Returns: | |
103 | * | |
104 | * `LTTNG_CONDITION_STATUS_OK`: | |
105 | * Success. | |
106 | * | |
107 | * `LTTNG_CONDITION_STATUS_ERROR`: | |
108 | * Memory error. | |
109 | * | |
110 | * `LTTNG_CONDITION_STATUS_INVALID`: | |
111 | * * `condition` is `NULL`. | |
112 | * * The type of `condition` is not | |
8dbb86b8 | 113 | * `LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES`. |
38114013 PP |
114 | * * `expr` is `NULL`. |
115 | * * `expr` is not a locator expression, that is, its type is not | |
116 | * one of: | |
117 | * | |
118 | * * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD` | |
119 | * * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD` | |
120 | * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD` | |
121 | * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT` | |
81d566c9 JR |
122 | * |
123 | * `LTTNG_CONDITION_STATUS_UNSUPPORTED`: | |
124 | * * The associated event-rule does not support runtime capture. | |
38114013 | 125 | */ |
4bd69c5f | 126 | LTTNG_EXPORT extern enum lttng_condition_status |
28f23191 JG |
127 | lttng_condition_event_rule_matches_append_capture_descriptor(struct lttng_condition *condition, |
128 | struct lttng_event_expr *expr); | |
38114013 PP |
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 | */ | |
4bd69c5f | 145 | LTTNG_EXPORT extern enum lttng_condition_status |
8dbb86b8 | 146 | lttng_condition_event_rule_matches_get_capture_descriptor_count( |
28f23191 | 147 | const struct lttng_condition *condition, unsigned int *count); |
38114013 PP |
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 | 159 | */ |
4bd69c5f | 160 | LTTNG_EXPORT extern const struct lttng_event_expr * |
8dbb86b8 | 161 | lttng_condition_event_rule_matches_get_capture_descriptor_at_index( |
28f23191 | 162 | const struct lttng_condition *condition, unsigned int index); |
38114013 | 163 | |
683d081a JR |
164 | #ifdef __cplusplus |
165 | } | |
166 | #endif | |
167 | ||
8dbb86b8 | 168 | #endif /* LTTNG_CONDITION_EVENT_RULE_MATCHES_H */ |