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