Add some info about extended value string to section 1.7.1
[obnox/wireshark/wip.git] / 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.