Wireshark 4.5.0
The Wireshark network protocol analyzer
Loading...
Searching...
No Matches
tvbparse.h
Go to the documentation of this file.
1
14/*
15 The intention behind this is to ease the writing of dissectors that have to
16 parse text without the need of writing into buffers.
17
18 It was originally written to avoid using lex and yacc for the xml dissector.
19
20 the parser is able to look for wanted elements these can be:
21
22 simple tokens:
23 - a char out of a string of needles
24 - a char not belonging to a string of needles
25 - a sequence of chars that belong to a set of chars
26 - a sequence of chars that do not belong to a set of chars
27 - a string
28 - a caseless string
29 - all the characters up to a certain wanted element (included or excluded)
30
31 composed elements:
32 - one of a given group of wanted elements
33 - a sequence of wanted elements
34 - some (at least one) instances of a wanted element
35
36 Once a wanted element is successfully extracted, by either tvbparse_get or
37 tvbparse_find, the parser will invoke a given callback
38 before and another one after every of its component's subelement's callbacks
39 are being called.
40
41 If tvbparse_get or tvbparse_find fail to extract the wanted element the
42 subelements callbacks are not going to be invoked.
43
44 The wanted elements are instantiated once by the proto_register_xxx function.
45
46 The parser is instantiated for every packet and it mantains its state.
47
48 The element's data is destroyed before the next packet is dissected.
49 */
50
51#ifndef _TVB_PARSE_H_
52#define _TVB_PARSE_H_
53
54#include <epan/tvbuff.h>
55#include "ws_symbol_export.h"
56
59typedef struct _tvbparse_t tvbparse_t;
60
61
62/*
63 * a callback function to be called before or after an element has been
64 * successfuly extracted.
65 *
66 * Note that if the token belongs to a composed token the callbacks of the
67 * components won't be called unless the composed token is successfully
68 * extracted.
69 *
70 * tvbparse_data: the private data of the parser
71 * wanted_data: the private data of the wanted element
72 * elem: the extracted element
73 */
74typedef void (*tvbparse_action_t)(void* tvbparse_data, const void* wanted_data, struct _tvbparse_elem_t* elem);
75
76typedef int (*tvbparse_condition_t)
77(tvbparse_t*, const int,
78 const tvbparse_wanted_t*,
80
81
82typedef enum {
83 TP_UNTIL_INCLUDE, /* last elem is included, its span is spent by the parser */
84 TP_UNTIL_SPEND, /* last elem is not included, but its span is spent by the parser */
85 TP_UNTIL_LEAVE /* last elem is not included, neither its span is spent by the parser */
86} until_mode_t;
87
88
90 int id;
91 tvbparse_condition_t condition;
92
93 union {
94 const char* str;
95 struct _tvbparse_wanted_t** handle;
96 struct {
97 union {
98 int64_t i;
99 uint64_t u;
100 double f;
101 } value;
102 } number;
103 enum ftenum ftenum;
104 struct {
105 until_mode_t mode;
106 const tvbparse_wanted_t* subelem;
107 } until;
108 struct {
109 wmem_map_t* table;
110 struct _tvbparse_wanted_t* key;
111 struct _tvbparse_wanted_t* other;
112 } hash;
113 GPtrArray* elems;
114 const tvbparse_wanted_t* subelem;
115 void* p;
116 } control;
117
118 int len;
119
120 unsigned min;
121 unsigned max;
122
123 const void* data;
124
125 tvbparse_action_t before;
126 tvbparse_action_t after;
127};
128
129/* an instance of a per packet parser */
131 wmem_allocator_t* scope;
132 tvbuff_t* tvb;
133 int offset;
134 int end_offset;
135 void* data;
136 const tvbparse_wanted_t* ignore;
137 int recursion_depth;
138};
139
140
141/* a matching token returned by either tvbparser_get or tvb_parser_find */
143 int id;
144
145 tvbparse_t* parser;
146 tvbuff_t* tvb;
147 int offset;
148 int len;
149
150 void* data;
151
152 struct _tvbparse_elem_t* sub;
153
154 struct _tvbparse_elem_t* next;
155 struct _tvbparse_elem_t* last;
156
157 const tvbparse_wanted_t* wanted;
158};
159
160
161/*
162 * definition of wanted token types
163 *
164 * the following functions define the tokens we will be able to look for in a tvb
165 * common parameters are:
166 *
167 * id: an arbitrary id that will be copied to the eventual token (don't use 0)
168 * private_data: persistent data to be passed to the callback action (wanted_data)
169 * before_cb: an callback function to be called before those of the subelements
170 * after_cb: an callback function to be called after those of the subelements
171 */
172
173
174/*
175 * a char element.
176 *
177 * When looked for it returns a simple element one character long if the char
178 * at the current offset matches one of the needles.
179 */
180WS_DLL_PUBLIC
181tvbparse_wanted_t* tvbparse_char(const int id,
182 const char* needles,
183 const void* private_data,
184 tvbparse_action_t before_cb,
185 tvbparse_action_t after_cb);
186
187/*
188 * a not_char element.
189 *
190 * When looked for it returns a simple element one character long if the char
191 * at the current offset does not match one of the needles.
192 */
193WS_DLL_PUBLIC
194tvbparse_wanted_t* tvbparse_not_char(const int id,
195 const char* needle,
196 const void* private_data,
197 tvbparse_action_t before_cb,
198 tvbparse_action_t after_cb);
199
200/*
201 * a chars element
202 *
203 * When looked for it returns a simple element one or more characters long if
204 * one or more char(s) starting from the current offset match one of the needles.
205 * An element will be returned if at least min_len chars are given (1 if it's 0)
206 * It will get at most max_len chars or as much as it can if max_len is 0.
207 */
208WS_DLL_PUBLIC
209tvbparse_wanted_t* tvbparse_chars(const int id,
210 const unsigned min_len,
211 const unsigned max_len,
212 const char* needles,
213 const void* private_data,
214 tvbparse_action_t before_cb,
215 tvbparse_action_t after_cb);
216
217/*
218 * a not_chars element
219 *
220 * When looked for it returns a simple element one or more characters long if
221 * one or more char(s) starting from the current offset do not match one of the
222 * needles.
223 * An element will be returned if at least min_len chars are given (1 if it's 0)
224 * It will get at most max_len chars or as much as it can if max_len is 0.
225 */
226WS_DLL_PUBLIC
227tvbparse_wanted_t* tvbparse_not_chars(const int id,
228 const unsigned min_len,
229 const unsigned max_len,
230 const char* needles,
231 const void* private_data,
232 tvbparse_action_t before_cb,
233 tvbparse_action_t after_cb);
234
235/*
236 * a string element
237 *
238 * When looked for it returns a simple element if we have the given string at
239 * the current offset
240 */
241WS_DLL_PUBLIC
242tvbparse_wanted_t* tvbparse_string(const int id,
243 const char* string,
244 const void* private_data,
245 tvbparse_action_t before_cb,
246 tvbparse_action_t after_cb);
247
248/*
249 * casestring
250 *
251 * When looked for it returns a simple element if we have a matching string at
252 * the current offset
253 */
254WS_DLL_PUBLIC
255tvbparse_wanted_t* tvbparse_casestring(const int id,
256 const char* str,
257 const void* data,
258 tvbparse_action_t before_cb,
259 tvbparse_action_t after_cb);
260
261/*
262 * until
263 *
264 * When looked for it returns a simple element containing all the characters
265 * found until the first match of the ending element if the ending element is
266 * found.
267 *
268 * When looking for until elements it calls tvbparse_find so it can be very slow.
269 *
270 * It won't have a subelement, the ending's callbacks won't get called.
271 */
272
273/*
274 * op_mode values determine how the terminating element and the current offset
275 * of the parser are handled
276 */
277WS_DLL_PUBLIC
278tvbparse_wanted_t* tvbparse_until(const int id,
279 const void* private_data,
280 tvbparse_action_t before_cb,
281 tvbparse_action_t after_cb,
282 const tvbparse_wanted_t* ending,
283 until_mode_t until_mode);
284
285/*
286 * one_of
287 *
288 * When looked for it will try to match to the given candidates and return a
289 * composed element whose subelement is the first match.
290 *
291 * The list of candidates is terminated with a NULL
292 *
293 */
294WS_DLL_PUBLIC
295tvbparse_wanted_t* tvbparse_set_oneof(const int id,
296 const void* private_data,
297 tvbparse_action_t before_cb,
298 tvbparse_action_t after_cb,
299 ...);
300
301/*
302 * hashed
303 */
304WS_DLL_PUBLIC
305tvbparse_wanted_t* tvbparse_hashed(const int id,
306 const void* data,
307 tvbparse_action_t before_cb,
308 tvbparse_action_t after_cb,
310 tvbparse_wanted_t* other,
311 ...);
312
313WS_DLL_PUBLIC
314void tvbparse_hashed_add(tvbparse_wanted_t* w, ...);
315
316/*
317 * sequence
318 *
319 * When looked for it will try to match in order all the given candidates. If
320 * every candidate is found in the given order it will return a composed
321 * element whose subelements are the matched elements.
322 *
323 * The list of candidates is terminated with a NULL.
324 *
325 */
326WS_DLL_PUBLIC
327tvbparse_wanted_t* tvbparse_set_seq(const int id,
328 const void* private_data,
329 tvbparse_action_t before_cb,
330 tvbparse_action_t after_cb,
331 ...);
332
333/*
334 * some
335 *
336 * When looked for it will try to match the given candidate at least min times
337 * and at most max times. If the given candidate is matched at least min times
338 * a composed element is returned.
339 *
340 */
341WS_DLL_PUBLIC
342tvbparse_wanted_t* tvbparse_some(const int id,
343 const unsigned min,
344 const unsigned max,
345 const void* private_data,
346 tvbparse_action_t before_cb,
347 tvbparse_action_t after_cb,
348 const tvbparse_wanted_t* wanted);
349
350#define tvbparse_one_or_more(id, private_data, before_cb, after_cb, wanted)\
351 tvbparse_some(id, 1, INT_MAX, private_data, before_cb, after_cb, wanted)
352
353
354/*
355 * handle
356 *
357 * this is a pointer to a pointer to a wanted element (that might have not
358 * been initialized yet) so that recursive structures
359 */
360WS_DLL_PUBLIC
361tvbparse_wanted_t* tvbparse_handle(tvbparse_wanted_t** handle);
362
363/* quoted
364 * this is a composed candidate, that will try to match a quoted string
365 * (included the quotes) including into it every escaped quote.
366 *
367 * C strings are matched with tvbparse_quoted(-1,NULL,NULL,NULL,"\"","\\")
368 */
369WS_DLL_PUBLIC
370tvbparse_wanted_t* tvbparse_quoted(const int id,
371 const void* data,
372 tvbparse_action_t before_cb,
373 tvbparse_action_t after_cb,
374 const char quote,
375 const char escape);
376
377/*
378 * a helper callback for quoted strings that will shrink the token to contain
379 * only the string andnot the quotes
380 */
381WS_DLL_PUBLIC
382void tvbparse_shrink_token_cb(void* tvbparse_data,
383 const void* wanted_data,
384 tvbparse_elem_t* tok);
385
386
387
388
389/* initialize the parser (at every packet)
390 * scope: memory scope/pool
391 * tvb: what are we parsing?
392 * offset: from where
393 * len: for how many bytes
394 * private_data: will be passed to the action callbacks
395 * ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)
396 */
397WS_DLL_PUBLIC
398tvbparse_t* tvbparse_init(wmem_allocator_t *scope,
399 tvbuff_t* tvb,
400 const int offset,
401 int len,
402 void* private_data,
403 const tvbparse_wanted_t* ignore);
404
405/* reset the parser */
406WS_DLL_PUBLIC
407bool tvbparse_reset(tvbparse_t* tt, const int offset, int len);
408
409WS_DLL_PUBLIC
410unsigned tvbparse_curr_offset(tvbparse_t* tt);
411unsigned tvbparse_len_left(tvbparse_t* tt);
412
413
414
415/*
416 * This will look for the wanted token at the current offset or after any given
417 * number of ignored tokens returning false if there's no match or true if there
418 * is a match.
419 * The parser will be left in its original state and no callbacks will be called.
420 */
421WS_DLL_PUBLIC
422bool tvbparse_peek(tvbparse_t* tt,
423 const tvbparse_wanted_t* wanted);
424
425/*
426 * This will look for the wanted token at the current offset or after any given
427 * number of ignored tokens returning NULL if there's no match.
428 * if there is a match it will set the offset of the current parser after
429 * the end of the token
430 */
431WS_DLL_PUBLIC
432tvbparse_elem_t* tvbparse_get(tvbparse_t* tt,
433 const tvbparse_wanted_t* wanted);
434
435/*
436 * Like tvbparse_get but this will look for a wanted token even beyond the
437 * current offset.
438 * This function is slow.
439 */
440WS_DLL_PUBLIC
441tvbparse_elem_t* tvbparse_find(tvbparse_t* tt,
442 const tvbparse_wanted_t* wanted);
443
444
445WS_DLL_PUBLIC
446void tvbparse_tree_add_elem(proto_tree* tree, tvbparse_elem_t* curr);
447
448#endif
Definition proto.h:901
Definition tvbparse.h:142
Definition tvbparse.h:130
Definition tvbparse.h:89
Definition wmem_allocator.h:27
Definition wmem_map.c:44
Definition tvbuff-int.h:35