epan/tvbparse.h

   1 /** @file
   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 "ws_symbol_export.h"
  56
  57 typedef struct _tvbparse_elem_t tvbparse_elem_t;
  58 typedef struct _tvbparse_wanted_t tvbparse_wanted_t;
  59 typedef 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  */
  74 typedef void (*tvbparse_action_t)(void* tvbparse_data, const void* wanted_data, struct _tvbparse_elem_t* elem);
  75
  76 typedef int (*tvbparse_condition_t)
  77 (tvbparse_t*, const int,
  78  const tvbparse_wanted_t*,
  79  tvbparse_elem_t**);
  80
  81
  82 typedef 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
  89 struct _tvbparse_wanted_t {
  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 */
 130 struct _tvbparse_t {
 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 */
 142 struct _tvbparse_elem_t {
 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  */
 180 WS_DLL_PUBLIC
 181 tvbparse_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  */
 193 WS_DLL_PUBLIC
 194 tvbparse_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  */
 208 WS_DLL_PUBLIC
 209 tvbparse_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  */
 226 WS_DLL_PUBLIC
 227 tvbparse_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  */
 241 WS_DLL_PUBLIC
 242 tvbparse_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  */
 254 WS_DLL_PUBLIC
 255 tvbparse_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  */
 277 WS_DLL_PUBLIC
 278 tvbparse_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  */
 294 WS_DLL_PUBLIC
 295 tvbparse_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  */
 304 WS_DLL_PUBLIC
 305 tvbparse_wanted_t* tvbparse_hashed(const int id,
 306                                    const void* data,
 307                                    tvbparse_action_t before_cb,
 308                                    tvbparse_action_t after_cb,
 309                                    tvbparse_wanted_t* key,
 310                                    tvbparse_wanted_t* other,
 311                                    ...);
 312
 313 WS_DLL_PUBLIC
 314 void 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  */
 326 WS_DLL_PUBLIC
 327 tvbparse_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  */
 341 WS_DLL_PUBLIC
 342 tvbparse_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  */
 360 WS_DLL_PUBLIC
 361 tvbparse_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  */
 369 WS_DLL_PUBLIC
 370 tvbparse_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  */
 381 WS_DLL_PUBLIC
 382 void 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  */
 397 WS_DLL_PUBLIC
 398 tvbparse_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 */
 406 WS_DLL_PUBLIC
 407 bool tvbparse_reset(tvbparse_t* tt, const int offset, int len);
 408
 409 WS_DLL_PUBLIC
 410 unsigned tvbparse_curr_offset(tvbparse_t* tt);
 411 unsigned 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  */
 421 WS_DLL_PUBLIC
 422 bool 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  */
 431 WS_DLL_PUBLIC
 432 tvbparse_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  */
 440 WS_DLL_PUBLIC
 441 tvbparse_elem_t* tvbparse_find(tvbparse_t* tt,
 442                                const tvbparse_wanted_t* wanted);
 443
 444
 445 WS_DLL_PUBLIC
 446 void tvbparse_tree_add_elem(proto_tree* tree, tvbparse_elem_t* curr);
 447
 448 #endif