add new function tvb_get_ephemeral_stringz()
[obnox/wireshark/wip.git] / doc / README.developer
1 $Id$
2
3 This file is a HOWTO for Ethereal developers. It describes how to start coding
4 a Ethereal protocol dissector and the use some of the important functions and
5 variables.
6
7 1. Setting up your protocol dissector code.
8
9 This section provides skeleton code for a protocol dissector. It also explains
10 the basic functions needed to enter values in the traffic summary columns,
11 add to the protocol tree, and work with registered header fields.
12
13 1.1 Code style.
14
15 1.1.1 Portability.
16
17 Ethereal runs on many platforms, and can be compiled with a number of
18 different compilers; here are some rules for writing code that will work
19 on multiple platforms.
20
21 Don't use C++-style comments (comments beginning with "//" and running
22 to the end of the line); Ethereal's dissectors are written in C, and
23 thus run through C rather than C++ compilers, and not all C compilers
24 support C++-style comments (GCC does, but IBM's C compiler for AIX, for
25 example, doesn't do so by default).
26
27 Don't initialize variables in their declaration with non-constant
28 values. Not all compilers support this. E.g. don't use
29         guint32 i = somearray[2];
30 use
31         guint32 i;
32         i = somearray[2];
33 instead.
34
35 Don't use zero-length arrays; not all compilers support them.  If an
36 array would have no members, just leave it out.
37
38 Don't declare variables in the middle of executable code; not all C
39 compilers support that.  Variables should be declared outside a
40 function, or at the beginning of a function or compound statement.
41
42 Don't use "inline"; not all compilers support it.  If you want to have a
43 function be an inline function if the compiler supports it, use
44 G_INLINE_FUNC, which is declared by <glib.h>.  This may not work with
45 functions declared in header files; if it doesn't work, don't declare
46 the function in a header file, even if this requires that you not make
47 it inline on any platform.
48
49 Don't use "uchar", "u_char", "ushort", "u_short", "uint", "u_int",
50 "ulong", "u_long" or "boolean"; they aren't defined on all platforms.
51 If you want an 8-bit unsigned quantity, use "guint8"; if you want an
52 8-bit character value with the 8th bit not interpreted as a sign bit,
53 use "guchar"; if you want a 16-bit unsigned quantity, use "guint16";
54 if you want a 32-bit unsigned quantity, use "guint32"; and if you want
55 an "int-sized" unsigned quantity, use "guint"; if you want a boolean,
56 use "gboolean".  Use "%d", "%u", "%x", and "%o" to print those types;
57 don't use "%ld", "%lu", "%lx", or "%lo", as longs are 64 bits long on
58 many platforms, but "guint32" is 32 bits long.
59
60 Don't use "long" to mean "signed 32-bit integer", and don't use
61 "unsigned long" to mean "unsigned 32-bit integer"; "long"s are 64 bits
62 long on many platforms.  Use "gint32" for signed 32-bit integers and use
63 "guint32" for unsigned 32-bit integers.
64
65 Don't use "long" to mean "signed 64-bit integer" and don't use "unsigned
66 long" to mean "unsigned 64-bit integer"; "long"s are 32 bits long on
67 other many platforms.  Don't use "long long" or "unsigned long long",
68 either, as not all platforms support them; use "gint64" or "guint64",
69 which will be defined as the appropriate types for 64-bit signed and
70 unsigned integers.
71
72 When printing or displaying the values of 64-bit integral data types,
73 don't assume use "%lld", "%llu", "%llx", or "%llo" - not all platforms
74 support "%ll" for printing 64-bit integral data types.  Instead, use
75 PRId64, PRIu64, PRIx64, and PRIo64, for example
76
77     proto_tree_add_text(tree, tvb, offset, 8,
78                         "Sequence Number: %" PRIu64, sequence_number);
79
80 When specifying an integral constant that doesn't fit in 32 bits, don't
81 use "LL" at the end of the constant - not all compilers use "LL" for
82 that.  Instead, put the constant in a call to the "G_GINT64_CONSTANT()"
83 macro, e.g.
84
85         G_GINT64_CONSTANT(11644473600U)
86
87 rather than
88
89         11644473600ULL
90
91 Don't use a label without a statement following it.  For example,
92 something such as
93
94         if (...) {
95
96                 ...
97
98         done:
99         }
100         
101 will not work with all compilers - you have to do
102
103         if (...) {
104
105                 ...
106
107         done:
108                 ;
109         }
110
111 with some statement, even if it's a null statement, after the label.
112
113 Don't use "bzero()", "bcopy()", or "bcmp()"; instead, use the ANSI C
114 routines
115
116         "memset()" (with zero as the second argument, so that it sets
117         all the bytes to zero);
118
119         "memcpy()" or "memmove()" (note that the first and second
120         arguments to "memcpy()" are in the reverse order to the
121         arguments to "bcopy()"; note also that "bcopy()" is typically
122         guaranteed to work on overlapping memory regions, while
123         "memcpy()" isn't, so if you may be copying from one region to a
124         region that overlaps it, use "memmove()", not "memcpy()" - but
125         "memcpy()" might be faster as a result of not guaranteeing
126         correct operation on overlapping memory regions);
127
128         and "memcmp()" (note that "memcmp()" returns 0, 1, or -1, doing
129         an ordered comparison, rather than just returning 0 for "equal"
130         and 1 for "not equal", as "bcmp()" does).
131
132 Not all platforms necessarily have "bzero()"/"bcopy()"/"bcmp()", and
133 those that do might not declare them in the header file on which they're
134 declared on your platform.
135
136 Don't use "index()" or "rindex()"; instead, use the ANSI C equivalents,
137 "strchr()" and "strrchr()".  Not all platforms necessarily have
138 "index()" or "rindex()", and those that do might not declare them in the
139 header file on which they're declared on your platform.
140
141 Don't fetch data from packets by getting a pointer to data in the packet
142 with "tvb_get_ptr()", casting that pointer to a pointer to a structure,
143 and dereferencing that pointer.  That point won't necessarily be aligned
144 on the proper boundary, which can cause crashes on some platforms (even
145 if it doesn't crash on an x86-based PC); furthermore, the data in a
146 packet is not necessarily in the byte order of the machine on which
147 Ethereal is running.  Use the tvbuff routines to extract individual
148 items from the packet, or use "proto_tree_add_item()" and let it extract
149 the items for you.
150
151 Don't use "ntohs()", "ntohl()", "htons()", or "htonl()"; the header
152 files required to define or declare them differ between platforms, and
153 you might be able to get away with not including the appropriate header
154 file on your platform but that might not work on other platforms. 
155 Instead, use "g_ntohs()", "g_ntohl()", "g_htons()", and "g_htonl()";
156 those are declared by <glib.h>, and you'll need to include that anyway,
157 as Ethereal header files that all dissectors must include use stuff from
158 <glib.h>.
159
160 Don't fetch a little-endian value using "tvb_get_ntohs() or
161 "tvb_get_ntohl()" and then using "g_ntohs()", "g_htons()", "g_ntohl()",
162 or "g_htonl()" on the resulting value - the g_ routines in question
163 convert between network byte order (big-endian) and *host* byte order,
164 not *little-endian* byte order; not all machines on which Ethereal runs
165 are little-endian, even though PC's are.  Fetch those values using
166 "tvb_get_letohs()" and "tvb_get_letohl()".
167
168 Don't put a comma after the last element of an enum - some compilers may
169 either warn about it (producing extra noise) or refuse to accept it.
170
171 Don't include <unistd.h> without protecting it with
172
173         #ifdef HAVE_UNISTD_H
174
175                 ...
176
177         #endif
178
179 and, if you're including it to get routines such as "open()", "close()",
180 "read()", and "write()" declared, also include <io.h> if present:
181
182         #ifdef HAVE_IO_H
183         #include <io.h>
184         #endif
185
186 in order to declare the Windows C library routines "_open()",
187 "_close()", "_read()", and "_write()".  Your file must include <glib.h>
188 - which many of the Ethereal header files include, so you might not have
189 to include it explicitly - in order to get "open()", "close()",
190 "read()", "write()", etc. mapped to "_open()", "_close()", "_read()",
191 "_write()", etc..
192
193 When opening a file with "fopen()", "freopen()", or "fdopen()", if the
194 file contains ASCII text, use "r", "w", "a", and so on as the open mode
195 - but if it contains binary data, use "rb", "wb", and so on.  On
196 Windows, if a file is opened in a text mode, writing a byte with the
197 value of octal 12 (newline) to the file causes two bytes, one with the
198 value octal 15 (carriage return) and one with the value octal 12, to be
199 written to the file, and causes bytes with the value octal 15 to be
200 discarded when reading the file (to translate between C's UNIX-style
201 lines that end with newline and Windows' DEC-style lines that end with
202 carriage return/line feed).
203
204 In addition, that also means that when opening or creating a binary
205 file, you must use "open()" (with O_CREAT and possibly O_TRUNC if the
206 file is to be created if it doesn't exist), and OR in the O_BINARY flag. 
207 That flag is not present on most, if not all, UNIX systems, so you must
208 also do
209
210         #ifndef O_BINARY
211         #define O_BINARY        0
212         #endif
213
214 to properly define it for UNIX (it's not necessary on UNIX).
215
216 Don't use forward declarations of static arrays without a specified size
217 in a fashion such as this:
218
219         static const value_string foo_vals[];
220
221                 ...
222
223         static const value_string foo_vals[] = {
224                 { 0,            "Red" },
225                 { 1,            "Green" },
226                 { 2,            "Blue" },
227                 { 0,            NULL }
228         };
229
230 as some compilers will reject the first of those statements.  Instead,
231 initialize the array at the point at which it's first declared, so that
232 the size is known.
233
234 Don't put declarations in the middle of a block; put them before all
235 code.  Not all compilers support declarations in the middle of code,
236 such as
237
238         int i;
239
240         i = foo();
241
242         int j;
243
244 For #define names and enum member names, prefix the names with a tag so
245 as to avoid collisions with other names - this might be more of an issue
246 on Windows, as it appears to #define names such as DELETE and
247 OPTIONAL.
248
249 Don't use the "numbered argument" feature that many UNIX printf's
250 implement, e.g.:
251
252         sprintf(add_string, " - (%1$d) (0x%1$04x)", value);
253
254 as not all UNIX printf's implement it, and Windows printf doesn't appear
255 to implement it.  Use something like
256
257         sprintf(add_string, " - (%d) (0x%04x)", value, value);
258
259 instead.
260
261 Don't use "variadic macros", such as
262
263         #define DBG(format, args...)    fprintf(stderr, format, ## args)
264
265 as not all C compilers support them.  Use macros that take a fixed
266 number of arguments, such as
267
268         #define DBG0(format)            fprintf(stderr, format)
269         #define DBG1(format, arg1)      fprintf(stderr, format, arg1)
270         #define DBG2(format, arg1, arg2) fprintf(stderr, format, arg1, arg2)
271
272                 ...
273
274 or something such as
275
276         #define DBG(args)               printf args
277
278 snprintf() -> g_snprintf()
279 snprintf() is not available on all platforms, so it's a good idea to use the 
280 g_snprintf() function declared by <glib.h> instead.
281
282 tmpnam() -> mkstemp()
283 tmpnam is insecure and should not be used any more. Ethereal brings its
284 own mkstemp implementation for use on platforms that lack mkstemp.
285 Note: mkstemp does not accept NULL as a parameter.
286
287 The pointer retured by a call to "tvb_get_ptr()" is not guaranteed to be
288 aligned on any particular byte boundary; this means that you cannot
289 safely cast it to any data type other than a pointer to "char",
290 "unsigned char", "guint8", or other one-byte data types.  You cannot,
291 for example, safely cast it to a pointer to a structure, and then access
292 the structure members directly; on some systems, unaligned accesses to
293 integral data types larger than 1 byte, and floating-point data types,
294 cause a trap, which will, at best, result in the OS slowly performing an
295 unaligned access for you, and will, on at least some platforms, cause
296 the program to be terminated.
297
298 Ethereal supports both platforms with GLib 1.2[.x]/GTK+ 1.2[.x] and GLib
299 2.x/GTK+ 1.3[.x] and 2.x.  If at all possible, either use only
300 mechanisms that are present in GLib 1.2[.x] and GTK+ 1.2[.x], use #if's
301 to conditionally use older or newer mechanisms depending on the platform
302 on which Ethereal is being built, or, if the code in GLib or GTK+ that
303 implements that mechanism will build with GLib 1.2[.x]/GTK+ 1.2[.x],
304 conditionally include that code as part of the Ethereal source and use
305 the included version with GLib 1.2[.x] or GTK+ 1.2[.x].  In particular,
306 if the GLib 2.x or GTK+ 2.x mechanism indicates that a routine is
307 deprecated and shouldn't be used in new code, and that it was renamed in
308 GLib 2.x or GTK+ 2.x and the new name should be used, disregard that and
309 use the old name - it'll still work with GLib 2.x or GTK+ 2.x, but will
310 also work with GLib 1.2[.x] and GTK+ 1.2[.x].
311
312 When different code must be used on UN*X and Win32, use a #if or #ifdef
313 that tests _WIN32, not WIN32.  Try to write code portably whenever
314 possible, however; note that there are some routines in Ethereal with
315 platform-dependent implementations and platform-independent APIs, such
316 as the routines in epan/filesystem.c, allowing the code that calls it to
317 be written portably without #ifdefs.
318
319 1.1.2 Robustness.
320
321 Ethereal is not guaranteed to read only network traces that contain correctly-
322 formed packets. Ethereal is commonly used is to track down networking problems, 
323 and the problems might be due to a buggy protocol implementation sending out 
324 bad packets.
325
326 Therefore, protocol dissectors not only have to be able to handle
327 correctly-formed packets without, for example, crashing or looping
328 infinitely, they also have to be able to handle *incorrectly*-formed
329 packets without crashing or looping infinitely.
330
331 Here are some suggestions for making dissectors more robust in the face
332 of incorrectly-formed packets:
333
334 Do *NOT* use "g_assert()" or "g_assert_not_reached()" in dissectors. 
335 *NO* value in a packet's data should be considered "wrong" in the sense
336 that it's a problem with the dissector if found; if it cannot do
337 anything else with a particular value from a packet's data, the
338 dissector should put into the protocol tree an indication that the
339 value is invalid, and should return.
340
341 If you are allocating a chunk of memory to contain data from a packet,
342 or to contain information derived from data in a packet, and the size of
343 the chunk of memory is derived from a size field in the packet, make
344 sure all the data is present in the packet before allocating the buffer.
345 Doing so means that
346
347         1) Ethereal won't leak that chunk of memory if an attempt to
348            fetch data not present in the packet throws an exception
349
350 and
351
352         2) it won't crash trying to allocate an absurdly-large chunk of
353            memory if the size field has a bogus large value.
354
355 If you're fetching into such a chunk of memory a string from the buffer,
356 and the string has a specified size, you can use "tvb_get_*_string()",
357 which will check whether the entire string is present before allocating
358 a buffer for the string, and will also put a trailing '\0' at the end of
359 the buffer.
360
361 If you're fetching into such a chunk of memory a 2-byte Unicode string
362 from the buffer, and the string has a specified size, you can use
363 "tvb_get_ephemeral_faked_unicode()", which will check whether the entire 
364 string is present before allocating a buffer for the string, and will also 
365 put a trailing '\0' at the end of the buffer.  The resulting string will be 
366 a sequence of single-byte characters; the only Unicode characters that
367 will be handled correctly are those in the ASCII range.  (Ethereal's
368 ability to handle non-ASCII strings is limited; it needs to be
369 improved.)
370
371 If you're fetching into such a chunk of memory a sequence of bytes from
372 the buffer, and the sequence has a specified size, you can use
373 "tvb_memdup()", which will check whether the entire sequence is present
374 before allocating a buffer for it.
375
376 Otherwise, you can check whether the data is present by using
377 "tvb_ensure_bytes_exist()" or by getting a pointer to the data by using
378 "tvb_get_ptr()", although note that there might be problems with using
379 the pointer from "tvb_get_ptr()" (see the item on this in the
380 Portability section above, and the next item below).
381
382 Note also that you should only fetch string data into a fixed-length
383 buffer if the code ensures that no more bytes than will fit into the
384 buffer are fetched ("the protocol ensures" isn't good enough, as
385 protocol specifications can't ensure only packets that conform to the
386 specification will be transmitted or that only packets for the protocol
387 in question will be interpreted as packets for that protocol by
388 Ethereal).  If there's no maximum length of string data to be fetched,
389 routines such as "tvb_get_*_string()" are safer, as they allocate a buffer
390 large enough to hold the string.  (Note that some variants of this call 
391 require you to free the string once you're finished with it.)
392
393 If you have gotten a pointer using "tvb_get_ptr()", you must make sure
394 that you do not refer to any data past the length passed as the last
395 argument to "tvb_get_ptr()"; while the various "tvb_get" routines
396 perform bounds checking and throw an exception if you refer to data not
397 available in the tvbuff, direct references through a pointer gotten from
398 "tvb_get_ptr()" do not do any bounds checking.
399
400 If you have a loop that dissects a sequence of items, each of which has
401 a length field, with the offset in the tvbuff advanced by the length of
402 the item, then, if the length field is the total length of the item, and
403 thus can be zero, you *MUST* check for a zero-length item and abort the
404 loop if you see one.  Otherwise, a zero-length item could cause the
405 dissector to loop infinitely.  You should also check that the offset,
406 after having the length added to it, is greater than the offset before
407 the length was added to it, if the length field is greater than 24 bits
408 long, so that, if the length value is *very* large and adding it to the
409 offset causes an overflow, that overflow is detected.
410
411 If you are fetching a length field from the buffer, corresponding to the
412 length of a portion of the packet, and subtracting from that length a
413 value corresponding to the length of, for example, a header in the
414 packet portion in question, *ALWAYS* check that the value of the length
415 field is greater than or equal to the length you're subtracting from it,
416 and report an error in the packet and stop dissecting the packet if it's
417 less than the length you're subtracting from it.  Otherwise, the
418 resulting length value will be negative, which will either cause errors
419 in the dissector or routines called by the dissector, or, if the value
420 is interpreted as an unsigned integer, will cause the value to be
421 interpreted as a very large positive value.
422
423 Any tvbuff offset that is added to as processing is done on a packet
424 should be stored in a 32-bit variable, such as an "int"; if you store it
425 in an 8-bit or 16-bit variable, you run the risk of the variable
426 overflowing.
427
428 sprintf() -> g_snprintf()
429 Prevent yourself from using the sprintf() function, as it does not test the 
430 length of the given output buffer and might be writing into memory areas not 
431 intended for. This function is one of the main causes of security problems 
432 like buffer exploits and many other bugs that are very hard to find. It's 
433 much better to use the g_snprintf() function declared by <glib.h> instead.
434
435 You should test your dissector against incorrectly-formed packets.  This 
436 can be done using the randpkt and editcap utilities that come with the
437 Ethereal distribution.  Testing using randpkt can be done by generating
438 output at the same layer as your protocol, and forcing Ethereal/Tethereal
439 to decode it as your protocol, e.g. if your protocol sits on top of UDP:
440
441     randpkt -c 50000 -t dns randpkt.pcap
442     tethereal -nVr randpkt.pcap -d udp.port==53,<myproto>
443     
444 Testing using editcap can be done using preexisting capture files and the
445 "-E" flag, which introduces errors in a capture file.  E.g.:
446
447     editcap -E 0.03 infile.pcap outfile.pcap
448     tethereal -nVr outfile.pcap
449
450 1.1.3 Name convention.
451
452 Ethereal uses the underscore_convention rather than the InterCapConvention for
453 function names, so new code should probably use underscores rather than
454 intercaps for functions and variable names. This is especially important if you
455 are writing code that will be called from outside your code.  We are just
456 trying to keep things consistent for other users.
457
458 1.1.4 White space convention.
459
460 Avoid using tab expansions different from 8 spaces, as not all text editors in
461 use by the developers support this.
462
463 When creating a new file, you are free to choose an indentation logic. Most of
464 the files in Ethereal tend to use 2-space or 4-space indentation. You are
465 encouraged to write a short comment on the indentation logic at the beginning
466 of this new file.
467
468 When editing an existing file, try following the existing indentation logic and
469 even if it very tempting, never ever use a restyler/reindenter utility on an
470 existing file.
471
472 1.2 Skeleton code.
473
474 Ethereal requires certain things when setting up a protocol dissector. 
475 Below is skeleton code for a dissector that you can copy to a file and
476 fill in.  Your dissector should follow the naming convention of packet-
477 followed by the abbreviated name for the protocol.  It is recommended
478 that where possible you keep to the IANA abbreviated name for the
479 protocol, if there is one, or a commonly-used abbreviation for the
480 protocol, if any.
481
482 Usually, you will put your newly created dissector file into the directory
483 epan/dissectors, just like all the other packet-....c files already in there.
484
485 Also, please add your dissector file to the corresponding makefile, 
486 described in section "1.9 Editing Makefile.common to add your dissector" below.
487
488 Dissectors that use the dissector registration to register with a lower level
489 dissector don't need to define a prototype in the .h file. For other
490 dissectors the main dissector routine should have a prototype in a header
491 file whose name is "packet-", followed by the abbreviated name for the
492 protocol, followed by ".h"; any dissector file that calls your dissector
493 should be changed to include that file.
494
495 You may not need to include all the headers listed in the skeleton
496 below, and you may need to include additional headers.  For example, the
497 code inside
498
499         #ifdef HAVE_LIBPCRE
500
501                 ...
502
503         #endif
504
505 is needed only if you are using a function from libpcre, e.g. the
506 "pcre_compile()" function.
507
508 The "$Id$"
509 in the comment will be updated by CVS when the file is
510 checked in; it will allow the RCS "ident" command to report which
511 version of the file is currently checked out.
512
513 When creating a new file, it is fine to just write "$Id$" as RCS will
514 automatically fill in the identifier at the time the file will be added to the
515 SVN repository (checked in).
516
517 ------------------------------------Cut here------------------------------------
518 /* packet-PROTOABBREV.c
519  * Routines for PROTONAME dissection
520  * Copyright 2000, YOUR_NAME <YOUR_EMAIL_ADDRESS>
521  *
522  * $Id$
523  *
524  * Ethereal - Network traffic analyzer
525  * By Gerald Combs <gerald@ethereal.com>
526  * Copyright 1998 Gerald Combs
527  *
528  * Copied from WHATEVER_FILE_YOU_USED (where "WHATEVER_FILE_YOU_USED"
529  * is a dissector file; if you just copied this from README.developer,
530  * don't bother with the "Copied from" - you don't even need to put
531  * in a "Copied from" if you copied an existing dissector, especially
532  * if the bulk of the code in the new dissector is your code)
533  * 
534  * This program is free software; you can redistribute it and/or
535  * modify it under the terms of the GNU General Public License
536  * as published by the Free Software Foundation; either version 2
537  * of the License, or (at your option) any later version.
538  * 
539  * This program is distributed in the hope that it will be useful,
540  * but WITHOUT ANY WARRANTY; without even the implied warranty of
541  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
542  * GNU General Public License for more details.
543  * 
544  * You should have received a copy of the GNU General Public License
545  * along with this program; if not, write to the Free Software
546  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
547  */
548
549 #ifdef HAVE_CONFIG_H
550 # include "config.h"
551 #endif
552
553 #include <stdio.h>
554 #include <stdlib.h>
555 #include <string.h>
556
557 #include <glib.h>
558
559 #include <epan/packet.h>
560 #include <epan/prefs.h>
561
562 /* IF PROTO exposes code to other dissectors, then it must be exported
563    in a header file. If not, a header file is not needed at all. */
564 #include "packet-PROTOABBREV.h"
565
566 /* Forward declaration we need below */
567 void proto_reg_handoff_PROTOABBREV(void);
568
569 /* Initialize the protocol and registered fields */
570 static int proto_PROTOABBREV = -1;
571 static int hf_PROTOABBREV_FIELDABBREV = -1;
572
573 /* Global sample preference ("controls" display of numbers) */
574 static gboolean gPREF_HEX = FALSE;
575
576 /* Initialize the subtree pointers */
577 static gint ett_PROTOABBREV = -1;
578
579 /* Code to actually dissect the packets */
580 static void
581 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
582 {
583
584 /* Set up structures needed to add the protocol subtree and manage it */
585         proto_item *ti;
586         proto_tree *PROTOABBREV_tree;
587
588 /* Make entries in Protocol column and Info column on summary display */
589         if (check_col(pinfo->cinfo, COL_PROTOCOL)) 
590                 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
591     
592 /* This field shows up as the "Info" column in the display; you should use
593    it, if possible, to summarize what's in the packet, so that a user looking
594    at the list of packets can tell what type of packet it is. See section 1.5
595    for more information.
596
597    Before changing the contents of a column you should make sure the column is
598    active by calling "check_col(pinfo->cinfo, COL_*)". If it is not active 
599    don't bother setting it.
600    
601    If you are setting the column to a constant string, use "col_set_str()", 
602    as it's more efficient than the other "col_set_XXX()" calls.
603
604    If you're setting it to a string you've constructed, or will be
605    appending to the column later, use "col_add_str()".
606
607    "col_add_fstr()" can be used instead of "col_add_str()"; it takes
608    "printf()"-like arguments.  Don't use "col_add_fstr()" with a format
609    string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
610    more efficient than "col_add_fstr()".
611
612    If you will be fetching any data from the packet before filling in
613    the Info column, clear that column first, in case the calls to fetch
614    data from the packet throw an exception because they're fetching data
615    past the end of the packet, so that the Info column doesn't have data
616    left over from the previous dissector; do
617
618         if (check_col(pinfo->cinfo, COL_INFO)) 
619                 col_clear(pinfo->cinfo, COL_INFO);
620
621    */
622
623         if (check_col(pinfo->cinfo, COL_INFO)) 
624                 col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
625
626 /* A protocol dissector can be called in 2 different ways:
627
628         (a) Operational dissection
629
630                 In this mode, Ethereal is only interested in the way protocols
631                 interact, protocol conversations are created, packets are reassembled
632                 and handed over to higher-level protocol dissectors.
633                 In this mode Ethereal does not build a so-called "protocol tree".
634
635         (b) Detailed dissection
636
637                 In this mode, Ethereal is also interested in all details of a given
638                 protocol, so a "protocol tree" is created.
639
640    Ethereal distinguishes between the 2 modes with the proto_tree pointer:
641         (a) <=> tree == NULL
642         (b) <=> tree != NULL
643
644    In the interest of speed, if "tree" is NULL, avoid building a
645    protocol tree and adding stuff to it, or even looking at any packet
646    data needed only if you're building the protocol tree, if possible.
647
648    Note, however, that you must fill in column information, create
649    conversations, reassemble packets, build any other persistent state
650    needed for dissection, and call subdissectors regardless of whether
651    "tree" is NULL or not.  This might be inconvenient to do without
652    doing most of the dissection work; the routines for adding items to
653    the protocol tree can be passed a null protocol tree pointer, in
654    which case they'll return a null item pointer, and
655    "proto_item_add_subtree()" returns a null tree pointer if passed a
656    null item pointer, so, if you're careful not to dereference any null
657    tree or item pointers, you can accomplish this by doing all the
658    dissection work.  This might not be as efficient as skipping that
659    work if you're not building a protocol tree, but if the code would
660    have a lot of tests whether "tree" is null if you skipped that work,
661    you might still be better off just doing all that work regardless of
662    whether "tree" is null or not. */
663         if (tree) {
664
665 /* NOTE: The offset and length values in the call to
666    "proto_tree_add_item()" define what data bytes to highlight in the hex
667    display window when the line in the protocol tree display
668    corresponding to that item is selected.
669
670    Supplying a length of -1 is the way to highlight all data from the
671    offset to the end of the packet. */
672
673 /* create display subtree for the protocol */
674                 ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, FALSE);
675
676                 PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
677
678 /* add an item to the subtree, see section 1.6 for more information */
679                 proto_tree_add_item(PROTOABBREV_tree,
680                     hf_PROTOABBREV_FIELDABBREV, tvb, offset, len, FALSE)
681
682
683 /* Continue adding tree items to process the packet here */
684
685
686         }
687
688 /* If this protocol has a sub-dissector call it here, see section 1.8 */
689 }
690
691
692 /* Register the protocol with Ethereal */
693
694 /* this format is require because a script is used to build the C function
695    that calls all the protocol registration.
696 */
697
698 void
699 proto_register_PROTOABBREV(void)
700 {                 
701   module_t *PROTOABBREV_module;
702
703 /* Setup list of header fields  See Section 1.6.1 for details*/
704         static hf_register_info hf[] = {
705                 { &hf_PROTOABBREV_FIELDABBREV,
706                         { "FIELDNAME",           "PROTOABBREV.FIELDABBREV",
707                         FIELDTYPE, FIELDBASE, FIELDCONVERT, BITMASK,          
708                         "FIELDDESCR", HFILL }
709                 },
710         };
711
712 /* Setup protocol subtree array */
713         static gint *ett[] = {
714                 &ett_PROTOABBREV,
715         };
716
717 /* Register the protocol name and description */
718         proto_PROTOABBREV = proto_register_protocol("PROTONAME",
719             "PROTOSHORTNAME", "PROTOABBREV");
720
721 /* Required function calls to register the header fields and subtrees used */
722         proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
723         proto_register_subtree_array(ett, array_length(ett));
724         
725 /* Register preferences module (See Section 2.6 for more on preferences) */       
726         PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
727      
728 /* Register a sample preference */        
729         prefs_register_bool_preference(PROTOABBREV_module, "showHex", 
730              "Display numbers in Hex",
731              "Enable to display numerical values in hexidecimal.",
732              &gPREF_HEX );        
733 }
734
735
736 /* If this dissector uses sub-dissector registration add a registration routine.
737    This exact format is required because a script is used to find these routines 
738    and create the code that calls these routines.
739    
740    This function is also called by preferences whenever "Apply" is pressed 
741    (see prefs_register_protocol above) so it should accommodate being called 
742    more than once.
743 */
744 void
745 proto_reg_handoff_PROTOABBREV(void)
746 {
747         static gboolean inited = FALSE;
748         
749         if( !inited ) {
750
751         dissector_handle_t PROTOABBREV_handle;
752
753         PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
754             proto_PROTOABBREV);
755         dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
756         
757         inited = TRUE;
758         }
759         
760         /* 
761           If you perform registration functions which are dependant upon
762           prefs the you should de-register everything which was associated
763           with the previous settings and re-register using the new prefs settings
764           here. In general this means you need to keep track of what value the
765           preference had at the time you registered using a local static in this
766           function. ie.
767
768           static int currentPort = -1;
769
770           if( -1 != currentPort ) {
771               dissector_delete( "tcp.port", currentPort, PROTOABBREV_handle);
772           }
773
774           currentPort = gPortPref;
775
776           dissector_add("tcp.port", currentPort, PROTOABBREV_handle);
777             
778         */
779 }
780
781 ------------------------------------Cut here------------------------------------
782
783 1.3 Explanation of needed substitutions in code skeleton.
784
785 In the above code block the following strings should be substituted with
786 your information.
787
788 YOUR_NAME       Your name, of course.  You do want credit, don't you?
789                 It's the only payment you will receive....
790 YOUR_EMAIL_ADDRESS      Keep those cards and letters coming.
791 WHATEVER_FILE_YOU_USED  Add this line if you are using another file as a
792                 starting point.
793 PROTONAME       The name of the protocol; this is displayed in the
794                 top-level protocol tree item for that protocol.
795 PROTOSHORTNAME  An abbreviated name for the protocol; this is displayed
796                 in the "Preferences" dialog box if your dissector has
797                 any preferences, and in the dialog box for filter fields
798                 when constructing a filter expression.
799 PROTOABBREV     A name for the protocol for use in filter expressions;
800                 it should contain only lower-case letters, digits, and
801                 hyphens.
802 FIELDNAME       The displayed name for the header field.
803 FIELDABBREV     The abbreviated name for the header field. (NO SPACES)
804 FIELDTYPE       FT_NONE, FT_BOOLEAN, FT_UINT8, FT_UINT16, FT_UINT24,
805                 FT_UINT32, FT_UINT64, FT_INT8, FT_INT16, FT_INT24, FT_INT32,
806                 FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
807                 FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_UINT_STRING,
808                 FT_ETHER, FT_BYTES, FT_IPv4, FT_IPv6, FT_IPXNET,
809                 FT_FRAMENUM, FT_PROTOCOL
810 FIELDBASE       BASE_NONE, BASE_DEC, BASE_HEX, BASE_OCT
811 FIELDCONVERT    VALS(x), TFS(x), NULL
812 BITMASK         Usually 0x0 unless using the TFS(x) field conversion.
813 FIELDDESCR      A brief description of the field.
814 PARENT_SUBFIELD Lower level protocol field used for lookup, i.e. "tcp.port"
815 ID_VALUE        Lower level protocol field value that identifies this protocol
816                 For example the TCP or UDP port number
817
818 If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
819 PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp".  Try to
820 conform with IANA names.
821
822 1.4 The dissector and the data it receives.
823
824
825 1.4.1 Header file.
826
827 This is only needed if the dissector doesn't use self-registration to
828 register itself with the lower level dissector, or if the protocol dissector
829 wants/needs to expose code to other subdissectors.
830
831 The dissector must declared as exactly as follows in the file 
832 packet-PROTOABBREV.h:
833
834 void
835 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
836
837
838 1.4.2 Extracting data from packets.
839
840 NOTE: See the README.tvbuff file for more details
841
842 The "tvb" argument to a dissector points to a buffer containing the raw
843 data to be analyzed by the dissector; for example, for a protocol
844 running atop UDP, it contains the UDP payload (but not the UDP header,
845 or any protocol headers above it).  A tvbuffer is a opaque data
846 structure, the internal data structures are hidden and the data must be
847 access via the tvbuffer accessors.
848
849 The accessors are:
850
851 Single-byte accessor:
852
853 guint8  tvb_get_guint8(tvbuff_t*, gint offset);
854
855 Network-to-host-order accessors for 16-bit integers (guint16), 32-bit
856 integers (guint32), and 24-bit integers:
857
858 guint16 tvb_get_ntohs(tvbuff_t*, gint offset);
859 guint32 tvb_get_ntohl(tvbuff_t*, gint offset);
860 guint32 tvb_get_ntoh24(tvbuff_t*, gint offset);
861
862 Network-to-host-order accessors for single-precision and
863 double-precision IEEE floating-point numbers:
864
865 gfloat tvb_get_ntohieee_float(tvbuff_t*, gint offset);
866 gdouble tvb_get_ntohieee_double(tvbuff_t*, gint offset);
867
868 Little-Endian-to-host-order accessors for 16-bit integers (guint16),
869 32-bit integers (guint32), and 24-bit integers:
870
871 guint16 tvb_get_letohs(tvbuff_t*, gint offset);
872 guint32 tvb_get_letohl(tvbuff_t*, gint offset);
873 guint32 tvb_get_letoh24(tvbuff_t*, gint offset);
874
875 Little-Endian-to-host-order accessors for single-precision and
876 double-precision IEEE floating-point numbers:
877
878 gfloat tvb_get_letohieee_float(tvbuff_t*, gint offset);
879 gdouble tvb_get_letohieee_double(tvbuff_t*, gint offset);
880
881 NOTE: IPv4 addresses are not to be converted to host byte order before
882 being passed to "proto_tree_add_ipv4()".  You should use "tvb_memcpy()"
883 to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
884 for example, try to use "tvb_get_ntohl()", find that it gives you the
885 wrong answer on the PC on which you're doing development, and try
886 "tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong
887 answer on big-endian machines.
888
889 String accessors:
890
891 guint8 *tvb_get_string(tvbuff_t*, gint offset, gint length);
892 guint8 *tvb_get_ephemeral_string(tvbuff_t*, gint offset, gint length);
893
894 Returns a null-terminated buffer containing data from the specified
895 tvbuff, starting at the specified offset, and containing the specified
896 length worth of characters (the length of the buffer will be length+1,
897 as it includes a null character to terminate the string).
898
899 tvb_get_string() returns a buffer allocated by g_malloc() so you must
900 g_free() it when you are finished with the string. Failure to g_free() this
901 buffer will lead to memory leaks.
902 tvb_get_ephemeral_string() returns a buffer allocated from a special heap
903 with a lifetime until the next packet is dissected. You do not need to
904 free() this buffer, it will happen automatically once the next packet is 
905 dissected.
906
907
908 guint8 *tvb_get_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
909 guint8 *tvb_get_ephemeral_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
910
911 Returns a null-terminated buffer, allocated with "g_malloc()",
912 containing data from the specified tvbuff, starting with at the
913 specified offset, and containing all characters from the tvbuff up to
914 and including a terminating null character in the tvbuff.  "*lengthp"
915 will be set to the length of the string, including the terminating null.
916
917 tvb_get_stringz() returns a buffer allocated by g_malloc() so you must
918 g_free() it when you are finished with the string. Failure to g_free() this
919 buffer will lead to memory leaks.
920 tvb_get_ephemeral_stringz() returns a buffer allocated from a special heap
921 with a lifetime until the next packet is dissected. You do not need to
922 free() this buffer, it will happen automatically once the next packet is 
923 dissected.
924
925
926 guint8 *tvb_fake_unicode(tvbuff_t*, gint offset, gint length);
927 guint8 *tvb_get_ephemeral_faked_unicode(tvbuff_t*, gint offset, gint length);
928
929 Converts a 2-byte unicode string to an ASCII string.
930 Returns a null-terminated buffer containing data from the specified
931 tvbuff, starting at the specified offset, and containing the specified
932 length worth of characters (the length of the buffer will be length+1,
933 as it includes a null character to terminate the string).
934
935 tvb_fake_unicode() returns a buffer allocated by g_malloc() so you must
936 g_free() it when you are finished with the string. Failure to g_free() this
937 buffer will lead to memory leaks.
938 tvb_get_ephemeral_faked_unicode() returns a buffer allocated from a special 
939 heap with a lifetime until the next packet is dissected. You do not need to
940 free() this buffer, it will happen automatically once the next packet is 
941 dissected.
942
943
944 Copying memory:
945 guint8* tvb_memcpy(tvbuff_t*, guint8* target, gint offset, gint length);
946
947 Copies into the specified target the specified length's worth of data
948 from the specified tvbuff, starting at the specified offset.
949
950 guint8* tvb_memdup(tvbuff_t*, gint offset, gint length);
951
952 Returns a buffer, allocated with "g_malloc()", containing the specified
953 length's worth of data from the specified tvbuff, starting at the
954 specified offset.
955
956 Pointer-retrieval:
957 /* WARNING! This function is possibly expensive, temporarily allocating
958  * another copy of the packet data. Furthermore, it's dangerous because once
959  * this pointer is given to the user, there's no guarantee that the user will
960  * honor the 'length' and not overstep the boundaries of the buffer.
961  */ 
962 guint8* tvb_get_ptr(tvbuff_t*, gint offset, gint length);
963
964 The reason that tvb_get_ptr() might have to allocate a copy of its data
965 only occurs with TVBUFF_COMPOSITES, data that spans multiple tvbuffers. 
966 If the user request a pointer to a range of bytes that spans the member
967 tvbuffs that make up the TVBUFF_COMPOSITE, the data will have to be
968 copied to another memory region to assure that all the bytes are
969 contiguous.
970
971
972
973 1.5 Functions to handle columns in the traffic summary window.
974
975 The topmost pane of the main window is a list of the packets in the
976 capture, possibly filtered by a display filter.
977
978 Each line corresponds to a packet, and has one or more columns, as
979 configured by the user.
980
981 Many of the columns are handled by code outside individual dissectors;
982 most dissectors need only specify the value to put in the "Protocol" and
983 "Info" columns.
984
985 Columns are specified by COL_ values; the COL_ value for the "Protocol"
986 field, typically giving an abbreviated name for the protocol (but not
987 the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the
988 COL_ value for the "Info" field, giving a summary of the contents of the
989 packet for that protocol, is COL_INFO. 
990
991 A value for a column should only be added if the user specified that it
992 be displayed; to check whether a given column is to be displayed, call
993 'check_col' with the COL_ value for that field as an argument - it will
994 return TRUE if the column is to be displayed and FALSE if it is not to
995 be displayed.
996
997 The value for a column can be specified with one of several functions,
998 all of which take the 'fd' argument to the dissector as their first
999 argument, and the COL_ value for the column as their second argument.
1000
1001 1.5.1 The col_set_str function.
1002
1003 'col_set_str' takes a string as its third argument, and sets the value
1004 for the column to that value.  It assumes that the pointer passed to it
1005 points to a string constant or a static "const" array, not to a
1006 variable, as it doesn't copy the string, it merely saves the pointer
1007 value; the argument can itself be a variable, as long as it always
1008 points to a string constant or a static "const" array.
1009
1010 It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if
1011 the dissector will be using 'col_append_str' or 'col_append_fstr" to
1012 append more information to the column, the string will have to be copied
1013 anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in
1014 that case.
1015
1016 For example, to set the "Protocol" column
1017 to "PROTOABBREV":
1018
1019         if (check_col(pinfo->cinfo, COL_PROTOCOL)) 
1020                 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
1021
1022
1023 1.5.2 The col_add_str function.
1024
1025 'col_add_str' takes a string as its third argument, and sets the value
1026 for the column to that value.  It takes the same arguments as
1027 'col_set_str', but copies the string, so that if the string is, for
1028 example, an automatic variable that won't remain in scope when the
1029 dissector returns, it's safe to use.
1030
1031
1032 1.5.3 The col_add_fstr function.
1033
1034 'col_add_fstr' takes a 'printf'-style format string as its third
1035 argument, and 'printf'-style arguments corresponding to '%' format
1036 items in that string as its subsequent arguments.  For example, to set
1037 the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a
1038 string containing the type of the request in the packet and "n" is an
1039 unsigned integer containing the number of bytes in the request:
1040
1041         if (check_col(pinfo->cinfo, COL_INFO)) 
1042                 col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes",
1043                     reqtype, n);
1044
1045 Don't use 'col_add_fstr' with a format argument of just "%s" -
1046 'col_add_str', or possibly even 'col_set_str' if the string that matches
1047 the "%s" is a static constant string, will do the same job more
1048 efficiently.
1049
1050
1051 1.5.4 The col_clear function.
1052
1053 If the Info column will be filled with information from the packet, that
1054 means that some data will be fetched from the packet before the Info
1055 column is filled in.  If the packet is so small that the data in
1056 question cannot be fetched, the routines to fetch the data will throw an
1057 exception (see the comment at the beginning about tvbuffers improving
1058 the handling of short packets - the tvbuffers keep track of how much
1059 data is in the packet, and throw an exception on an attempt to fetch
1060 data past the end of the packet, so that the dissector won't process
1061 bogus data), causing the Info column not to be filled in.
1062
1063 This means that the Info column will have data for the previous
1064 protocol, which would be confusing if, for example, the Protocol column
1065 had data for this protocol.
1066
1067 Therefore, before a dissector fetches any data whatsoever from the
1068 packet (unless it's a heuristic dissector fetching data to determine
1069 whether the packet is one that it should dissect, in which case it
1070 should check, before fetching the data, whether there's any data to
1071 fetch; if there isn't, it should return FALSE), it should set the
1072 Protocol column and the Info column.
1073
1074 If the Protocol column will ultimately be set to, for example, a value
1075 containing a protocol version number, with the version number being a
1076 field in the packet, the dissector should, before fetching the version
1077 number field or any other field from the packet, set it to a value
1078 without a version number, using 'col_set_str', and should later set it
1079 to a value with the version number after it's fetched the version
1080 number.
1081
1082 If the Info column will ultimately be set to a value containing
1083 information from the packet, the dissector should, before fetching any
1084 fields from the packet, clear the column using 'col_clear' (which is
1085 more efficient than clearing it by calling 'col_set_str' or
1086 'col_add_str' with a null string), and should later set it to the real
1087 string after it's fetched the data to use when doing that.
1088
1089
1090 1.5.5 The col_append_str function.
1091
1092 Sometimes the value of a column, especially the "Info" column, can't be
1093 conveniently constructed at a single point in the dissection process;
1094 for example, it might contain small bits of information from many of the
1095 fields in the packet.  'col_append_str' takes, as arguments, the same
1096 arguments as 'col_add_str', but the string is appended to the end of the
1097 current value for the column, rather than replacing the value for that
1098 column.  (Note that no blank separates the appended string from the
1099 string to which it is appended; if you want a blank there, you must add
1100 it yourself as part of the string being appended.)
1101
1102
1103 1.5.6 The col_append_fstr function.
1104
1105 'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to
1106 'col_add_str' - it takes, as arguments, the same arguments as
1107 'col_add_fstr', but the formatted string is appended to the end of the
1108 current value for the column, rather than replacing the value for that
1109 column.
1110
1111 1.5.7 The col_append_sep_str and col_append_sep_fstr functions.
1112
1113 In specific situations the developer knows that a column's value will be
1114 created in a stepwise manner, where the appended values are listed. Both
1115 'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item
1116 separator between two consecutive items, and will not add the separator at the
1117 beginning of the column. The remainder of the work both functions do is
1118 identical to what 'col_append_str' and 'col_append_fstr' do.
1119
1120 1.6 Constructing the protocol tree.
1121
1122 The middle pane of the main window, and the topmost pane of a packet
1123 popup window, are constructed from the "protocol tree" for a packet.
1124
1125 The protocol tree, or proto_tree, is a GNode, the N-way tree structure
1126 available within GLIB. Of course the protocol dissectors don't care
1127 what a proto_tree really is; they just pass the proto_tree pointer as an
1128 argument to the routines which allow them to add items and new branches
1129 to the tree.
1130
1131 When a packet is selected in the packet-list pane, or a packet popup
1132 window is created, a new logical protocol tree (proto_tree) is created. 
1133 The pointer to the proto_tree (in this case, 'protocol tree'), is passed
1134 to the top-level protocol dissector, and then to all subsequent protocol
1135 dissectors for that packet, and then the GUI tree is drawn via
1136 proto_tree_draw().
1137
1138 The logical proto_tree needs to know detailed information about the
1139 protocols and fields about which information will be collected from the
1140 dissection routines. By strictly defining (or "typing") the data that can
1141 be attached to a proto tree, searching and filtering becomes possible.
1142 This means that the for every protocol and field (which I also call
1143 "header fields", since they are fields in the protocol headers) which
1144 might be attached to a tree, some information is needed.
1145
1146 Every dissector routine will need to register its protocols and fields
1147 with the central protocol routines (in proto.c). At first I thought I
1148 might keep all the protocol and field information about all the
1149 dissectors in one file, but decentralization seemed like a better idea.
1150 That one file would have gotten very large; one small change would have
1151 required a re-compilation of the entire file. Also, by allowing
1152 registration of protocols and fields at run-time, loadable modules of
1153 protocol dissectors (perhaps even user-supplied) is feasible.
1154
1155 To do this, each protocol should have a register routine, which will be
1156 called when Ethereal starts.  The code to call the register routines is
1157 generated automatically; to arrange that a protocol's register routine
1158 be called at startup:
1159
1160         the file containing a dissector's "register" routine must be
1161         added to "DISSECTOR_SRC" in "epan/dissectors/Makefile.common";
1162  
1163         the "register" routine must have a name of the form
1164         "proto_register_XXX";
1165   
1166         the "register" routine must take no argument, and return no
1167         value;
1168  
1169         the "register" routine's name must appear in the source file
1170         either at the beginning of the line, or preceded only by "void "
1171         at the beginning of the line (that'd typically be the
1172         definition) - other white space shouldn't cause a problem, e.g.:
1173  
1174 void proto_register_XXX(void) {
1175  
1176         ...
1177  
1178 }
1179  
1180 and
1181  
1182 void
1183 proto_register_XXX( void )
1184 {
1185  
1186         ...
1187  
1188 }
1189  
1190         and so on should work.
1191
1192 For every protocol or field that a dissector wants to register, a variable of
1193 type int needs to be used to keep track of the protocol. The IDs are
1194 needed for establishing parent/child relationships between protocols and
1195 fields, as well as associating data with a particular field so that it
1196 can be stored in the logical tree and displayed in the GUI protocol
1197 tree.
1198
1199 Some dissectors will need to create branches within their tree to help
1200 organize header fields. These branches should be registered as header
1201 fields. Only true protocols should be registered as protocols. This is
1202 so that a display filter user interface knows how to distinguish
1203 protocols from fields.
1204
1205 A protocol is registered with the name of the protocol and its
1206 abbreviation.
1207
1208 Here is how the frame "protocol" is registered.
1209
1210         int proto_frame;
1211
1212         proto_frame = proto_register_protocol (
1213                 /* name */            "Frame",
1214                 /* short name */      "Frame",
1215                 /* abbrev */          "frame" );
1216
1217 A header field is also registered with its name and abbreviation, but
1218 information about the its data type is needed. It helps to look at
1219 the header_field_info struct to see what information is expected:
1220
1221 struct header_field_info {
1222         char                            *name;
1223         char                            *abbrev;
1224         enum ftenum                     type;
1225         int                             display;
1226         void                            *strings;
1227         guint                           bitmask;
1228         char                            *blurb;
1229
1230         int                             id;       /* calculated */
1231         int                             parent;
1232         int                             bitshift; /* calculated */
1233 };
1234
1235 name
1236 ----
1237 A string representing the name of the field. This is the name
1238 that will appear in the graphical protocol tree.
1239
1240 abbrev
1241 ------
1242 A string with an abbreviation of the field. We concatenate the
1243 abbreviation of the parent protocol with an abbreviation for the field,
1244 using a period as a separator. For example, the "src" field in an IP packet
1245 would have "ip.src" as an abbreviation. It is acceptable to have
1246 multiple levels of periods if, for example, you have fields in your
1247 protocol that are then subdivided into subfields. For example, TRMAC
1248 has multiple error fields, so the abbreviations follow this pattern:
1249 "trmac.errors.iso", "trmac.errors.noniso", etc.
1250
1251 The abbreviation is the identifier used in a display filter.
1252
1253 type
1254 ----
1255 The type of value this field holds. The current field types are:
1256
1257         FT_NONE                 No field type. Used for fields that
1258                                 aren't given a value, and that can only
1259                                 be tested for presence or absence; a
1260                                 field that represents a data structure,
1261                                 with a subtree below it containing
1262                                 fields for the members of the structure,
1263                                 or that represents an array with a
1264                                 subtree below it containing fields for
1265                                 the members of the array, might be an
1266                                 FT_NONE field.
1267         FT_PROTOCOL             Used for protocols which will be placing
1268                                 themselves as top-level items in the
1269                                 "Packet Details" pane of the UI.
1270         FT_BOOLEAN              0 means "false", any other value means
1271                                 "true".
1272         FT_FRAMENUM             A frame number; if this is used, the "Go
1273                                 To Corresponding Frame" menu item can
1274                                 work on that field.
1275         FT_UINT8                An 8-bit unsigned integer.
1276         FT_UINT16               A 16-bit unsigned integer.
1277         FT_UINT24               A 24-bit unsigned integer.
1278         FT_UINT32               A 32-bit unsigned integer.
1279         FT_UINT64               A 64-bit unsigned integer.
1280         FT_INT8                 An 8-bit signed integer.
1281         FT_INT16                A 16-bit signed integer.
1282         FT_INT24                A 24-bit signed integer.
1283         FT_INT32                A 32-bit signed integer.
1284         FT_INT64                A 64-bit signed integer.
1285         FT_FLOAT                A single-precision floating point number.
1286         FT_DOUBLE               A double-precision floating point number.
1287         FT_ABSOLUTE_TIME        Seconds (4 bytes) and nanoseconds (4 bytes)
1288                                 of time displayed as month name, month day,
1289                                 year, hours, minutes, and seconds with 9
1290                                 digits after the decimal point.
1291         FT_RELATIVE_TIME        Seconds (4 bytes) and nanoseconds (4 bytes)
1292                                 of time displayed as seconds and 9 digits
1293                                 after the decimal point.
1294         FT_STRING               A string of characters, not necessarily
1295                                 NUL-terminated, but possibly NUL-padded.
1296                                 This, and the other string-of-characters
1297                                 types, are to be used for text strings,
1298                                 not raw binary data.
1299         FT_STRINGZ              A NUL-terminated string of characters.
1300         FT_UINT_STRING          A counted string of characters, consisting
1301                                 of a count (represented as an integral
1302                                 value) followed immediately by the
1303                                 specified number of characters.
1304         FT_ETHER                A six octet string displayed in
1305                                 Ethernet-address format.
1306         FT_BYTES                A string of bytes with arbitrary values;
1307                                 used for raw binary data.
1308         FT_IPv4                 A version 4 IP address (4 bytes) displayed
1309                                 in dotted-quad IP address format (4
1310                                 decimal numbers separated by dots).
1311         FT_IPv6                 A version 6 IP address (16 bytes) displayed
1312                                 in standard IPv6 address format.
1313         FT_IPXNET               An IPX address displayed in hex as a 6-byte
1314                                 network number followed by a 6-byte station
1315                                 address. 
1316
1317 Some of these field types are still not handled in the display filter
1318 routines, but the most common ones are. The FT_UINT* variables all
1319 represent unsigned integers, and the FT_INT* variables all represent
1320 signed integers; the number on the end represent how many bits are used
1321 to represent the number.
1322
1323 display
1324 -------
1325 The display field has a couple of overloaded uses. This is unfortunate,
1326 but since we're C as an application programming language, this sometimes
1327 makes for cleaner programs. Right now I still think that overloading
1328 this variable was okay.
1329
1330 For integer fields (FT_UINT* and FT_INT*), this variable represents the
1331 base in which you would like the value displayed.  The acceptable bases
1332 are:
1333
1334         BASE_DEC,
1335         BASE_HEX,
1336         BASE_OCT
1337
1338 BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
1339 respectively.
1340
1341 For FT_BOOLEAN fields that are also bitfields, 'display' is used to tell
1342 the proto_tree how wide the parent bitfield is.  With integers this is
1343 not needed since the type of integer itself (FT_UINT8, FT_UINT16,
1344 FT_UINT24, FT_UINT32, etc.) tells the proto_tree how wide the parent
1345 bitfield is.
1346
1347 Additionally, BASE_NONE is used for 'display' as a NULL-value. That is,
1348 for non-integers and non-bitfield FT_BOOLEANs, you'll want to use BASE_NONE
1349 in the 'display' field.  You may not use BASE_NONE for integers.
1350
1351 It is possible that in the future we will record the endianness of
1352 integers. If so, it is likely that we'll use a bitmask on the display field
1353 so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX.
1354 But that has not happened yet.
1355
1356 strings
1357 -------
1358 Some integer fields, of type FT_UINT*, need labels to represent the true
1359 value of a field.  You could think of those fields as having an
1360 enumerated data type, rather than an integral data type.
1361
1362 A 'value_string' structure is a way to map values to strings. 
1363
1364         typedef struct _value_string {
1365                 guint32  value;
1366                 gchar   *strptr;
1367         } value_string;
1368
1369 For fields of that type, you would declare an array of "value_string"s:
1370
1371         static const value_string valstringname[] = {
1372                 { INTVAL1, "Descriptive String 1" }, 
1373                 { INTVAL2, "Descriptive String 2" }, 
1374                 { 0,       NULL },
1375         };
1376
1377 (the last entry in the array must have a NULL 'strptr' value, to
1378 indicate the end of the array).  The 'strings' field would be set to
1379 'VALS(valstringname)'.
1380
1381 If the field has a numeric rather than an enumerated type, the 'strings'
1382 field would be set to NULL.
1383
1384 FT_BOOLEANS have a default map of 0 = "False", 1 (or anything else) = "True".
1385 Sometimes it is useful to change the labels for boolean values (e.g.,
1386 to "Yes"/"No", "Fast"/"Slow", etc.).  For these mappings, a struct called
1387 true_false_string is used. (This struct is new as of Ethereal 0.7.6).
1388
1389         typedef struct true_false_string {
1390                 char    *true_string;
1391                 char    *false_string;
1392         } true_false_string;
1393
1394 For Boolean fields for which "False" and "True" aren't the desired
1395 labels, you would declare a "true_false_string"s:
1396
1397         static const true_false_string boolstringname = {
1398                 "String for True",
1399                 "String for False"
1400         };
1401
1402 Its two fields are pointers to the string representing truth, and the
1403 string representing falsehood.  For FT_BOOLEAN fields that need a
1404 'true_false_string' struct, the 'strings' field would be set to
1405 'TFS(&boolstringname)'. 
1406
1407 If the Boolean field is to be displayed as "False" or "True", the
1408 'strings' field would be set to NULL.
1409
1410 bitmask
1411 -------
1412 If the field is a bitfield, then the bitmask is the mask which will
1413 leave only the bits needed to make the field when ANDed with a value.
1414 The proto_tree routines will calculate 'bitshift' automatically
1415 from 'bitmask', by finding the rightmost set bit in the bitmask.
1416 If the field is not a bitfield, then bitmask should be set to 0.
1417
1418 blurb
1419 -----
1420 This is a string giving a proper description of the field.
1421 It should be at least one grammatically complete sentence.
1422 It is meant to provide a more detailed description of the field than the
1423 name alone provides. This information will be used in the man page, and
1424 in a future GUI display-filter creation tool. We might also add tooltips
1425 to the labels in the GUI protocol tree, in which case the blurb would
1426 be used as the tooltip text.
1427
1428
1429 1.6.1 Field Registration.
1430
1431 Protocol registration is handled by creating an instance of the
1432 header_field_info struct (or an array of such structs), and
1433 calling the registration function along with the registration ID of
1434 the protocol that is the parent of the fields. Here is a complete example:
1435
1436         static int proto_eg = -1;
1437         static int hf_field_a = -1;
1438         static int hf_field_b = -1;
1439
1440         static hf_register_info hf[] = {
1441
1442                 { &hf_field_a,
1443                 { "Field A",    "proto.field_a", FT_UINT8, BASE_HEX, NULL,
1444                         0xf0, "Field A represents Apples", HFILL }},
1445
1446                 { &hf_field_b,
1447                 { "Field B",    "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs),
1448                         0x0, "Field B represents Bananas", HFILL }}
1449         };
1450
1451         proto_eg = proto_register_protocol("Example Protocol",
1452             "PROTO", "proto");
1453         proto_register_field_array(proto_eg, hf, array_length(hf));
1454
1455 Be sure that your array of hf_register_info structs is declared 'static',
1456 since the proto_register_field_array() function does not create a copy
1457 of the information in the array... it uses that static copy of the
1458 information that the compiler created inside your array. Here's the
1459 layout of the hf_register_info struct:
1460
1461 typedef struct hf_register_info {
1462         int                     *p_id;  /* pointer to parent variable */
1463         header_field_info       hfinfo;
1464 } hf_register_info;
1465
1466 Also be sure to use the handy array_length() macro found in packet.h
1467 to have the compiler compute the array length for you at compile time.
1468
1469 If you don't have any fields to register, do *NOT* create a zero-length
1470 "hf" array; not all compilers used to compile Ethereal support them. 
1471 Just omit the "hf" array, and the "proto_register_field_array()" call,
1472 entirely.
1473
1474 It is OK to have header fields with a different format be registered with
1475 the same abbreviation. For instance, the following is valid:
1476
1477         static hf_register_info hf[] = {
1478
1479                 { &hf_field_8bit, /* 8-bit version of proto.field */
1480                 { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL,
1481                         0x00, "Field represents FOO", HFILL }},
1482
1483                 { &hf_field_32bit, /* 32-bit version of proto.field */
1484                 { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL,
1485                         0x00, "Field represents FOO", HFILL }}
1486         };
1487
1488 This way a filter expression can match a header field, irrespective of the
1489 representation of it in the specific protocol context. This is interesting
1490 for protocols with variable-width header fields.
1491
1492 The HFILL macro at the end of the struct will set resonable default values
1493 for internally used fields.
1494
1495 1.6.2 Adding Items and Values to the Protocol Tree.
1496
1497 A protocol item is added to an existing protocol tree with one of a
1498 handful of proto_XXX_DO_YYY() functions.
1499
1500 Remember that it only makes sense to add items to a protocol tree if its
1501 proto_tree pointer is not null. Should you add an item to a NULL tree, then
1502 the proto_XXX_DO_YYY() function will immediately return. The cost of this
1503 function call can be avoided by checking for the tree pointer.
1504
1505 Subtrees can be made with the proto_item_add_subtree() function:
1506
1507         item = proto_tree_add_item(....);
1508         new_tree = proto_item_add_subtree(item, tree_type);
1509
1510 This will add a subtree under the item in question; a subtree can be
1511 created under an item made by any of the "proto_tree_add_XXX" functions,
1512 so that the tree can be given an arbitrary depth.
1513
1514 Subtree types are integers, assigned by
1515 "proto_register_subtree_array()".  To register subtree types, pass an
1516 array of pointers to "gint" variables to hold the subtree type values to
1517 "proto_register_subtree_array()":
1518
1519         static gint ett_eg = -1;
1520         static gint ett_field_a = -1;
1521
1522         static gint *ett[] = {
1523                 &ett_eg,
1524                 &ett_field_a,
1525         };
1526
1527         proto_register_subtree_array(ett, array_length(ett));
1528
1529 in your "register" routine, just as you register the protocol and the
1530 fields for that protocol.
1531
1532 There are several functions that the programmer can use to add either
1533 protocol or field labels to the proto_tree:
1534
1535         proto_item*
1536         proto_tree_add_item(tree, id, tvb, start, length, little_endian);
1537
1538         proto_item*
1539         proto_tree_add_item_hidden(tree, id, tvb, start, length, little_endian);
1540
1541         proto_item*
1542         proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
1543
1544         proto_item*
1545         proto_tree_add_protocol_format(tree, id, tvb, start, length,
1546             format, ...);
1547
1548         proto_item *
1549         proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr);
1550
1551         proto_item *
1552         proto_tree_add_bytes_hidden(tree, id, tvb, start, length, start_ptr);
1553
1554         proto_item *
1555         proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr,
1556             format, ...);
1557
1558         proto_item *
1559         proto_tree_add_time(tree, id, tvb, start, length, value_ptr);
1560
1561         proto_item *
1562         proto_tree_add_time_hidden(tree, id, tvb, start, length, value_ptr);
1563
1564         proto_item *
1565         proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr,
1566             format, ...);
1567
1568         proto_item *
1569         proto_tree_add_ipxnet(tree, id, tvb, start, length, value);
1570
1571         proto_item *
1572         proto_tree_add_ipxnet_hidden(tree, id, tvb, start, length, value);
1573
1574         proto_item *
1575         proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value,
1576             format, ...);
1577
1578         proto_item *
1579         proto_tree_add_ipv4(tree, id, tvb, start, length, value);
1580
1581         proto_item *
1582         proto_tree_add_ipv4_hidden(tree, id, tvb, start, length, value);
1583
1584         proto_item *
1585         proto_tree_add_ipv4_format(tree, id, tvb, start, length, value,
1586             format, ...);
1587
1588         proto_item *
1589         proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr);
1590
1591         proto_item *
1592         proto_tree_add_ipv6_hidden(tree, id, tvb, start, length, value_ptr);
1593
1594         proto_item *
1595         proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr,
1596             format, ...);
1597
1598         proto_item *
1599         proto_tree_add_ether(tree, id, tvb, start, length, value_ptr);
1600
1601         proto_item *
1602         proto_tree_add_ether_hidden(tree, id, tvb, start, length, value_ptr);
1603
1604         proto_item *
1605         proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr,
1606             format, ...);
1607
1608         proto_item *
1609         proto_tree_add_string(tree, id, tvb, start, length, value_ptr);
1610
1611         proto_item *
1612         proto_tree_add_string_hidden(tree, id, tvb, start, length, value_ptr);
1613
1614         proto_item *
1615         proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr,
1616             format, ...);
1617
1618         proto_item *
1619         proto_tree_add_boolean(tree, id, tvb, start, length, value);
1620
1621         proto_item *
1622         proto_tree_add_boolean_hidden(tree, id, tvb, start, length, value);
1623
1624         proto_item *
1625         proto_tree_add_boolean_format(tree, id, tvb, start, length, value,
1626             format, ...);
1627
1628         proto_item *
1629         proto_tree_add_float(tree, id, tvb, start, length, value);
1630
1631         proto_item *
1632         proto_tree_add_float_hidden(tree, id, tvb, start, length, value);
1633
1634         proto_item *
1635         proto_tree_add_float_format(tree, id, tvb, start, length, value,
1636             format, ...);
1637
1638         proto_item *
1639         proto_tree_add_double(tree, id, tvb, start, length, value);
1640
1641         proto_item *
1642         proto_tree_add_double_hidden(tree, id, tvb, start, length, value);
1643
1644         proto_item *
1645         proto_tree_add_double_format(tree, id, tvb, start, length, value,
1646             format, ...);
1647
1648         proto_item *
1649         proto_tree_add_uint(tree, id, tvb, start, length, value);
1650
1651         proto_item *
1652         proto_tree_add_uint_hidden(tree, id, tvb, start, length, value);
1653
1654         proto_item *
1655         proto_tree_add_uint_format(tree, id, tvb, start, length, value,
1656             format, ...);
1657
1658         proto_item *
1659         proto_tree_add_uint64(tree, id, tvb, start, length, value);
1660
1661         proto_item *
1662         proto_tree_add_uint64_format(tree, id, tvb, start, length, value,
1663             format, ...);
1664
1665         proto_item *
1666         proto_tree_add_int(tree, id, tvb, start, length, value);
1667
1668         proto_item *
1669         proto_tree_add_int_hidden(tree, id, tvb, start, length, value);
1670
1671         proto_item *
1672         proto_tree_add_int_format(tree, id, tvb, start, length, value,
1673             format, ...);
1674
1675         proto_item *
1676         proto_tree_add_int64(tree, id, tvb, start, length, value);
1677
1678         proto_item *
1679         proto_tree_add_int64_format(tree, id, tvb, start, length, value,
1680             format, ...);
1681
1682         proto_item*
1683         proto_tree_add_text(tree, tvb, start, length, format, ...);
1684
1685         proto_item*
1686         proto_tree_add_text_valist(tree, tvb, start, length, format, ap);
1687
1688 The 'tree' argument is the tree to which the item is to be added.  The
1689 'tvb' argument is the tvbuff from which the item's value is being
1690 extracted; the 'start' argument is the offset from the beginning of that
1691 tvbuff of the item being added, and the 'length' argument is the length,
1692 in bytes, of the item.
1693
1694 The length of some items cannot be determined until the item has been
1695 dissected; to add such an item, add it with a length of -1, and, when the
1696 dissection is complete, set the length with 'proto_item_set_len()':
1697
1698         void
1699         proto_item_set_len(ti, length);
1700
1701 The "ti" argument is the value returned by the call that added the item
1702 to the tree, and the "length" argument is the length of the item.
1703
1704 proto_tree_add_item()
1705 ---------------------
1706 proto_tree_add_item is used when you wish to do no special formatting. 
1707 The item added to the GUI tree will contain the name (as passed in the
1708 proto_register_*() function) and a value.  The value will be fetched
1709 from the tvbuff by proto_tree_add_item(), based on the type of the field
1710 and, for integral and Boolean fields, the byte order of the value; the
1711 byte order is specified by the 'little_endian' argument, which is TRUE
1712 if the value is little-endian and FALSE if it is big-endian.
1713
1714 Now that definitions of fields have detailed information about bitfield
1715 fields, you can use proto_tree_add_item() with no extra processing to
1716 add bitfield values to your tree.  Here's an example.  Take the Format
1717 Identifer (FID) field in the Transmission Header (TH) portion of the SNA
1718 protocol.  The FID is the high nibble of the first byte of the TH.  The
1719 FID would be registered like this:
1720
1721         name            = "Format Identifer"
1722         abbrev          = "sna.th.fid"
1723         type            = FT_UINT8
1724         display         = BASE_HEX
1725         strings         = sna_th_fid_vals
1726         bitmask         = 0xf0
1727
1728 The bitmask contains the value which would leave only the FID if bitwise-ANDed
1729 against the parent field, the first byte of the TH.
1730
1731 The code to add the FID to the tree would be;
1732
1733         proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1, TRUE);
1734
1735 The definition of the field already has the information about bitmasking
1736 and bitshifting, so it does the work of masking and shifting for us!
1737 This also means that you no longer have to create value_string structs
1738 with the values bitshifted.  The value_string for FID looks like this,
1739 even though the FID value is actually contained in the high nibble. 
1740 (You'd expect the values to be 0x0, 0x10, 0x20, etc.)
1741
1742 /* Format Identifier */
1743 static const value_string sna_th_fid_vals[] = {
1744         { 0x0,  "SNA device <--> Non-SNA Device" },
1745         { 0x1,  "Subarea Node <--> Subarea Node" },
1746         { 0x2,  "Subarea Node <--> PU2" },
1747         { 0x3,  "Subarea Node or SNA host <--> Subarea Node" },
1748         { 0x4,  "?" },
1749         { 0x5,  "?" },
1750         { 0xf,  "Adjaced Subarea Nodes" },
1751         { 0,    NULL }
1752 };
1753
1754 The final implication of this is that display filters work the way you'd
1755 naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent
1756 Subarea Nodes. The user does not have to shift the value of the FID to
1757 the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
1758 before Ethereal 0.7.6.
1759
1760 proto_tree_add_item_hidden()
1761 ----------------------------
1762 proto_tree_add_item_hidden is used to add fields and values to a tree,
1763 but not show them on a GUI tree.  The caller may want a value to be
1764 included in a tree so that the packet can be filtered on this field, but
1765 the representation of that field in the tree is not appropriate.  An
1766 example is the token-ring routing information field (RIF).  The best way
1767 to show the RIF in a GUI is by a sequence of ring and bridge numbers. 
1768 Rings are 3-digit hex numbers, and bridges are single hex digits:
1769
1770         RIF: 001-A-013-9-C0F-B-555
1771
1772 In the case of RIF, the programmer should use a field with no value and
1773 use proto_tree_add_none_format() to build the above representation. The
1774 programmer can then add the ring and bridge values, one-by-one, with
1775 proto_tree_add_item_hidden() so that the user can then filter on or
1776 search for a particular ring or bridge. Here's a skeleton of how the
1777 programmer might code this.
1778
1779         char *rif;
1780         rif = create_rif_string(...);
1781
1782         proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
1783
1784         for(i = 0; i < num_rings; i++) {
1785                 proto_tree_add_item_hidden(tree, hf_tr_rif_ring, ..., FALSE);
1786         }
1787         for(i = 0; i < num_rings - 1; i++) {
1788                 proto_tree_add_item_hidden(tree, hf_tr_rif_bridge, ..., FALSE);
1789         }
1790
1791 The logical tree has these items:
1792
1793         hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
1794         hf_tr_rif_ring,  hidden, value=0x001
1795         hf_tr_rif_bridge, hidden, value=0xA
1796         hf_tr_rif_ring,  hidden, value=0x013
1797         hf_tr_rif_bridge, hidden, value=0x9
1798         hf_tr_rif_ring,  hidden, value=0xC0F
1799         hf_tr_rif_bridge, hidden, value=0xB
1800         hf_tr_rif_ring,  hidden, value=0x555
1801
1802 GUI or print code will not display the hidden fields, but a display
1803 filter or "packet grep" routine will still see the values. The possible
1804 filter is then possible:
1805
1806         tr.rif_ring eq 0x013
1807
1808 proto_tree_add_protocol_format()
1809 ----------------------------
1810 proto_tree_add_protocol_format is used to add the top-level item for the
1811 protocol when the dissector routines wants complete control over how the
1812 field and value will be represented on the GUI tree.  The ID value for
1813 the protocol is passed in as the "id" argument; the rest of the
1814 arguments are a "printf"-style format and any arguments for that format. 
1815 The caller must include the name of the protocol in the format; it is
1816 not added automatically as in proto_tree_add_item().
1817
1818 proto_tree_add_none_format()
1819 ----------------------------
1820 proto_tree_add_none_format is used to add an item of type FT_NONE.
1821 The caller must include the name of the field in the format; it is
1822 not added automatically as in proto_tree_add_item().
1823
1824 proto_tree_add_bytes()
1825 proto_tree_add_time()
1826 proto_tree_add_ipxnet()
1827 proto_tree_add_ipv4()
1828 proto_tree_add_ipv6()
1829 proto_tree_add_ether()
1830 proto_tree_add_string()
1831 proto_tree_add_boolean()
1832 proto_tree_add_float()
1833 proto_tree_add_double()
1834 proto_tree_add_uint()
1835 proto_tree_add_uint64()
1836 proto_tree_add_int()
1837 proto_tree_add_int64()
1838 ----------------------------
1839 These routines are used to add items to the protocol tree if either:
1840
1841         the value of the item to be added isn't just extracted from the
1842         packet data, but is computed from data in the packet;
1843
1844         the value was fetched into a variable.
1845
1846 The 'value' argument has the value to be added to the tree.
1847
1848 NOTE: in all cases where the 'value' argument is a pointer, a copy is
1849 made of the object pointed to; if you have dynamically allocated a
1850 buffer for the object, that buffer will not be freed when the protocol
1851 tree is freed - you must free the buffer yourself when you don't need it
1852 any more.
1853
1854 For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a
1855 sequence of bytes.
1856
1857 For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
1858 "nstime_t", which is a structure containing the time to be added; it has
1859 'secs' and 'nsecs' members, giving the integral part and the fractional
1860 part of a time in units of seconds, with 'nsecs' being the number of
1861 nanoseconds.  For absolute times, "secs" is a UNIX-style seconds since
1862 January 1, 1970, 00:00:00 GMT value.
1863
1864 For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
1865 network address.
1866
1867 For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4
1868 address, in network byte order.
1869
1870 For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a
1871 128-bit IPv6 address.
1872
1873 For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a
1874 48-bit MAC address.
1875
1876 For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a
1877 text string.
1878
1879 For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer;
1880 zero means "false", and non-zero means "true".
1881
1882 For proto_tree_add_float(), the 'value' argument is a 'float' in the
1883 host's floating-point format.
1884
1885 For proto_tree_add_double(), the 'value' argument is a 'double' in the
1886 host's floating-point format.
1887
1888 For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
1889 integer value, in host byte order.  (This routine cannot be used to add
1890 64-bit integers.)
1891
1892 For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
1893 integer value, in host byte order.
1894
1895 For proto_tree_add_int(), the 'value' argument is a 32-bit signed
1896 integer value, in host byte order.  (This routine cannot be used to add
1897 64-bit integers.)
1898
1899 For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
1900 integer value, in host byte order.
1901
1902 proto_tree_add_bytes_hidden()
1903 proto_tree_add_time_hidden()
1904 proto_tree_add_ipxnet_hidden()
1905 proto_tree_add_ipv4_hidden()
1906 proto_tree_add_ipv6_hidden()
1907 proto_tree_add_ether_hidden()
1908 proto_tree_add_string_hidden()
1909 proto_tree_add_boolean_hidden()
1910 proto_tree_add_float_hidden()
1911 proto_tree_add_double_hidden()
1912 proto_tree_add_uint_hidden()
1913 proto_tree_add_int_hidden()
1914 ----------------------------
1915 These routines add fields and values to a tree, but don't show them in
1916 the GUI tree.  They are used for the same reason that
1917 proto_tree_add_item() is used.
1918
1919 proto_tree_add_bytes_format()
1920 proto_tree_add_time_format()
1921 proto_tree_add_ipxnet_format()
1922 proto_tree_add_ipv4_format()
1923 proto_tree_add_ipv6_format()
1924 proto_tree_add_ether_format()
1925 proto_tree_add_string_format()
1926 proto_tree_add_boolean_format()
1927 proto_tree_add_float_format()
1928 proto_tree_add_double_format()
1929 proto_tree_add_uint_format()
1930 proto_tree_add_uint64_format()
1931 proto_tree_add_int_format()
1932 proto_tree_add_int64_format()
1933 ----------------------------
1934 These routines are used to add items to the protocol tree when the
1935 dissector routines wants complete control over how the field and value
1936 will be represented on the GUI tree.  The argument giving the value is
1937 the same as the corresponding proto_tree_add_XXX() function; the rest of
1938 the arguments are a "printf"-style format and any arguments for that
1939 format.  The caller must include the name of the field in the format; it
1940 is not added automatically as in the proto_tree_add_XXX() functions.
1941
1942 proto_tree_add_text()
1943 ---------------------
1944 proto_tree_add_text() is used to add a label to the GUI tree.  It will
1945 contain no value, so it is not searchable in the display filter process. 
1946 This function was needed in the transition from the old-style proto_tree
1947 to this new-style proto_tree so that Ethereal would still decode all
1948 protocols w/o being able to filter on all protocols and fields. 
1949 Otherwise we would have had to cripple Ethereal's functionality while we
1950 converted all the old-style proto_tree calls to the new-style proto_tree
1951 calls.
1952
1953 This can also be used for items with subtrees, which may not have values
1954 themselves - the items in the subtree are the ones with values.
1955
1956 For a subtree, the label on the subtree might reflect some of the items
1957 in the subtree.  This means the label can't be set until at least some
1958 of the items in the subtree have been dissected.  To do this, use
1959 'proto_item_set_text()' or 'proto_item_append_text()':
1960
1961         void
1962         proto_item_set_text(proto_item *ti, ...);
1963
1964         void
1965         proto_item_append_text(proto_item *ti, ...);
1966
1967 'proto_item_set_text()' takes as an argument the value returned by
1968 'proto_tree_add_text()', a 'printf'-style format string, and a set of
1969 arguments corresponding to '%' format items in that string, and replaces
1970 the text for the item created by 'proto_tree_add_text()' with the result
1971 of applying the arguments to the format string. 
1972
1973 'proto_item_append_text()' is similar, but it appends to the text for
1974 the item the result of applying the arguments to the format string.
1975
1976 For example, early in the dissection, one might do:
1977
1978         ti = proto_tree_add_text(tree, tvb, offset, length, <label>);
1979
1980 and later do
1981
1982         proto_item_set_text(ti, "%s: %s", type, value);
1983
1984 after the "type" and "value" fields have been extracted and dissected. 
1985 <label> would be a label giving what information about the subtree is
1986 available without dissecting any of the data in the subtree.
1987
1988 Note that an exception might thrown when trying to extract the values of
1989 the items used to set the label, if not all the bytes of the item are
1990 available.  Thus, one should create the item with text that is as
1991 meaningful as possible, and set it or append additional information to
1992 it as the values needed to supply that information is extracted.
1993
1994 proto_tree_add_text_valist()
1995 ---------------------
1996 This is like proto_tree_add_text(), but takes, as the last argument, a
1997 'va_list'; it is used to allow routines that take a printf-like
1998 variable-length list of arguments to add a text item to the protocol
1999 tree.
2000
2001 1.7 Utility routines
2002
2003 1.7.1 match_strval and val_to_str
2004
2005 A dissector may need to convert a value to a string, using a
2006 'value_string' structure, by hand, rather than by declaring a field with
2007 an associated 'value_string' structure; this might be used, for example,
2008 to generate a COL_INFO line for a frame.
2009
2010 'match_strval()' will do that:
2011
2012         gchar*
2013         match_strval(guint32 val, const value_string *vs)
2014
2015 It will look up the value 'val' in the 'value_string' table pointed to
2016 by 'vs', and return either the corresponding string, or NULL if the
2017 value could not be found in the table.  Note that, unless 'val' is
2018 guaranteed to be a value in the 'value_string' table ("guaranteed" as in
2019 "the code has already checked that it's one of those values" or "the
2020 table handles all possible values of the size of 'val'", not "the
2021 protocol spec says it has to be" - protocol specs do not prevent invalid
2022 packets from being put onto a network or into a purported packet capture
2023 file), you must check whether 'match_strval()' returns NULL, and arrange
2024 that its return value not be dereferenced if it's NULL.  In particular,
2025 don't use it in a call to generate a COL_INFO line for a frame such as
2026
2027         col_add_fstr(COL_INFO, ", %s", match_strval(val, table));
2028
2029 unless is it certain that 'val' is in 'table'.
2030
2031 'val_to_str()' can be used to generate a string for values not found in
2032 the table:
2033
2034         gchar*
2035         val_to_str(guint32 val, const value_string *vs, const char *fmt)
2036
2037 If the value 'val' is found in the 'value_string' table pointed to by
2038 'vs', 'val_to_str' will return the corresponding string; otherwise, it
2039 will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
2040 to generate a string, and will return a pointer to that string. 
2041 (Currently, it has three 64-byte static buffers, and cycles through
2042 them; this permits the results of up to three calls to 'val_to_str' to
2043 be passed as arguments to a routine using those strings.)
2044
2045
2046 1.8 Calling Other Dissectors
2047
2048 NOTE: This is discussed in the README.tvbuff file.  For more 
2049 information on tvbuffers consult that file.
2050
2051 As each dissector completes its portion of the protocol analysis, it
2052 is expected to create a new tvbuff of type TVBUFF_SUBSET which
2053 contains the payload portion of the protocol (that is, the bytes
2054 that are relevant to the next dissector).
2055
2056 The syntax for creating a new TVBUFF_SUBSET is:
2057
2058 next_tvb = tvb_new_subset(tvb, offset, length, reported_length)
2059
2060 Where:
2061         tvb is the tvbuff that the dissector has been working on. It
2062         can be a tvbuff of any type.
2063
2064         next_tvb is the new TVBUFF_SUBSET.
2065
2066         offset is the byte offset of 'tvb' at which the new tvbuff
2067         should start.  The first byte is the 0th byte.
2068
2069         length is the number of bytes in the new TVBUFF_SUBSET. A length
2070         argument of -1 says to use as many bytes as are available in
2071         'tvb'.
2072
2073         reported_length is the number of bytes that the current protocol
2074         says should be in the payload. A reported_length of -1 says that
2075         the protocol doesn't say anything about the size of its payload.
2076
2077
2078 An example from packet-ipx.c -
2079
2080 void
2081 dissect_ipx(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
2082 {
2083         tvbuff_t        *next_tvb;
2084         int             reported_length, available_length;
2085
2086  
2087         /* Make the next tvbuff */
2088
2089 /* IPX does have a length value in the header, so calculate report_length */
2090    Set this to -1 if there isn't any length information in the protocol
2091 */
2092         reported_length = ipx_length - IPX_HEADER_LEN;
2093
2094 /* Calculate the available data in the packet, 
2095    set this to -1 to use all the data in the tv_buffer
2096 */
2097         available_length = tvb_length(tvb) - IPX_HEADER_LEN;
2098
2099 /* Create the tvbuffer for the next dissector */
2100         next_tvb = tvb_new_subset(tvb, IPX_HEADER_LEN,
2101                         MIN(available_length, reported_length),
2102                         reported_length);
2103
2104 /* call the next dissector */
2105         dissector_next( next_tvb, pinfo, tree);
2106
2107
2108 1.9 Editing Makefile.common to add your dissector.
2109
2110 To arrange that your dissector will be built as part of Ethereal, you
2111 must add the name of the source file for your dissector to the
2112 'DISSECTOR_SRC' macro in the 'Makefile.common' file in the 'epan/dissectors'
2113 directory.  (Note that this is for modern versions of UNIX, so there
2114 is no 14-character limitation on file names, and for modern versions of
2115 Windows, so there is no 8.3-character limitation on file names.)
2116
2117 If your dissector also has its own header file or files, you must add
2118 them to the 'DISSECTOR_INCLUDES' macro in the 'Makefile.common' file in
2119 the 'epan/dissectors' directory, so that it's included when release source
2120 tarballs are built (otherwise, the source in the release tarballs won't
2121 compile).
2122
2123 1.10 Using the SVN source code tree.
2124
2125   See <http://www.ethereal.com/development.html#source>
2126
2127 1.11 Submitting code for your new dissector.
2128
2129   - TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
2130     Use fuzz-test.sh and/or randpkt against your dissector.  These are
2131     described at <http://wiki.ethereal.com/FuzzTesting>.
2132
2133   - Subscribe to <mailto:ethereal-dev@ethereal.com> by sending an email to
2134     <mailto:ethereal-dev-request@ethereal.com?body="help"> or visiting 
2135     <http://www.ethereal.com/lists/>.
2136   
2137   - 'svn add' all the files of your new dissector.
2138   
2139   - 'svn diff' the workspace and save the result to a file.
2140   
2141   - Send the diff file along with a note requesting it's inclusion to
2142     <mailto:ethereal-dev@ethereal.com>. You can also use this procedure for
2143     providing patches to your dissector or any other part of ethereal.
2144
2145   - If possible, add sample capture files to the sample captures page at
2146     <http://wiki.ethereal.com/SampleCaptures>.  These files are used by
2147     the automated build system for fuzz testing.
2148
2149   - If you find that you are contributing a lot to ethereal on an ongoing
2150     basis you can request to become a committer which will allow you to
2151     commit files to subversion directly.
2152
2153 2. Advanced dissector topics.
2154
2155 2.1 ?? 
2156
2157 2.2 Following "conversations".
2158
2159 In ethereal a conversation is defined as a series of data packet between two
2160 address:port combinations.  A conversation is not sensitive to the direction of
2161 the packet.  The same conversation will be returned for a packet bound from
2162 ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
2163
2164 There are five routines that you will use to work with a conversation:
2165 conversation_new, find_conversation, conversation_add_proto_data,
2166 conversation_get_proto_data, and conversation_delete_proto_data.
2167
2168
2169 2.2.1 The conversation_init function.
2170
2171 This is an internal routine for the conversation code.  As such the you
2172 will not have to call this routine.  Just be aware that this routine is
2173 called at the start of each capture and before the packets are filtered
2174 with a display filter.  The routine will destroy all stored
2175 conversations.  This routine does NOT clean up any data pointers that are
2176 passed in the conversation_new 'data' variable.  You are responsible for
2177 this clean up if you pass a malloc'ed pointer in this variable.
2178
2179 See item 2.2.7 for more information about the 'data' pointer.
2180
2181
2182 2.2.2 The conversation_new function.
2183
2184 This routine will create a new conversation based upon two address/port
2185 pairs.  If you want to associate with the conversation a pointer to a
2186 private data structure you must use the conversation_add_proto_data
2187 function.  The ptype variable is used to differentiate between
2188 conversations over different protocols, i.e. TCP and UDP.  The options
2189 variable is used to define a conversation that will accept any destination
2190 address and/or port.  Set options = 0 if the destination port and address
2191 are know when conversation_new is called.  See section 2.4 for more
2192 information on usage of the options parameter.
2193
2194 The conversation_new prototype:
2195         conversation_t *conversation_new(guint32 setup_frame, address *addr1,
2196             address *addr2, port_type ptype, guint32 port1, guint32 port2,
2197             guint options);
2198
2199 Where:
2200         guint32 setup_frame = The lowest numbered frame for this conversation
2201         address* addr1      = first data packet address
2202         address* addr2      = second data packet address
2203         port_type ptype     = port type, this is defined in packet.h
2204         guint32 port1       = first data packet port
2205         guint32 port2       = second data packet port
2206         guint options       = conversation options, NO_ADDR2 and/or NO_PORT2
2207
2208 setup_frame indicates the first frame for this conversation, and is used to
2209 distinguish multiple conversations with the same addr1/port1 and addr2/port2
2210 pair that occur within the same capture session.
2211
2212 "addr1" and "port1" are the first address/port pair; "addr2" and "port2"
2213 are the second address/port pair.  A conversation doesn't have source
2214 and destination address/port pairs - packets in a conversation go in
2215 both directions - so "addr1"/"port1" may be the source or destination
2216 address/port pair; "addr2"/"port2" would be the other pair.
2217
2218 If NO_ADDR2 is specified, the conversation is set up so that a
2219 conversation lookup will match only the "addr1" address; if NO_PORT2 is
2220 specified, the conversation is set up so that a conversation lookup will
2221 match only the "port1" port; if both are specified, i.e.
2222 NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
2223 match only the "addr1"/"port1" address/port pair.  This can be used if a
2224 packet indicates that, later in the capture, a conversation will be
2225 created using certain addresses and ports, in the case where the packet
2226 doesn't specify the addresses and ports of both sides.
2227
2228 2.2.3 The find_conversation function.
2229
2230 Call this routine to look up a conversation.  If no conversation is found,
2231 the routine will return a NULL value.
2232
2233 The find_conversation prototype:
2234
2235         conversation_t *find_conversation(guint32 frame_num, address *addr_a,
2236             address *addr_b, port_type ptype, guint32 port_a, guint32 port_b,
2237             guint options);
2238
2239 Where:
2240         guint32 frame_num = a frame number to match
2241         address* addr_a = first address
2242         address* addr_b = second address
2243         port_type ptype = port type
2244         guint32 port_a  = first data packet port
2245         guint32 port_b  = second data packet port
2246         guint options   = conversation options, NO_ADDR_B and/or NO_PORT_B
2247
2248 frame_num is a frame number to match. The conversation returned is where
2249         (frame_num >= conversation->setup_frame
2250         && frame_num < conversation->next->setup_frame)
2251 Suppose there are a total of 3 conversations (A, B, and C) that match
2252 addr_a/port_a and addr_b/port_b, where the setup_frame used in
2253 conversation_new() for A, B and C are 10, 50, and 100 respectively. The
2254 frame_num passed in find_conversation is compared to the setup_frame of each
2255 conversation. So if (frame_num >= 10 && frame_num < 50), conversation A is
2256 returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned.
2257 If (frame_num >= 100) conversation C is returned.
2258
2259 "addr_a" and "port_a" are the first address/port pair; "addr_b" and
2260 "port_b" are the second address/port pair.  Again, as a conversation
2261 doesn't have source and destination address/port pairs, so
2262 "addr_a"/"port_a" may be the source or destination address/port pair;
2263 "addr_b"/"port_b" would be the other pair.  The search will match the
2264 "a" address/port pair against both the "1" and "2" address/port pairs,
2265 and match the "b" address/port pair against both the "2" and "1"
2266 address/port pairs; you don't have to worry about which side the "a" or
2267 "b" pairs correspond to.
2268
2269 If the NO_ADDR_B flag was specified to "find_conversation()", the
2270 "addr_b" address will be treated as matching any "wildcarded" address;
2271 if the NO_PORT_B flag was specified, the "port_b" port will be treated
2272 as matching any "wildcarded" port.  If both flags are specified, i.e. 
2273 NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
2274 any "wildcarded" address and the "port_b" port will be treated as
2275 matching any "wildcarded" port.
2276
2277
2278 2.2.4 The conversation_add_proto_data function.
2279
2280 Once you have created a conversation with conversation_new, you can
2281 associate data with it using this function.
2282
2283 The conversation_add_proto_data prototype:
2284
2285         void conversation_add_proto_data(conversation_t *conv, int proto,
2286             void *proto_data);
2287
2288 Where:
2289         conversation_t *conv = the conversation in question
2290         int proto            = registered protocol number
2291         void *data           = dissector data structure
2292
2293 "conversation" is the value returned by conversation_new.  "proto" is a
2294 unique protocol number created with proto_register_protocol.  Protocols
2295 are typically registered in the proto_register_XXXX section of your
2296 dissector.  "data" is a pointer to the data you wish to associate with the
2297 conversation.  Using the protocol number allows several dissectors to
2298 associate data with a given conversation.
2299
2300
2301 2.2.5 The conversation_get_proto_data function.
2302
2303 After you have located a conversation with find_conversation, you can use
2304 this function to retrieve any data associated with it.
2305
2306 The conversation_get_proto_data prototype:
2307
2308         void *conversation_get_proto_data(conversation_t *conv, int proto);
2309
2310 Where:
2311         conversation_t *conv = the conversation in question
2312         int proto            = registered protocol number
2313         
2314 "conversation" is the conversation created with conversation_new.  "proto"
2315 is a unique protocol number acreated with proto_register_protocol,
2316 typically in the proto_register_XXXX portion of a dissector.  The function
2317 returns a pointer to the data requested, or NULL if no data was found.
2318
2319
2320 2.2.6 The conversation_delete_proto_data function.
2321
2322 After you are finished with a conversation, you can remove your assocation
2323 with this function.  Please note that ONLY the conversation entry is
2324 removed.  If you have allocated any memory for your data, you must free it
2325 as well.
2326
2327 The conversation_delete_proto_data prototype:
2328
2329         void conversation_delete_proto_data(conversation_t *conv, int proto);
2330         
2331 Where:
2332         conversation_t *conv = the conversation in question
2333         int proto            = registered protocol number
2334
2335 "conversation" is the conversation created with conversation_new.  "proto"
2336 is a unique protocol number acreated with proto_register_protocol,
2337 typically in the proto_register_XXXX portion of a dissector.
2338
2339 2.2.7 The example conversation code with GMemChunk's
2340
2341 For a conversation between two IP addresses and ports you can use this as an
2342 example.  This example uses the GMemChunk to allocate memory and stores the data
2343 pointer in the conversation 'data' variable.
2344
2345 NOTE: Remember to register the init routine (my_dissector_init) in the
2346 protocol_register routine.
2347
2348
2349 /************************ Globals values ************************/
2350
2351 /* the number of entries in the memory chunk array */
2352 #define my_init_count 10
2353
2354 /* define your structure here */
2355 typedef struct {
2356
2357 }my_entry_t;
2358
2359 /* the GMemChunk base structure */
2360 static GMemChunk *my_vals = NULL;
2361
2362 /* Registered protocol number
2363 static int my_proto = -1;
2364
2365
2366 /********************* in the dissector routine *********************/
2367
2368 /* the local variables in the dissector */
2369
2370 conversation_t *conversation;
2371 my_entry_t *data_ptr
2372
2373
2374 /* look up the conversation */
2375
2376 conversation = find_conversation(pinfo->fd->num, &pinfo->src, &pinfo->dst,
2377         pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2378
2379 /* if conversation found get the data pointer that you stored */
2380 if ( conversation)
2381     data_ptr = (my_entry_t*)conversation_get_proto_data(conversation,
2382             my_proto);
2383 else {
2384
2385     /* new conversation create local data structure */
2386
2387     data_ptr = g_mem_chunk_alloc(my_vals);
2388
2389     /*** add your code here to setup the new data structure ***/
2390
2391     /* create the conversation with your data pointer  */
2392
2393     conversation_new(pinfo->fd->num,  &pinfo->src, &pinfo->dst, pinfo->ptype,
2394             pinfo->srcport, pinfo->destport, 0);
2395     conversation_add_proto_data(conversation, my_proto, (void *) data_ptr);
2396 }
2397
2398 /* at this point the conversation data is ready */
2399
2400
2401 /******************* in the dissector init routine *******************/
2402
2403 #define my_init_count 20
2404
2405 static void
2406 my_dissector_init( void){
2407
2408     /* destroy memory chunks if needed */
2409
2410     if ( my_vals)
2411         g_mem_chunk_destroy(my_vals);
2412
2413     /* now create memory chunks */
2414
2415     my_vals = g_mem_chunk_new( "my_proto_vals",
2416             sizeof( _entry_t),
2417             my_init_count * sizeof( my_entry_t),
2418             G_ALLOC_AND_FREE);
2419 }
2420
2421 /***************** in the protocol register routine *****************/
2422
2423 /* register re-init routine */
2424
2425 register_init_routine( &my_dissector_init);
2426
2427 my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto");
2428
2429
2430 2.2.8 An example conversation code that starts at a specific frame number
2431
2432 Sometimes a disector has determined that a new conversation is needed that
2433 starts at a specific frame number, when a capture session encompasses multiple
2434 conversation that reuse the same src/dest ip/port pairs. You can use the
2435 compare the conversation->setup_frame returned by find_conversation with
2436 pinfo->fd->num to determine whether or not there already exists a conversation
2437 that starts at the specific frame number.
2438
2439 /* in the dissector routine */
2440
2441         conversation = find_conversation(pinfo->fd->num, &pinfo->src, &pinfo->dst,
2442             pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2443         if (conversation == NULL || (conversation->setup_frame != pinfo->fd->num)) {
2444                 /* It's not part of any conversation or the returned
2445                  * conversation->setup_frame doesn't match the current frame
2446                  * create a new one.
2447                  */
2448                 conversation = conversation_new(pinfo->fd->num, &pinfo->src,
2449                     &pinfo->dst, pinfo->ptype, pinfo->srcport, pinfo->destport,
2450                     NULL, 0);
2451         }
2452
2453
2454 2.2.9 The example conversation code using conversation index field
2455
2456 Sometimes the conversation isn't enough to define a unique data storage
2457 value for the network traffic.  For example if you are storing information
2458 about requests carried in a conversation, the request may have an
2459 identifier that is used to  define the request. In this case the
2460 conversation and the identifier are required to find the data storage
2461 pointer.  You can use the conversation data structure index value to
2462 uniquely define the conversation.  
2463
2464 See packet-afs.c for an example of how to use the conversation index.  In
2465 this dissector multiple requests are sent in the same conversation.  To store
2466 information for each request the dissector has an internal hash table based
2467 upon the conversation index and values inside the request packets. 
2468
2469
2470         /* in the dissector routine */
2471
2472         /* to find a request value, first lookup conversation to get index */
2473         /* then used the conversation index, and request data to find data */
2474         /* in the local hash table */
2475
2476         conversation = find_conversation(pinfo->fd->num, &pinfo->src, &pinfo->dst,
2477             pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2478         if (conversation == NULL) {
2479                 /* It's not part of any conversation - create a new one. */
2480                 conversation = conversation_new(pinfo->fd->num, &pinfo->src,
2481                     &pinfo->dst, pinfo->ptype, pinfo->srcport, pinfo->destport,
2482                     NULL, 0);
2483         }
2484
2485         request_key.conversation = conversation->index; 
2486         request_key.service = pntohs(&rxh->serviceId);
2487         request_key.callnumber = pntohl(&rxh->callNumber);
2488
2489         request_val = (struct afs_request_val *) g_hash_table_lookup(
2490                 afs_request_hash, &request_key);
2491
2492         /* only allocate a new hash element when it's a request */
2493         opcode = 0;
2494         if ( !request_val && !reply)
2495         {
2496                 new_request_key = g_mem_chunk_alloc(afs_request_keys);
2497                 *new_request_key = request_key;
2498
2499                 request_val = g_mem_chunk_alloc(afs_request_vals);
2500                 request_val -> opcode = pntohl(&afsh->opcode);
2501                 opcode = request_val->opcode;
2502
2503                 g_hash_table_insert(afs_request_hash, new_request_key,
2504                         request_val);
2505         }
2506
2507
2508
2509 2.3 Dynamic conversation dissector registration
2510
2511
2512 NOTE:   This sections assumes that all information is available to
2513         create a complete conversation, source port/address and
2514         destination port/address.  If either the destination port or
2515         address is know, see section 2.4 Dynamic server port dissector
2516         registration.
2517
2518 For protocols that negotiate a secondary port connection, for example
2519 packet-msproxy.c, a conversation can install a dissector to handle 
2520 the secondary protocol dissection.  After the conversation is created
2521 for the negotiated ports use the conversation_set_dissector to define
2522 the dissection routine.
2523 Before we create these conversations or assign a dissector to them we should
2524 first check that the conversation does not already exist and if it exists
2525 whether it is registered to our protocol or not.
2526 We should do this because is uncommon but it does happen that multiple 
2527 different protocols can use the same socketpair during different stages of 
2528 an application cycle. By keeping track of the frame number a conversation
2529 was started in ethereal can still tell these different protocols apart.
2530
2531 The second argument to conversation_set_dissector is a dissector handle,
2532 which is created with a call to create_dissector_handle or
2533 register_dissector.
2534
2535 create_dissector_handle takes as arguments a pointer to the dissector
2536 function and a protocol ID as returned by proto_register_protocol;
2537 register_dissector takes as arguments a string giving a name for the
2538 dissector, a pointer to the dissector function, and a protocol ID.
2539
2540 The protocol ID is the ID for the protocol dissected by the function. 
2541 The function will not be called if the protocol has been disabled by the
2542 user; instead, the data for the protocol will be dissected as raw data.
2543
2544 An example -
2545
2546 /* the handle for the dynamic dissector *
2547 static dissector_handle_t sub_dissector_handle;
2548
2549 /* prototype for the dynamic dissector */
2550 static void sub_dissector( tvbuff_t *tvb, packet_info *pinfo,
2551                 proto_tree *tree);
2552
2553 /* in the main protocol dissector, where the next dissector is setup */
2554
2555 /* if conversation has a data field, create it and load structure */
2556
2557 /* First check if a conversation already exists for this 
2558         socketpair
2559 */
2560         conversation = find_conversation(pinfo->fd->num, 
2561                                 &pinfo->src, &pinfo->dst, protocol, 
2562                                 src_port, dst_port, new_conv_info, 0);
2563
2564 /* If there is no such conversation, or if there is one but for 
2565    someone elses protocol then we just create a new conversation
2566    and assign our protocol to it.
2567 */
2568         if( (conversation==NULL) 
2569           || (conversation->dissector_handle!=sub_dissector_handle) ){
2570             new_conv_info = g_mem_chunk_alloc( new_conv_vals);
2571             new_conv_info->data1 = value1;
2572
2573 /* create the conversation for the dynamic port */
2574             conversation = conversation_new(pinfo->fd->num, 
2575                     &pinfo->src, &pinfo->dst, protocol,
2576                     src_port, dst_port, new_conv_info, 0);
2577
2578 /* set the dissector for the new conversation */
2579             conversation_set_dissector(conversation, sub_dissector_handle);
2580         }
2581                 ...
2582
2583 void
2584 proto_register_PROTOABBREV(void)
2585 {                 
2586         ...
2587
2588         sub_dissector_handle = create_dissector_handle(sub_dissector,
2589             proto);
2590
2591         ...
2592 }
2593
2594 2.4 Dynamic server port dissector registration
2595
2596 NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
2597 conversation with only one port and address set, this isn't a
2598 requirement.  Either the second port or the second address can be set
2599 when the conversation is created.
2600
2601 For protocols that define a server address and port for a secondary
2602 protocol, a conversation can be used to link a protocol dissector to
2603 the server port and address.  The key is to create the new 
2604 conversation with the second address and port set to the "accept
2605 any" values.  
2606
2607 Some server applications can use the same port for different protocols during 
2608 different stages of a transaction. For example it might initially use SNMP
2609 to perform some discovery and later switch to use TFTP using the same port.
2610 In order to handle this properly we must first check whether such a 
2611 conversation already exists or not and if it exists we also check whether the
2612 registered dissector_handle for that conversation is "our" dissector or not.
2613 If not we create a new conversation ontop of the previous one and set this new 
2614 conversation to use our protocol.
2615 Since ethereal keeps track of the frame number where a conversation started
2616 ethereal will still be able to keep the packets apart eventhough they do use
2617 the same socketpair.
2618                 (See packet-tftp.c and packet-snmp.c for examples of this)
2619
2620 There are two support routines that will allow the second port and/or
2621 address to be set latter.  
2622
2623 conversation_set_port2( conversation_t *conv, guint32 port);
2624 conversation_set_addr2( conversation_t *conv, address addr);
2625
2626 These routines will change the second address or port for the
2627 conversation.  So, the server port conversation will be converted into a
2628 more complete conversation definition.  Don't use these routines if you
2629 want create a conversation between the server and client and retain the
2630 server port definition, you must create a new conversation.
2631
2632
2633 An example -
2634
2635 /* the handle for the dynamic dissector *
2636 static dissector_handle_t sub_dissector_handle;
2637
2638         ...
2639
2640 /* in the main protocol dissector, where the next dissector is setup */
2641
2642 /* if conversation has a data field, create it and load structure */
2643
2644         new_conv_info = g_mem_chunk_alloc( new_conv_vals);
2645         new_conv_info->data1 = value1;
2646
2647 /* create the conversation for the dynamic server address and port      */
2648 /* NOTE: The second address and port values don't matter because the    */
2649 /* NO_ADDR2 and NO_PORT2 options are set.                               */
2650
2651 /* First check if a conversation already exists for this 
2652         IP/protocol/port
2653 */
2654         conversation = find_conversation(pinfo->fd->num, 
2655                                 &server_src_addr, 0, protocol, 
2656                                 server_src_port, 0, NO_ADDR2 | NO_PORT_B);
2657 /* If there is no such conversation, or if there is one but for 
2658    someone elses protocol then we just create a new conversation
2659    and assign our protocol to it.
2660 */
2661         if( (conversation==NULL) 
2662           || (conversation->dissector_handle!=sub_dissector_handle) ){
2663             conversation = conversation_new(pinfo->fd->num,  
2664                 &server_src_addr, 0, protocol,
2665                 server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2);
2666
2667 /* set the dissector for the new conversation */
2668             conversation_set_dissector(conversation, sub_dissector_handle);
2669         }
2670
2671 2.5 Per packet information
2672
2673 Information can be stored for each data packet that is processed by the dissector.
2674 The information is added with the p_add_proto_data function and retreived with the 
2675 p_get_proto_data function.  The data pointers passed into the p_add_proto_data are
2676 not managed by the proto_data routines. If you use malloc or any other dynamic 
2677 memory allocation scheme, you must release the data when it isn't required.
2678
2679 void
2680 p_add_proto_data(frame_data *fd, int proto, void *proto_data)
2681 void *
2682 p_get_proto_data(frame_data *fd, int proto)
2683
2684 Where: 
2685         fd         - The fd pointer in the pinfo structure, pinfo->fd
2686         proto      - Protocol id returned by the proto_register_protocol call during initialization
2687         proto_data - pointer to the dissector data.
2688
2689
2690 2.6 User Preferences
2691
2692 If the dissector has user options, there is support for adding these preferences
2693 to a configuration dialog.
2694
2695 You must register the module with the preferences routine with -
2696
2697 module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void))
2698
2699 Where: proto_id   - the value returned by "proto_register_protocol()" when
2700                     the protocol was registered
2701          apply_cb - Callback routine that is call when preferences are applied
2702
2703
2704 Then you can register the fields that can be configured by the user with these routines -
2705
2706         /* Register a preference with an unsigned integral value. */
2707         void prefs_register_uint_preference(module_t *module, const char *name,
2708             const char *title, const char *description, guint base, guint *var);
2709
2710         /* Register a preference with an Boolean value. */
2711         void prefs_register_bool_preference(module_t *module, const char *name,
2712             const char *title, const char *description, gboolean *var);
2713
2714         /* Register a preference with an enumerated value. */
2715         void prefs_register_enum_preference(module_t *module, const char *name,
2716             const char *title, const char *description, gint *var,
2717             const enum_val_t *enumvals, gboolean radio_buttons)
2718
2719         /* Register a preference with a character-string value. */
2720         void prefs_register_string_preference(module_t *module, const char *name,
2721             const char *title, const char *description, char **var)
2722
2723         /* Register a preference with a range of unsigned integers (e.g.,
2724          * "1-20,30-40").
2725          */
2726         void prefs_register_range_preference(module_t *module, const char *name,
2727             const char *title, const char *description, range_t *var,
2728             guint32 max_value)
2729
2730 Where: module - Returned by the prefs_register_protocol routine
2731          name     - This is appended to the name of the protocol, with a
2732                     "." between them, to construct a name that identifies
2733                     the field in the preference file; the name itself
2734                     should not include the protocol name, as the name in
2735                     the preference file will already have it
2736          title    - Field title in the preferences dialog
2737          description - Comments added to the preference file above the 
2738                        preference value
2739          var      - pointer to the storage location that is updated when the
2740                     field is changed in the preference dialog box
2741          enumvals - an array of enum_val_t structures.  This must be
2742                     NULL-terminated; the members of that structure are:
2743
2744                         a short name, to be used with the "-o" flag - it
2745                         should not contain spaces or upper-case letters,
2746                         so that it's easier to put in a command line;
2747
2748                         a description, which is used in the GUI (and
2749                         which, for compatibility reasons, is currently
2750                         what's written to the preferences file) - it can
2751                         contain spaces, capital letters, punctuation,
2752                         etc.;
2753
2754                         the numerical value corresponding to that name
2755                         and description
2756          radio_buttons - TRUE if the field is to be displayed in the
2757                          preferences dialog as a set of radio buttons,
2758                          FALSE if it is to be displayed as an option
2759                          menu
2760          max_value - The maximum allowed value for a range (0 is the minimum).
2761
2762 An example from packet-beep.c -
2763         
2764   proto_beep = proto_register_protocol("Blocks Extensible Exchange Protocol",
2765                                        "BEEP", "beep");
2766
2767         ...
2768
2769   /* Register our configuration options for BEEP, particularly our port */
2770
2771   beep_module = prefs_register_protocol(proto_beep, proto_reg_handoff_beep);
2772
2773   prefs_register_uint_preference(beep_module, "tcp.port", "BEEP TCP Port",
2774                                  "Set the port for BEEP messages (if other"
2775                                  " than the default of 10288)",
2776                                  10, &global_beep_tcp_port);
2777
2778   prefs_register_bool_preference(beep_module, "strict_header_terminator", 
2779                                  "BEEP Header Requires CRLF", 
2780                                  "Specifies that BEEP requires CRLF as a "
2781                                  "terminator, and not just CR or LF",
2782                                  &global_beep_strict_term);
2783
2784 This will create preferences "beep.tcp.port" and
2785 "beep.strict_header_terminator", the first of which is an unsigned
2786 integer and the second of which is a Boolean.
2787
2788 2.7 Reassembly/desegmentation for protocols running atop TCP
2789
2790 There are two main ways of reassembling a Protocol Data Unit (PDU) which
2791 spans across multiple TCP segments.  The first approach is simpler, but  
2792 assumes you are running atop of TCP when this occurs (but your dissector  
2793 might run atop of UDP, too, for example), and that your PDUs consist of a  
2794 fixed amount of data that includes enough information to determine the PDU 
2795 length, possibly followed by additional data.  The second method is more 
2796 generic but requires more code and is less efficient.
2797
2798 2.7.1 Using tcp_dissect_pdus()
2799
2800 For the first method, you register two different dissection methods, one
2801 for the TCP case, and one for the other cases.  It is a good idea to
2802 also have a dissect_PROTO_common function which will parse the generic
2803 content that you can find in all PDUs which is called from
2804 dissect_PROTO_tcp when the reassembly is complete and from
2805 dissect_PROTO_udp (or dissect_PROTO_other).
2806
2807 To register the distinct dissector functions, consider the following
2808 example, stolen from packet-dns.c:
2809
2810         dissector_handle_t dns_udp_handle;
2811         dissector_handle_t dns_tcp_handle;
2812         dissector_handle_t mdns_udp_handle;
2813
2814         dns_udp_handle = create_dissector_handle(dissect_dns_udp,
2815             proto_dns);
2816         dns_tcp_handle = create_dissector_handle(dissect_dns_tcp,
2817             proto_dns);
2818         mdns_udp_handle = create_dissector_handle(dissect_mdns_udp,
2819             proto_dns);
2820
2821         dissector_add("udp.port", UDP_PORT_DNS, dns_udp_handle);
2822         dissector_add("tcp.port", TCP_PORT_DNS, dns_tcp_handle);
2823         dissector_add("udp.port", UDP_PORT_MDNS, mdns_udp_handle);
2824         dissector_add("tcp.port", TCP_PORT_MDNS, dns_tcp_handle);
2825
2826 The dissect_dns_udp function does very little work and calls
2827 dissect_dns_common, while dissect_dns_tcp calls tcp_dissect_pdus with a
2828 reference to a callback which will be called with reassembled data:
2829
2830         static void
2831         dissect_dns_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
2832         {
2833                 tcp_dissect_pdus(tvb, pinfo, tree, dns_desegment, 2,
2834                     get_dns_pdu_len, dissect_dns_tcp_pdu);
2835         }
2836
2837 (The dissect_dns_tcp_pdu function acts similarly to dissect_dns_udp.) 
2838 The arguments to tcp_dissect_pdus are:
2839
2840         the tvbuff pointer, packet_info pointer, and proto_tree pointer
2841         passed to the dissector;
2842
2843         a gboolean flag indicating whether desegmentation is enabled for
2844         your protocol;
2845
2846         the number of bytes of PDU data required to determine the length
2847         of the PDU;
2848
2849         a routine that takes as arguments a tvbuff pointer and an offset
2850         value representing the offset into the tvbuff at which a PDU
2851         begins and should return - *without* throwing an exception (it
2852         is guaranteed that the number of bytes specified by the previous
2853         argument to tcp_dissect_pdus is available, but more data might
2854         not be available, so don't refer to any data past that) - the
2855         total length of the PDU, in bytes;
2856
2857         a routine that's passed a tvbuff pointer, packet_info pointer,
2858         and proto_tree pointer, with the tvbuff containing a
2859         possibly-reassembled PDU, and that should dissect that PDU.
2860
2861 2.7.2 Modifying the pinfo struct
2862
2863 The second reassembly mode is prefered when the dissector cannot determine 
2864 how many bytes it will need to read in order to determine the size of a PDU. 
2865 For this mode it is reccommended that your dissector be the newer dissector 
2866 type which returns "int" rather than the older type which returned "void".
2867
2868 This reassembly mode relies on Ethereal's mechanism for processing multiple PDUs
2869 per frame. When a dissector processes a PDU from a tvbuff the PDU may not be
2870 aligned to a frame of the underlying protocol. Ethereal allows dissectors to
2871 process PDUs in an idempotent way--dissectors only need to consider one PDU at a 
2872 time. If your dissector discovers that it can not process a complete PDU from 
2873 the current tvbuff the dissector should halt processing and request additional 
2874 bytes from the lower level dissector.
2875
2876 Your dissect_PROTO will be called by the lower level dissector whenever 
2877 sufficient new bytes become available. Each time your dissector is called it is 
2878 provided a different tvbuff, though the tvbuffs may contain data that your 
2879 dissector declined to process during a previous call. When called a dissector 
2880 should examine the tvbuff provided and determine if an entire PDU is available. 
2881 If sufficient bytes are available the dissector processes the PDU and returns 
2882 the length of the PDU from your dissect_PROTO.
2883
2884 Completion of a PDU is signified by dissect_PROTO returning a positive value. 
2885 The value is the number of bytes which were processed from the tvbuff. If there 
2886 were insufficient bytes in the tvbuff to complete a PDU then the dissect_PROTO 
2887 returns a negative value requesting additional bytes. The negative return value 
2888 indicates how many additional bytes are required. Additionally dissect_PROTO 
2889 must update the pinfo structure to indicate that more bytes are required. The 
2890 desegment_offset field is the offset in the tvbuff at which the dissector will 
2891 continue processing when next called. The desegment_len field should contain the 
2892 estimated number of additional bytes required for completing the PDU. The 
2893 dissect_PROTO will not be called again until the specified number of bytes are
2894 available. pinfo->desegment_len may be set to -1 if dissect_PROTO cannot 
2895 determine how many additional bytes are required. Dissectors should set the
2896 desegment_len to a reasonable value when possible rather than always setting
2897 -1 as it will generally be more efficient.
2898
2899 static hf_register_info hf[] = {
2900     {&hf_cstring,
2901      {"C String", "c.string", FT_STRING, BASE_NONE, NULL, 0x0,
2902       "C String", HFILL}
2903      }
2904    };
2905
2906 /**
2907 *   Dissect a buffer containing a C string.
2908 *
2909 *   @param  tvb     The buffer to dissect.
2910 *   @param  pinfo   Packet Info.
2911 *   @param  tree    The protocol tree.
2912 *   @return Number of bytes from the tvbuff_t which were processed or a negative
2913 *           value indicating more bytes are needed.
2914 **/
2915 static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree)
2916 {
2917     guint offset = 0;
2918     gint available = tvb_reported_length_remaining(tvb, offset);
2919     gint len = tvb_strnlen( tvb, offset, available );
2920
2921     if( -1 == len ) {
2922         /* No '\0' found, ask for another byte. */
2923         pinfo->desegment_offset = offset;
2924         pinfo->desegment_len = 1;
2925         return -1;
2926     }
2927     
2928     if (check_col(pinfo->cinfo, COL_INFO)) {
2929         col_set_str(pinfo->cinfo, COL_INFO, "C String");
2930     }
2931
2932     len += 1; /* Add one for the '\0' */
2933     
2934     if (tree) {
2935         proto_tree_add_item(tree, hf_cstring, tvb, offset, len, FALSE);
2936     }
2937
2938     return len;
2939 }
2940
2941 This simple dissector will repeatedly return -1 requesting one more byte until 
2942 the tvbuff contains a complete C string. The C string will then be added to the 
2943 protocol tree. Unfortunately since there is no way to guess the size of C String 
2944 without seeing the entire string this dissector can never request more than one
2945 additional byte.
2946
2947 3. Plugins
2948
2949 See the README.plugins for more information on how to "pluginize" 
2950 a dissector.
2951
2952 4.0 Extending Wiretap.
2953
2954 5.0 How the Display Filter Engine works
2955
2956 code:
2957 epan/dfilter/* - the display filter engine, including
2958                 scanner, parser, syntax-tree semantics checker, DFVM bytecode
2959                 generator, and DFVM engine.
2960 epan/ftypes/* - the definitions of the various FT_* field types.
2961 epan/proto.c   - proto_tree-related routines
2962
2963 5.1 Parsing text
2964
2965 The scanner/parser pair read the string representing the display filter
2966 and convert it into a very simple syntax tree.  The syntax tree is very
2967 simple in that it is possible that many of the nodes contain unparsed
2968 chunks of text from the display filter.
2969
2970 5.1 Enhancing the syntax tree.
2971
2972 The semantics of the simple syntax tree are checked to make sure that
2973 the fields that are being compared are being compared to appropriate
2974 values.  For example, if a field is an integer, it can't be compared to
2975 a string, unless a value_string has been defined for that field.
2976
2977 During the process of checking the semantics, the simple syntax tree is
2978 fleshed out and no longer contains nodes with unparsed information.  The
2979 syntax tree is no longer in its simple form, but in its complete form.
2980
2981 5.2 Converting to DFVM bytecode
2982
2983 The syntax tree is analyzed to create a sequence of bytecodes in the
2984 "DFVM" language.  "DFVM" stands for Display Filter Virtual Machine.  The
2985 DFVM is similar in spirit, but not in definition, to the BPF VM that
2986 libpcap uses to analyze packets.
2987
2988 A virtual bytecode is created and used so that the actual process of
2989 filtering packets will be fast.  That is, it should be faster to process
2990 a list of VM bytecodes than to attempt to filter packets directly from
2991 the syntax tree.  (heh...  no measurement has been made to support this
2992 supposition)
2993
2994 5.3 Filtering
2995
2996 Once the DFVM bytecode has been produced, it's a simple matter of
2997 running the DFVM engine against the proto_tree from the packet
2998 dissection, using the DFVM bytecodes as instructions.  If the DFVM
2999 bytecode is known before packet dissection occurs, the
3000 proto_tree-related code can be "primed" to store away pointers to
3001 field_info structures that are interesting to the display filter.  This
3002 makes lookup of those field_info structures during the filtering process
3003 faster.
3004
3005
3006 6.0 Adding new capabilities.
3007
3008
3009
3010
3011 James Coe <jammer@cin.net>
3012 Gilbert Ramirez <gram@alumni.rice.edu>
3013 Jeff Foster <jfoste@woodward.com>
3014 Olivier Abad <oabad@cybercable.fr>
3015 Laurent Deniel <laurent.deniel@free.fr>
3016 Gerald Combs <gerald@ethereal.com>
3017 Guy Harris <guy@alum.mit.edu>