Wireshark  2.9.0-477-g68ec514b
The Wireshark network protocol analyzer
tvbparse.h
1 /* tvbparse.h
2  *
3  * an API for text tvb parsers
4  *
5  * Copyright 2005, Luis E. Garcia Ontanon <luis@ontanon.org>
6  *
7  * Wireshark - Network traffic analyzer
8  * By Gerald Combs <gerald@wireshark.org>
9  * Copyright 1998 Gerald Combs
10  *
11  * SPDX-License-Identifier: GPL-2.0-or-later
12  */
13 
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 <glib.h>
56 #include "ws_symbol_export.h"
57 
58 typedef struct _tvbparse_elem_t tvbparse_elem_t;
60 typedef struct _tvbparse_t tvbparse_t;
61 
62 
63 /*
64  * a callback function to be called before or after an element has been
65  * successfuly extracted.
66  *
67  * Note that if the token belongs to a composed token the callbacks of the
68  * components won't be called unless the composed token is successfully
69  * extracted.
70  *
71  * tvbparse_data: the private data of the parser
72  * wanted_data: the private data of the wanted element
73  * elem: the extracted element
74  */
75 typedef void (*tvbparse_action_t)(void* tvbparse_data, const void* wanted_data, struct _tvbparse_elem_t* elem);
76 
77 typedef int (*tvbparse_condition_t)
78 (tvbparse_t*, const int,
79  const tvbparse_wanted_t*,
80  tvbparse_elem_t**);
81 
82 
83 typedef enum {
84  TP_UNTIL_INCLUDE, /* last elem is included, its span is spent by the parser */
85  TP_UNTIL_SPEND, /* last elem is not included, but its span is spent by the parser */
86  TP_UNTIL_LEAVE /* last elem is not included, neither its span is spent by the parser */
87 } until_mode_t;
88 
89 
91  int id;
92  tvbparse_condition_t condition;
93 
94  union {
95  const gchar* str;
96  struct _tvbparse_wanted_t** handle;
97  struct {
98  union {
99  gint64 i;
100  guint64 u;
101  gdouble f;
102  } value;
103  gboolean (*comp)(void*,const void*);
104  void* (*extract)(tvbuff_t*,guint);
105  } number;
106  enum ftenum ftenum;
107  struct {
108  until_mode_t mode;
109  const tvbparse_wanted_t* subelem;
110  } until;
111  struct {
112  wmem_map_t* table;
113  struct _tvbparse_wanted_t* key;
114  struct _tvbparse_wanted_t* other;
115  } hash;
116  GPtrArray* elems;
117  const tvbparse_wanted_t* subelem;
118  void* p;
119  } control;
120 
121  int len;
122 
123  guint min;
124  guint max;
125 
126  const void* data;
127 
128  tvbparse_action_t before;
129  tvbparse_action_t after;
130 };
131 
132 /* an instance of a per packet parser */
133 struct _tvbparse_t {
134  tvbuff_t* tvb;
135  int offset;
136  int end_offset;
137  void* data;
138  const tvbparse_wanted_t* ignore;
139  int recursion_depth;
140 };
141 
142 
143 /* a matching token returned by either tvbparser_get or tvb_parser_find */
145  int id;
146 
147  tvbuff_t* tvb;
148  int offset;
149  int len;
150 
151  void* data;
152 
153  struct _tvbparse_elem_t* sub;
154 
155  struct _tvbparse_elem_t* next;
156  struct _tvbparse_elem_t* last;
157 
158  const tvbparse_wanted_t* wanted;
159 };
160 
161 
162 /*
163  * definition of wanted token types
164  *
165  * the following functions define the tokens we will be able to look for in a tvb
166  * common parameters are:
167  *
168  * id: an arbitrary id that will be copied to the eventual token (don't use 0)
169  * private_data: persistent data to be passed to the callback action (wanted_data)
170  * before_cb: an callback function to be called before those of the subelements
171  * after_cb: an callback function to be called after those of the subelements
172  */
173 
174 
175 /*
176  * a char element.
177  *
178  * When looked for it returns a simple element one character long if the char
179  * at the current offset matches one of the the needles.
180  */
181 WS_DLL_PUBLIC
182 tvbparse_wanted_t* tvbparse_char(const int id,
183  const gchar* needles,
184  const void* private_data,
185  tvbparse_action_t before_cb,
186  tvbparse_action_t after_cb);
187 
188 /*
189  * a not_char element.
190  *
191  * When looked for it returns a simple element one character long if the char
192  * at the current offset does not match one of the the needles.
193  */
194 WS_DLL_PUBLIC
195 tvbparse_wanted_t* tvbparse_not_char(const int id,
196  const gchar* needle,
197  const void* private_data,
198  tvbparse_action_t before_cb,
199  tvbparse_action_t after_cb);
200 
201 /*
202  * a chars element
203  *
204  * When looked for it returns a simple element one or more characters long if
205  * one or more char(s) starting from the current offset match one of the needles.
206  * An element will be returned if at least min_len chars are given (1 if it's 0)
207  * It will get at most max_len chars or as much as it can if max_len is 0.
208  */
209 WS_DLL_PUBLIC
210 tvbparse_wanted_t* tvbparse_chars(const int id,
211  const guint min_len,
212  const guint max_len,
213  const gchar* needles,
214  const void* private_data,
215  tvbparse_action_t before_cb,
216  tvbparse_action_t after_cb);
217 
218 /*
219  * a not_chars element
220  *
221  * When looked for it returns a simple element one or more characters long if
222  * one or more char(s) starting from the current offset do not match one of the
223  * needles.
224  * An element will be returned if at least min_len chars are given (1 if it's 0)
225  * It will get at most max_len chars or as much as it can if max_len is 0.
226  */
227 WS_DLL_PUBLIC
228 tvbparse_wanted_t* tvbparse_not_chars(const int id,
229  const guint min_len,
230  const guint max_len,
231  const gchar* needles,
232  const void* private_data,
233  tvbparse_action_t before_cb,
234  tvbparse_action_t after_cb);
235 
236 /*
237  * a string element
238  *
239  * When looked for it returns a simple element if we have the given string at
240  * the current offset
241  */
242 WS_DLL_PUBLIC
243 tvbparse_wanted_t* tvbparse_string(const int id,
244  const gchar* string,
245  const void* private_data,
246  tvbparse_action_t before_cb,
247  tvbparse_action_t after_cb);
248 
249 /*
250  * casestring
251  *
252  * When looked for it returns a simple element if we have a matching string at
253  * the current offset
254  */
255 WS_DLL_PUBLIC
256 tvbparse_wanted_t* tvbparse_casestring(const int id,
257  const gchar* str,
258  const void* data,
259  tvbparse_action_t before_cb,
260  tvbparse_action_t after_cb);
261 
262 /*
263  * until
264  *
265  * When looked for it returns a simple element containing all the characters
266  * found until the first match of the ending element if the ending element is
267  * found.
268  *
269  * When looking for until elements it calls tvbparse_find so it can be very slow.
270  *
271  * It won't have a subelement, the ending's callbacks won't get called.
272  */
273 
274 /*
275  * op_mode values determine how the terminating element and the current offset
276  * of the parser are handled
277  */
278 WS_DLL_PUBLIC
279 tvbparse_wanted_t* tvbparse_until(const int id,
280  const void* private_data,
281  tvbparse_action_t before_cb,
282  tvbparse_action_t after_cb,
283  const tvbparse_wanted_t* ending,
284  until_mode_t until_mode);
285 
286 /*
287  * one_of
288  *
289  * When looked for it will try to match to the given candidates and return a
290  * composed element whose subelement is the first match.
291  *
292  * The list of candidates is terminated with a NULL
293  *
294  */
295 WS_DLL_PUBLIC
296 tvbparse_wanted_t* tvbparse_set_oneof(const int id,
297  const void* private_data,
298  tvbparse_action_t before_cb,
299  tvbparse_action_t after_cb,
300  ...);
301 
302 /*
303  * hashed
304  */
305 WS_DLL_PUBLIC
306 tvbparse_wanted_t* tvbparse_hashed(const int id,
307  const void* data,
308  tvbparse_action_t before_cb,
309  tvbparse_action_t after_cb,
310  tvbparse_wanted_t* key,
311  tvbparse_wanted_t* other,
312  ...);
313 
314 WS_DLL_PUBLIC
315 void tvbparse_hashed_add(tvbparse_wanted_t* w, ...);
316 
317 /*
318  * sequence
319  *
320  * When looked for it will try to match in order all the given candidates. If
321  * every candidate is found in the given order it will return a composed
322  * element whose subelements are the matcheed elemets.
323  *
324  * The list of candidates is terminated with a NULL.
325  *
326  */
327 WS_DLL_PUBLIC
328 tvbparse_wanted_t* tvbparse_set_seq(const int id,
329  const void* private_data,
330  tvbparse_action_t before_cb,
331  tvbparse_action_t after_cb,
332  ...);
333 
334 /*
335  * some
336  *
337  * When looked for it will try to match the given candidate at least min times
338  * and at most max times. If the given candidate is matched at least min times
339  * a composed element is returned.
340  *
341  */
342 WS_DLL_PUBLIC
343 tvbparse_wanted_t* tvbparse_some(const int id,
344  const guint min,
345  const guint max,
346  const void* private_data,
347  tvbparse_action_t before_cb,
348  tvbparse_action_t after_cb,
349  const tvbparse_wanted_t* wanted);
350 
351 #define tvbparse_one_or_more(id, private_data, before_cb, after_cb, wanted)\
352  tvbparse_some(id, 1, G_MAXINT, private_data, before_cb, after_cb, wanted)
353 
354 
355 /*
356  * handle
357  *
358  * this is a pointer to a pointer to a wanted element (that might have not
359  * been initialized yet) so that recursive structures
360  */
361 WS_DLL_PUBLIC
362 tvbparse_wanted_t* tvbparse_handle(tvbparse_wanted_t** handle);
363 
364 #if 0
365 
366 enum ft_cmp_op {
367  TVBPARSE_CMP_GT,
368  TVBPARSE_CMP_GE,
369  TVBPARSE_CMP_EQ,
370  TVBPARSE_CMP_NE,
371  TVBPARSE_CMP_LE,
372  TVBPARSE_CMP_LT
373 };
374 
375 /* not yet tested */
376 tvbparse_wanted_t* tvbparse_ft(int id,
377  const void* data,
378  tvbparse_action_t before_cb,
379  tvbparse_action_t after_cb,
380  enum ftenum ftenum);
381 
382 /* not yet tested */
383 tvbparse_wanted_t* tvbparse_end_of_buffer(int id,
384  const void* data,
385  tvbparse_action_t before_cb,
386  tvbparse_action_t after_cb);
387 /* not yet tested */
388 tvbparse_wanted_t* tvbparse_ft_numcmp(int id,
389  const void* data,
390  tvbparse_action_t before_cb,
391  tvbparse_action_t after_cb,
392  enum ftenum ftenum,
393  int little_endian,
394  enum ft_cmp_op ft_cmp_op,
395  ... );
396 
397 #endif
398 
399 /* quoted
400  * this is a composed candidate, that will try to match a quoted string
401  * (included the quotes) including into it every escaped quote.
402  *
403  * C strings are matched with tvbparse_quoted(-1,NULL,NULL,NULL,"\"","\\")
404  */
405 WS_DLL_PUBLIC
406 tvbparse_wanted_t* tvbparse_quoted(const int id,
407  const void* data,
408  tvbparse_action_t before_cb,
409  tvbparse_action_t after_cb,
410  const char quote,
411  const char escape);
412 
413 /*
414  * a helper callback for quoted strings that will shrink the token to contain
415  * only the string andnot the quotes
416  */
417 WS_DLL_PUBLIC
418 void tvbparse_shrink_token_cb(void* tvbparse_data,
419  const void* wanted_data,
420  tvbparse_elem_t* tok);
421 
422 
423 
424 
425 /* initialize the parser (at every packet)
426  * tvb: what are we parsing?
427  * offset: from where
428  * len: for how many bytes
429  * private_data: will be passed to the action callbacks
430  * ignore: a wanted token type to be ignored (the associated cb WILL be called when it matches)
431  */
432 WS_DLL_PUBLIC
433 tvbparse_t* tvbparse_init(tvbuff_t* tvb,
434  const int offset,
435  int len,
436  void* private_data,
437  const tvbparse_wanted_t* ignore);
438 
439 /* reset the parser */
440 WS_DLL_PUBLIC
441 gboolean tvbparse_reset(tvbparse_t* tt, const int offset, int len);
442 
443 WS_DLL_PUBLIC
444 guint tvbparse_curr_offset(tvbparse_t* tt);
445 guint tvbparse_len_left(tvbparse_t* tt);
446 
447 
448 
449 /*
450  * This will look for the wanted token at the current offset or after any given
451  * number of ignored tokens returning FALSE if there's no match or TRUE if there
452  * is a match.
453  * The parser will be left in its original state and no callbacks will be called.
454  */
455 WS_DLL_PUBLIC
456 gboolean tvbparse_peek(tvbparse_t* tt,
457  const tvbparse_wanted_t* wanted);
458 
459 /*
460  * This will look for the wanted token at the current offset or after any given
461  * number of ignored tokens returning NULL if there's no match.
462  * if there is a match it will set the offset of the current parser after
463  * the end of the token
464  */
465 WS_DLL_PUBLIC
466 tvbparse_elem_t* tvbparse_get(tvbparse_t* tt,
467  const tvbparse_wanted_t* wanted);
468 
469 /*
470  * Like tvbparse_get but this will look for a wanted token even beyond the
471  * current offset.
472  * This function is slow.
473  */
474 WS_DLL_PUBLIC
475 tvbparse_elem_t* tvbparse_find(tvbparse_t* tt,
476  const tvbparse_wanted_t* wanted);
477 
478 
479 WS_DLL_PUBLIC
480 void tvbparse_tree_add_elem(proto_tree* tree, tvbparse_elem_t* curr);
481 
482 #endif
Definition: tvbparse.h:144
Definition: conditions.c:23
Definition: wmem_map.c:44
Definition: tvbparse.h:90
Definition: tvbparse.h:133
Definition: tvbuff-int.h:35
Definition: proto.h:759