doc/README.display_filter

   1 $Id$
   2
   3 XXX - move this file to epan?
   4
   5 1. How the Display Filter Engine works.
   6
   7 code:
   8 epan/dfilter/* - the display filter engine, including
   9                 scanner, parser, syntax-tree semantics checker, DFVM bytecode
  10                 generator, and DFVM engine.
  11 epan/ftypes/* - the definitions of the various FT_* field types.
  12 epan/proto.c   - proto_tree-related routines
  13
  14 1.1 Parsing text.
  15
  16 The scanner/parser pair read the string representing the display filter
  17 and convert it into a very simple syntax tree.  The syntax tree is very
  18 simple in that it is possible that many of the nodes contain unparsed
  19 chunks of text from the display filter.
  20
  21 1.1 Enhancing the syntax tree.
  22
  23 The semantics of the simple syntax tree are checked to make sure that
  24 the fields that are being compared are being compared to appropriate
  25 values.  For example, if a field is an integer, it can't be compared to
  26 a string, unless a value_string has been defined for that field.
  27
  28 During the process of checking the semantics, the simple syntax tree is
  29 fleshed out and no longer contains nodes with unparsed information.  The
  30 syntax tree is no longer in its simple form, but in its complete form.
  31
  32 1.2 Converting to DFVM bytecode.
  33
  34 The syntax tree is analyzed to create a sequence of bytecodes in the
  35 "DFVM" language.  "DFVM" stands for Display Filter Virtual Machine.  The
  36 DFVM is similar in spirit, but not in definition, to the BPF VM that
  37 libpcap uses to analyze packets.
  38
  39 A virtual bytecode is created and used so that the actual process of
  40 filtering packets will be fast.  That is, it should be faster to process
  41 a list of VM bytecodes than to attempt to filter packets directly from
  42 the syntax tree.  (heh...  no measurement has been made to support this
  43 supposition)
  44
  45 1.3 Filtering.
  46
  47 Once the DFVM bytecode has been produced, it's a simple matter of
  48 running the DFVM engine against the proto_tree from the packet
  49 dissection, using the DFVM bytecodes as instructions.  If the DFVM
  50 bytecode is known before packet dissection occurs, the
  51 proto_tree-related code can be "primed" to store away pointers to
  52 field_info structures that are interesting to the display filter.  This
  53 makes lookup of those field_info structures during the filtering process
  54 faster.
  55
  56 1.4 Display Filter Functions.
  57
  58 You define a display filter function by adding an entry to
  59 the df_functions table in epan/dfilter/dfunctions.c. The record struct
  60 is defined in dfunctions.h, and shown here:
  61
  62 typedef struct {
  63     char            *name;
  64     DFFuncType      function;
  65     ftenum_t        retval_ftype;
  66     guint           min_nargs;
  67     guint           max_nargs;
  68     DFSemCheckType  semcheck_param_function;
  69 } df_func_def_t;
  70
  71 name - the name of the function; this is how the user will call your
  72     function in the display filter language
  73
  74 function - this is the run-time processing of your function.
  75
  76 retval_ftype - what type of FT_* type does your function return?
  77
  78 min_nargs - minimum number of arguments your function accepts
  79 max_nargs - maximum number of arguments your function accepts
  80
  81 semcheck_param_function - called during the semantic check of the
  82     display filter string.
  83
  84 DFFuncType function
  85 -------------------
  86 typedef gboolean (*DFFuncType)(GList *arg1list, GList *arg2list, GList **retval);
  87
  88 The return value of your function is a gboolean; TRUE if processing went fine,
  89 or FALSE if there was some sort of exception.
  90
  91 For now, display filter functions can accept a maximum of 2 arguments.
  92 The "arg1list" parameter is the GList for the first argument. The
  93 'arg2list" parameter is the GList for the second argument. All arguments
  94 to display filter functions are lists. This is because in the display
  95 filter language a protocol field may have multiple instances. For example,
  96 a field like "ip.addr" will exist more than once in a single frame. So
  97 when the user invokes this display filter:
  98
  99     somefunc(ip.addr) == TRUE
 100
 101 even though "ip.addr" is a single argument, the "somefunc" function will
 102 receive a GList of *all* the values of "ip.addr" in the frame.
 103
 104 Similarly, the return value of the function needs to be a GList, since all
 105 values in the display filter language are lists. The GList** retval argument
 106 is passed to your function so you can set the pointer to your return value.
 107
 108 DFSemCheckType
 109 --------------
 110 typedef void (*DFSemCheckType)(int param_num, stnode_t *st_node);
 111
 112 For each parameter in the syntax tree, this function will be called.
 113 "param_num" will indicate the number of the parameter, starting with 0.
 114 The "stnode_t" is the syntax-tree node representing that parameter.
 115 If everything is okay with the value of that stnode_t, your function
 116 does nothing --- it merely returns. If something is wrong, however,
 117 it should THROW a TypeError exception.