Commit | Line | Data |
---|---|---|
48c47564 PP |
1 | /* |
2 | * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com> | |
3 | * | |
4 | * SPDX-License-Identifier: LGPL-2.1-only | |
5 | * | |
6 | */ | |
7 | ||
8 | #ifndef LTTNG_EVENT_EXPR_H | |
9 | #define LTTNG_EVENT_EXPR_H | |
10 | ||
11 | #include <stdbool.h> | |
12 | ||
13 | struct lttng_event_expr; | |
14 | ||
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | ||
19 | /* | |
20 | * Types of an event expression. | |
21 | */ | |
22 | enum lttng_event_expr_type { | |
23 | /* | |
24 | * Returned by lttng_event_expr_get_type() with an invalid | |
25 | * parameter. | |
26 | */ | |
27 | LTTNG_EVENT_EXPR_TYPE_INVALID = -1, | |
28 | ||
29 | /* | |
30 | * The named payload field of an event. | |
31 | * | |
32 | * Command-line expression example: | |
33 | * | |
34 | * next_prio | |
35 | */ | |
36 | LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD = 0, | |
37 | ||
38 | /* | |
39 | * The named per-channel context field of an event. | |
40 | * | |
41 | * Command-line expression example: | |
42 | * | |
43 | * $ctx.vpid | |
44 | */ | |
45 | LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD = 1, | |
46 | ||
47 | /* | |
48 | * The named application-specific context field of an event. | |
49 | * | |
50 | * Command-line expression example: | |
51 | * | |
52 | * $app.iga:active-clients | |
53 | */ | |
54 | LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD = 2, | |
55 | ||
56 | /* | |
57 | * The element of an array field. | |
58 | * | |
59 | * Command-line expression example: | |
60 | * | |
61 | * my_field[4] | |
62 | * $ctx.some_context[5][1] | |
63 | */ | |
64 | LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT = 3, | |
65 | }; | |
66 | ||
67 | /* | |
68 | * Event expression API status codes. | |
69 | */ | |
70 | enum lttng_event_expr_status { | |
71 | /* | |
72 | * Invalid parameter. | |
73 | */ | |
74 | LTTNG_EVENT_EXPR_STATUS_INVALID = -1, | |
75 | ||
76 | /* | |
77 | * Success. | |
78 | */ | |
79 | LTTNG_EVENT_EXPR_STATUS_OK = 0, | |
80 | }; | |
81 | ||
82 | /* | |
83 | * Returns the type of the event expression `expr`, or | |
84 | * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`. | |
85 | */ | |
86 | extern enum lttng_event_expr_type lttng_event_expr_get_type( | |
87 | const struct lttng_event_expr *expr); | |
88 | ||
89 | /* | |
90 | * Creates an event payload field expression for the payload field named | |
91 | * `field_name`. | |
92 | * | |
93 | * Returns `NULL` if: | |
94 | * | |
95 | * * There's a memory error. | |
96 | * * `field_name` is `NULL`. | |
97 | */ | |
98 | extern struct lttng_event_expr *lttng_event_expr_event_payload_field_create( | |
99 | const char *field_name); | |
100 | ||
101 | /* | |
102 | * Returns the field name of the event payload field expression `expr`, | |
103 | * or `NULL` if: | |
104 | * | |
105 | * * `expr` is `NULL`. | |
106 | * * The type of `expr` is not | |
107 | * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`. | |
108 | */ | |
109 | extern const char *lttng_event_expr_event_payload_field_get_name( | |
110 | const struct lttng_event_expr *expr); | |
111 | ||
112 | /* | |
113 | * Creates a per-channel context field expression for the per-channel | |
114 | * context field named `field_name`. | |
115 | * | |
116 | * Returns `NULL` if: | |
117 | * | |
118 | * * There's a memory error. | |
119 | * * `field_name` is `NULL`. | |
120 | */ | |
121 | extern struct lttng_event_expr * | |
122 | lttng_event_expr_channel_context_field_create(const char *field_name); | |
123 | ||
124 | /* | |
125 | * Returns the field name of the per-channel context field | |
126 | * expression `expr`, or `NULL` if: | |
127 | * | |
128 | * `expr` is `NULL`. | |
129 | * * The type of `expr` is not | |
130 | * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`. | |
131 | */ | |
132 | extern const char *lttng_event_expr_channel_context_field_get_name( | |
133 | const struct lttng_event_expr *expr); | |
134 | ||
135 | /* | |
136 | * Creates an application-specific context field expression for the | |
137 | * application-specific context field provided by the provider named | |
138 | * `provider_name` and having the type named `type_name`. | |
139 | * | |
140 | * Returns `NULL` if: | |
141 | * | |
142 | * * There's a memory error. | |
143 | * * `provider_name` is `NULL`. | |
144 | * * `type_name` is `NULL`. | |
145 | */ | |
146 | extern struct lttng_event_expr * | |
147 | lttng_event_expr_app_specific_context_field_create( | |
148 | const char *provider_name, const char *type_name); | |
149 | ||
150 | /* | |
151 | * Returns the provider name of the application-specific context field | |
152 | * expression `expr`, or `NULL` if: | |
153 | * | |
154 | * * `expr` is `NULL`. | |
155 | * * The type of `expr` is not | |
156 | * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. | |
157 | */ | |
158 | extern const char * | |
159 | lttng_event_expr_app_specific_context_field_get_provider_name( | |
160 | const struct lttng_event_expr *expr); | |
161 | ||
162 | /* | |
163 | * Returns the type name of the application-specific context field | |
164 | * expression `expr`, or `NULL` if: | |
165 | * | |
166 | * * `expr` is `NULL`. | |
167 | * * The type of `expr` is not | |
168 | * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. | |
169 | */ | |
170 | extern const char * | |
171 | lttng_event_expr_app_specific_context_field_get_type_name( | |
172 | const struct lttng_event_expr *expr); | |
173 | ||
174 | /* | |
175 | * Creates an array field element expression for the parent array field | |
176 | * `array_field_expr` (transfering the ownership) and the index `index`. | |
177 | * | |
178 | * Returns `NULL` if: | |
179 | * | |
180 | * * There's a memory error. | |
181 | * * `array_field_expr` is `NULL`. | |
182 | * * `array_field_expr` is not a locator expression, that is, its type | |
183 | * is not one of: | |
184 | * | |
185 | * * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD` | |
186 | * * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD` | |
187 | * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD` | |
188 | * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT` | |
189 | */ | |
190 | extern struct lttng_event_expr *lttng_event_expr_array_field_element_create( | |
191 | struct lttng_event_expr *array_field_expr, | |
192 | unsigned int index); | |
193 | ||
194 | /* | |
195 | * Returns the parent array field expression of the array field element | |
196 | * expression `expr`, or `NULL` if: | |
197 | * | |
198 | * * `expr` is `NULL`. | |
199 | * * The type of `expr` is not | |
200 | * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`. | |
201 | */ | |
202 | extern const struct lttng_event_expr * | |
203 | lttng_event_expr_array_field_element_get_parent_expr( | |
204 | const struct lttng_event_expr *expr); | |
205 | ||
206 | /* | |
207 | * Sets `*index` to the index of the array field element expression | |
208 | * `expr`. | |
209 | * | |
210 | * Returns: | |
211 | * | |
212 | * `LTTNG_EVENT_EXPR_STATUS_OK`: | |
213 | * Success. | |
214 | * | |
215 | * `LTTNG_EVENT_EXPR_STATUS_INVALID`: | |
216 | * * `expr` is `NULL`. | |
217 | * * The type of `expr` is not | |
218 | * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`. | |
219 | * * `index` is `NULL`. | |
220 | */ | |
221 | extern enum lttng_event_expr_status | |
222 | lttng_event_expr_array_field_element_get_index( | |
223 | const struct lttng_event_expr *expr, unsigned int *index); | |
224 | ||
225 | /* | |
226 | * Returns whether or not the event expressions `expr_a` and `expr_b` | |
227 | * are equal. | |
228 | * | |
229 | * `expr_a` and `expr_b` can be `NULL`. | |
230 | */ | |
231 | extern bool lttng_event_expr_is_equal(const struct lttng_event_expr *expr_a, | |
232 | const struct lttng_event_expr *expr_b); | |
233 | ||
234 | /* | |
235 | * Destroys the event expression `expr` if not `NULL`. | |
236 | */ | |
237 | extern void lttng_event_expr_destroy(struct lttng_event_expr *expr); | |
238 | ||
239 | #ifdef __cplusplus | |
240 | } | |
241 | #endif | |
242 | ||
243 | #endif /* LTTNG_EVENT_EXPR_H */ |