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
7 1. Setting up your protocol dissector code.
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.
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.
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).
27 Don't use zero-length arrays; not all compilers support them. If an
28 array would have no members, just leave it out.
30 Don't declare variables in the middle of executable code; not all C
31 compilers support that. Variables should be declared outside a
32 function, or at the beginning of a function or compound statement.
34 Don't use "inline"; not all compilers support it. If you want to have a
35 function be an inline function if the compiler supports it, use
36 G_INLINE_FUNC, which is declared by <glib.h>. This may not work with
37 functions declared in header files; if it doesn't work, don't declare
38 the function in a header file, even if this requires that you not make
39 it inline on any platform.
41 Don't use "uchar", "u_char", "ushort", "u_short", "uint", "u_int",
42 "ulong", "u_long" or "boolean"; they aren't defined on all platforms.
43 If you want an 8-bit unsigned quantity, use "guint8"; if you want an
44 8-bit character value with the 8th bit not interpreted as a sign bit,
45 use "guchar"; if you want a 16-bit unsigned quantity, use "guint16";
46 if you want a 32-bit unsigned quantity, use "guint32"; and if you want
47 an "int-sized" unsigned quantity, use "guint"; if you want a boolean,
48 use "gboolean". Use "%d", "%u", "%x", and "%o" to print those types;
49 don't use "%ld", "%lu", "%lx", or "%lo", as longs are 64 bits long on
50 many platforms, but "guint32" is 32 bits long.
52 Don't use "long" to mean "signed 32-bit integer", and don't use
53 "unsigned long" to mean "unsigned 32-bit integer"; "long"s are 64 bits
54 long on many platforms. Use "gint32" for signed 32-bit integers and use
55 "guint32" for unsigned 32-bit integers.
57 Don't use "long" to mean "signed 64-bit integer" and don't use "unsigned
58 long" to mean "unsigned 64-bit integer"; "long"s are 32 bits long on
59 other many platforms. Don't use "long long" or "unsigned long long",
60 either, as not all platforms support them; use "gint64" or "guint64",
61 which will be defined as the appropriate types for 64-bit signed and
64 When printing or displaying the values of 64-bit integral data types,
65 don't assume use "%lld", "%llu", "%llx", or "%llo" - not all platforms
66 support "%ll" for printing 64-bit integral data types. Instead, use
67 PRId64, PRIu64, PRIx64, and PRIo64, for example
69 proto_tree_add_text(tree, tvb, offset, 8,
70 "Sequence Number: %" PRIu64, sequence_number);
72 When specifying an integral constant that doesn't fit in 32 bits, don't
73 use "LL" at the end of the constant - not all compilers use "LL" for
74 that. Instead, put the constant in a call to the "G_GINT64_CONSTANT()"
77 G_GINT64_CONSTANT(11644473600U)
83 Don't use a label without a statement following it. For example,
93 will not work with all compilers - you have to do
103 with some statement, even if it's a null statement, after the label.
105 Don't use "bzero()", "bcopy()", or "bcmp()"; instead, use the ANSI C
108 "memset()" (with zero as the second argument, so that it sets
109 all the bytes to zero);
111 "memcpy()" or "memmove()" (note that the first and second
112 arguments to "memcpy()" are in the reverse order to the
113 arguments to "bcopy()"; note also that "bcopy()" is typically
114 guaranteed to work on overlapping memory regions, while
115 "memcpy()" isn't, so if you may be copying from one region to a
116 region that overlaps it, use "memmove()", not "memcpy()" - but
117 "memcpy()" might be faster as a result of not guaranteeing
118 correct operation on overlapping memory regions);
120 and "memcmp()" (note that "memcmp()" returns 0, 1, or -1, doing
121 an ordered comparison, rather than just returning 0 for "equal"
122 and 1 for "not equal", as "bcmp()" does).
124 Not all platforms necessarily have "bzero()"/"bcopy()"/"bcmp()", and
125 those that do might not declare them in the header file on which they're
126 declared on your platform.
128 Don't use "index()" or "rindex()"; instead, use the ANSI C equivalents,
129 "strchr()" and "strrchr()". Not all platforms necessarily have
130 "index()" or "rindex()", and those that do might not declare them in the
131 header file on which they're declared on your platform.
133 Don't fetch data from packets by getting a pointer to data in the packet
134 with "tvb_get_ptr()", casting that pointer to a pointer to a structure,
135 and dereferencing that pointer. That point won't necessarily be aligned
136 on the proper boundary, which can cause crashes on some platforms (even
137 if it doesn't crash on an x86-based PC); furthermore, the data in a
138 packet is not necessarily in the byte order of the machine on which
139 Ethereal is running. Use the tvbuff routines to extract individual
140 items from the packet, or use "proto_tree_add_item()" and let it extract
143 Don't use "ntohs()", "ntohl()", "htons()", or "htonl()"; the header
144 files required to define or declare them differ between platforms, and
145 you might be able to get away with not including the appropriate header
146 file on your platform but that might not work on other platforms.
147 Instead, use "g_ntohs()", "g_ntohl()", "g_htons()", and "g_htonl()";
148 those are declared by <glib.h>, and you'll need to include that anyway,
149 as Ethereal header files that all dissectors must include use stuff from
152 Don't fetch a little-endian value using "tvb_get_ntohs() or
153 "tvb_get_ntohl()" and then using "g_ntohs()", "g_htons()", "g_ntohl()",
154 or "g_htonl()" on the resulting value - the g_ routines in question
155 convert between network byte order (big-endian) and *host* byte order,
156 not *little-endian* byte order; not all machines on which Ethereal runs
157 are little-endian, even though PC's are. Fetch those values using
158 "tvb_get_letohs()" and "tvb_get_letohl()".
160 Don't put a comma after the last element of an enum - some compilers may
161 either warn about it (producing extra noise) or refuse to accept it.
163 Don't include <unistd.h> without protecting it with
171 and, if you're including it to get routines such as "open()", "close()",
172 "read()", and "write()" declared, also include <io.h> if present:
178 in order to declare the Windows C library routines "_open()",
179 "_close()", "_read()", and "_write()". Your file must include <glib.h>
180 - which many of the Ethereal header files include, so you might not have
181 to include it explicitly - in order to get "open()", "close()",
182 "read()", "write()", etc. mapped to "_open()", "_close()", "_read()",
185 When opening a file with "fopen()", "freopen()", or "fdopen()", if the
186 file contains ASCII text, use "r", "w", "a", and so on as the open mode
187 - but if it contains binary data, use "rb", "wb", and so on. On
188 Windows, if a file is opened in a text mode, writing a byte with the
189 value of octal 12 (newline) to the file causes two bytes, one with the
190 value octal 15 (carriage return) and one with the value octal 12, to be
191 written to the file, and causes bytes with the value octal 15 to be
192 discarded when reading the file (to translate between C's UNIX-style
193 lines that end with newline and Windows' DEC-style lines that end with
194 carriage return/line feed).
196 In addition, that also means that when opening or creating a binary
197 file, you must use "open()" (with O_CREAT and possibly O_TRUNC if the
198 file is to be created if it doesn't exist), and OR in the O_BINARY flag.
199 That flag is not present on most, if not all, UNIX systems, so you must
206 to properly define it for UNIX (it's not necessary on UNIX).
208 Don't use forward declarations of static arrays without a specified size
209 in a fashion such as this:
211 static const value_string foo_vals[];
215 static const value_string foo_vals[] = {
222 as some compilers will reject the first of those statements. Instead,
223 initialize the array at the point at which it's first declared, so that
226 Don't put declarations in the middle of a block; put them before all
227 code. Not all compilers support declarations in the middle of code,
236 For #define names and enum member names, prefix the names with a tag so
237 as to avoid collisions with other names - this might be more of an issue
238 on Windows, as it appears to #define names such as DELETE and
241 Don't use the "numbered argument" feature that many UNIX printf's
244 sprintf(add_string, " - (%1$d) (0x%1$04x)", value);
246 as not all UNIX printf's implement it, and Windows printf doesn't appear
247 to implement it. Use something like
249 sprintf(add_string, " - (%d) (0x%04x)", value, value);
253 Don't use "variadic macros", such as
255 #define DBG(format, args...) fprintf(stderr, format, ## args)
257 as not all C compilers support them. Use macros that take a fixed
258 number of arguments, such as
260 #define DBG0(format) fprintf(stderr, format)
261 #define DBG1(format, arg1) fprintf(stderr, format, arg1)
262 #define DBG2(format, arg1, arg2) fprintf(stderr, format, arg1, arg2)
268 #define DBG(args) printf args
270 snprintf() -> g_snprintf()
271 snprintf() is not available on all platforms, so it's a good idea to use the
272 g_snprintf() function declared by <glib.h> instead.
274 tmpnam() -> mkstemp()
275 tmpnam is insecure and should not be used any more. Ethereal brings its
276 own mkstemp implementation for use on platforms that lack mkstemp.
277 Note: mkstemp does not accept NULL as a parameter.
279 The pointer retured by a call to "tvb_get_ptr()" is not guaranteed to be
280 aligned on any particular byte boundary; this means that you cannot
281 safely cast it to any data type other than a pointer to "char",
282 "unsigned char", "guint8", or other one-byte data types. You cannot,
283 for example, safely cast it to a pointer to a structure, and then access
284 the structure members directly; on some systems, unaligned accesses to
285 integral data types larger than 1 byte, and floating-point data types,
286 cause a trap, which will, at best, result in the OS slowly performing an
287 unaligned access for you, and will, on at least some platforms, cause
288 the program to be terminated.
290 Ethereal supports both platforms with GLib 1.2[.x]/GTK+ 1.2[.x] and GLib
291 2.x/GTK+ 1.3[.x] and 2.x. If at all possible, either use only
292 mechanisms that are present in GLib 1.2[.x] and GTK+ 1.2[.x], use #if's
293 to conditionally use older or newer mechanisms depending on the platform
294 on which Ethereal is being built, or, if the code in GLib or GTK+ that
295 implements that mechanism will build with GLib 1.2[.x]/GTK+ 1.2[.x],
296 conditionally include that code as part of the Ethereal source and use
297 the included version with GLib 1.2[.x] or GTK+ 1.2[.x]. In particular,
298 if the GLib 2.x or GTK+ 2.x mechanism indicates that a routine is
299 deprecated and shouldn't be used in new code, and that it was renamed in
300 GLib 2.x or GTK+ 2.x and the new name should be used, disregard that and
301 use the old name - it'll still work with GLib 2.x or GTK+ 2.x, but will
302 also work with GLib 1.2[.x] and GTK+ 1.2[.x].
304 When different code must be used on UN*X and Win32, use a #if or #ifdef
305 that tests _WIN32, not WIN32. Try to write code portably whenever
306 possible, however; note that there are some routines in Ethereal with
307 platform-dependent implementations and platform-independent APIs, such
308 as the routines in epan/filesystem.c, allowing the code that calls it to
309 be written portably without #ifdefs.
313 Ethereal is not guaranteed to read only network traces that contain
314 correctly-formed packets; in fact, one of the reasons why Ethereal is
315 used is to track down networking problems, and the problems might be due
316 to a buggy protocol implementation sending out bad packets.
318 Therefore, protocol dissectors not only have to be able to handle
319 correctly-formed packets without, for example, crashing or looping
320 infinitely, they also have to be able to handle *incorrectly*-formed
321 packets without crashing or looping infinitely.
323 Here are some suggestions for making dissectors more robust in the face
324 of incorrectly-formed packets:
326 Do *NOT* use "g_assert()" or "g_assert_not_reached()" in dissectors.
327 *NO* value in a packet's data should be considered "wrong" in the sense
328 that it's a problem with the dissector if found; if it cannot do
329 anything else with a particular value from a packet's data, the
330 dissector should put into the protocol tree an indication that the
331 value is invalid, and should return.
333 If you are allocating a chunk of memory to contain data from a packet,
334 or to contain information derived from data in a packet, and the size of
335 the chunk of memory is derived from a size field in the packet, make
336 sure all the data is present in the packet before allocating the buffer.
339 1) Ethereal won't leak that chunk of memory if an attempt to
340 fetch data not present in the packet throws an exception
344 2) it won't crash trying to allocate an absurdly-large chunk of
345 memory if the size field has a bogus large value.
347 If you're fetching into such a chunk of memory a string from the buffer,
348 and the string has a specified size, you can use "tvb_get_string()",
349 which will check whether the entire string is present before allocating
350 a buffer for the string, and will also put a trailing '\0' at the end of
353 If you're fetching into such a chunk of memory a 2-byte Unicode string
354 from the buffer, and the string has a specified size, you can use
355 "tvb_fake_unicode()", which will check whether the entire string is
356 present before allocating a buffer for the string, and will also put a
357 trailing '\0' at the end of the buffer. The resulting string will be a
358 sequence of single-byte characters; the only Unicode characters that
359 will be handled correctly are those in the ASCII range. (Ethereal's
360 ability to handle non-ASCII strings is limited; it needs to be
363 If you're fetching into such a chunk of memory a sequence of bytes from
364 the buffer, and the sequence has a specified size, you can use
365 "tvb_memdup()", which will check whether the entire sequence is present
366 before allocating a buffer for it.
368 Otherwise, you can check whether the data is present by using
369 "tvb_ensure_bytes_exist()" or by getting a pointer to the data by using
370 "tvb_get_ptr()", although note that there might be problems with using
371 the pointer from "tvb_get_ptr()" (see the item on this in the
372 Portability section above, and the next item below).
374 Note also that you should only fetch string data into a fixed-length
375 buffer if the code ensures that no more bytes than will fit into the
376 buffer are fetched ("the protocol ensures" isn't good enough, as
377 protocol specifications can't ensure only packets that conform to the
378 specification will be transmitted or that only packets for the protocol
379 in question will be interpreted as packets for that protocol by
380 Ethereal). If there's no maximum length of string data to be fetched,
381 routines such as "tvb_get_string()" are safer, as they allocate a buffer
382 large enough to hold the string. (Note that you should free the string
383 once you're finished with it.)
385 If you have gotten a pointer using "tvb_get_ptr()", you must make sure
386 that you do not refer to any data past the length passed as the last
387 argument to "tvb_get_ptr()"; while the various "tvb_get" routines
388 perform bounds checking and throw an exception if you refer to data not
389 available in the tvbuff, direct references through a pointer gotten from
390 "tvb_get_ptr()" do not do any bounds checking.
392 If you have a loop that dissects a sequence of items, each of which has
393 a length field, with the offset in the tvbuff advanced by the length of
394 the item, then, if the length field is the total length of the item, and
395 thus can be zero, you *MUST* check for a zero-length item and abort the
396 loop if you see one. Otherwise, a zero-length item could cause the
397 dissector to loop infinitely. You should also check that the offset,
398 after having the length added to it, is greater than the offset before
399 the length was added to it, if the length field is greater than 24 bits
400 long, so that, if the length value is *very* large and adding it to the
401 offset causes an overflow, that overflow is detected.
403 Any tvbuff offset that is added to as processing is done on a packet
404 should be stored in a 32-bit variable, such as an "int"; if you store it
405 in an 8-bit or 16-bit variable, you run the risk of the variable
408 sprintf() -> g_snprintf()
409 Prevent yourself from using the sprintf() function, as it does not test the
410 length of the given output buffer and might be writing into memory areas not
411 intended for. This function is one of the main causes of security problems
412 like buffer exploits and many other bugs that are very hard to find. It's
413 much better to use the g_snprintf() function declared by <glib.h> instead.
415 1.1.3 Name convention.
417 Ethereal uses the underscore_convention rather than the InterCapConvention for
418 function names, so new code should probably use underscores rather than
419 intercaps for functions and variable names. This is especially important if you
420 are writing code that will be called from outside your code. We are just
421 trying to keep things consistent for other users.
423 1.1.4 White space convention.
425 Avoid using tab expansions different from 8 spaces, as not all text editors in
426 use by the developers support this.
428 When creating a new file, you are free to choose an indentation logic. Most of
429 the files in Ethereal tend to use 2-space or 4-space indentation. You are
430 encouraged to write a short comment on the indentation logic at the beginning
433 When editing an existing file, try following the existing indentation logic.
437 Ethereal requires certain things when setting up a protocol dissector.
438 Below is skeleton code for a dissector that you can copy to a file and
439 fill in. Your dissector should follow the naming convention of packet-
440 followed by the abbreviated name for the protocol. It is recommended
441 that where possible you keep to the IANA abbreviated name for the
442 protocol, if there is one, or a commonly-used abbreviation for the
445 Usually, you will put your newly created dissector file into the directory
446 epan/dissectors, just like all the other packet-....c files already in there.
448 Also, please add your dissector file to the corresponding makefile,
449 described in section "1.9 Editing Makefile.common to add your dissector" below.
451 Dissectors that use the dissector registration to register with a lower level
452 dissector don't need to define a prototype in the .h file. For other
453 dissectors the main dissector routine should have a prototype in a header
454 file whose name is "packet-", followed by the abbreviated name for the
455 protocol, followed by ".h"; any dissector file that calls your dissector
456 should be changed to include that file.
458 You may not need to include all the headers listed in the skeleton
459 below, and you may need to include additional headers. For example, the
468 is needed only if you are using a function from libpcre, e.g. the
469 "pcre_compile()" function.
472 in the comment will be updated by CVS when the file is
473 checked in; it will allow the RCS "ident" command to report which
474 version of the file is currently checked out.
476 When creating a new file, it is fine to just write "$Id$" as RCS will
477 automatically fill in the identifier at the time the file will be added to the
478 SVN repository (checked in).
480 ------------------------------------Cut here------------------------------------
481 /* packet-PROTOABBREV.c
482 * Routines for PROTONAME dissection
483 * Copyright 2000, YOUR_NAME <YOUR_EMAIL_ADDRESS>
487 * Ethereal - Network traffic analyzer
488 * By Gerald Combs <gerald@ethereal.com>
489 * Copyright 1998 Gerald Combs
491 * Copied from WHATEVER_FILE_YOU_USED (where "WHATEVER_FILE_YOU_USED"
492 * is a dissector file; if you just copied this from README.developer,
493 * don't bother with the "Copied from" - you don't even need to put
494 * in a "Copied from" if you copied an existing dissector, especially
495 * if the bulk of the code in the new dissector is your code)
497 * This program is free software; you can redistribute it and/or
498 * modify it under the terms of the GNU General Public License
499 * as published by the Free Software Foundation; either version 2
500 * of the License, or (at your option) any later version.
502 * This program is distributed in the hope that it will be useful,
503 * but WITHOUT ANY WARRANTY; without even the implied warranty of
504 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
505 * GNU General Public License for more details.
507 * You should have received a copy of the GNU General Public License
508 * along with this program; if not, write to the Free Software
509 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
522 #include <epan/packet.h>
523 #include <epan/prefs.h>
525 /* IF PROTO exposes code to other dissectors, then it must be exported
526 in a header file. If not, a header file is not needed at all. */
527 #include "packet-PROTOABBREV.h"
529 /* Forward declaration we need below */
530 void proto_reg_handoff_PROTOABBREV(void);
532 /* Initialize the protocol and registered fields */
533 static int proto_PROTOABBREV = -1;
534 static int hf_PROTOABBREV_FIELDABBREV = -1;
536 /* Global sample preference ("controls" display of numbers) */
537 static gboolean gPREF_HEX = FALSE;
539 /* Initialize the subtree pointers */
540 static gint ett_PROTOABBREV = -1;
542 /* Code to actually dissect the packets */
544 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
547 /* Set up structures needed to add the protocol subtree and manage it */
549 proto_tree *PROTOABBREV_tree;
551 /* Make entries in Protocol column and Info column on summary display */
552 if (check_col(pinfo->cinfo, COL_PROTOCOL))
553 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
555 /* This field shows up as the "Info" column in the display; you should use
556 it, if possible, to summarize what's in the packet, so that a user looking
557 at the list of packets can tell what type of packet it is. See section 1.5
558 for more information.
560 Before changing the contents of a column you should make sure the column is
561 active by calling "check_col(pinfo->cinfo, COL_*)". If it is not active
562 don't bother setting it.
564 If you are setting the column to a constant string, use "col_set_str()",
565 as it's more efficient than the other "col_set_XXX()" calls.
567 If you're setting it to a string you've constructed, or will be
568 appending to the column later, use "col_add_str()".
570 "col_add_fstr()" can be used instead of "col_add_str()"; it takes
571 "printf()"-like arguments. Don't use "col_add_fstr()" with a format
572 string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
573 more efficient than "col_add_fstr()".
575 If you will be fetching any data from the packet before filling in
576 the Info column, clear that column first, in case the calls to fetch
577 data from the packet throw an exception because they're fetching data
578 past the end of the packet, so that the Info column doesn't have data
579 left over from the previous dissector; do
581 if (check_col(pinfo->cinfo, COL_INFO))
582 col_clear(pinfo->cinfo, COL_INFO);
586 if (check_col(pinfo->cinfo, COL_INFO))
587 col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
589 /* A protocol dissector can be called in 2 different ways:
591 (a) Operational dissection
593 In this mode, Ethereal is only interested in the way protocols
594 interact, protocol conversations are created, packets are reassembled
595 and handed over to higher-level protocol dissectors.
596 In this mode Ethereal does not build a so-called "protocol tree".
598 (b) Detailed dissection
600 In this mode, Ethereal is also interested in all details of a given
601 protocol, so a "protocol tree" is created.
603 Ethereal distinguishes between the 2 modes with the proto_tree pointer:
607 In the interest of speed, if "tree" is NULL, avoid building a
608 protocol tree and adding stuff to it, or even looking at any packet
609 data needed only if you're building the protocol tree, if possible.
611 Note, however, that you must fill in column information, create
612 conversations, reassemble packets, build any other persistent state
613 needed for dissection, and call subdissectors regardless of whether
614 "tree" is NULL or not. This might be inconvenient to do without
615 doing most of the dissection work; the routines for adding items to
616 the protocol tree can be passed a null protocol tree pointer, in
617 which case they'll return a null item pointer, and
618 "proto_item_add_subtree()" returns a null tree pointer if passed a
619 null item pointer, so, if you're careful not to dereference any null
620 tree or item pointers, you can accomplish this by doing all the
621 dissection work. This might not be as efficient as skipping that
622 work if you're not building a protocol tree, but if the code would
623 have a lot of tests whether "tree" is null if you skipped that work,
624 you might still be better off just doing all that work regardless of
625 whether "tree" is null or not. */
628 /* NOTE: The offset and length values in the call to
629 "proto_tree_add_item()" define what data bytes to highlight in the hex
630 display window when the line in the protocol tree display
631 corresponding to that item is selected.
633 Supplying a length of -1 is the way to highlight all data from the
634 offset to the end of the packet. */
636 /* create display subtree for the protocol */
637 ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, FALSE);
639 PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
641 /* add an item to the subtree, see section 1.6 for more information */
642 proto_tree_add_item(PROTOABBREV_tree,
643 hf_PROTOABBREV_FIELDABBREV, tvb, offset, len, FALSE)
646 /* Continue adding tree items to process the packet here */
651 /* If this protocol has a sub-dissector call it here, see section 1.8 */
655 /* Register the protocol with Ethereal */
657 /* this format is require because a script is used to build the C function
658 that calls all the protocol registration.
662 proto_register_PROTOABBREV(void)
664 module_t *PROTOABBREV_module;
666 /* Setup list of header fields See Section 1.6.1 for details*/
667 static hf_register_info hf[] = {
668 { &hf_PROTOABBREV_FIELDABBREV,
669 { "FIELDNAME", "PROTOABBREV.FIELDABBREV",
670 FIELDTYPE, FIELDBASE, FIELDCONVERT, BITMASK,
671 "FIELDDESCR", HFILL }
675 /* Setup protocol subtree array */
676 static gint *ett[] = {
680 /* Register the protocol name and description */
681 proto_PROTOABBREV = proto_register_protocol("PROTONAME",
682 "PROTOSHORTNAME", "PROTOABBREV");
684 /* Required function calls to register the header fields and subtrees used */
685 proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
686 proto_register_subtree_array(ett, array_length(ett));
688 /* Register preferences module (See Section 2.6 for more on preferences) */
689 PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
691 /* Register a sample preference */
692 prefs_register_bool_preference(PROTOABBREV_module, "showHex",
693 "Display numbers in Hex",
694 "Enable to display numerical values in hexidecimal.",
699 /* If this dissector uses sub-dissector registration add a registration routine.
700 This exact format is required because a script is used to find these routines
701 and create the code that calls these routines.
703 This function is also called by preferences whenever "Apply" is pressed
704 (see prefs_register_protocol above) so it should accommodate being called
708 proto_reg_handoff_PROTOABBREV(void)
710 static gboolean inited = FALSE;
714 dissector_handle_t PROTOABBREV_handle;
716 PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
718 dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
724 If you perform registration functions which are dependant upon
725 prefs the you should de-register everything which was associated
726 with the previous settings and re-register using the new prefs settings
727 here. In general this means you need to keep track of what value the
728 preference had at the time you registered using a local static in this
731 static int currentPort = -1;
733 if( -1 != currentPort ) {
734 dissector_delete( "tcp.port", currentPort, PROTOABBREV_handle);
737 currentPort = gPortPref;
739 dissector_add("tcp.port", currentPort, PROTOABBREV_handle);
744 ------------------------------------Cut here------------------------------------
746 1.3 Explanation of needed substitutions in code skeleton.
748 In the above code block the following strings should be substituted with
751 YOUR_NAME Your name, of course. You do want credit, don't you?
752 It's the only payment you will receive....
753 YOUR_EMAIL_ADDRESS Keep those cards and letters coming.
754 WHATEVER_FILE_YOU_USED Add this line if you are using another file as a
756 PROTONAME The name of the protocol; this is displayed in the
757 top-level protocol tree item for that protocol.
758 PROTOSHORTNAME An abbreviated name for the protocol; this is displayed
759 in the "Preferences" dialog box if your dissector has
760 any preferences, and in the dialog box for filter fields
761 when constructing a filter expression.
762 PROTOABBREV A name for the protocol for use in filter expressions;
763 it should contain only lower-case letters, digits, and
765 FIELDNAME The displayed name for the header field.
766 FIELDABBREV The abbreviated name for the header field. (NO SPACES)
767 FIELDTYPE FT_NONE, FT_BOOLEAN, FT_UINT8, FT_UINT16, FT_UINT24,
768 FT_UINT32, FT_UINT64, FT_INT8, FT_INT16, FT_INT24, FT_INT32,
769 FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
770 FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_UINT_STRING,
771 FT_ETHER, FT_BYTES, FT_IPv4, FT_IPv6, FT_IPXNET,
773 FIELDBASE BASE_NONE, BASE_DEC, BASE_HEX, BASE_OCT
774 FIELDCONVERT VALS(x), TFS(x), NULL
775 BITMASK Usually 0x0 unless using the TFS(x) field conversion.
776 FIELDDESCR A brief description of the field.
777 PARENT_SUBFIELD Lower level protocol field used for lookup, i.e. "tcp.port"
778 ID_VALUE Lower level protocol field value that identifies this protocol
779 For example the TCP or UDP port number
781 If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
782 PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
783 conform with IANA names.
785 1.4 The dissector and the data it receives.
790 This is only needed if the dissector doesn't use self-registration to
791 register itself with the lower level dissector, or if the protocol dissector
792 wants/needs to expose code to other subdissectors.
794 The dissector must declared as exactly as follows in the file
795 packet-PROTOABBREV.h:
798 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
801 1.4.2 Extracting data from packets.
803 NOTE: See the README.tvbuff file for more details
805 The "tvb" argument to a dissector points to a buffer containing the raw
806 data to be analyzed by the dissector; for example, for a protocol
807 running atop UDP, it contains the UDP payload (but not the UDP header,
808 or any protocol headers above it). A tvbuffer is a opaque data
809 structure, the internal data structures are hidden and the data must be
810 access via the tvbuffer accessors.
814 Single-byte accessor:
816 guint8 tvb_get_guint8(tvbuff_t*, gint offset);
818 Network-to-host-order accessors for 16-bit integers (guint16), 32-bit
819 integers (guint32), and 24-bit integers:
821 guint16 tvb_get_ntohs(tvbuff_t*, gint offset);
822 guint32 tvb_get_ntohl(tvbuff_t*, gint offset);
823 guint32 tvb_get_ntoh24(tvbuff_t*, gint offset);
825 Network-to-host-order accessors for single-precision and
826 double-precision IEEE floating-point numbers:
828 gfloat tvb_get_ntohieee_float(tvbuff_t*, gint offset);
829 gdouble tvb_get_ntohieee_double(tvbuff_t*, gint offset);
831 Little-Endian-to-host-order accessors for 16-bit integers (guint16),
832 32-bit integers (guint32), and 24-bit integers:
834 guint16 tvb_get_letohs(tvbuff_t*, gint offset);
835 guint32 tvb_get_letohl(tvbuff_t*, gint offset);
836 guint32 tvb_get_letoh24(tvbuff_t*, gint offset);
838 Little-Endian-to-host-order accessors for single-precision and
839 double-precision IEEE floating-point numbers:
841 gfloat tvb_get_letohieee_float(tvbuff_t*, gint offset);
842 gdouble tvb_get_letohieee_double(tvbuff_t*, gint offset);
844 NOTE: IPv4 addresses are not to be converted to host byte order before
845 being passed to "proto_tree_add_ipv4()". You should use "tvb_memcpy()"
846 to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
847 for example, try to use "tvb_get_ntohl()", find that it gives you the
848 wrong answer on the PC on which you're doing development, and try
849 "tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong
850 answer on big-endian machines.
854 guint8 *tvb_get_string(tvbuff_t*, gint offset, gint length);
856 Returns a null-terminated buffer, allocated with "g_malloc()" (so it
857 must be freed with "g_free()"), containing data from the specified
858 tvbuff, starting at the specified offset, and containing the specified
859 length worth of characters (the length of the buffer will be length+1,
860 as it includes a null character to terminate the string).
862 guint8 *tvb_get_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
864 Returns a null-terminated buffer, allocated with "g_malloc()",
865 containing data from the specified tvbuff, starting with at the
866 specified offset, and containing all characters from the tvbuff up to
867 and including a terminating null character in the tvbuff. "*lengthp"
868 will be set to the length of the string, including the terminating null.
871 guint8* tvb_memcpy(tvbuff_t*, guint8* target, gint offset, gint length);
873 Copies into the specified target the specified length's worth of data
874 from the specified tvbuff, starting at the specified offset.
876 guint8* tvb_memdup(tvbuff_t*, gint offset, gint length);
878 Returns a buffer, allocated with "g_malloc()", containing the specified
879 length's worth of data from the specified tvbuff, starting at the
883 /* WARNING! This function is possibly expensive, temporarily allocating
884 * another copy of the packet data. Furthermore, it's dangerous because once
885 * this pointer is given to the user, there's no guarantee that the user will
886 * honor the 'length' and not overstep the boundaries of the buffer.
888 guint8* tvb_get_ptr(tvbuff_t*, gint offset, gint length);
890 The reason that tvb_get_ptr() might have to allocate a copy of its data
891 only occurs with TVBUFF_COMPOSITES, data that spans multiple tvbuffers.
892 If the user request a pointer to a range of bytes that spans the member
893 tvbuffs that make up the TVBUFF_COMPOSITE, the data will have to be
894 copied to another memory region to assure that all the bytes are
899 1.5 Functions to handle columns in the traffic summary window.
901 The topmost pane of the main window is a list of the packets in the
902 capture, possibly filtered by a display filter.
904 Each line corresponds to a packet, and has one or more columns, as
905 configured by the user.
907 Many of the columns are handled by code outside individual dissectors;
908 most dissectors need only specify the value to put in the "Protocol" and
911 Columns are specified by COL_ values; the COL_ value for the "Protocol"
912 field, typically giving an abbreviated name for the protocol (but not
913 the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the
914 COL_ value for the "Info" field, giving a summary of the contents of the
915 packet for that protocol, is COL_INFO.
917 A value for a column should only be added if the user specified that it
918 be displayed; to check whether a given column is to be displayed, call
919 'check_col' with the COL_ value for that field as an argument - it will
920 return TRUE if the column is to be displayed and FALSE if it is not to
923 The value for a column can be specified with one of several functions,
924 all of which take the 'fd' argument to the dissector as their first
925 argument, and the COL_ value for the column as their second argument.
927 1.5.1 The col_set_str function.
929 'col_set_str' takes a string as its third argument, and sets the value
930 for the column to that value. It assumes that the pointer passed to it
931 points to a string constant or a static "const" array, not to a
932 variable, as it doesn't copy the string, it merely saves the pointer
933 value; the argument can itself be a variable, as long as it always
934 points to a string constant or a static "const" array.
936 It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if
937 the dissector will be using 'col_append_str' or 'col_append_fstr" to
938 append more information to the column, the string will have to be copied
939 anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in
942 For example, to set the "Protocol" column
945 if (check_col(pinfo->cinfo, COL_PROTOCOL))
946 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
949 1.5.2 The col_add_str function.
951 'col_add_str' takes a string as its third argument, and sets the value
952 for the column to that value. It takes the same arguments as
953 'col_set_str', but copies the string, so that if the string is, for
954 example, an automatic variable that won't remain in scope when the
955 dissector returns, it's safe to use.
958 1.5.3 The col_add_fstr function.
960 'col_add_fstr' takes a 'printf'-style format string as its third
961 argument, and 'printf'-style arguments corresponding to '%' format
962 items in that string as its subsequent arguments. For example, to set
963 the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a
964 string containing the type of the request in the packet and "n" is an
965 unsigned integer containing the number of bytes in the request:
967 if (check_col(pinfo->cinfo, COL_INFO))
968 col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes",
971 Don't use 'col_add_fstr' with a format argument of just "%s" -
972 'col_add_str', or possibly even 'col_set_str' if the string that matches
973 the "%s" is a static constant string, will do the same job more
977 1.5.4 The col_clear function.
979 If the Info column will be filled with information from the packet, that
980 means that some data will be fetched from the packet before the Info
981 column is filled in. If the packet is so small that the data in
982 question cannot be fetched, the routines to fetch the data will throw an
983 exception (see the comment at the beginning about tvbuffers improving
984 the handling of short packets - the tvbuffers keep track of how much
985 data is in the packet, and throw an exception on an attempt to fetch
986 data past the end of the packet, so that the dissector won't process
987 bogus data), causing the Info column not to be filled in.
989 This means that the Info column will have data for the previous
990 protocol, which would be confusing if, for example, the Protocol column
991 had data for this protocol.
993 Therefore, before a dissector fetches any data whatsoever from the
994 packet (unless it's a heuristic dissector fetching data to determine
995 whether the packet is one that it should dissect, in which case it
996 should check, before fetching the data, whether there's any data to
997 fetch; if there isn't, it should return FALSE), it should set the
998 Protocol column and the Info column.
1000 If the Protocol column will ultimately be set to, for example, a value
1001 containing a protocol version number, with the version number being a
1002 field in the packet, the dissector should, before fetching the version
1003 number field or any other field from the packet, set it to a value
1004 without a version number, using 'col_set_str', and should later set it
1005 to a value with the version number after it's fetched the version
1008 If the Info column will ultimately be set to a value containing
1009 information from the packet, the dissector should, before fetching any
1010 fields from the packet, clear the column using 'col_clear' (which is
1011 more efficient than clearing it by calling 'col_set_str' or
1012 'col_add_str' with a null string), and should later set it to the real
1013 string after it's fetched the data to use when doing that.
1016 1.5.5 The col_append_str function.
1018 Sometimes the value of a column, especially the "Info" column, can't be
1019 conveniently constructed at a single point in the dissection process;
1020 for example, it might contain small bits of information from many of the
1021 fields in the packet. 'col_append_str' takes, as arguments, the same
1022 arguments as 'col_add_str', but the string is appended to the end of the
1023 current value for the column, rather than replacing the value for that
1024 column. (Note that no blank separates the appended string from the
1025 string to which it is appended; if you want a blank there, you must add
1026 it yourself as part of the string being appended.)
1029 1.5.6 The col_append_fstr function.
1031 'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to
1032 'col_add_str' - it takes, as arguments, the same arguments as
1033 'col_add_fstr', but the formatted string is appended to the end of the
1034 current value for the column, rather than replacing the value for that
1037 1.5.7 The col_append_sep_str and col_append_sep_fstr functions.
1039 In specific situations the developer knows that a column's value will be
1040 created in a stepwise manner, where the appended values are listed. Both
1041 'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item
1042 separator between two consecutive items, and will not add the separator at the
1043 beginning of the column. The remainder of the work both functions do is
1044 identical to what 'col_append_str' and 'col_append_fstr' do.
1046 1.6 Constructing the protocol tree.
1048 The middle pane of the main window, and the topmost pane of a packet
1049 popup window, are constructed from the "protocol tree" for a packet.
1051 The protocol tree, or proto_tree, is a GNode, the N-way tree structure
1052 available within GLIB. Of course the protocol dissectors don't care
1053 what a proto_tree really is; they just pass the proto_tree pointer as an
1054 argument to the routines which allow them to add items and new branches
1057 When a packet is selected in the packet-list pane, or a packet popup
1058 window is created, a new logical protocol tree (proto_tree) is created.
1059 The pointer to the proto_tree (in this case, 'protocol tree'), is passed
1060 to the top-level protocol dissector, and then to all subsequent protocol
1061 dissectors for that packet, and then the GUI tree is drawn via
1064 The logical proto_tree needs to know detailed information about the
1065 protocols and fields about which information will be collected from the
1066 dissection routines. By strictly defining (or "typing") the data that can
1067 be attached to a proto tree, searching and filtering becomes possible.
1068 This means that the for every protocol and field (which I also call
1069 "header fields", since they are fields in the protocol headers) which
1070 might be attached to a tree, some information is needed.
1072 Every dissector routine will need to register its protocols and fields
1073 with the central protocol routines (in proto.c). At first I thought I
1074 might keep all the protocol and field information about all the
1075 dissectors in one file, but decentralization seemed like a better idea.
1076 That one file would have gotten very large; one small change would have
1077 required a re-compilation of the entire file. Also, by allowing
1078 registration of protocols and fields at run-time, loadable modules of
1079 protocol dissectors (perhaps even user-supplied) is feasible.
1081 To do this, each protocol should have a register routine, which will be
1082 called when Ethereal starts. The code to call the register routines is
1083 generated automatically; to arrange that a protocol's register routine
1084 be called at startup:
1086 the file containing a dissector's "register" routine must be
1087 added to "DISSECTOR_SRC" in "epan/dissectors/Makefile.common";
1089 the "register" routine must have a name of the form
1090 "proto_register_XXX";
1092 the "register" routine must take no argument, and return no
1095 the "register" routine's name must appear in the source file
1096 either at the beginning of the line, or preceded only by "void "
1097 at the beginning of the line (that'd typically be the
1098 definition) - other white space shouldn't cause a problem, e.g.:
1100 void proto_register_XXX(void) {
1109 proto_register_XXX( void )
1116 and so on should work.
1118 For every protocol or field that a dissector wants to register, a variable of
1119 type int needs to be used to keep track of the protocol. The IDs are
1120 needed for establishing parent/child relationships between protocols and
1121 fields, as well as associating data with a particular field so that it
1122 can be stored in the logical tree and displayed in the GUI protocol
1125 Some dissectors will need to create branches within their tree to help
1126 organize header fields. These branches should be registered as header
1127 fields. Only true protocols should be registered as protocols. This is
1128 so that a display filter user interface knows how to distinguish
1129 protocols from fields.
1131 A protocol is registered with the name of the protocol and its
1134 Here is how the frame "protocol" is registered.
1138 proto_frame = proto_register_protocol (
1140 /* short name */ "Frame",
1141 /* abbrev */ "frame" );
1143 A header field is also registered with its name and abbreviation, but
1144 information about the its data type is needed. It helps to look at
1145 the header_field_info struct to see what information is expected:
1147 struct header_field_info {
1156 int id; /* calculated */
1158 int bitshift; /* calculated */
1163 A string representing the name of the field. This is the name
1164 that will appear in the graphical protocol tree.
1168 A string with an abbreviation of the field. We concatenate the
1169 abbreviation of the parent protocol with an abbreviation for the field,
1170 using a period as a separator. For example, the "src" field in an IP packet
1171 would have "ip.src" as an abbreviation. It is acceptable to have
1172 multiple levels of periods if, for example, you have fields in your
1173 protocol that are then subdivided into subfields. For example, TRMAC
1174 has multiple error fields, so the abbreviations follow this pattern:
1175 "trmac.errors.iso", "trmac.errors.noniso", etc.
1177 The abbreviation is the identifier used in a display filter.
1181 The type of value this field holds. The current field types are:
1183 FT_NONE No field type. Used for fields that
1184 aren't given a value, and that can only
1185 be tested for presence or absence; a
1186 field that represents a data structure,
1187 with a subtree below it containing
1188 fields for the members of the structure,
1189 or that represents an array with a
1190 subtree below it containing fields for
1191 the members of the array, might be an
1193 FT_BOOLEAN 0 means "false", any other value means
1195 FT_FRAMENUM A frame number; if this is used, the "Go
1196 To Corresponding Frame" menu item can
1198 FT_UINT8 An 8-bit unsigned integer.
1199 FT_UINT16 A 16-bit unsigned integer.
1200 FT_UINT24 A 24-bit unsigned integer.
1201 FT_UINT32 A 32-bit unsigned integer.
1202 FT_UINT64 A 64-bit unsigned integer.
1203 FT_INT8 An 8-bit signed integer.
1204 FT_INT16 A 16-bit signed integer.
1205 FT_INT24 A 24-bit signed integer.
1206 FT_INT32 A 32-bit signed integer.
1207 FT_INT64 A 64-bit signed integer.
1208 FT_FLOAT A single-precision floating point number.
1209 FT_DOUBLE A double-precision floating point number.
1210 FT_ABSOLUTE_TIME Seconds (4 bytes) and nanoseconds (4 bytes)
1211 of time displayed as month name, month day,
1212 year, hours, minutes, and seconds with 9
1213 digits after the decimal point.
1214 FT_RELATIVE_TIME Seconds (4 bytes) and nanoseconds (4 bytes)
1215 of time displayed as seconds and 9 digits
1216 after the decimal point.
1217 FT_STRING A string of characters, not necessarily
1218 NUL-terminated, but possibly NUL-padded.
1219 This, and the other string-of-characters
1220 types, are to be used for text strings,
1221 not raw binary data.
1222 FT_STRINGZ A NUL-terminated string of characters.
1223 FT_UINT_STRING A counted string of characters, consisting
1224 of a count (represented as an integral
1225 value) followed immediately by the
1226 specified number of characters.
1227 FT_ETHER A six octet string displayed in
1228 Ethernet-address format.
1229 FT_BYTES A string of bytes with arbitrary values;
1230 used for raw binary data.
1231 FT_IPv4 A version 4 IP address (4 bytes) displayed
1232 in dotted-quad IP address format (4
1233 decimal numbers separated by dots).
1234 FT_IPv6 A version 6 IP address (16 bytes) displayed
1235 in standard IPv6 address format.
1236 FT_IPXNET An IPX address displayed in hex as a 6-byte
1237 network number followed by a 6-byte station
1240 Some of these field types are still not handled in the display filter
1241 routines, but the most common ones are. The FT_UINT* variables all
1242 represent unsigned integers, and the FT_INT* variables all represent
1243 signed integers; the number on the end represent how many bits are used
1244 to represent the number.
1248 The display field has a couple of overloaded uses. This is unfortunate,
1249 but since we're C as an application programming language, this sometimes
1250 makes for cleaner programs. Right now I still think that overloading
1251 this variable was okay.
1253 For integer fields (FT_UINT* and FT_INT*), this variable represents the
1254 base in which you would like the value displayed. The acceptable bases
1261 BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
1264 For FT_BOOLEAN fields that are also bitfields, 'display' is used to tell
1265 the proto_tree how wide the parent bitfield is. With integers this is
1266 not needed since the type of integer itself (FT_UINT8, FT_UINT16,
1267 FT_UINT24, FT_UINT32, etc.) tells the proto_tree how wide the parent
1270 Additionally, BASE_NONE is used for 'display' as a NULL-value. That is,
1271 for non-integers and non-bitfield FT_BOOLEANs, you'll want to use BASE_NONE
1272 in the 'display' field. You may not use BASE_NONE for integers.
1274 It is possible that in the future we will record the endianness of
1275 integers. If so, it is likely that we'll use a bitmask on the display field
1276 so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX.
1277 But that has not happened yet.
1281 Some integer fields, of type FT_UINT*, need labels to represent the true
1282 value of a field. You could think of those fields as having an
1283 enumerated data type, rather than an integral data type.
1285 A 'value_string' structure is a way to map values to strings.
1287 typedef struct _value_string {
1292 For fields of that type, you would declare an array of "value_string"s:
1294 static const value_string valstringname[] = {
1295 { INTVAL1, "Descriptive String 1" },
1296 { INTVAL2, "Descriptive String 2" },
1300 (the last entry in the array must have a NULL 'strptr' value, to
1301 indicate the end of the array). The 'strings' field would be set to
1302 'VALS(valstringname)'.
1304 If the field has a numeric rather than an enumerated type, the 'strings'
1305 field would be set to NULL.
1307 FT_BOOLEANS have a default map of 0 = "False", 1 (or anything else) = "True".
1308 Sometimes it is useful to change the labels for boolean values (e.g.,
1309 to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
1310 true_false_string is used. (This struct is new as of Ethereal 0.7.6).
1312 typedef struct true_false_string {
1315 } true_false_string;
1317 For Boolean fields for which "False" and "True" aren't the desired
1318 labels, you would declare a "true_false_string"s:
1320 static const true_false_string boolstringname = {
1325 Its two fields are pointers to the string representing truth, and the
1326 string representing falsehood. For FT_BOOLEAN fields that need a
1327 'true_false_string' struct, the 'strings' field would be set to
1328 'TFS(&boolstringname)'.
1330 If the Boolean field is to be displayed as "False" or "True", the
1331 'strings' field would be set to NULL.
1335 If the field is a bitfield, then the bitmask is the mask which will
1336 leave only the bits needed to make the field when ANDed with a value.
1337 The proto_tree routines will calculate 'bitshift' automatically
1338 from 'bitmask', by finding the rightmost set bit in the bitmask.
1339 If the field is not a bitfield, then bitmask should be set to 0.
1343 This is a string giving a proper description of the field.
1344 It should be at least one grammatically complete sentence.
1345 It is meant to provide a more detailed description of the field than the
1346 name alone provides. This information will be used in the man page, and
1347 in a future GUI display-filter creation tool. We might also add tooltips
1348 to the labels in the GUI protocol tree, in which case the blurb would
1349 be used as the tooltip text.
1352 1.6.1 Field Registration.
1354 Protocol registration is handled by creating an instance of the
1355 header_field_info struct (or an array of such structs), and
1356 calling the registration function along with the registration ID of
1357 the protocol that is the parent of the fields. Here is a complete example:
1359 static int proto_eg = -1;
1360 static int hf_field_a = -1;
1361 static int hf_field_b = -1;
1363 static hf_register_info hf[] = {
1366 { "Field A", "proto.field_a", FT_UINT8, BASE_HEX, NULL,
1367 0xf0, "Field A represents Apples", HFILL }},
1370 { "Field B", "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs),
1371 0x0, "Field B represents Bananas", HFILL }}
1374 proto_eg = proto_register_protocol("Example Protocol",
1376 proto_register_field_array(proto_eg, hf, array_length(hf));
1378 Be sure that your array of hf_register_info structs is declared 'static',
1379 since the proto_register_field_array() function does not create a copy
1380 of the information in the array... it uses that static copy of the
1381 information that the compiler created inside your array. Here's the
1382 layout of the hf_register_info struct:
1384 typedef struct hf_register_info {
1385 int *p_id; /* pointer to parent variable */
1386 header_field_info hfinfo;
1389 Also be sure to use the handy array_length() macro found in packet.h
1390 to have the compiler compute the array length for you at compile time.
1392 If you don't have any fields to register, do *NOT* create a zero-length
1393 "hf" array; not all compilers used to compile Ethereal support them.
1394 Just omit the "hf" array, and the "proto_register_field_array()" call,
1397 It is OK to have header fields with a different format be registered with
1398 the same abbreviation. For instance, the following is valid:
1400 static hf_register_info hf[] = {
1402 { &hf_field_8bit, /* 8-bit version of proto.field */
1403 { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL,
1404 0x00, "Field represents FOO", HFILL }},
1406 { &hf_field_32bit, /* 32-bit version of proto.field */
1407 { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL,
1408 0x00, "Field represents FOO", HFILL }}
1411 This way a filter expression can match a header field, irrespective of the
1412 representation of it in the specific protocol context. This is interesting
1413 for protocols with variable-width header fields.
1415 The HFILL macro at the end of the struct will set resonable default values
1416 for internally used fields.
1418 1.6.2 Adding Items and Values to the Protocol Tree.
1420 A protocol item is added to an existing protocol tree with one of a
1421 handful of proto_XXX_DO_YYY() functions.
1423 Remember that it only makes sense to add items to a protocol tree if its
1424 proto_tree pointer is not null. Should you add an item to a NULL tree, then
1425 the proto_XXX_DO_YYY() function will immediately return. The cost of this
1426 function call can be avoided by checking for the tree pointer.
1428 Subtrees can be made with the proto_item_add_subtree() function:
1430 item = proto_tree_add_item(....);
1431 new_tree = proto_item_add_subtree(item, tree_type);
1433 This will add a subtree under the item in question; a subtree can be
1434 created under an item made by any of the "proto_tree_add_XXX" functions,
1435 so that the tree can be given an arbitrary depth.
1437 Subtree types are integers, assigned by
1438 "proto_register_subtree_array()". To register subtree types, pass an
1439 array of pointers to "gint" variables to hold the subtree type values to
1440 "proto_register_subtree_array()":
1442 static gint ett_eg = -1;
1443 static gint ett_field_a = -1;
1445 static gint *ett[] = {
1450 proto_register_subtree_array(ett, array_length(ett));
1452 in your "register" routine, just as you register the protocol and the
1453 fields for that protocol.
1455 There are several functions that the programmer can use to add either
1456 protocol or field labels to the proto_tree:
1459 proto_tree_add_item(tree, id, tvb, start, length, little_endian);
1462 proto_tree_add_item_hidden(tree, id, tvb, start, length, little_endian);
1465 proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
1468 proto_tree_add_protocol_format(tree, id, tvb, start, length,
1472 proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr);
1475 proto_tree_add_bytes_hidden(tree, id, tvb, start, length, start_ptr);
1478 proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr,
1482 proto_tree_add_time(tree, id, tvb, start, length, value_ptr);
1485 proto_tree_add_time_hidden(tree, id, tvb, start, length, value_ptr);
1488 proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr,
1492 proto_tree_add_ipxnet(tree, id, tvb, start, length, value);
1495 proto_tree_add_ipxnet_hidden(tree, id, tvb, start, length, value);
1498 proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value,
1502 proto_tree_add_ipv4(tree, id, tvb, start, length, value);
1505 proto_tree_add_ipv4_hidden(tree, id, tvb, start, length, value);
1508 proto_tree_add_ipv4_format(tree, id, tvb, start, length, value,
1512 proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr);
1515 proto_tree_add_ipv6_hidden(tree, id, tvb, start, length, value_ptr);
1518 proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr,
1522 proto_tree_add_ether(tree, id, tvb, start, length, value_ptr);
1525 proto_tree_add_ether_hidden(tree, id, tvb, start, length, value_ptr);
1528 proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr,
1532 proto_tree_add_string(tree, id, tvb, start, length, value_ptr);
1535 proto_tree_add_string_hidden(tree, id, tvb, start, length, value_ptr);
1538 proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr,
1542 proto_tree_add_boolean(tree, id, tvb, start, length, value);
1545 proto_tree_add_boolean_hidden(tree, id, tvb, start, length, value);
1548 proto_tree_add_boolean_format(tree, id, tvb, start, length, value,
1552 proto_tree_add_float(tree, id, tvb, start, length, value);
1555 proto_tree_add_float_hidden(tree, id, tvb, start, length, value);
1558 proto_tree_add_float_format(tree, id, tvb, start, length, value,
1562 proto_tree_add_double(tree, id, tvb, start, length, value);
1565 proto_tree_add_double_hidden(tree, id, tvb, start, length, value);
1568 proto_tree_add_double_format(tree, id, tvb, start, length, value,
1572 proto_tree_add_uint(tree, id, tvb, start, length, value);
1575 proto_tree_add_uint_hidden(tree, id, tvb, start, length, value);
1578 proto_tree_add_uint_format(tree, id, tvb, start, length, value,
1582 proto_tree_add_uint64(tree, id, tvb, start, length, value);
1585 proto_tree_add_uint64_format(tree, id, tvb, start, length, value,
1589 proto_tree_add_int(tree, id, tvb, start, length, value);
1592 proto_tree_add_int_hidden(tree, id, tvb, start, length, value);
1595 proto_tree_add_int_format(tree, id, tvb, start, length, value,
1599 proto_tree_add_int64(tree, id, tvb, start, length, value);
1602 proto_tree_add_int64_format(tree, id, tvb, start, length, value,
1606 proto_tree_add_text(tree, tvb, start, length, format, ...);
1609 proto_tree_add_text_valist(tree, tvb, start, length, format, ap);
1611 The 'tree' argument is the tree to which the item is to be added. The
1612 'tvb' argument is the tvbuff from which the item's value is being
1613 extracted; the 'start' argument is the offset from the beginning of that
1614 tvbuff of the item being added, and the 'length' argument is the length,
1615 in bytes, of the item.
1617 The length of some items cannot be determined until the item has been
1618 dissected; to add such an item, add it with a length of -1, and, when the
1619 dissection is complete, set the length with 'proto_item_set_len()':
1622 proto_item_set_len(ti, length);
1624 The "ti" argument is the value returned by the call that added the item
1625 to the tree, and the "length" argument is the length of the item.
1627 proto_tree_add_item()
1628 ---------------------
1629 proto_tree_add_item is used when you wish to do no special formatting.
1630 The item added to the GUI tree will contain the name (as passed in the
1631 proto_register_*() function) and a value. The value will be fetched
1632 from the tvbuff by proto_tree_add_item(), based on the type of the field
1633 and, for integral and Boolean fields, the byte order of the value; the
1634 byte order is specified by the 'little_endian' argument, which is TRUE
1635 if the value is little-endian and FALSE if it is big-endian.
1637 Now that definitions of fields have detailed information about bitfield
1638 fields, you can use proto_tree_add_item() with no extra processing to
1639 add bitfield values to your tree. Here's an example. Take the Format
1640 Identifer (FID) field in the Transmission Header (TH) portion of the SNA
1641 protocol. The FID is the high nibble of the first byte of the TH. The
1642 FID would be registered like this:
1644 name = "Format Identifer"
1645 abbrev = "sna.th.fid"
1648 strings = sna_th_fid_vals
1651 The bitmask contains the value which would leave only the FID if bitwise-ANDed
1652 against the parent field, the first byte of the TH.
1654 The code to add the FID to the tree would be;
1656 proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1, TRUE);
1658 The definition of the field already has the information about bitmasking
1659 and bitshifting, so it does the work of masking and shifting for us!
1660 This also means that you no longer have to create value_string structs
1661 with the values bitshifted. The value_string for FID looks like this,
1662 even though the FID value is actually contained in the high nibble.
1663 (You'd expect the values to be 0x0, 0x10, 0x20, etc.)
1665 /* Format Identifier */
1666 static const value_string sna_th_fid_vals[] = {
1667 { 0x0, "SNA device <--> Non-SNA Device" },
1668 { 0x1, "Subarea Node <--> Subarea Node" },
1669 { 0x2, "Subarea Node <--> PU2" },
1670 { 0x3, "Subarea Node or SNA host <--> Subarea Node" },
1673 { 0xf, "Adjaced Subarea Nodes" },
1677 The final implication of this is that display filters work the way you'd
1678 naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent
1679 Subarea Nodes. The user does not have to shift the value of the FID to
1680 the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
1681 before Ethereal 0.7.6.
1683 proto_tree_add_item_hidden()
1684 ----------------------------
1685 proto_tree_add_item_hidden is used to add fields and values to a tree,
1686 but not show them on a GUI tree. The caller may want a value to be
1687 included in a tree so that the packet can be filtered on this field, but
1688 the representation of that field in the tree is not appropriate. An
1689 example is the token-ring routing information field (RIF). The best way
1690 to show the RIF in a GUI is by a sequence of ring and bridge numbers.
1691 Rings are 3-digit hex numbers, and bridges are single hex digits:
1693 RIF: 001-A-013-9-C0F-B-555
1695 In the case of RIF, the programmer should use a field with no value and
1696 use proto_tree_add_none_format() to build the above representation. The
1697 programmer can then add the ring and bridge values, one-by-one, with
1698 proto_tree_add_item_hidden() so that the user can then filter on or
1699 search for a particular ring or bridge. Here's a skeleton of how the
1700 programmer might code this.
1703 rif = create_rif_string(...);
1705 proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
1707 for(i = 0; i < num_rings; i++) {
1708 proto_tree_add_item_hidden(tree, hf_tr_rif_ring, ..., FALSE);
1710 for(i = 0; i < num_rings - 1; i++) {
1711 proto_tree_add_item_hidden(tree, hf_tr_rif_bridge, ..., FALSE);
1714 The logical tree has these items:
1716 hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
1717 hf_tr_rif_ring, hidden, value=0x001
1718 hf_tr_rif_bridge, hidden, value=0xA
1719 hf_tr_rif_ring, hidden, value=0x013
1720 hf_tr_rif_bridge, hidden, value=0x9
1721 hf_tr_rif_ring, hidden, value=0xC0F
1722 hf_tr_rif_bridge, hidden, value=0xB
1723 hf_tr_rif_ring, hidden, value=0x555
1725 GUI or print code will not display the hidden fields, but a display
1726 filter or "packet grep" routine will still see the values. The possible
1727 filter is then possible:
1729 tr.rif_ring eq 0x013
1731 proto_tree_add_protocol_format()
1732 ----------------------------
1733 proto_tree_add_protocol_format is used to add the top-level item for the
1734 protocol when the dissector routines wants complete control over how the
1735 field and value will be represented on the GUI tree. The ID value for
1736 the protocol is passed in as the "id" argument; the rest of the
1737 arguments are a "printf"-style format and any arguments for that format.
1738 The caller must include the name of the protocol in the format; it is
1739 not added automatically as in proto_tree_add_item().
1741 proto_tree_add_none_format()
1742 ----------------------------
1743 proto_tree_add_none_format is used to add an item of type FT_NONE.
1744 The caller must include the name of the field in the format; it is
1745 not added automatically as in proto_tree_add_item().
1747 proto_tree_add_bytes()
1748 proto_tree_add_time()
1749 proto_tree_add_ipxnet()
1750 proto_tree_add_ipv4()
1751 proto_tree_add_ipv6()
1752 proto_tree_add_ether()
1753 proto_tree_add_string()
1754 proto_tree_add_boolean()
1755 proto_tree_add_float()
1756 proto_tree_add_double()
1757 proto_tree_add_uint()
1758 proto_tree_add_uint64()
1759 proto_tree_add_int()
1760 proto_tree_add_int64()
1761 ----------------------------
1762 These routines are used to add items to the protocol tree if either:
1764 the value of the item to be added isn't just extracted from the
1765 packet data, but is computed from data in the packet;
1767 the value was fetched into a variable.
1769 The 'value' argument has the value to be added to the tree.
1771 NOTE: in all cases where the 'value' argument is a pointer, a copy is
1772 made of the object pointed to; if you have dynamically allocated a
1773 buffer for the object, that buffer will not be freed when the protocol
1774 tree is freed - you must free the buffer yourself when you don't need it
1777 For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a
1780 For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
1781 "nstime_t", which is a structure containing the time to be added; it has
1782 'secs' and 'nsecs' members, giving the integral part and the fractional
1783 part of a time in units of seconds, with 'nsecs' being the number of
1784 nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
1785 January 1, 1970, 00:00:00 GMT value.
1787 For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
1790 For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4
1791 address, in network byte order.
1793 For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a
1794 128-bit IPv6 address.
1796 For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a
1799 For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a
1802 For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer;
1803 zero means "false", and non-zero means "true".
1805 For proto_tree_add_float(), the 'value' argument is a 'float' in the
1806 host's floating-point format.
1808 For proto_tree_add_double(), the 'value' argument is a 'double' in the
1809 host's floating-point format.
1811 For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
1812 integer value, in host byte order. (This routine cannot be used to add
1815 For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
1816 integer value, in host byte order.
1818 For proto_tree_add_int(), the 'value' argument is a 32-bit signed
1819 integer value, in host byte order. (This routine cannot be used to add
1822 For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
1823 integer value, in host byte order.
1825 proto_tree_add_bytes_hidden()
1826 proto_tree_add_time_hidden()
1827 proto_tree_add_ipxnet_hidden()
1828 proto_tree_add_ipv4_hidden()
1829 proto_tree_add_ipv6_hidden()
1830 proto_tree_add_ether_hidden()
1831 proto_tree_add_string_hidden()
1832 proto_tree_add_boolean_hidden()
1833 proto_tree_add_float_hidden()
1834 proto_tree_add_double_hidden()
1835 proto_tree_add_uint_hidden()
1836 proto_tree_add_int_hidden()
1837 ----------------------------
1838 These routines add fields and values to a tree, but don't show them in
1839 the GUI tree. They are used for the same reason that
1840 proto_tree_add_item() is used.
1842 proto_tree_add_bytes_format()
1843 proto_tree_add_time_format()
1844 proto_tree_add_ipxnet_format()
1845 proto_tree_add_ipv4_format()
1846 proto_tree_add_ipv6_format()
1847 proto_tree_add_ether_format()
1848 proto_tree_add_string_format()
1849 proto_tree_add_boolean_format()
1850 proto_tree_add_float_format()
1851 proto_tree_add_double_format()
1852 proto_tree_add_uint_format()
1853 proto_tree_add_uint64_format()
1854 proto_tree_add_int_format()
1855 proto_tree_add_int64_format()
1856 ----------------------------
1857 These routines are used to add items to the protocol tree when the
1858 dissector routines wants complete control over how the field and value
1859 will be represented on the GUI tree. The argument giving the value is
1860 the same as the corresponding proto_tree_add_XXX() function; the rest of
1861 the arguments are a "printf"-style format and any arguments for that
1862 format. The caller must include the name of the field in the format; it
1863 is not added automatically as in the proto_tree_add_XXX() functions.
1865 proto_tree_add_text()
1866 ---------------------
1867 proto_tree_add_text() is used to add a label to the GUI tree. It will
1868 contain no value, so it is not searchable in the display filter process.
1869 This function was needed in the transition from the old-style proto_tree
1870 to this new-style proto_tree so that Ethereal would still decode all
1871 protocols w/o being able to filter on all protocols and fields.
1872 Otherwise we would have had to cripple Ethereal's functionality while we
1873 converted all the old-style proto_tree calls to the new-style proto_tree
1876 This can also be used for items with subtrees, which may not have values
1877 themselves - the items in the subtree are the ones with values.
1879 For a subtree, the label on the subtree might reflect some of the items
1880 in the subtree. This means the label can't be set until at least some
1881 of the items in the subtree have been dissected. To do this, use
1882 'proto_item_set_text()' or 'proto_item_append_text()':
1885 proto_item_set_text(proto_item *ti, ...);
1888 proto_item_append_text(proto_item *ti, ...);
1890 'proto_item_set_text()' takes as an argument the value returned by
1891 'proto_tree_add_text()', a 'printf'-style format string, and a set of
1892 arguments corresponding to '%' format items in that string, and replaces
1893 the text for the item created by 'proto_tree_add_text()' with the result
1894 of applying the arguments to the format string.
1896 'proto_item_append_text()' is similar, but it appends to the text for
1897 the item the result of applying the arguments to the format string.
1899 For example, early in the dissection, one might do:
1901 ti = proto_tree_add_text(tree, tvb, offset, length, <label>);
1905 proto_item_set_text(ti, "%s: %s", type, value);
1907 after the "type" and "value" fields have been extracted and dissected.
1908 <label> would be a label giving what information about the subtree is
1909 available without dissecting any of the data in the subtree.
1911 Note that an exception might thrown when trying to extract the values of
1912 the items used to set the label, if not all the bytes of the item are
1913 available. Thus, one should create the item with text that is as
1914 meaningful as possible, and set it or append additional information to
1915 it as the values needed to supply that information is extracted.
1917 proto_tree_add_text_valist()
1918 ---------------------
1919 This is like proto_tree_add_text(), but takes, as the last argument, a
1920 'va_list'; it is used to allow routines that take a printf-like
1921 variable-length list of arguments to add a text item to the protocol
1924 1.7 Utility routines
1926 1.7.1 match_strval and val_to_str
1928 A dissector may need to convert a value to a string, using a
1929 'value_string' structure, by hand, rather than by declaring a field with
1930 an associated 'value_string' structure; this might be used, for example,
1931 to generate a COL_INFO line for a frame.
1933 'match_strval()' will do that:
1936 match_strval(guint32 val, const value_string *vs)
1938 It will look up the value 'val' in the 'value_string' table pointed to
1939 by 'vs', and return either the corresponding string, or NULL if the
1940 value could not be found in the table. Note that, unless 'val' is
1941 guaranteed to be a value in the 'value_string' table ("guaranteed" as in
1942 "the code has already checked that it's one of those values" or "the
1943 table handles all possible values of the size of 'val'", not "the
1944 protocol spec says it has to be" - protocol specs do not prevent invalid
1945 packets from being put onto a network or into a purported packet capture
1946 file), you must check whether 'match_strval()' returns NULL, and arrange
1947 that its return value not be dereferenced if it's NULL. In particular,
1948 don't use it in a call to generate a COL_INFO line for a frame such as
1950 col_add_fstr(COL_INFO, ", %s", match_strval(val, table));
1952 unless is it certain that 'val' is in 'table'.
1954 'val_to_str()' can be used to generate a string for values not found in
1958 val_to_str(guint32 val, const value_string *vs, const char *fmt)
1960 If the value 'val' is found in the 'value_string' table pointed to by
1961 'vs', 'val_to_str' will return the corresponding string; otherwise, it
1962 will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
1963 to generate a string, and will return a pointer to that string.
1964 (Currently, it has three 64-byte static buffers, and cycles through
1965 them; this permits the results of up to three calls to 'val_to_str' to
1966 be passed as arguments to a routine using those strings.)
1969 1.8 Calling Other Dissectors
1971 NOTE: This is discussed in the README.tvbuff file. For more
1972 information on tvbuffers consult that file.
1974 As each dissector completes its portion of the protocol analysis, it
1975 is expected to create a new tvbuff of type TVBUFF_SUBSET which
1976 contains the payload portion of the protocol (that is, the bytes
1977 that are relevant to the next dissector).
1979 The syntax for creating a new TVBUFF_SUBSET is:
1981 next_tvb = tvb_new_subset(tvb, offset, length, reported_length)
1984 tvb is the tvbuff that the dissector has been working on. It
1985 can be a tvbuff of any type.
1987 next_tvb is the new TVBUFF_SUBSET.
1989 offset is the byte offset of 'tvb' at which the new tvbuff
1990 should start. The first byte is the 0th byte.
1992 length is the number of bytes in the new TVBUFF_SUBSET. A length
1993 argument of -1 says to use as many bytes as are available in
1996 reported_length is the number of bytes that the current protocol
1997 says should be in the payload. A reported_length of -1 says that
1998 the protocol doesn't say anything about the size of its payload.
2001 An example from packet-ipx.c -
2004 dissect_ipx(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
2007 int reported_length, available_length;
2010 /* Make the next tvbuff */
2012 /* IPX does have a length value in the header, so calculate report_length */
2013 Set this to -1 if there isn't any length information in the protocol
2015 reported_length = ipx_length - IPX_HEADER_LEN;
2017 /* Calculate the available data in the packet,
2018 set this to -1 to use all the data in the tv_buffer
2020 available_length = tvb_length(tvb) - IPX_HEADER_LEN;
2022 /* Create the tvbuffer for the next dissector */
2023 next_tvb = tvb_new_subset(tvb, IPX_HEADER_LEN,
2024 MIN(available_length, reported_length),
2027 /* call the next dissector */
2028 dissector_next( next_tvb, pinfo, tree);
2031 1.9 Editing Makefile.common to add your dissector.
2033 To arrange that your dissector will be built as part of Ethereal, you
2034 must add the name of the source file for your dissector to the
2035 'DISSECTOR_SRC' macro in the 'Makefile.common' file in the 'epan/dissectors'
2036 directory. (Note that this is for modern versions of UNIX, so there
2037 is no 14-character limitation on file names, and for modern versions of
2038 Windows, so there is no 8.3-character limitation on file names.)
2040 If your dissector also has its own header file or files, you must add
2041 them to the 'DISSECTOR_INCLUDES' macro in the 'Makefile.common' file in
2042 the 'epan/dissectors' directory, so that it's included when release source
2043 tarballs are built (otherwise, the source in the release tarballs won't
2046 1.10 Using the SVN source code tree.
2048 See <http://www.ethereal.com/development.html#source>
2050 1.11 Submitting code for your new dissector.
2052 - Subscribe to <mailto:ethereal-dev@ethereal.com> by sending an email to
2053 <mailto:ethereal-dev-request@ethereal.com?body="help"> or visiting
2054 <http://www.ethereal.com/lists/>.
2056 - 'svn add' all the files of your new dissector.
2058 - 'svn diff' the workspace and save the result to a file.
2060 - Send the diff file along with a note requesting it's inclusion to
2061 <mailto:ethereal-dev@ethereal.com>. You can also use this procedure for
2062 providing patches to your dissector or any other part of ethereal.
2064 - If you find that you are contributing a lot to ethereal on an ongoing
2065 basis you can request to become a committer which will allow you to commit
2066 files to subversion directly.
2068 2. Advanced dissector topics.
2072 2.2 Following "conversations".
2074 In ethereal a conversation is defined as a series of data packet between two
2075 address:port combinations. A conversation is not sensitive to the direction of
2076 the packet. The same conversation will be returned for a packet bound from
2077 ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
2079 There are five routines that you will use to work with a conversation:
2080 conversation_new, find_conversation, conversation_add_proto_data,
2081 conversation_get_proto_data, and conversation_delete_proto_data.
2084 2.2.1 The conversation_init function.
2086 This is an internal routine for the conversation code. As such the you
2087 will not have to call this routine. Just be aware that this routine is
2088 called at the start of each capture and before the packets are filtered
2089 with a display filter. The routine will destroy all stored
2090 conversations. This routine does NOT clean up any data pointers that are
2091 passed in the conversation_new 'data' variable. You are responsible for
2092 this clean up if you pass a malloc'ed pointer in this variable.
2094 See item 2.2.7 for more information about the 'data' pointer.
2097 2.2.2 The conversation_new function.
2099 This routine will create a new conversation based upon two address/port
2100 pairs. If you want to associate with the conversation a pointer to a
2101 private data structure you must use the conversation_add_proto_data
2102 function. The ptype variable is used to differentiate between
2103 conversations over different protocols, i.e. TCP and UDP. The options
2104 variable is used to define a conversation that will accept any destination
2105 address and/or port. Set options = 0 if the destination port and address
2106 are know when conversation_new is called. See section 2.4 for more
2107 information on usage of the options parameter.
2109 The conversation_new prototype:
2110 conversation_t *conversation_new(address *addr1, address *addr2,
2111 port_type ptype, guint32 port1, guint32 port2, guint options);
2114 address* addr1 = first data packet address
2115 address* addr2 = second data packet address
2116 port_type ptype = port type, this is defined in packet.h
2117 guint32 port1 = first data packet port
2118 guint32 port2 = second data packet port
2119 guint options = conversation options, NO_ADDR2 and/or NO_PORT2
2121 "addr1" and "port1" are the first address/port pair; "addr2" and "port2"
2122 are the second address/port pair. A conversation doesn't have source
2123 and destination address/port pairs - packets in a conversation go in
2124 both directions - so "addr1"/"port1" may be the source or destination
2125 address/port pair; "addr2"/"port2" would be the other pair.
2127 If NO_ADDR2 is specified, the conversation is set up so that a
2128 conversation lookup will match only the "addr1" address; if NO_PORT2 is
2129 specified, the conversation is set up so that a conversation lookup will
2130 match only the "port1" port; if both are specified, i.e.
2131 NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
2132 match only the "addr1"/"port1" address/port pair. This can be used if a
2133 packet indicates that, later in the capture, a conversation will be
2134 created using certain addresses and ports, in the case where the packet
2135 doesn't specify the addresses and ports of both sides.
2137 2.2.3 The find_conversation function.
2139 Call this routine to look up a conversation. If no conversation is found,
2140 the routine will return a NULL value.
2142 The find_conversation prototype:
2144 conversation_t *find_conversation(address *addr_a, address *addr_b,
2145 port_type ptype, guint32 port_a, guint32 port_b, guint options);
2148 address* addr_a = first address
2149 address* addr_b = second address
2150 port_type ptype = port type
2151 guint32 port_a = first data packet port
2152 guint32 port_b = second data packet port
2153 guint options = conversation options, NO_ADDR_B and/or NO_PORT_B
2155 "addr_a" and "port_a" are the first address/port pair; "addr_b" and
2156 "port_b" are the second address/port pair. Again, as a conversation
2157 doesn't have source and destination address/port pairs, so
2158 "addr_a"/"port_a" may be the source or destination address/port pair;
2159 "addr_b"/"port_b" would be the other pair. The search will match the
2160 "a" address/port pair against both the "1" and "2" address/port pairs,
2161 and match the "b" address/port pair against both the "2" and "1"
2162 address/port pairs; you don't have to worry about which side the "a" or
2163 "b" pairs correspond to.
2165 If the NO_ADDR_B flag was specified to "find_conversation()", the
2166 "addr_b" address will be treated as matching any "wildcarded" address;
2167 if the NO_PORT_B flag was specified, the "port_b" port will be treated
2168 as matching any "wildcarded" port. If both flags are specified, i.e.
2169 NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
2170 any "wildcarded" address and the "port_b" port will be treated as
2171 matching any "wildcarded" port.
2174 2.2.4 The conversation_add_proto_data function.
2176 Once you have created a conversation with conversation_new, you can
2177 associate data with it using this function.
2179 The conversation_add_proto_data prototype:
2181 void conversation_add_proto_data(conversation_t *conv, int proto,
2185 conversation_t *conv = the conversation in question
2186 int proto = registered protocol number
2187 void *data = dissector data structure
2189 "conversation" is the value returned by conversation_new. "proto" is a
2190 unique protocol number created with proto_register_protocol. Protocols
2191 are typically registered in the proto_register_XXXX section of your
2192 dissector. "data" is a pointer to the data you wish to associate with the
2193 conversation. Using the protocol number allows several dissectors to
2194 associate data with a given conversation.
2197 2.2.5 The conversation_get_proto_data function.
2199 After you have located a conversation with find_conversation, you can use
2200 this function to retrieve any data associated with it.
2202 The conversation_get_proto_data prototype:
2204 void *conversation_get_proto_data(conversation_t *conv, int proto);
2207 conversation_t *conv = the conversation in question
2208 int proto = registered protocol number
2210 "conversation" is the conversation created with conversation_new. "proto"
2211 is a unique protocol number acreated with proto_register_protocol,
2212 typically in the proto_register_XXXX portion of a dissector. The function
2213 returns a pointer to the data requested, or NULL if no data was found.
2216 2.2.6 The conversation_delete_proto_data function.
2218 After you are finished with a conversation, you can remove your assocation
2219 with this function. Please note that ONLY the conversation entry is
2220 removed. If you have allocated any memory for your data, you must free it
2223 The conversation_delete_proto_data prototype:
2225 void conversation_delete_proto_data(conversation_t *conv, int proto);
2228 conversation_t *conv = the conversation in question
2229 int proto = registered protocol number
2231 "conversation" is the conversation created with conversation_new. "proto"
2232 is a unique protocol number acreated with proto_register_protocol,
2233 typically in the proto_register_XXXX portion of a dissector.
2236 2.2.7 The example conversation code with GMemChunk's
2238 For a conversation between two IP addresses and ports you can use this as an
2239 example. This example uses the GMemChunk to allocate memory and stores the data
2240 pointer in the conversation 'data' variable.
2242 NOTE: Remember to register the init routine (my_dissector_init) in the
2243 protocol_register routine.
2246 /************************ Globals values ************************/
2248 /* the number of entries in the memory chunk array */
2249 #define my_init_count 10
2251 /* define your structure here */
2256 /* the GMemChunk base structure */
2257 static GMemChunk *my_vals = NULL;
2259 /* Registered protocol number
2260 static int my_proto = -1;
2263 /********************* in the dissector routine *********************/
2265 /* the local variables in the dissector */
2267 conversation_t *conversation;
2268 my_entry_t *data_ptr
2271 /* look up the conversation */
2273 conversation = find_conversation( &pinfo->src, &pinfo->dst, pinfo->ptype,
2274 pinfo->srcport, pinfo->destport, 0);
2276 /* if conversation found get the data pointer that you stored */
2278 data_ptr = (my_entry_t*)conversation_get_proto_data(conversation,
2282 /* new conversation create local data structure */
2284 data_ptr = g_mem_chunk_alloc(my_protocol_vals);
2286 /*** add your code here to setup the new data structure ***/
2288 /* create the conversation with your data pointer */
2290 conversation_new( &pinfo->src, &pinfo->dst, pinfo->ptype,
2291 pinfo->srcport, pinfo->destport, 0);
2292 conversation_add_proto_data(conversation, my_proto, (void *) data_ptr);
2295 /* at this point the conversation data is ready */
2298 /******************* in the dissector init routine *******************/
2300 #define my_init_count 20
2303 my_dissector_init( void){
2305 /* destroy memory chunks if needed */
2308 g_mem_chunk_destroy(my_vals);
2310 /* now create memory chunks */
2312 my_vals = g_mem_chunk_new( "my_proto_vals",
2314 my_init_count * sizeof( my_entry_t),
2318 /***************** in the protocol register routine *****************/
2320 /* register re-init routine */
2322 register_init_routine( &my_dissector_init);
2324 my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto");
2327 2.2.8 The example conversation code using conversation index field
2329 Sometimes the conversation isn't enough to define a unique data storage
2330 value for the network traffic. For example if you are storing information
2331 about requests carried in a conversation, the request may have an
2332 identifier that is used to define the request. In this case the
2333 conversation and the identifier are required to find the data storage
2334 pointer. You can use the conversation data structure index value to
2335 uniquely define the conversation.
2337 See packet-afs.c for an example of how to use the conversation index. In
2338 this dissector multiple requests are sent in the same conversation. To store
2339 information for each request the dissector has an internal hash table based
2340 upon the conversation index and values inside the request packets.
2343 /* in the dissector routine */
2345 /* to find a request value, first lookup conversation to get index */
2346 /* then used the conversation index, and request data to find data */
2347 /* in the local hash table */
2349 conversation = find_conversation(&pinfo->src, &pinfo->dst, pinfo->ptype,
2350 pinfo->srcport, pinfo->destport, 0);
2351 if (conversation == NULL) {
2352 /* It's not part of any conversation - create a new one. */
2353 conversation = conversation_new(&pinfo->src, &pinfo->dst, pinfo->ptype,
2354 pinfo->srcport, pinfo->destport, NULL, 0);
2357 request_key.conversation = conversation->index;
2358 request_key.service = pntohs(&rxh->serviceId);
2359 request_key.callnumber = pntohl(&rxh->callNumber);
2361 request_val = (struct afs_request_val *) g_hash_table_lookup(
2362 afs_request_hash, &request_key);
2364 /* only allocate a new hash element when it's a request */
2366 if ( !request_val && !reply)
2368 new_request_key = g_mem_chunk_alloc(afs_request_keys);
2369 *new_request_key = request_key;
2371 request_val = g_mem_chunk_alloc(afs_request_vals);
2372 request_val -> opcode = pntohl(&afsh->opcode);
2373 opcode = request_val->opcode;
2375 g_hash_table_insert(afs_request_hash, new_request_key,
2381 2.3 Dynamic conversation dissector registration
2384 NOTE: This sections assumes that all information is available to
2385 create a complete conversation, source port/address and
2386 destination port/address. If either the destination port or
2387 address is know, see section 2.4 Dynamic server port dissector
2390 For protocols that negotiate a secondary port connection, for example
2391 packet-msproxy.c, a conversation can install a dissector to handle
2392 the secondary protocol dissection. After the conversation is created
2393 for the negotiated ports use the conversation_set_dissector to define
2394 the dissection routine.
2396 The second argument to conversation_set_dissector is a dissector handle,
2397 which is created with a call to create_dissector_handle or
2400 create_dissector_handle takes as arguments a pointer to the dissector
2401 function and a protocol ID as returned by proto_register_protocol;
2402 register_dissector takes as arguments a string giving a name for the
2403 dissector, a pointer to the dissector function, and a protocol ID.
2405 The protocol ID is the ID for the protocol dissected by the function.
2406 The function will not be called if the protocol has been disabled by the
2407 user; instead, the data for the protocol will be dissected as raw data.
2411 /* the handle for the dynamic dissector *
2412 static dissector_handle_t sub_dissector_handle;
2414 /* prototype for the dynamic dissector */
2415 static void sub_dissector( tvbuff_t *tvb, packet_info *pinfo,
2418 /* in the main protocol dissector, where the next dissector is setup */
2420 /* if conversation has a data field, create it and load structure */
2422 new_conv_info = g_mem_chunk_alloc( new_conv_vals);
2423 new_conv_info->data1 = value1;
2425 /* create the conversation for the dynamic port */
2426 conversation = conversation_new( &pinfo->src, &pinfo->dst, protocol,
2427 src_port, dst_port, new_conv_info, 0);
2429 /* set the dissector for the new conversation */
2430 conversation_set_dissector(conversation, sub_dissector_handle);
2435 proto_register_PROTOABBREV(void)
2439 sub_dissector_handle = create_dissector_handle(sub_dissector,
2445 2.4 Dynamic server port dissector registration
2447 NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
2448 conversation with only one port and address set, this isn't a
2449 requirement. Either the second port or the second address can be set
2450 when the conversation is created.
2452 For protocols that define a server address and port for a secondary
2453 protocol, a conversation can be used to link a protocol dissector to
2454 the server port and address. The key is to create the new
2455 conversation with the second address and port set to the "accept
2458 There are two support routines that will allow the second port and/or
2459 address to be set latter.
2461 conversation_set_port2( conversation_t *conv, guint32 port);
2462 conversation_set_addr2( conversation_t *conv, address addr);
2464 These routines will change the second address or port for the
2465 conversation. So, the server port conversation will be converted into a
2466 more complete conversation definition. Don't use these routines if you
2467 want create a conversation between the server and client and retain the
2468 server port definition, you must create a new conversation.
2473 /* the handle for the dynamic dissector *
2474 static dissector_handle_t sub_dissector_handle;
2478 /* in the main protocol dissector, where the next dissector is setup */
2480 /* if conversation has a data field, create it and load structure */
2482 new_conv_info = g_mem_chunk_alloc( new_conv_vals);
2483 new_conv_info->data1 = value1;
2485 /* create the conversation for the dynamic server address and port */
2486 /* NOTE: The second address and port values don't matter because the */
2487 /* NO_ADDR2 and NO_PORT2 options are set. */
2489 conversation = conversation_new( &server_src_addr, 0, protocol,
2490 server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2);
2492 /* set the dissector for the new conversation */
2493 conversation_set_dissector(conversation, sub_dissector_handle);
2496 2.5 Per packet information
2498 Information can be stored for each data packet that is processed by the dissector.
2499 The information is added with the p_add_proto_data function and retreived with the
2500 p_get_proto_data function. The data pointers passed into the p_add_proto_data are
2501 not managed by the proto_data routines. If you use malloc or any other dynamic
2502 memory allocation scheme, you must release the data when it isn't required.
2505 p_add_proto_data(frame_data *fd, int proto, void *proto_data)
2507 p_get_proto_data(frame_data *fd, int proto)
2510 fd - The fd pointer in the pinfo structure, pinfo->fd
2511 proto - Protocol id returned by the proto_register_protocol call during initialization
2512 proto_data - pointer to the dissector data.
2515 2.6 User Preferences
2517 If the dissector has user options, there is support for adding these preferences
2518 to a configuration dialog.
2520 You must register the module with the preferences routine with -
2522 module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void))
2524 Where: proto_id - the value returned by "proto_register_protocol()" when
2525 the protocol was registered
2526 apply_cb - Callback routine that is call when preferences are applied
2529 Then you can register the fields that can be configured by the user with these routines -
2531 /* Register a preference with an unsigned integral value. */
2532 void prefs_register_uint_preference(module_t *module, const char *name,
2533 const char *title, const char *description, guint base, guint *var);
2535 /* Register a preference with an Boolean value. */
2536 void prefs_register_bool_preference(module_t *module, const char *name,
2537 const char *title, const char *description, gboolean *var);
2539 /* Register a preference with an enumerated value. */
2540 void prefs_register_enum_preference(module_t *module, const char *name,
2541 const char *title, const char *description, gint *var,
2542 const enum_val_t *enumvals, gboolean radio_buttons)
2544 /* Register a preference with a character-string value. */
2545 void prefs_register_string_preference(module_t *module, const char *name,
2546 const char *title, const char *description, char **var)
2548 /* Register a preference with a range of unsigned integers (e.g.,
2551 void prefs_register_range_preference(module_t *module, const char *name,
2552 const char *title, const char *description, range_t *var,
2555 Where: module - Returned by the prefs_register_protocol routine
2556 name - This is appended to the name of the protocol, with a
2557 "." between them, to construct a name that identifies
2558 the field in the preference file; the name itself
2559 should not include the protocol name, as the name in
2560 the preference file will already have it
2561 title - Field title in the preferences dialog
2562 description - Comments added to the preference file above the
2564 var - pointer to the storage location that is updated when the
2565 field is changed in the preference dialog box
2566 enumvals - an array of enum_val_t structures. This must be
2567 NULL-terminated; the members of that structure are:
2569 a short name, to be used with the "-o" flag - it
2570 should not contain spaces or upper-case letters,
2571 so that it's easier to put in a command line;
2573 a description, which is used in the GUI (and
2574 which, for compatibility reasons, is currently
2575 what's written to the preferences file) - it can
2576 contain spaces, capital letters, punctuation,
2579 the numerical value corresponding to that name
2581 radio_buttons - TRUE if the field is to be displayed in the
2582 preferences dialog as a set of radio buttons,
2583 FALSE if it is to be displayed as an option
2585 max_value - The maximum allowed value for a range (0 is the minimum).
2587 An example from packet-beep.c -
2589 proto_beep = proto_register_protocol("Blocks Extensible Exchange Protocol",
2594 /* Register our configuration options for BEEP, particularly our port */
2596 beep_module = prefs_register_protocol(proto_beep, proto_reg_handoff_beep);
2598 prefs_register_uint_preference(beep_module, "tcp.port", "BEEP TCP Port",
2599 "Set the port for BEEP messages (if other"
2600 " than the default of 10288)",
2601 10, &global_beep_tcp_port);
2603 prefs_register_bool_preference(beep_module, "strict_header_terminator",
2604 "BEEP Header Requires CRLF",
2605 "Specifies that BEEP requires CRLF as a "
2606 "terminator, and not just CR or LF",
2607 &global_beep_strict_term);
2609 This will create preferences "beep.tcp.port" and
2610 "beep.strict_header_terminator", the first of which is an unsigned
2611 integer and the second of which is a Boolean.
2613 2.7 Reassembly/desegmentation for protocols running atop TCP
2615 There are two main ways of reassembling a Protocol Data Unit (PDU) which
2616 spans across multiple TCP segments. The first approach is simpler, but
2617 assumes you are running atop of TCP when this occurs (but your dissector
2618 might run atop of UDP, too, for example), and that your PDUs consist of a
2619 fixed amount of data that includes enough information to determine the PDU
2620 length, possibly followed by additional data. The second method is more
2621 generic but requires more code and is less efficient.
2623 For the first method, you register two different dissection methods, one
2624 for the TCP case, and one for the other cases. It is a good idea to
2625 also have a dissect_PROTO_common function which will parse the generic
2626 content that you can find in all PDUs which is called from
2627 dissect_PROTO_tcp when the reassembly is complete and from
2628 dissect_PROTO_udp (or dissect_PROTO_other).
2630 To register the distinct dissector functions, consider the following
2631 example, stolen from packet-dns.c:
2633 dissector_handle_t dns_udp_handle;
2634 dissector_handle_t dns_tcp_handle;
2635 dissector_handle_t mdns_udp_handle;
2637 dns_udp_handle = create_dissector_handle(dissect_dns_udp,
2639 dns_tcp_handle = create_dissector_handle(dissect_dns_tcp,
2641 mdns_udp_handle = create_dissector_handle(dissect_mdns_udp,
2644 dissector_add("udp.port", UDP_PORT_DNS, dns_udp_handle);
2645 dissector_add("tcp.port", TCP_PORT_DNS, dns_tcp_handle);
2646 dissector_add("udp.port", UDP_PORT_MDNS, mdns_udp_handle);
2647 dissector_add("tcp.port", TCP_PORT_MDNS, dns_tcp_handle);
2649 The dissect_dns_udp function does very little work and calls
2650 dissect_dns_common, while dissect_dns_tcp calls tcp_dissect_pdus with a
2651 reference to a callback which will be called with reassembled data:
2654 dissect_dns_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
2656 tcp_dissect_pdus(tvb, pinfo, tree, dns_desegment, 2,
2657 get_dns_pdu_len, dissect_dns_tcp_pdu);
2660 (The dissect_dns_tcp_pdu function acts similarly to dissect_dns_udp.)
2661 The arguments to tcp_dissect_pdus are:
2663 the tvbuff pointer, packet_info pointer, and proto_tree pointer
2664 passed to the dissector;
2666 a gboolean flag indicating whether desegmentation is enabled for
2669 the number of bytes of PDU data required to determine the length
2672 a routine that takes as arguments a tvbuff pointer and an offset
2673 value representing the offset into the tvbuff at which a PDU
2674 begins and should return - *without* throwing an exception (it
2675 is guaranteed that the number of bytes specified by the previous
2676 argument to tcp_dissect_pdus is available, but more data might
2677 not be available, so don't refer to any data past that) - the
2678 total length of the PDU, in bytes;
2680 a routine that's passed a tvbuff pointer, packet_info pointer,
2681 and proto_tree pointer, with the tvbuff containing a
2682 possibly-reassembled PDU, and that should dissect that PDU.
2684 The second method is to return a modified pinfo structure when
2685 dissect_PROTO is called. In this case, you have to check if you have
2686 collected enough bytes: if you have enough, you parse the PDU, and if
2687 don't have enough bytes, you return from the dissector supplying
2688 information to the caller on how many bytes you need to proceed. This
2689 is done by indicating the offset where you would like to start again and
2690 the number of bytes that you need in pinfo->desegment_*:
2692 if (i_miss_five_bytes) {
2693 pinfo->desegment_offset = offset;
2694 pinfo->desegment_len = 5;
2697 You can repeat this procedure until you've got enough bytes; for
2698 example, you can request one byte more until you've got the byte you're
2699 searching for if the data to be dissected consists of a sequence of
2700 bytes ending with a particular byte value.
2704 See the README.plugins for more information on how to "pluginize"
2707 4.0 Extending Wiretap.
2709 5.0 How the Display Filter Engine works
2712 epan/dfilter/* - the display filter engine, including
2713 scanner, parser, syntax-tree semantics checker, DFVM bytecode
2714 generator, and DFVM engine.
2715 epan/ftypes/* - the definitions of the various FT_* field types.
2716 epan/proto.c - proto_tree-related routines
2720 The scanner/parser pair read the string representing the display filter
2721 and convert it into a very simple syntax tree. The syntax tree is very
2722 simple in that it is possible that many of the nodes contain unparsed
2723 chunks of text from the display filter.
2725 5.1 Enhancing the syntax tree.
2727 The semantics of the simple syntax tree are checked to make sure that
2728 the fields that are being compared are being compared to appropriate
2729 values. For example, if a field is an integer, it can't be compared to
2730 a string, unless a value_string has been defined for that field.
2732 During the process of checking the semantics, the simple syntax tree is
2733 fleshed out and no longer contains nodes with unparsed information. The
2734 syntax tree is no longer in its simple form, but in its complete form.
2736 5.2 Converting to DFVM bytecode
2738 The syntax tree is analyzed to create a sequence of bytecodes in the
2739 "DFVM" language. "DFVM" stands for Display Filter Virtual Machine. The
2740 DFVM is similar in spirit, but not in definition, to the BPF VM that
2741 libpcap uses to analyze packets.
2743 A virtual bytecode is created and used so that the actual process of
2744 filtering packets will be fast. That is, it should be faster to process
2745 a list of VM bytecodes than to attempt to filter packets directly from
2746 the syntax tree. (heh... no measurement has been made to support this
2751 Once the DFVM bytecode has been produced, it's a simple matter of
2752 running the DFVM engine against the proto_tree from the packet
2753 dissection, using the DFVM bytecodes as instructions. If the DFVM
2754 bytecode is known before packet dissection occurs, the
2755 proto_tree-related code can be "primed" to store away pointers to
2756 field_info structures that are interesting to the display filter. This
2757 makes lookup of those field_info structures during the filtering process
2761 6.0 Adding new capabilities.
2766 James Coe <jammer@cin.net>
2767 Gilbert Ramirez <gram@alumni.rice.edu>
2768 Jeff Foster <jfoste@woodward.com>
2769 Olivier Abad <oabad@cybercable.fr>
2770 Laurent Deniel <laurent.deniel@free.fr>
2771 Gerald Combs <gerald@ethereal.com>
2772 Guy Harris <guy@alum.mit.edu>