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