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