This document is an attempt, to bring some light to the things done, when
packet capturing is performed. There might be things missing, and others
maybe wrong :-( The following will concentrate a bit on the Windows
port of Wireshark.


XXX: when ongoing file reorganization will be completed, the following
two lists maybe won't be needed any longer!

libpcap related source files:
-----------------------------
capture-pcap-util.c
capture-pcap-util.h
capture-pcap-util-int.h
capture-pcap-util-unix.c
capture-wpcap.c
capture-wpcap.h

Capture related source files:
-----------------------------
capture.c
capture.h
capture_loop.c
capture_loop.h
capture_opts.c
capture_sync.c
capture_ui_utils.c
capture_ui_utils.h


Capture driver
--------------
Wireshark doesn't have direct access to the capture hardware. Instead of this,
it uses the Libpcap/Winpcap library to capture data from network cards.

On Win32, in capture-wpcap.c the function ws_module_open("wpcap.dll") is called
to load the wpcap.dll. This dll includes all functions needed for
packet capturing.



Capture File
------------
There are some kinds of targets to put the capture data into:

-temporary file
-user specified "single" capture file
-user specified "ringbuffer" capture file

Which kind of file is used depends on the user settings. In principle there
is no difference in handling these files, so if not otherwise notified,
it will be called the capture file.

The capture file is stored, using the wiretap library.


Overview
--------
Capturing is done using a two task model: the currently running (parent)
process will spawn a child process to do the real capture work, namely
controlling libpcap. This two task model is used because it's necessary
to split the capturing process (which should avoid packet drop) from the parent
process which might need significant time to display the data.

When a capture is started, the parent builds a "command line" and creates a
new child process with it. A pipe from the child to the parent is created
which is used to transfer control messages.

The child will init libpcap and send the parent a "new capture file is used"
control message through the pipe.

The child cyclically takes the packet data from libpcap and saves it to disk.
From time to time it will send the parent a "new packets" control message.

If the parent process receives this "new packets" message and the option
"Update list of packets in real time" is used, it will read the packet data
from the file, dissect and display it.


If the user wants to stop the capture, this can be done in two ways: by
menu/toolbar of the parent process or the Stop button of the child processes
dialog box (which obviously cannot be used it this dialog is hidden).

The Stop button will stop the capture itself, close the control pipe and then
closes itself. The parent will detect this and stop its part of the capture.

If the menu/toolbar is used, the parent will send a break signal to the child
which will lead to the same sequence as described above.

Win32 only: as the windows implementation of signals simply doesn't work,
another pipe from the parent to the child is used to send a "close capture"
message instead of a signal.


Start capture
-------------
A capture is started, by specifying to start the capture at the command line,
trigger the OK button in the "Capture Options" dialog box and some more. The
capture start is actually done by calling the capture_start() function in
capture.c.


Capture child (Loop)
--------------------
The capture child will open the target capture file, prepare pcap things,
init stop conditions, init the capture statistic dialog (if not hidden) and
start a loop which is running until the flag ld.go is FALSE.

Inside this loop,

-Qt main things are updated
-pcap_dispatch(capture_pcap_cb) is called
-the capture stop conditions are checked (ld.go is set to FALSE to finish)
-update the capture statistic dialog (if not hidden)

While this loop is running, the pcap_dispatch() will call capture_pcap_cb()
for every packet captured. Inside this, the packet data is converted into
wtap (wiretap) format and saved to file. Beside saving, it is trying to
do some basic dissecting (for the statistic window), by calling the
appropriate capture_xxx function.

When the user triggered a capture stop or one of the capture stop conditions
matched, the ld.go flag is set to FALSE, and the loop will stop shortly after.


Capture parent
--------------
In the capture parent the cap_pipe_input_cb() function is called "cyclically"
(unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show
it on the main screen. While the capture is in progress, no other capture file
can be opened.


Updating
--------
The actual packet capturing inside the libpcap is done using its own task.
Catching and processing the packet data from the libpcap is done using the
pcap_dispatch() function.

Unfortunately, the closest thing to a design document is the
"README.developer" document in the "doc" directory of the Wireshark
source tree; however, although that's useful for people adding new
protocol dissectors to Wireshark, it doesn't describe the operations of
the "core" of Wireshark.

We have no document describing that; however, a quick summary of the
part of the code you'd probably be working with is:

	for every capture file that Wireshark has open, there's a
	"capture_file" structure - Wireshark currently supports only one
	open capture file at a time, and that structure is named
	"cfile" (see the "file.h" header file);

	that structure has a member "plist", which points to a
	"frame_data" structure - every link-layer frame that Wireshark
	has read in has a "frame_data" structure (see the
	"epan/packet.h" header file), the "plist" member of "cfile"
	points to the first frame, and each frame has a "next" member
	that points to the next frame in the capture (or is null for the
	last frame);

	each "frame_data" struct has:

		a pointer to the next frame (null for the last frame);

		a pointer to the previous frame (null for the first
		frame);

		information such as the ordinal number of the frame in
		the capture, the time stamps for the capture, the size
		of the packet data in bytes, the size of the frame in
		bytes (which might not equal the size of the packet data
		if, for example, the program capturing the packets
		captured no more than the first N bytes of the capture,
		for some value of N);

		the byte offset in the capture file where the frame's
		data is located.

See the "print_packets()" routine in "file.c" for an example of a
routine that goes through all the packets in the capture; the loop does

	for (fdata = cf->plist; fdata != NULL; fdata = fdata->next) {

		update a progress bar (because it could take a
		    significant period of time to process all packets);

		read the packet data if the packet is to be printed;

		print the packet;

	}

The "wtap_seek_read()" call reads the packet data into memory; the
"epan_dissect_new()" call "dissects" that data, building a tree
structure for the fields in the packet.

This file is a HOWTO for Wireshark developers. It describes general development
and coding practices for contributing to Wireshark no matter which part of
Wireshark you want to work on.

To learn how to write a dissector, read this first, then read the file
README.dissector.

This file is compiled to give in depth information on Wireshark.
It is by no means all inclusive and complete. Please feel free to send
remarks and patches to the developer mailing list.

0. Prerequisites.

Before starting to develop a new dissector, a "running" Wireshark build
environment is required - there's no such thing as a standalone "dissector
build toolkit".

How to setup such an environment is platform dependent; detailed
information about these steps can be found in the "Developer's Guide"
(available from: https://www.wireshark.org) and in the INSTALL and
README.md files of the sources root dir.

0.1. General README files.

You'll find additional information in the following README files:

- README.capture        - the capture engine internals
- README.design         - Wireshark software design - incomplete
- README.developer      - this file
- README.dissector      - How to dissect a packet
- README.display_filter - Display Filter Engine
- README.idl2wrs        - CORBA IDL converter
- README.packaging      - how to distribute a software package containing WS
- README.regression     - regression testing of WS and TS
- README.stats_tree     - a tree statistics counting specific packets
- README.tapping        - "tap" a dissector to get protocol specific events
- README.xml-output     - how to work with the PDML exported output
- wiretap/README.developer - how to add additional capture file types to
  Wiretap

0.2. Dissector related README files.

You'll find additional dissector related information in the file
README.dissector as well as the following README files:

- README.heuristic      - what are heuristic dissectors and how to write them
- README.plugins        - how to "pluginize" a dissector
- README.request_response_tracking - how to track req./resp. times and such
- README.wmem           - how to obtain "memory leak free" memory

0.3 Contributors

James Coe <jammer[AT]cin.net>
Gilbert Ramirez <gram[AT]alumni.rice.edu>
Jeff Foster <jfoste[AT]woodward.com>
Olivier Abad <oabad[AT]cybercable.fr>
Laurent Deniel <laurent.deniel[AT]free.fr>
Gerald Combs <gerald[AT]wireshark.org>
Guy Harris <guy[AT]alum.mit.edu>
Ulf Lamping <ulf.lamping[AT]web.de>

1. Portability.

Wireshark runs on many platforms, and can be compiled with a number of
different compilers; here are some rules for writing code that will work
on multiple platforms.

In general, not all C99 features can be used since some C compilers used to
compile Wireshark, such as Microsoft's C compiler, don't support all C99
features.  The C99 features that can be used are:

 - flexible array members
 - compound literals
 - designated initializers
 - "//" comments
 - mixed declarations and code
 - new block scopes for selection and iteration statements (that is, declaring
   the type in a for-loop like: for (int i = 0; i < n; i++) ;)
 - macros with a variable number of arguments (variadic macros)
 - trailing comma in enum declarations
 - inline functions (guaranteed only by use of glib.h)

Don't initialize global or static variables (variables with static
storage duration) in their declaration with non-constant values.  Not
all compilers support this.  E.g., if "i" is a static or global
variable, don't declare "i" as

    guint32 i = somearray[2];

outside a function, or as

    static guint32 i = somearray[2];

inside or outside a function, declare it as just

    guint32 i;

or

    static guint32 i;

and later, in code, initialize it with

    i = somearray[2];

instead.  Initializations of variables with automatic storage duration -
i.e., local variables - with non-constant values is permitted, so,
within a function

    guint32 i = somearray[2];

is allowed.

Don't use zero-length arrays as structure members, use flexible array members
instead.

Don't use anonymous unions; not all compilers support them.
Example:

    typedef struct foo {
      guint32 foo;
      union {
        guint32 foo_l;
        guint16 foo_s;
      } u;  /* have a name here */
    } foo_t;

Don't use "uchar", "u_char", "ushort", "u_short", "uint", "u_int",
"ulong", "u_long" or "boolean"; they aren't defined on all platforms.
If you want an 8-bit unsigned quantity, use "guint8"; if you want an
8-bit character value with the 8th bit not interpreted as a sign bit,
use "guchar"; if you want a 16-bit unsigned quantity, use "guint16";
if you want a 32-bit unsigned quantity, use "guint32"; and if you want
an "int-sized" unsigned quantity, use "guint"; if you want a boolean,
use "gboolean".  Use "%d", "%u", "%x", and "%o" to print those types;
don't use "%ld", "%lu", "%lx", or "%lo", as longs are 64 bits long on
many platforms, but "guint32" is 32 bits long.

Don't use "long" to mean "signed 32-bit integer", and don't use
"unsigned long" to mean "unsigned 32-bit integer"; "long"s are 64 bits
long on many platforms.  Use "gint32" for signed 32-bit integers and use
"guint32" for unsigned 32-bit integers.

Don't use "long" to mean "signed 64-bit integer" and don't use "unsigned
long" to mean "unsigned 64-bit integer"; "long"s are 32 bits long on
many other platforms.  Don't use "long long" or "unsigned long long",
either, as not all platforms support them; use "gint64" or "guint64",
which will be defined as the appropriate types for 64-bit signed and
unsigned integers.

On LLP64 data model systems (notably 64-bit Windows), "int" and "long"
are 32 bits while "size_t" and "ptrdiff_t" are 64 bits. This means that
the following will generate a compiler warning:

    int i;
    i = strlen("hello, sailor");  /* Compiler warning */

Normally, you'd just make "i" a size_t. However, many GLib and Wireshark
functions won't accept a size_t on LLP64:

    size_t i;
    char greeting[] = "hello, sailor";
    guint byte_after_greet;

    i = strlen(greeting);
    byte_after_greet = tvb_get_guint8(tvb, i); /* Compiler warning */

Try to use the appropriate data type when you can. When you can't, you
will have to cast to a compatible data type, e.g.

    size_t i;
    char greeting[] = "hello, sailor";
    guint byte_after_greet;

    i = strlen(greeting);
    byte_after_greet = tvb_get_guint8(tvb, (gint) i); /* OK */

or

    gint i;
    char greeting[] = "hello, sailor";
    guint byte_after_greet;

    i = (gint) strlen(greeting);
    byte_after_greet = tvb_get_guint8(tvb, i); /* OK */

See http://www.unix.org/version2/whatsnew/lp64_wp.html for more
information on the sizes of common types in different data models.

When printing or displaying the values of 64-bit integral data types,
don't use "%lld", "%llu", "%llx", or "%llo" - not all platforms
support "%ll" for printing 64-bit integral data types.  Instead, for
GLib routines, and routines that use them, such as all the routines in
Wireshark that take format arguments, use G_GINT64_MODIFIER, for example:

    proto_tree_add_uint64_format_value(tree, hf_uint64, tvb, offset, len,
                                       val, "%" G_GINT64_MODIFIER "u", val);

When specifying an integral constant that doesn't fit in 32 bits, don't
use "LL" at the end of the constant - not all compilers use "LL" for
that.  Instead, put the constant in a call to the "G_GINT64_CONSTANT()"
macro, e.g.

    G_GINT64_CONSTANT(-11644473600), G_GUINT64_CONSTANT(11644473600)

rather than

    -11644473600LL, 11644473600ULL

Don't assume that you can scan through a va_list initialized by va_start
more than once without closing it with va_end and re-initializing it with
va_start.  This applies even if you're not scanning through it yourself,
but are calling a routine that scans through it, such as vfprintf() or
one of the routines in Wireshark that takes a format and a va_list as an
argument.  You must do

    va_start(ap, format);
    call_routine1(xxx, format, ap);
    va_end(ap);
    va_start(ap, format);
    call_routine2(xxx, format, ap);
    va_end(ap);

rather
    va_start(ap, format);
    call_routine1(xxx, format, ap);
    call_routine2(xxx, format, ap);
    va_end(ap);

Don't use a label without a statement following it.  For example,
something such as

    if (...) {

        ...

    done:
    }

will not work with all compilers - you have to do

    if (...) {

        ...

    done:
        ;
    }

with some statement, even if it's a null statement, after the label.

Don't use "bzero()", "bcopy()", or "bcmp()"; instead, use the ANSI C
routines

    "memset()" (with zero as the second argument, so that it sets
    all the bytes to zero);

    "memcpy()" or "memmove()" (note that the first and second
    arguments to "memcpy()" are in the reverse order to the
    arguments to "bcopy()"; note also that "bcopy()" is typically
    guaranteed to work on overlapping memory regions, while
    "memcpy()" isn't, so if you may be copying from one region to a
    region that overlaps it, use "memmove()", not "memcpy()" - but
    "memcpy()" might be faster as a result of not guaranteeing
    correct operation on overlapping memory regions);

    and "memcmp()" (note that "memcmp()" returns 0, 1, or -1, doing
    an ordered comparison, rather than just returning 0 for "equal"
    and 1 for "not equal", as "bcmp()" does).

Not all platforms necessarily have "bzero()"/"bcopy()"/"bcmp()", and
those that do might not declare them in the header file on which they're
declared on your platform.

Don't use "index()" or "rindex()"; instead, use the ANSI C equivalents,
"strchr()" and "strrchr()".  Not all platforms necessarily have
"index()" or "rindex()", and those that do might not declare them in the
header file on which they're declared on your platform.

Don't use "tvb_get_ptr()".  If you must use it, keep in mind that the pointer
returned by a call to "tvb_get_ptr()" is not guaranteed to be aligned on any
particular byte boundary; this means that you cannot safely cast it to any
data type other than a pointer to "char", "unsigned char", "guint8", or other
one-byte data types.  Casting a pointer returned by tvb_get_ptr() into any
multi-byte data type or structure may cause crashes on some platforms (even
if it does not crash on x86-based PCs).  Even if such mis-aligned accesses
don't crash on your platform they will be slower than properly aligned
accesses would be.  Furthermore, the data in a packet is not necessarily in
the byte order of the machine on which Wireshark is running.  Use the tvbuff
routines to extract individual items from the packet, or, better yet, use
"proto_tree_add_item()" and let it extract the items for you.

Don't use structures that overlay packet data, or into which you copy
packet data; the C programming language does not guarantee any
particular alignment of fields within a structure, and even the
extensions that try to guarantee that are compiler-specific and not
necessarily supported by all compilers used to build Wireshark.  Using
bitfields in those structures is even worse; the order of bitfields
is not guaranteed.

Don't use "ntohs()", "ntohl()", "htons()", or "htonl()"; the header
files required to define or declare them differ between platforms, and
you might be able to get away with not including the appropriate header
file on your platform but that might not work on other platforms.
Instead, use "g_ntohs()", "g_ntohl()", "g_htons()", and "g_htonl()";
those are declared by <glib.h>, and you'll need to include that anyway,
as Wireshark header files that all dissectors must include use stuff from
<glib.h>.

Don't fetch a little-endian value using "tvb_get_ntohs() or
"tvb_get_ntohl()" and then using "g_ntohs()", "g_htons()", "g_ntohl()",
or "g_htonl()" on the resulting value - the g_ routines in question
convert between network byte order (big-endian) and *host* byte order,
not *little-endian* byte order; not all machines on which Wireshark runs
are little-endian, even though PCs are.  Fetch those values using
"tvb_get_letohs()" and "tvb_get_letohl()".

Do not use "open()", "rename()", "mkdir()", "stat()", "unlink()", "remove()",
"fopen()", "freopen()" directly.  Instead use "ws_open()", "ws_rename()",
"ws_mkdir()", "ws_stat()", "ws_unlink()", "ws_remove()", "ws_fopen()",
"ws_freopen()": these wrapper functions change the path and file name from
UTF8 to UTF16 on Windows allowing the functions to work correctly when the
path or file name contain non-ASCII characters.

Also, use ws_read(), ws_write(), ws_lseek(), ws_dup(), ws_fstat(), and
ws_fdopen(), rather than read(), write(), lseek(), dup(), fstat(), and
fdopen() on descriptors returned by ws_open().

Those functions are declared in <wsutil/file_util.h>; include that
header in any code that uses any of those routines.

When opening a file with "ws_fopen()", "ws_freopen()", or "ws_fdopen()", if
the file contains ASCII text, use "r", "w", "a", and so on as the open mode
- but if it contains binary data, use "rb", "wb", and so on.  On
Windows, if a file is opened in a text mode, writing a byte with the
value of octal 12 (newline) to the file causes two bytes, one with the
value octal 15 (carriage return) and one with the value octal 12, to be
written to the file, and causes bytes with the value octal 15 to be
discarded when reading the file (to translate between C's UNIX-style
lines that end with newline and Windows' DEC-style lines that end with
carriage return/line feed).

In addition, that also means that when opening or creating a binary
file, you must use "ws_open()" (with O_CREAT and possibly O_TRUNC if the
file is to be created if it doesn't exist), and OR in the O_BINARY flag,
even on UN*X - O_BINARY is defined by <wsutil/file_util.h> as 0 on UN*X.

Do not include <unistd.h>, <fcntl.h>, or <io.h> to declare any of the
routines listed as replaced by routines in <wsutil/file_util.h>;
instead, just include <wsutil/file_util.h>.

If you need the declarations of other functions defined by <unistd.h>,
don't include it without protecting it with

    #ifdef HAVE_UNISTD_H

        ...

    #endif

Don't use forward declarations of static arrays without a specified size
in a fashion such as this:

    static const value_string foo_vals[];

        ...

    static const value_string foo_vals[] = {
        { 0,        "Red" },
        { 1,        "Green" },
        { 2,        "Blue" },
        { 0,        NULL }
    };

as some compilers will reject the first of those statements.  Instead,
initialize the array at the point at which it's first declared, so that
the size is known.

For #define names and enum member names, prefix the names with a tag so
as to avoid collisions with other names - this might be more of an issue
on Windows, as it appears to #define names such as DELETE and
OPTIONAL.

Don't use the "positional parameters" extension that many UNIX printf's
implement, e.g.:

    snprintf(add_string, 30, " - (%1$d) (0x%1$04x)", value);

as not all UNIX printf's implement it, and Windows printf doesn't appear
to implement it.  Use something like

    snprintf(add_string, 30, " - (%d) (0x%04x)", value, value);

instead.

Don't use

    case N ... M:

as that's not supported by all compilers.

Prefer the C99 output functions from <stdio.h> instead of their GLib
replacements (note that positional format parameters are not part of C99).
In the past we used to recommend using g_snprintf() and g_vsnprintf()
instead but since Visual Studio 2015 native C99 implementations are
available on all platforms we support. These are optimized better than
the gnulib (GLib) implementation and on hot codepaths that can be a
noticeable difference in execution speed.

tmpnam() -> mkstemp()
tmpnam is insecure and should not be used any more. Wireshark brings its
own mkstemp implementation for use on platforms that lack mkstemp.
Note: mkstemp does not accept NULL as a parameter.

Wireshark requires minimum versions of each of the libraries it uses, in
particular GLib 2.32.0 and Qt 5.3.0 or newer. If you require a mechanism
that is available only in a newer version of a library then use its
version detection macros, e.g. "#if GLIB_CHECK_VERSION(...)" and "#if
QT_VERSION_CHECK(...)" to conditionally compile code using that
mechanism.

When different code must be used on UN*X and Win32, use a #if or #ifdef
that tests _WIN32, not WIN32.  Try to write code portably whenever
possible, however; note that there are some routines in Wireshark with
platform-dependent implementations and platform-independent APIs, such
as the routines in epan/filesystem.c, allowing the code that calls it to
be written portably without #ifdefs.

Wireshark uses Libgcrypt as general-purpose crypto library. To use it from
your dissector, do not include gcrypt.h directly, but use the wrapper file
wsutil/wsgcrypt.h instead.

2. String handling

Do not use functions such as strcat() or strcpy().
A lot of work has been done to remove the existing calls to these functions and
we do not want any new callers of these functions.

Instead use snprintf() since that function will if used correctly prevent
buffer overflows for large strings.

Be sure that all pointers passed to %s specifiers in format strings are non-
NULL. Some implementations will automatically replace NULL pointers with the
string "(NULL)", but most will not.

When using a buffer to create a string, do not use a buffer stored on the stack.
I.e. do not use a buffer declared as

   char buffer[1024];

instead allocate a buffer dynamically using the string-specific or plain wmem
routines (see README.wmem) such as

   wmem_strbuf_t *strbuf;
   strbuf = wmem_strbuf_new(pinfo->pool, "");
   wmem_strbuf_append_printf(strbuf, ...

or

   char *buffer=NULL;
   ...
   #define MAX_BUFFER 1024
   buffer=wmem_alloc(pinfo->pool, MAX_BUFFER);
   buffer[0]='\0';
   ...
   snprintf(buffer, MAX_BUFFER, ...

This avoids the stack from being corrupted in case there is a bug in your code
that accidentally writes beyond the end of the buffer.


If you write a routine that will create and return a pointer to a filled in
string and if that buffer will not be further processed or appended to after
the routine returns (except being added to the proto tree),
do not preallocate the buffer to fill in and pass as a parameter instead
pass a pointer to a pointer to the function and return a pointer to a
wmem-allocated buffer that will be automatically freed. (see README.wmem)

I.e. do not write code such as
  static void
  foo_to_str(char *string, ... ){
     <fill in string>
  }
  ...
     char buffer[1024];
     ...
     foo_to_str(buffer, ...
     proto_tree_add_string(... buffer ...

instead write the code as
  static void
  foo_to_str(char **buffer, ...
    #define MAX_BUFFER x
    *buffer=wmem_alloc(pinfo->pool, MAX_BUFFER);
    <fill in *buffer>
  }
  ...
    char *buffer;
    ...
    foo_to_str(&buffer, ...
    proto_tree_add_string(... *buffer ...

Use wmem_ allocated buffers. They are very fast and nice. These buffers are all
automatically free()d when the dissection of the current packet ends so you
don't have to worry about free()ing them explicitly in order to not leak memory.
Please read README.wmem.

Source files can use UTF-8 encoding, but characters outside the ASCII
range should be used sparingly. It should be safe to use non-ASCII
characters in comments and strings, but some compilers (such as GCC
versions prior to 10) may not support extended identifiers very well.
There is also no guarantee that a developer's text editor will interpret
the characters the way you intend them to be interpreted.

The majority of Wireshark encodes strings as UTF-8. The main exception
is the code that uses the Qt API, which uses UTF-16. Console output is
UTF-8, but as with the source code extended characters should be used
sparingly since some consoles (most notably Windows' cmd.exe) have
limited support for UTF-8.

3. Robustness.

Wireshark is not guaranteed to read only network traces that contain correctly-
formed packets. Wireshark is commonly used to track down networking
problems, and the problems might be due to a buggy protocol implementation
sending out bad packets.

Therefore, code does not only have to be able to handle
correctly-formed packets without, for example, crashing or looping
infinitely, they also have to be able to handle *incorrectly*-formed
packets without crashing or looping infinitely.

Here are some suggestions for making code more robust in the face
of incorrectly-formed packets:

Do *NOT* use "ws_assert()" or "ws_assert_not_reached()" with input data in dissectors.
*NO* value in a packet's data should be considered "wrong" in the sense
that it's a problem with the dissector if found; if it cannot do
anything else with a particular value from a packet's data, the
dissector should put into the protocol tree an indication that the
value is invalid, and should return.  The "expert" mechanism should be
used for that purpose.

Use assertions to catch logic errors in your program. A failed assertion
indicates a bug in the code. Use ws_assert() instead of g_assert() to
test a logic condition. Note that ws_assert() will be removed with
WS_DISABLE_ASSERT. Therefore assertions should not have any side-effects,
otherwise the program may behave inconsistently.

Use ws_assert_not_reached() instead of g_assert_not_reached() for
unreachable error conditions. For example if (and only if) you know
'myvar' can only have the values 1 and 2 do:
    switch(myvar) {
    case 1:
        (...)
        break;
    case 2:
        (...)
        break;
    default:
        ws_assert_not_reached();
        break;
    }

For dissectors use DISSECTOR_ASSERT() and DISSECTOR_ASSERT_NOT_REACHED()
instead, with the same caveats as above.

You should continue to use g_assert_true(), g_assert_cmpstr(), etc for
"test code", such as unit testing. These assertions are always active.
See the GLib Testing API documentation for the details on each of those
functions.

If there is a case where you are checking not for an invalid data item
in the packet, but for a bug in the dissector (for example, an
assumption being made at a particular point in the code about the
internal state of the dissector), use the DISSECTOR_ASSERT macro for
that purpose; this will put into the protocol tree an indication that
the dissector has a bug in it, and will not crash the application.

If you are allocating a chunk of memory to contain data from a packet,
or to contain information derived from data in a packet, and the size of
the chunk of memory is derived from a size field in the packet, make
sure all the data is present in the packet before allocating the buffer.
Doing so means that:

    1) Wireshark won't leak that chunk of memory if an attempt to
       fetch data not present in the packet throws an exception.

and

    2) it won't crash trying to allocate an absurdly-large chunk of
       memory if the size field has a bogus large value.

If you're fetching into such a chunk of memory a string from the buffer,
and the string has a specified size, you can use "tvb_get_*_string()",
which will check whether the entire string is present before allocating
a buffer for the string, and will also put a trailing '\0' at the end of
the buffer.

If you're fetching into such a chunk of memory a 2-byte Unicode string
from the buffer, and the string has a specified size, you can use
"tvb_get_faked_unicode()", which will check whether the entire string
is present before allocating a buffer for the string, and will also
put a trailing '\0' at the end of the buffer.  The resulting string will be
a sequence of single-byte characters; the only Unicode characters that
will be handled correctly are those in the ASCII range.  (Wireshark's
ability to handle non-ASCII strings is limited; it needs to be
improved.)

If you're fetching into such a chunk of memory a sequence of bytes from
the buffer, and the sequence has a specified size, you can use
"tvb_memdup()", which will check whether the entire sequence is present
before allocating a buffer for it.

Otherwise, you can check whether the data is present by using
"tvb_ensure_bytes_exist()" although this frequently is not needed: the
TVB-accessor routines can handle requests to read data beyond the end of
the TVB (by throwing an exception which will either mark the frame as
truncated--not all the data was captured--or as malformed).

Note also that you should only fetch string data into a fixed-length
buffer if the code ensures that no more bytes than will fit into the
buffer are fetched ("the protocol ensures" isn't good enough, as
protocol specifications can't ensure only packets that conform to the
specification will be transmitted or that only packets for the protocol
in question will be interpreted as packets for that protocol by
Wireshark).  If there's no maximum length of string data to be fetched,
routines such as "tvb_get_*_string()" are safer, as they allocate a buffer
large enough to hold the string.  (Note that some variants of this call
require you to free the string once you're finished with it.)

If you have gotten a pointer using "tvb_get_ptr()" (which you should not
have: you should seriously consider a better alternative to this function),
you must make sure that you do not refer to any data past the length passed
as the last argument to "tvb_get_ptr()"; while the various "tvb_get"
routines perform bounds checking and throw an exception if you refer to data
not available in the tvbuff, direct references through a pointer gotten from
"tvb_get_ptr()" do not do any bounds checking.

If you have a loop that dissects a sequence of items, each of which has
a length field, with the offset in the tvbuff advanced by the length of
the item, then, if the length field is the total length of the item, and
thus can be zero, you *MUST* check for a zero-length item and abort the
loop if you see one.  Otherwise, a zero-length item could cause the
dissector to loop infinitely.  You should also check that the offset,
after having the length added to it, is greater than the offset before
the length was added to it, if the length field is greater than 24 bits
long, so that, if the length value is *very* large and adding it to the
offset causes an overflow, that overflow is detected.

If you have a

    for (i = {start}; i < {end}; i++)

loop, make sure that the type of the loop index variable is large enough
to hold the maximum {end} value plus 1; otherwise, the loop index
variable can overflow before it ever reaches its maximum value.  In
particular, be very careful when using gint8, guint8, gint16, or guint16
variables as loop indices; you almost always want to use an "int"/"gint"
or "unsigned int"/"guint" as the loop index rather than a shorter type.

If you are fetching a length field from the buffer, corresponding to the
length of a portion of the packet, and subtracting from that length a
value corresponding to the length of, for example, a header in the
packet portion in question, *ALWAYS* check that the value of the length
field is greater than or equal to the length you're subtracting from it,
and report an error in the packet and stop dissecting the packet if it's
less than the length you're subtracting from it.  Otherwise, the
resulting length value will be negative, which will either cause errors
in the dissector or routines called by the dissector, or, if the value
is interpreted as an unsigned integer, will cause the value to be
interpreted as a very large positive value.

Any tvbuff offset that is added to as processing is done on a packet
should be stored in a 32-bit variable, such as an "int"; if you store it
in an 8-bit or 16-bit variable, you run the risk of the variable
overflowing.

sprintf() -> snprintf()
Prevent yourself from using the sprintf() function, as it does not test the
length of the given output buffer and might be writing into unintended memory
areas. This function is one of the main causes of security problems like buffer
exploits and many other bugs that are very hard to find. It's much better to
use the snprintf() function declared by <stdio.h> instead.

You should test your dissector against incorrectly-formed packets.  This
can be done using the randpkt and editcap utilities that come with the
Wireshark distribution.  Testing using randpkt can be done by generating
output at the same layer as your protocol, and forcing Wireshark/TShark
to decode it as your protocol, e.g. if your protocol sits on top of UDP:

    randpkt -c 50000 -t dns randpkt.pcap
    tshark -nVr randpkt.pcap -d udp.port==53,<myproto>

Testing using editcap can be done using preexisting capture files and the
"-E" flag, which introduces errors in a capture file.  E.g.:

    editcap -E 0.03 infile.pcap outfile.pcap
    tshark -nVr outfile.pcap

The script fuzz-test.sh is available to help automate these tests.

4. Name convention.

Wireshark uses the underscore_convention rather than the InterCapConvention for
function names, so new code should probably use underscores rather than
intercaps for functions and variable names. This is especially important if you
are writing code that will be called from outside your code.  We are just
trying to keep things consistent for other developers.

C symbols exported from libraries shipped with Wireshark should start with a
prefix that helps avoiding name collision with public symbols from other shared
libraries. The current suggested prefixes for newly added symbols are
ws_, wslua_, wmem_ and wtap_.

5. White space convention.

Most of the C and C++ files in Wireshark use 4-space or 2-space indentation.
When creating new files you are you are strongly encouraged to use 4-space
indentation for source code in order to ensure consistency between files.

Please avoid using tab expansions different from 8 column widths, as not all
text editors in use by the developers support this. For a detailed discussion
of tabs, spaces, and indentation, see

    http://www.jwz.org/doc/tabs-vs-spaces.html

We use EditorConfig (http://editorconfig.org) files to provide formatting
hints. Most editors and IDEs support EditorConfig, either directly or via
a plugin. If yours requires a plugin we encourage you to install it. Our
default EditorConfig indentation style for C and C++ files is 4 spaces.

Many files also have a short comment (modelines) on the indentation logic at
the end of the file. This was required in the past but has been superseded by
EditorConfig. See

    https://www.wireshark.org/tools/modelines.html

for more information.

Please do not leave trailing whitespace (spaces/tabs) on lines.

Quite a bit of our source code has varying indentation styles. When editing an
existing file, try following the existing indentation logic. If you wish to
convert a file to 4 space indentation, please do so in its own commit and be
sure to remove its .editorconfig entry so that the default setting takes
effect.

6. Compiler warnings

You should write code that is free of compiler warnings. Such warnings will
often indicate questionable code and sometimes even real bugs, so it's best
to avoid warnings at all.

The compiler flags in the Makefiles are set to "treat warnings as errors",
so your code won't even compile when warnings occur.

7. General observations about architecture

One day we might conceivably wish to load dissectors on demand and do other
more sophisticated kinds of unit test. Plus other scenarios not immediately
obvious. For this to be possible it is important that the code in epan/ does
not depend on code in epan/dissectors, i.e it is possible to compile epan
without linking with dissector code. It helps to view dissectors as clients
of an API provided by epan (libwireshark being constituted by two distinct
components "epan" and "dissectors" bundled together, plus other bits and
pieces). The reverse is not* true; epan should not be the client of an API
provided by dissectors.

The main way this separation of concerns is achieved is by using runtime
registration interfaces in epan for dissectors, preferences, etc. that are
dynamic and do not have any dissector routines hard coded. Naturally this
is also an essential component of a plugin system (libwireshark has plugins
for taps, dissectors and an experimental interface to augment dissection with
new extension languages).

8. Miscellaneous notes

Each commit in your branch corresponds to a different VCSVERSION string
automatically defined in the header 'vcs_version.h' during the build. If you happen
to find it convenient to disable this feature it can be done using:

    touch .git/wireshark-disable-versioning

i.e., the file 'wireshark-disable-versioning' must exist in the git repo dir.

/*
 * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 *
 * Local variables:
 * c-basic-offset: 4
 * tab-width: 8
 * indent-tabs-mode: nil
 * End:
 *
 * vi: set shiftwidth=4 tabstop=8 expandtab:
 * :indentSize=4:tabSize=8:noTabs=true:
 */

(This is a consolidation of documentation written by stig, sahlberg, and gram)

What is the display filter system?
==================================
The display filter system allows the user to select packets by testing
for values in the proto_tree that Wireshark constructs for that packet.
Every proto_item in the proto_tree has an 'abbrev' field
and a 'type' field, which tells the display filter engine the name
of the field and its type (what values it can hold).

For example, this is the definition of the ip.proto field from packet-ip.c:

{ &hf_ip_proto,
      { "Protocol", "ip.proto", FT_UINT8, BASE_DEC | BASE_EXT_STRING,
              &ipproto_val_ext, 0x0, NULL, HFILL }},

This definition says that "ip.proto" is the display-filter name for
this field, and that its field-type is FT_UINT8.

The display filter system has 3 major parts to it:

    1. A type system (field types, or "ftypes")
    2. A parser, to convert a user's query to an internal representation
    3. An engine that uses the internal representation to select packets.


code:
epan/dfilter/* - the display filter engine, including
		scanner, parser, syntax-tree semantics checker, DFVM bytecode
		generator, and DFVM engine.
epan/ftypes/* - the definitions of the various FT_* field types.
epan/proto.c   - proto_tree-related routines


The field type system
=====================
The field type system is stored in epan/ftypes.

The proto_tree system #includes ftypes.h, which gives it the ftenum
definition, which is the enum of all possible ftypes:

/* field types */
enum ftenum {
    FT_NONE,        /* used for text labels with no value */
    FT_PROTOCOL,
    FT_BOOLEAN,     /* TRUE and FALSE come from <glib.h> */
    FT_UINT8,
    FT_UINT16,
    FT_UINT24,      /* really a UINT32, but displayed as3 hex-digits if FD_HEX*/
    FT_UINT32,
    FT_UINT64,
    etc., etc.
}

It also provides the definition of fvalue_t, the struct that holds the *value*
that corresponds to the type. Each proto_item (proto_node) holds an fvalue_t
due to having a field_info struct (defined in proto.h).

The fvalue_t is mostly just a gigantic union of possible C-language types
(as opposed to FT_* types):

typedef struct _fvalue_t {
        ftype_t *ftype;
        union {
                /* Put a few basic types in here */
                guint32         uinteger;
                gint32          sinteger;
                guint64         integer64;
                gdouble         floating;
                gchar           *string;
                guchar          *ustring;
                GByteArray      *bytes;
                ipv4_addr       ipv4;
                ipv6_addr       ipv6;
                e_guid_t        guid;
                nstime_t        time;
                tvbuff_t        *tvb;
                GRegex          *re;
        } value;

        /* The following is provided for private use
         * by the fvalue. */
        gboolean        fvalue_gboolean1;

} fvalue_t;


Defining a field type
---------------------
The ftype system itself is designed to be modular, so that new field types
can be added when necessary.

Each field type must implement an ftype_t structure, also defined in
ftypes.h. This is the way a field type is registered with the ftype engine.

If you take a look at ftype-integer.c, you will see that it provides
an ftype_register_integers() function, that fills in many such ftype_t
structs. It creates one for each integer type: FT_UINT8, FT_UINT16,
FT_UINT32, etc.

The ftype_t struct defines the things needed for the ftype:

    * its ftenum value
    * a string representation of the FT name ("FT_UINT8")
    * how much data it consumes in the packet
    * how to store that value in an fvalue_t: new(), free(),
        various value-related functions
    * how to compare that value against another
    * how to slice that value (strings and byte ranges can be sliced)

Using an fvalue_t
-----------------
Once the value of a field is stored in an fvalue_t (stored in
each proto_item via field_info), it's easy to use those values,
thanks to the various fvalue_*() functions defined in ftypes.h.

Functions like fvalue_get(), fvalue_eq(), etc., are all generic
interfaces to get information about the field's value. They work
on any field type because of the ftype_t struct, which is the lookup
table that the field-type engine uses to work with any field type.

The display filter parser
=========================
The display filter parser (along with the comparison engine)
is stored in epan/dfilter.

The scanner/parser pair read the string representing the display filter
and convert it into a very simple syntax tree.  The syntax tree is very
simple in that it is possible that many of the nodes contain unparsed
chunks of text from the display filter.

There are four phases to parsing a user's request:

 1. Scanning the string for dfilter syntax
 2. Parsing the keywords according to the dfilter grammar, into a
        syntax tree
 3. Doing a semantic check of the nodes in that syntax tree
 4. Converting the syntax tree into a series of DFVM byte codes

The dfilter_compile() function, in epan/dfilter/dfilter.c,
runs these 4 phases. The end result is a dfwork_t object (dfw), that
can be passed to dfilter_apply() to actually run the display filter
against a set of proto_trees.


Scanning the display filter string
----------------------------------
epan/dfilter/scanner.l is the lex scanner for finding keywords
in the user's display filter string.

Its operation is simple. It finds the special function and comparison
operators ("==", "!=", "eq", "ne", etc.), it finds slice operations
( "[0:1]" ), quoted strings, IP addresses, numbers, and any other "special"
keywords or string types.

Anything it doesn't know how to handle is passed to to grammar parser
as an unparsed string (TOKEN_UNPARSED). This includes field names. The
scanner does not interpret any protocol field names at all.

The scanner has to return a token type (TOKEN_*, and in many cases,
a value. The value will be an stnode_t struct, which is a syntax
tree node object. Since the final storage of the parse will
be in a syntax tree, it is convenient for the scanner to fill in
syntax tree nodes with values when it can.

The stnode_t definition is in epan/dfilter/syntax-tree.h


Parsing the keywords according to the dfilter grammar
-----------------------------------------------------
The grammar parser is implemented with the 'lemon' tool,
rather than the traditional yacc or bison grammar parser,
as lemon grammars were found to be easier to work with. The
lemon parser specification (epan/dfilter/grammar.lemon) is
much easier to read than its bison counterpart would be,
thanks to lemon's feature of being able to name fields, rather
then using numbers ($1, $2, etc.)

The lemon tool is located in tools/lemon in the Wireshark
distribution.

An on-line introduction to lemon is available at:

http://www.sqlite.org/src/doc/trunk/doc/lemon.html

The grammar specifies which type of constructs are possible
within the dfilter language ("dfilter-lang")

An "expression" in dfilter-lang can be a relational test or a logical test.

A relational test compares a value against another, which is usually
a field (or a slice of a field) against some static value, like:

    ip.proto == 1
    eth.dst != ff:ff:ff:ff:ff:ff

A logical test combines other expressions with "and", "or", and "not".

At the end of the grammatical parsing, the dfw object will
have a valid syntax tree, pointed at by dfw->st_root.

If there is an error in the syntax, the parser will call dfilter_fail()
with an appropriate error message, which the UI will need to report
to the user.

The syntax tree system
----------------------
The syntax tree is created as a result of running the lemon-based
grammar parser on the scanned tokens. The syntax tree code
is in epan/dfilter/syntax-tree* and epan/dfilter/sttree-*. It too
uses a set of code modules that implement different syntax node types,
similar to how the field-type system registers a set of ftypes
with a central engine.

Each node (stnode_t) in the syntax tree has a type (sttype).
These sttypes are very much related to ftypes (field types), but there
is not a one-to-one correspondence. The syntax tree nodes are slightly
high-level. For example, there is only a single INTEGER sttype, unlike
the ftype system that has a type for UINT64, UINT32, UINT16, UINT8, etc.

typedef enum {
        STTYPE_UNINITIALIZED,
        STTYPE_TEST,
        STTYPE_UNPARSED,
        STTYPE_STRING,
        STTYPE_FIELD,
        STTYPE_FVALUE,
        STTYPE_INTEGER,
        STTYPE_RANGE,
        STTYPE_FUNCTION,
        STTYPE_SET,
        STTYPE_NUM_TYPES
} sttype_id_t;


The root node of the syntax tree is the main test or comparison
being done.

Semantic Check
--------------
After the parsing is done and a syntax tree is available, the
code in semcheck.c does a semantic check of what is in the syntax
tree.

The semantics of the simple syntax tree are checked to make sure that
the fields that are being compared are being compared to appropriate
values.  For example, if a field is an integer, it can't be compared to
a string, unless a value_string has been defined for that field.

During the process of checking the semantics, the simple syntax tree is
fleshed out and no longer contains nodes with unparsed information.  The
syntax tree is no longer in its simple form, but in its complete form.

For example, if the dfilter is slicing a field and comparing
against a set of bytes, semcheck.c has to check that the field
in question can indeed be sliced.

Or, can a field be compared against a certain type of value (string,
integer, float, IPv4 address, etc.)

The semcheck code also makes adjustments to the syntax tree
when it needs to. The parser sometimes stores raw, unparsed strings
in the syntax tree, and semcheck has to convert them to
certain types. For example, the display filter may contain
a value_string string (the "enum" type that protocols can use
to define the possible textual descriptions of numeric fields), and
semcheck will convert that value_string string into the correct
integer value.

Truth be told, the semcheck.c code is a bit disorganized, and could
be re-designed & re-written.

DFVM Byte Codes
---------------
The syntax tree is analyzed to create a sequence of bytecodes in the
"DFVM" language.  "DFVM" stands for Display Filter Virtual Machine.  The
DFVM is similar in spirit, but not in definition, to the BPF VM that
libpcap uses to analyze packets.

A virtual bytecode is created and used so that the actual process of
filtering packets will be fast.  That is, it should be faster to process
a list of VM bytecodes than to attempt to filter packets directly from
the syntax tree.  (heh...  no measurement has been made to support this
supposition)

The DFVM opcodes are defined in epan/dfilter/dfvm.h (dfvm_opcode_t).
Similar to how the BPF opcode system works in libpcap, there is a
limited set of opcodes. They operate by loading values from the
proto_tree into registers, loading pre-defined values into
registers, and comparing them. The opcodes are checked in sequence, and
there are only 2 branching opcodes: IF_TRUE_GOTO and IF_FALSE_GOTO.
Both of these can only branch forwards, and never backwards. In this way
sets of DFVM instructions will never get into an infinite loop.

The epan/dfilter/gencode.c code converts the syntax tree
into a set of dvfm instructions.

The constants that are in the DFVM instructions (the constant
values that the user is checking against) are pre-loaded
into registers via the dvfm_init_const() call, and stored
in the dfilter_t structure for when the display filter is
actually applied.


DFVM Engine
===========
Once the DFVM bytecode has been produced, it's a simple matter of
running the DFVM engine against the proto_tree from the packet
dissection, using the DFVM bytecodes as instructions.  If the DFVM
bytecode is known before packet dissection occurs, the
proto_tree-related code can be "primed" to store away pointers to
field_info structures that are interesting to the display filter.  This
makes lookup of those field_info structures during the filtering process
faster.

The dfilter_apply() function runs a single pre-compiled
display filter against a single proto_tree function, and returns
TRUE or FALSE, meaning that the filter matched or not.

That function calls dfvm_apply(), which runs across the DFVM
instructions, loading protocol field values into DFVM registers
and doing the comparisons.

There is a top-level Makefile target called 'dftest' which
builds a 'dftest' executable that will print out the DFVM
bytecode for any display filter given on the command-line.
To build it, run:

$ make dftest

To use it, give it the display filter on the command-line:

$ ./dftest 'ip.addr == 127.0.0.1'
Filter: "ip.addr == 127.0.0.1"

Constants:
00000 PUT_FVALUE        127.0.0.1 <FT_IPv4> -> reg#1

Instructions:
00000 READ_TREE         ip.addr -> reg#0
00001 IF-FALSE-GOTO     3
00002 ANY_EQ            reg#0 == reg#1
00003 RETURN


The output shows the original display filter, then the opcodes
that put constant values into registers. The registers are
numbered, and are shown in the output as "reg#n", where 'n' is the
identifying number.

Then the instructions are shown. These are the instructions
which are run for each proto_tree.

This is what happens in this example:

00000 READ_TREE         ip.addr -> reg#0

Any ip.addr fields in the proto_tree are loaded into register 0. Yes,
multiple values can be loaded into a single register. As a result
of this READ_TREE, the accumulator will hold TRUE or FALSE, indicating
if any field's value was loaded, or not.

00001 IF-FALSE-GOTO     3

If the load failed because there were no ip.addr fields
in the proto_tree, then we jump to instruction 3.

00002 ANY_EQ            reg#0 == reg#1

This checks to see if any of the fields in register 0
(which has the pre-loaded constant value of 127.0.0.1) are equal
to any of the fields in register 1 (which are all of the ip.addr
fields in the proto tree). The resulting value in the
accumulator will be TRUE if any of the fields match, or FALSE
if none match.

00003 RETURN

This returns the accumulator's value, either TRUE or FALSE.

In addition to dftest, there is also a tools/dfilter-test script
which is a unit-test script for the display filter engine.
It makes use of text2pcap and tshark to run specific display
filters against specific captures (embedded within dfilter-test).



Display Filter Functions
========================
You define a display filter function by adding an entry to
the df_functions table in epan/dfilter/dfunctions.c. The record struct
is defined in dfunctions.h, and shown here:

typedef struct {
    char            *name;
    DFFuncType      function;
    ftenum_t        retval_ftype;
    guint           min_nargs;
    guint           max_nargs;
    DFSemCheckType  semcheck_param_function;
} df_func_def_t;

name - the name of the function; this is how the user will call your
    function in the display filter language

function - this is the run-time processing of your function.

retval_ftype - what type of FT_* type does your function return?

min_nargs - minimum number of arguments your function accepts
max_nargs - maximum number of arguments your function accepts

semcheck_param_function - called during the semantic check of the
    display filter string.

DFFuncType function
-------------------
typedef gboolean (*DFFuncType)(GList *arg1list, GList *arg2list, GList **retval);

The return value of your function is a gboolean; TRUE if processing went fine,
or FALSE if there was some sort of exception.

For now, display filter functions can accept a maximum of 2 arguments.
The "arg1list" parameter is the GList for the first argument. The
'arg2list" parameter is the GList for the second argument. All arguments
to display filter functions are lists. This is because in the display
filter language a protocol field may have multiple instances. For example,
a field like "ip.addr" will exist more than once in a single frame. So
when the user invokes this display filter:

    somefunc(ip.addr) == TRUE

even though "ip.addr" is a single argument, the "somefunc" function will
receive a GList of *all* the values of "ip.addr" in the frame.

Similarly, the return value of the function needs to be a GList, since all
values in the display filter language are lists. The GList** retval argument
is passed to your function so you can set the pointer to your return value.

DFSemCheckType
--------------
typedef void (*DFSemCheckType)(int param_num, stnode_t *st_node);

For each parameter in the syntax tree, this function will be called.
"param_num" will indicate the number of the parameter, starting with 0.
The "stnode_t" is the syntax-tree node representing that parameter.
If everything is okay with the value of that stnode_t, your function
does nothing --- it merely returns. If something is wrong, however,
it should THROW a TypeError exception.


Example: add an 'in' display filter operation
=============================================

This example has been discussed on wireshark-dev in April 2004. It illustrates
how a more complex operation can be added to the display filter language.

Question:

	If I want to add an 'in' display filter operation, I need to define
	several things. This can happen in different ways. For instance,
	every value from the "in" value collection will result in a test.
	There are 2 options here, either a test for a single value:

		(x in {a b c})

	or a test for a value in a given range:

		(x in {a ... z})

	or even a combination of both. The former example can be reduced to:

		((x == a) or (x == b) or (x == c))

	while the latter can be reduced to

		((x >= MIN(a, z)) and (x <= MAX(a, z)))

	I understand that I can replace "x in {" with the following steps:
	first store x in the "in" test buffer, then add "(" to the display
	filter expression internally.

	Similarly I can replace the closing brace "}" with the following
	steps: release x from the "in" test buffer and then add ")"
	to the display filter expression internally.

	How could I do this?

Answer:

	This could be done in grammar.lemon. The grammar would produce
	syntax tree nodes, combining them with "or", when it is given
	tokens that represent the "in" syntax.

	It could also be done later in the process, maybe in
	semcheck.c. But if you can do it earlier, in grammar.lemon,
	then you shouldn't have to worry about modifying anything in
	semcheck.c, as the syntax tree that is passed to semcheck.c
	won't contain any new type of operators... just lots of nodes
	combined with "or".

How to add an operator FOO to the display filter language?
==========================================================

Go to wireshark/epan/dfilter/

Edit grammar.lemon and add the operator. Add the operator FOO and the
test logic (defining TEST_OP_FOO).

Edit scanner.l and add the operator name(s) hence defining
TOKEN_TEST_FOO. Also update the simple() or add the new operand's code.

Edit sttype-test.h and add the TEST_OP_FOO to the list of test operations.

Edit sttype-test.c and add TEST_OP_FOO to the num_operands() method.

Edit gencode.c, add TEST_OP_FOO in the gen_test() method by defining
ANY_FOO.

Edit dfvm.h and add ANY_FOO to the enum dfvm_opcode_t structure.

Edit dfvm.c and add ANY_FOO to dfvm_dump() (for the dftest display filter
test binary), to dfvm_apply() hence defining the methods fvalue_foo().

Edit semcheck.c and look at the check_relation_XXX() methods if they
still apply to the foo operator; if not, amend the code. Start from the
check_test() method to discover the logic.

Go to wireshark/epan/ftypes/

Edit ftypes.h and declare the fvalue_foo(), ftype_can_foo() and
fvalue_foo() methods. Add the cmp_foo() method to the struct _ftype_t.

This is the first time that a make in wireshark/epan/dfilter/ can
succeed. If it fails, then some code in the previously edited files must
be corrected.

Edit ftypes.c and define the fvalue_foo() method with its associated
logic. Define also the ftype_can_foo() and fvalue_foo() methods.

Edit all ftype-*.c files and add the required fvalue_foo() methods.

This is the point where you should be able to compile without errors in
wireshark/epan/ftypes/. If not, first fix the errors.

Go to wireshark/epan/ and run make. If this one succeeds, then we're
almost done as no errors should occur here.

Go to wireshark/ and run make. One thing to do is make dftest and see
if you can construct valid display filters with your new operator. Or
you may want to move directly to the generation of Wireshark.

Also look at ui/qt/display_filter_expression_dialog.cpp and the display
filter expression generator.

How to add a new test to the test suite
=======================================

All display filter tests are located in test/suite_dfilter.
You can add a test to an existing file or create a new file.

Each new test class must define "trace_file", which names
a capture file in "test/captures". All the tests
run in that class will use that one capture file.

There are 2 fixtures you can use for testing:

checkDFilterCount(dfilter, expected_count)

    This will run the display filter through tshark, on the
    file named by "trace_file", and assert that the
    number of resulting packets equals "expected_count". This
    also asserts that tshark does not fail; success with zero
    matches is not the same as failure to compile the display
    filter string.

checkDFilterFail(dfilter, error)

    This will run dftest with the display filter, and check
    that it fails with a given error message. This is useful
    when expecting display filter syntax errors to be caught.

To execute tests:

# Run all dfilter tests
$ test/test.py suite_dfilter

# Run all tests from group_tvb.py:
$ test/test.py suite_dfilter.group_tvb

# For faster, parallel tests, install the "pytest-xdist" first
# (for example, using "pip install pytest-xdist"), then:
$ pytest -nauto test -k suite_dfilter

# Run all tests from group_tvb.py, in parallel:
$ pytest -nauto test -k case_tvb

# Run a single test from group_tvb.py, case_tvb.test_slice_4:
$ pytest test -k "case_tvb and test_slice_4"

See also https://www.wireshark.org/docs/wsdg_html_chunked/ChapterTests.html

This file is a HOWTO for Wireshark developers interested in writing or working
on Wireshark protocol dissectors. It describes expected code patterns and the
use of some of the important functions and variables.

This file is compiled to give in depth information on Wireshark.
It is by no means all inclusive and complete. Please feel free to send
remarks and patches to the developer mailing list.

If you haven't read README.developer, read that first!

0. Prerequisites.

Before starting to develop a new dissector, a "running" Wireshark build
environment is required - there's no such thing as a standalone "dissector
build toolkit".

How to setup such an environment is platform dependent; detailed
information about these steps can be found in the "Developer's Guide"
(available from: https://www.wireshark.org) and in the INSTALL and
README.md files of the sources root dir.

0.1. Dissector related README files.

You'll find additional dissector related information in the following README
files:

- README.heuristic      - what are heuristic dissectors and how to write them
- README.plugins        - how to "pluginize" a dissector
- README.request_response_tracking - how to track req./resp. times and such
- README.wmem           - how to obtain "memory leak free" memory

0.2 Contributors

James Coe <jammer[AT]cin.net>
Gilbert Ramirez <gram[AT]alumni.rice.edu>
Jeff Foster <jfoste[AT]woodward.com>
Olivier Abad <oabad[AT]cybercable.fr>
Laurent Deniel <laurent.deniel[AT]free.fr>
Gerald Combs <gerald[AT]wireshark.org>
Guy Harris <guy[AT]alum.mit.edu>
Ulf Lamping <ulf.lamping[AT]web.de>
Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com>

1. Setting up your protocol dissector code.

This section provides skeleton code for a protocol dissector. It also explains
the basic functions needed to enter values in the traffic summary columns,
add to the protocol tree, and work with registered header fields.

1.1 Skeleton code.

Wireshark requires certain things when setting up a protocol dissector.
We provide basic skeleton code for a dissector that you can copy to a new file
and fill in. Your dissector should follow the naming convention of "packet-"
followed by the abbreviated name for the protocol. It is recommended that where
possible you keep to the IANA abbreviated name for the protocol, if there is
one, or a commonly-used abbreviation for the protocol, if any.

The skeleton code lives in the file "packet-PROTOABBREV.c" in the same source
directory as this README.

If instead of using the skeleton you base your dissector on an existing real
dissector, please put a little note in the copyright header indicating which
dissector you started with.

Usually, you will put your newly created dissector file into the directory
epan/dissectors/, just like all the other packet-*.c files already in there.

Also, please add your dissector file to the corresponding makefiles,
described in section "1.8 Editing CMakeLists.txt to add your dissector" below.

Dissectors that use the dissector registration API to register with a lower
level protocol (this is the vast majority) don't need to define a prototype in
their .h file. For other dissectors the main dissector routine should have a
prototype in a header file whose name is "packet-", followed by the abbreviated
name for the protocol, followed by ".h"; any dissector file that calls your
dissector should be changed to include that file.

You may not need to include all the headers listed in the skeleton, and you may
need to include additional headers.

1.2 Explanation of needed substitutions in code skeleton.

In the skeleton sample code the following strings should be substituted with
your information.

YOUR_NAME       Your name, of course. You do want credit, don't you?
                It's the only payment you will receive....
YOUR_EMAIL_ADDRESS  Keep those cards and letters coming.
PROTONAME       The name of the protocol; this is displayed in the
                top-level protocol tree item for that protocol.
PROTOSHORTNAME  An abbreviated name for the protocol; this is displayed
                in the "Preferences" dialog box if your dissector has
                any preferences, in the dialog box of enabled protocols,
                and in the dialog box for filter fields when constructing
                a filter expression.
PROTOABBREV     A name for the protocol for use in filter expressions;
                it may contain only lower-case letters, digits, and hyphens,
                underscores, and periods.
LICENSE         The license this dissector is under. Please use a SPDX License
                identifier.
YEARS           The years the above license is valid for.
FIELDNAME       The displayed name for the header field.
FIELDABBREV     The abbreviated name for the header field; it may contain
                only letters, digits, hyphens, underscores, and periods.
FIELDTYPE       FT_NONE, FT_BOOLEAN, FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24,
                FT_UINT32, FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64,
                FT_INT8, FT_INT16, FT_INT24, FT_INT32, FT_INT40, FT_INT48,
                FT_INT56, FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
                FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EUI64,
                FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4,
                FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_GUID, FT_OID,
                FT_REL_OID, FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FC, FT_FCWWN
FIELDDISPLAY    --For FT_UINT{8,16,24,32,40,48,56,64} and
                       FT_INT{8,16,24,32,40,48,56,64):

                  BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX, BASE_HEX_DEC,
                  BASE_CUSTOM, or BASE_NONE, possibly ORed with
                  BASE_RANGE_STRING, BASE_EXT_STRING, BASE_VAL64_STRING,
                  BASE_ALLOW_ZERO, BASE_UNIT_STRING, BASE_SPECIAL_VALS,
                  BASE_NO_DISPLAY_VALUE, or BASE_SHOW_ASCII_PRINTABLE

                  BASE_NONE may be used with a non-NULL FIELDCONVERT when the
                  numeric value of the field itself is not of significance to
                  the user (for example, the number is a generated field).
                  When this is the case the numeric value is not shown to the
                  user in the protocol decode nor is it used when preparing
                  filters for the field in question.

                  BASE_NO_DISPLAY_VALUE will just display the field name with
                  no value. It is intended for byte arrays (FT_BYTES or
                  FT_UINT_BYTES) or header fields above a subtree. The
                  value will still be filterable, just not displayed.

                --For FT_UINT16:

                  BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP

                --For FT_UINT24:

                  BASE_OUI

                --For FT_CHAR:
                  BASE_HEX, BASE_OCT, BASE_CUSTOM, or BASE_NONE, possibly
                  ORed with BASE_RANGE_STRING, BASE_EXT_STRING or
                  BASE_VAL64_STRING.

                  BASE_NONE can be used in the same way as with FT_UINT8.

                --For FT_ABSOLUTE_TIME:

                  ABSOLUTE_TIME_LOCAL, ABSOLUTE_TIME_UTC, or
                  ABSOLUTE_TIME_DOY_UTC

                --For FT_BOOLEAN:

                  if BITMASK is non-zero:
                    Number of bits in the field containing the FT_BOOLEAN
                    bitfield.
                  otherwise:
                    (must be) BASE_NONE

                --For FT_STRING, FT_STRINGZ and FT_UINT_STRING:

                  STR_ASCII or STR_UNICODE

                --For FT_BYTES and FT_UINT_BYTES:

                  SEP_DOT, SEP_DASH, SEP_COLON, or SEP_SPACE to provide
                  a separator between bytes; BASE_NONE has no separator
                  between bytes.  These can be ORed with BASE_ALLOW_ZERO
                  and BASE_SHOW_ASCII_PRINTABLE.

                  BASE_ALLOW_ZERO displays <none> instead of <MISSING>
                  for a zero-sized byte array.
                  BASE_SHOW_ASCII_PRINTABLE will check whether the
                  field's value consists entirely of printable ASCII
                  characters and, if so, will display the field's value
                  as a string, in quotes.  The value will still be
                  filterable as a byte value.

                --For FT_IPv4:

                  BASE_NETMASK - Used for IPv4 address that should never
                                 attempted to be resolved (like netmasks)
                  otherwise:
                    (must be) BASE_NONE

                --For all other types:

                  BASE_NONE
FIELDCONVERT    VALS(x), VALS64(x), RVALS(x), TFS(x), CF_FUNC(x), NULL
BITMASK         Used to mask a field not 8-bit aligned or with a size other
                than a multiple of 8 bits
FIELDDESCR      A brief description of the field, or NULL. [Please do not use ""].

If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
conform with IANA names.

1.2.1 Automatic substitution in code skeleton

Instead of manual substitutions in the code skeleton, a tool to automate it can
be found under the tools directory. The script is called tools/generate-dissector.py
and takes all the needed options to generate a compilable dissector. Look at the
above fields to know how to set them. Some assumptions have been made in the
generation to shorten the list of required options. The script patches the
CMakeLists.txt file adding the new dissector in the proper list, alphabetically
sorted.

1.3 The dissector and the data it receives.


1.3.1 Header file.

This is only needed if the dissector doesn't use self-registration to
register itself with the lower level dissector, or if the protocol dissector
wants/needs to expose code to other subdissectors.

The dissector must be declared exactly as follows in the file
packet-PROTOABBREV.h:

int
dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);


1.3.2 Extracting data from packets.

NOTE: See the file /epan/tvbuff.h for more details.

The "tvb" argument to a dissector points to a buffer containing the raw
data to be analyzed by the dissector; for example, for a protocol
running atop UDP, it contains the UDP payload (but not the UDP header,
or any protocol headers above it). A tvbuffer is an opaque data
structure, the internal data structures are hidden and the data must be
accessed via the tvbuffer accessors.

The accessors are:

Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits:

guint8 tvb_get_bits8(tvbuff_t *tvb, gint bit_offset, const gint no_of_bits);
guint16 tvb_get_bits16(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);
guint32 tvb_get_bits32(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);
guint64 tvb_get_bits64(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);

Single-byte accessors for 8-bit unsigned integers (guint8) and 8-bit
signed integers (gint8):

guint8  tvb_get_guint8(tvbuff_t *tvb, const gint offset);
gint8  tvb_get_gint8(tvbuff_t *tvb, const gint offset);

Network-to-host-order accessors:

16-bit unsigned (guint16) and signed (gint16) integers:

guint16 tvb_get_ntohs(tvbuff_t *tvb, const gint offset);
gint16 tvb_get_ntohis(tvbuff_t *tvb, const gint offset);

24-bit unsigned and signed integers:

guint32 tvb_get_ntoh24(tvbuff_t *tvb, const gint offset);
gint32 tvb_get_ntohi24(tvbuff_t *tvb, const gint offset);

32-bit unsigned (guint32) and signed (gint32) integers:

guint32 tvb_get_ntohl(tvbuff_t *tvb, const gint offset);
gint32 tvb_get_ntohil(tvbuff_t *tvb, const gint offset);

40-bit unsigned and signed integers:

guint64 tvb_get_ntoh40(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_ntohi40(tvbuff_t *tvb, const gint offset);

48-bit unsigned and signed integers:

guint64 tvb_get_ntoh48(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_ntohi48(tvbuff_t *tvb, const gint offset);

56-bit unsigned and signed integers:

guint64 tvb_get_ntoh56(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_ntohi56(tvbuff_t *tvb, const gint offset);

64-bit unsigned (guint64) and signed (gint64) integers:

guint64 tvb_get_ntoh64(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_ntohi64(tvbuff_t *tvb, const gint offset);

Single-precision and double-precision IEEE floating-point numbers:

gfloat tvb_get_ntohieee_float(tvbuff_t *tvb, const gint offset);
gdouble tvb_get_ntohieee_double(tvbuff_t *tvb, const gint offset);

Little-Endian-to-host-order accessors:

16-bit unsigned (guint16) and signed (gint16) integers:

guint16 tvb_get_letohs(tvbuff_t *tvb, const gint offset);
gint16 tvb_get_letohis(tvbuff_t *tvb, const gint offset);

24-bit unsigned and signed integers:

guint32 tvb_get_letoh24(tvbuff_t *tvb, const gint offset);
gint32 tvb_get_letohi24(tvbuff_t *tvb, const gint offset);

32-bit unsigned (guint32) and signed (gint32) integers:

guint32 tvb_get_letohl(tvbuff_t *tvb, const gint offset);
gint32 tvb_get_letohil(tvbuff_t *tvb, const gint offset);

40-bit unsigned and signed integers:

guint64 tvb_get_letoh40(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_letohi40(tvbuff_t *tvb, const gint offset);

48-bit unsigned and signed integers:

guint64 tvb_get_letoh48(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_letohi48(tvbuff_t *tvb, const gint offset);

56-bit unsigned and signed integers:

guint64 tvb_get_letoh56(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_letohi56(tvbuff_t *tvb, const gint offset);

64-bit unsigned (guint64) and signed (gint64) integers:

guint64 tvb_get_letoh64(tvbuff_t *tvb, const gint offset);
gint64 tvb_get_letohi64(tvbuff_t *tvb, const gint offset);

NOTE: Although each of the integer accessors above return types with
specific sizes, the returned values are subject to C's integer promotion
rules. It's often safer and more useful to use int or guint for 32-bit
and smaller types, and gint64 or guint64 for 40-bit and larger types.
Just because a value occupied 16 bits on the wire or over the air
doesn't mean it will within Wireshark.

Single-precision and double-precision IEEE floating-point numbers:

gfloat tvb_get_letohieee_float(tvbuff_t *tvb, const gint offset);
gdouble tvb_get_letohieee_double(tvbuff_t *tvb, const gint offset);

Encoding-to_host-order accessors:

16-bit unsigned (guint16) and signed (gint16) integers:

guint16 tvb_get_guint16(tvbuff_t *tvb, const gint offset, const guint encoding);
gint16 tvb_get_gint16(tvbuff_t *tvb, const gint offset, const guint encoding);

24-bit unsigned and signed integers:

guint32 tvb_get_guint24(tvbuff_t *tvb, const gint offset, const guint encoding);
gint32 tvb_get_gint24(tvbuff_t *tvb, const gint offset, const guint encoding);

32-bit unsigned (guint32) and signed (gint32) integers:

guint32 tvb_get_guint32(tvbuff_t *tvb, const gint offset, const guint encoding);
gint32 tvb_get_gint32(tvbuff_t *tvb, const gint offset, const guint encoding);

40-bit unsigned and signed integers:

guint64 tvb_get_guint40(tvbuff_t *tvb, const gint offset, const guint encoding);
gint64 tvb_get_gint40(tvbuff_t *tvb, const gint offset, const guint encoding);

48-bit unsigned and signed integers:

guint64 tvb_get_guint48(tvbuff_t *tvb, const gint offset, const guint encoding);
gint64 tvb_get_gint48(tvbuff_t *tvb, const gint offset, const guint encoding);

56-bit unsigned and signed integers:

guint64 tvb_get_guint56(tvbuff_t *tvb, const gint offset, const guint encoding);
gint64 tvb_get_gint56(tvbuff_t *tvb, const gint offset, const guint encoding);

64-bit unsigned (guint64) and signed (gint64) integers:

guint64 tvb_get_guint64(tvbuff_t *tvb, const gint offset, const guint encoding);
gint64 tvb_get_gint64(tvbuff_t *tvb, const gint offset, const guint encoding);

Single-precision and double-precision IEEE floating-point numbers:

gfloat tvb_get_ieee_float(tvbuff_t *tvb, const gint offset, const guint encoding);
gdouble tvb_get_ieee_double(tvbuff_t *tvb, const gint offset, const guint encoding);

"encoding" should be ENC_BIG_ENDIAN for Network-to-host-order,
ENC_LITTLE_ENDIAN for Little-Endian-to-host-order, or ENC_HOST_ENDIAN
for host order.

Accessors for IPv4 and IPv6 addresses:

guint32 tvb_get_ipv4(tvbuff_t *tvb, const gint offset);
void tvb_get_ipv6(tvbuff_t *tvb, const gint offset, ws_in6_addr *addr);

NOTE: IPv4 addresses are not to be converted to host byte order before
being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()"
to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
for example, try to use "tvb_get_ntohl()", find that it gives you the
wrong answer on the PC on which you're doing development, and try
"tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong
answer on big-endian machines.

gchar *tvb_ip_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset)
gchar *tvb_ip6_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset)

Returns a null-terminated buffer containing a string with IPv4 or IPv6 Address
from the specified tvbuff, starting at the specified offset.

Accessors for GUID:

void tvb_get_ntohguid(tvbuff_t *tvb, const gint offset, e_guid_t *guid);
void tvb_get_letohguid(tvbuff_t *tvb, const gint offset, e_guid_t *guid);
void tvb_get_guid(tvbuff_t *tvb, const gint offset, e_guid_t *guid, const guint encoding);

String accessors:

guint8 *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint length, const guint encoding);

Returns a null-terminated buffer allocated from the specified scope, containing
data from the specified tvbuff, starting at the specified offset, and containing
the specified length worth of characters. Reads data in the specified encoding
and produces UTF-8 in the buffer. See below for a list of input encoding values.

The buffer is allocated in the given wmem scope (see README.wmem for more
information).

guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding);

Returns a null-terminated buffer allocated from the specified scope,
containing data from the specified tvbuff, starting at the specified
offset, and containing all characters from the tvbuff up to and
including a terminating null character in the tvbuff. Reads data in the
specified encoding and produces UTF-8 in the buffer. See below for a
list of input encoding values. "*lengthp" will be set to the length of
the string, including the terminating null.

The buffer is allocated in the given wmem scope (see README.wmem for more
information).

const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp);

Returns a null-terminated const buffer containing data from the
specified tvbuff, starting at the specified offset, and containing all
bytes from the tvbuff up to and including a terminating null character
in the tvbuff. "*lengthp" will be set to the length of the string,
including the terminating null.

You do not need to free() this buffer; it will happen automatically once
the next packet is dissected. This function is slightly more efficient
than the others because it does not allocate memory and copy the string,
but it does not do any mapping to UTF-8 or checks for valid octet
sequences.

gint tvb_get_nstringz(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer);
gint tvb_get_nstringz0(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer);

Copies bufsize bytes, including the terminating NULL, to buffer. If a NULL
terminator is found before reaching bufsize, only the bytes up to and including
the NULL are copied. Returns the number of bytes copied (not including
terminating NULL), or -1 if the string was truncated in the buffer due to
not having reached the terminating NULL. In this case, the resulting
buffer is not NULL-terminated.
tvb_get_nstringz0() works like tvb_get_nstringz(), but never returns -1 since
the string is guaranteed to have a terminating NULL. If the string was truncated
when copied into buffer, a NULL is placed at the end of buffer to terminate it.

gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvbuff_t *tvb,
                                      const gint bit_offset, gint no_of_chars);

tvb_get_ts_23_038_7bits_string() returns a string of a given number of
characters and encoded according to 3GPP TS 23.038 7 bits alphabet.

The buffer is allocated in the given wmem scope (see README.wmem for more
information).

Byte Array Accessors:

gchar *tvb_bytes_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint len);

Formats a bunch of data from a tvbuff as bytes, returning a pointer
to the string with the data formatted as two hex digits for each byte.
The string pointed to is stored in an "wmem_alloc'd" buffer which will be freed
depending on its scope (typically wmem_packet_scope which is freed after the frame).
The formatted string will contain the hex digits for at most the first 16 bytes of
the data. If len is greater than 16 bytes, a trailing "..." will be added to the string.

gchar *tvb_bytes_to_str_punct(wmem_allocator_t *scope, tvbuff_t *tvb,
                              const gint offset, const gint len, const gchar punct);

This function is similar to tvb_bytes_to_str(...) except that 'punct' is inserted
between the hex representation of each byte.

GByteArray *tvb_get_string_bytes(tvbuff_t *tvb, const gint offset, const gint length,
                                 const guint encoding, GByteArray* bytes, gint *endoff)

Given a tvbuff, an offset into the tvbuff, and a length that starts
at that offset (which may be -1 for "all the way to the end of the
tvbuff"), fetch the hex-decoded byte values of the tvbuff into the
passed-in 'bytes' array, based on the passed-in encoding. In other
words, convert from a hex-ascii string in tvbuff, into the supplied
GByteArray.

gchar *tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const gint offset, const gint len, dgt_set_t *dgt, gboolean skip_first);

Given a tvbuff, an offset into the tvbuff, and a length that starts
at that offset (which may be -1 for "all the way to the end of the
tvbuff"), fetch BCD encoded digits from a tvbuff starting from either
the low or high half byte, formatting the digits according to an input digit set,
if NUll a default digit set of 0-9 returning "?" for overdecadic digits will be used.
A pointer to the packet scope allocated string will be returned.
Note: a tvbuff content of 0xf is considered a 'filler' and will end the conversion.

Copying memory:
void* tvb_memcpy(tvbuff_t *tvb, void* target, const gint offset, size_t length);

Copies into the specified target the specified length's worth of data
from the specified tvbuff, starting at the specified offset.

void *tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, size_t length);

Returns a buffer containing a copy of the given TVB bytes. The buffer is
allocated in the given wmem scope (see README.wmem for more information).

Pointer-retrieval:
/* WARNING! Don't use this function. There is almost always a better way.
 * It's dangerous because once this pointer is given to the user, there's
 * no guarantee that the user will honor the 'length' and not overstep the
 * boundaries of the buffer. Also see the warning in the Portability section.
 */
const guint8* tvb_get_ptr(tvbuff_t *tvb, const gint offset, const gint length);

Length query:
Get amount of captured data in the buffer (which is *NOT* necessarily the
length of the packet). You probably want tvb_reported_length instead:

    guint tvb_captured_length(const tvbuff_t *tvb);

Get reported length of buffer:

    guint tvb_reported_length(const tvbuff_t *tvb);


1.4 Functions to handle columns in the traffic summary window.

The topmost pane of the main window is a list of the packets in the
capture, possibly filtered by a display filter.

Each line corresponds to a packet, and has one or more columns, as
configured by the user.

Many of the columns are handled by code outside individual dissectors;
most dissectors need only specify the value to put in the "Protocol" and
"Info" columns.

Columns are specified by COL_ values; the COL_ value for the "Protocol"
field, typically giving an abbreviated name for the protocol (but not
the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the
COL_ value for the "Info" field, giving a summary of the contents of the
packet for that protocol, is COL_INFO.

The value for a column can be specified with one of several functions,
all of which take the 'fd' argument to the dissector as their first
argument, and the COL_ value for the column as their second argument.

1.4.1 The col_set_str function.

'col_set_str' takes a string as its third argument, and sets the value
for the column to that value. It assumes that the pointer passed to it
points to a string constant or a static "const" array, not to a
variable, as it doesn't copy the string, it merely saves the pointer
value; the argument can itself be a variable, as long as it always
points to a string constant or a static "const" array.

It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if
the dissector will be using 'col_append_str' or 'col_append_fstr" to
append more information to the column, the string will have to be copied
anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in
that case.

For example, to set the "Protocol" column
to "PROTOABBREV":

    col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");


1.4.2 The col_add_str function.

'col_add_str' takes a string as its third argument, and sets the value
for the column to that value. It takes the same arguments as
'col_set_str', but copies the string, so that if the string is, for
example, an automatic variable that won't remain in scope when the
dissector returns, it's safe to use.


1.4.3 The col_add_fstr function.

'col_add_fstr' takes a 'printf'-style format string as its third
argument, and 'printf'-style arguments corresponding to '%' format
items in that string as its subsequent arguments. For example, to set
the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a
string containing the type of the request in the packet and "n" is an
unsigned integer containing the number of bytes in the request:

    col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes",
                 reqtype, n);

Don't use 'col_add_fstr' with a format argument of just "%s" -
'col_add_str', or possibly even 'col_set_str' if the string that matches
the "%s" is a static constant string, will do the same job more
efficiently.


1.4.4 The col_clear function.

If the Info column will be filled with information from the packet, that
means that some data will be fetched from the packet before the Info
column is filled in. If the packet is so small that the data in
question cannot be fetched, the routines to fetch the data will throw an
exception (see the comment at the beginning about tvbuffers improving
the handling of short packets - the tvbuffers keep track of how much
data is in the packet, and throw an exception on an attempt to fetch
data past the end of the packet, so that the dissector won't process
bogus data), causing the Info column not to be filled in.

This means that the Info column will have data for the previous
protocol, which would be confusing if, for example, the Protocol column
had data for this protocol.

Therefore, before a dissector fetches any data whatsoever from the
packet (unless it's a heuristic dissector fetching data to determine
whether the packet is one that it should dissect, in which case it
should check, before fetching the data, whether there's any data to
fetch; if there isn't, it should return FALSE), it should set the
Protocol column and the Info column.

If the Protocol column will ultimately be set to, for example, a value
containing a protocol version number, with the version number being a
field in the packet, the dissector should, before fetching the version
number field or any other field from the packet, set it to a value
without a version number, using 'col_set_str', and should later set it
to a value with the version number after it's fetched the version
number.

If the Info column will ultimately be set to a value containing
information from the packet, the dissector should, before fetching any
fields from the packet, clear the column using 'col_clear' (which is
more efficient than clearing it by calling 'col_set_str' or
'col_add_str' with a null string), and should later set it to the real
string after it's fetched the data to use when doing that.


1.4.5 The col_append_str function.

Sometimes the value of a column, especially the "Info" column, can't be
conveniently constructed at a single point in the dissection process;
for example, it might contain small bits of information from many of the
fields in the packet. 'col_append_str' takes, as arguments, the same
arguments as 'col_add_str', but the string is appended to the end of the
current value for the column, rather than replacing the value for that
column. (Note that no blank separates the appended string from the
string to which it is appended; if you want a blank there, you must add
it yourself as part of the string being appended.)


1.4.6 The col_append_fstr function.

'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to
'col_add_str' - it takes, as arguments, the same arguments as
'col_add_fstr', but the formatted string is appended to the end of the
current value for the column, rather than replacing the value for that
column.

1.4.7 The col_append_sep_str and col_append_sep_fstr functions.

In specific situations the developer knows that a column's value will be
created in a stepwise manner, where the appended values are listed. Both
'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item
separator between two consecutive items, and will not add the separator at the
beginning of the column. The remainder of the work both functions do is
identical to what 'col_append_str' and 'col_append_fstr' do.

1.4.8 The col_set_fence and col_prepend_fence_fstr functions.

Sometimes a dissector may be called multiple times for different PDUs in the
same frame (for example in the case of SCTP chunk bundling: several upper
layer data packets may be contained in one SCTP packet). If the upper layer
dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it
begins dissecting each of those PDUs then when the frame is fully dissected
the Info column would contain only the string from the last PDU in the frame.
The 'col_set_fence' function erects a "fence" in the column that prevents
subsequent 'col_...' calls from clearing the data currently in that column.
For example, the SCTP dissector calls 'col_set_fence' on the Info column
after it has called any subdissectors for that chunk so that subdissectors
of any subsequent chunks may only append to the Info column.
'col_prepend_fence_fstr' prepends data before a fence (moving it if
necessary). It will create a fence at the end of the prepended data if the
fence does not already exist.


1.4.9 The col_set_time function.

The 'col_set_time' function takes an nstime value as its third argument.
This nstime value is a relative value and will be added as such to the
column. The fourth argument is the filtername holding this value. This
way, rightclicking on the column makes it possible to build a filter
based on the time-value.

For example:

    col_set_time(pinfo->cinfo, COL_REL_TIME, &ts, "s4607.ploc.time");


1.5 Constructing the protocol tree.

The middle pane of the main window, and the topmost pane of a packet
popup window, are constructed from the "protocol tree" for a packet.

The protocol tree, or proto_tree, is a GNode, the N-way tree structure
available within GLIB. Of course the protocol dissectors don't care
what a proto_tree really is; they just pass the proto_tree pointer as an
argument to the routines which allow them to add items and new branches
to the tree.

When a packet is selected in the packet-list pane, or a packet popup
window is created, a new logical protocol tree (proto_tree) is created.
The pointer to the proto_tree (in this case, 'protocol tree'), is passed
to the top-level protocol dissector, and then to all subsequent protocol
dissectors for that packet, and then the GUI tree is drawn via
proto_tree_draw().

The logical proto_tree needs to know detailed information about the protocols
and fields about which information will be collected from the dissection
routines. By strictly defining (or "typing") the data that can be attached to a
proto tree, searching and filtering becomes possible. This means that for
every protocol and field (which I also call "header fields", since they are
fields in the protocol headers) which might be attached to a tree, some
information is needed.

Every dissector routine will need to register its protocols and fields
with the central protocol routines (in proto.c). At first I thought I
might keep all the protocol and field information about all the
dissectors in one file, but decentralization seemed like a better idea.
That one file would have gotten very large; one small change would have
required a re-compilation of the entire file. Also, by allowing
registration of protocols and fields at run-time, loadable modules of
protocol dissectors (perhaps even user-supplied) is feasible.

To do this, each protocol should have a register routine, which will be
called when Wireshark starts. The code to call the register routines is
generated automatically; to arrange that a protocol's register routine
be called at startup:

    the file containing a dissector's "register" routine must be
    added to "DISSECTOR_SRC" in "epan/dissectors/CMakeLists.txt";

    the "register" routine must have a name of the form
    "proto_register_XXX";

    the "register" routine must take no argument, and return no
    value;

    the "register" routine's name must appear in the source file
    either at the beginning of the line, or preceded only by "void "
    at the beginning of the line (that would typically be the
    definition) - other white space shouldn't cause a problem, e.g.:

void proto_register_XXX(void) {

    ...

}

and

void
proto_register_XXX( void )
{

    ...

}

    and so on should work.

For every protocol or field that a dissector wants to register, a variable of
type int needs to be used to keep track of the protocol. The IDs are
needed for establishing parent/child relationships between protocols and
fields, as well as associating data with a particular field so that it
can be stored in the logical tree and displayed in the GUI protocol
tree.

Some dissectors will need to create branches within their tree to help
organize header fields. These branches should be registered as header
fields. Only true protocols should be registered as protocols. This is
so that a display filter user interface knows how to distinguish
protocols from fields.

A protocol is registered with the name of the protocol and its
abbreviation.

Here is how the frame "protocol" is registered.

        int proto_frame;

        proto_frame = proto_register_protocol (
                /* name */            "Frame",
                /* short name */      "Frame",
                /* abbrev */          "frame" );

A header field is also registered with its name and abbreviation, but
information about its data type is needed. It helps to look at
the header_field_info struct to see what information is expected:

struct header_field_info {
    const char      *name;
    const char      *abbrev;
    enum ftenum     type;
    int             display;
    const void      *strings;
    guint64         bitmask;
    const char      *blurb;
    .....
};

name (FIELDNAME)
----------------
A string representing the name of the field. This is the name
that will appear in the graphical protocol tree. It must be a non-empty
string.

abbrev (FIELDABBREV)
--------------------
A string with an abbreviation of the field. The abbreviation should start
with the abbreviation of the parent protocol followed by a period as a
separator. For example, the "src" field in an IP packet would have "ip.src"
as an abbreviation. It is acceptable to have multiple levels of periods if,
for example, you have fields in your protocol that are then subdivided into
subfields. For example, TRMAC has multiple error fields, so the abbreviations
follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc.

The abbreviation is the identifier used in a display filter. As such it
cannot be an empty string.

type (FIELDTYPE)
----------------
The type of value this field holds. The current field types are:

    FT_NONE     No field type. Used for fields that
                aren't given a value, and that can only
                be tested for presence or absence; a
                field that represents a data structure,
                with a subtree below it containing
                fields for the members of the structure,
                or that represents an array with a
                subtree below it containing fields for
                the members of the array, might be an
                FT_NONE field.
    FT_PROTOCOL Used for protocols which will be placing
                themselves as top-level items in the
                "Packet Details" pane of the UI.
    FT_BOOLEAN  0 means "false", any other value means
                "true".
    FT_FRAMENUM A frame number; if this is used, the "Go
                To Corresponding Frame" menu item can
                work on that field.
    FT_CHAR     An 8-bit ASCII character. It's treated similarly to an
                FT_UINT8, but is displayed as a C-style character
                constant.
    FT_UINT8    An 8-bit unsigned integer.
    FT_UINT16   A 16-bit unsigned integer.
    FT_UINT24   A 24-bit unsigned integer.
    FT_UINT32   A 32-bit unsigned integer.
    FT_UINT40   A 40-bit unsigned integer.
    FT_UINT48   A 48-bit unsigned integer.
    FT_UINT56   A 56-bit unsigned integer.
    FT_UINT64   A 64-bit unsigned integer.
    FT_INT8     An 8-bit signed integer.
    FT_INT16    A 16-bit signed integer.
    FT_INT24    A 24-bit signed integer.
    FT_INT32    A 32-bit signed integer.
    FT_INT40    A 40-bit signed integer.
    FT_INT48    A 48-bit signed integer.
    FT_INT56    A 56-bit signed integer.
    FT_INT64    A 64-bit signed integer.
    FT_FLOAT    A single-precision floating point number.
    FT_DOUBLE   A double-precision floating point number.
    FT_ABSOLUTE_TIME    An absolute time from some fixed point in time,
                displayed as the date, followed by the time, as
                hours, minutes, and seconds with 9 digits after
                the decimal point.
    FT_RELATIVE_TIME    Seconds (4 bytes) and nanoseconds (4 bytes)
                of time relative to an arbitrary time.
                displayed as seconds and 9 digits
                after the decimal point.
    FT_STRING   A string of characters, not necessarily
                NULL-terminated, but possibly NULL-padded.
                This, and the other string-of-characters
                types, are to be used for text strings,
                not raw binary data.
    FT_STRINGZ  A NULL-terminated string of characters.
                The string length is normally the length
                given in the proto_tree_add_item() call.
                However if the length given in the call
                is -1, then the length used is that
                returned by calling tvb_strsize().
                This should only be used if the string,
                in the packet, is always terminated with
                a NULL character, either because the length
                isn't otherwise specified or because a
                character count *and* a NULL terminator are
                both used.
    FT_STRINGZPAD   A NULL-padded string of characters.
                The length is given in the proto_tree_add_item()
                call, but may be larger than the length of
                the string, with extra bytes being NULL padding.
                This is typically used for fixed-length fields
                that contain a string value that might be shorter
                than the fixed length.
    FT_STRINGZTRUNC  A NULL-truncated string of characters.
                The length is given in the proto_tree_add_item()
                call, but may be larger than the length of
                the string, with a NULL character after the last
                character of the string, and the remaining bytes
                being padding with unspecified contents.  This is
                typically used for fixed-length fields that contain
                a string value that might be shorter than the fixed
                length.
    FT_UINT_STRING  A counted string of characters, consisting
                of a count (represented as an integral value,
                of width given in the proto_tree_add_item()
                call) followed immediately by that number of
                characters.
    FT_ETHER    A six octet string displayed in
                Ethernet-address format.
    FT_BYTES    A string of bytes with arbitrary values;
                used for raw binary data.
    FT_UINT_BYTES   A counted string of bytes, consisting
                of a count (represented as an integral value,
                of width given in the proto_tree_add_item()
                call) followed immediately by that number of
                arbitrary values; used for raw binary data.
    FT_IPv4     A version 4 IP address (4 bytes) displayed
                in dotted-quad IP address format (4
                decimal numbers separated by dots).
    FT_IPv6     A version 6 IP address (16 bytes) displayed
                in standard IPv6 address format.
    FT_IPXNET   An IPX address displayed in hex as a 6-byte
                network number followed by a 6-byte station
                address.
    FT_GUID     A Globally Unique Identifier
    FT_OID      An ASN.1 Object Identifier
    FT_REL_OID  An ASN.1 Relative Object Identifier
    FT_EUI64    A EUI-64 Address
    FT_AX25     A AX-25 Address
    FT_VINES    A Vines Address
    FT_SYSTEM_ID  An OSI System-ID
    FT_FCWWN    A Fibre Channel WWN Address

Some of these field types are still not handled in the display filter
routines, but the most common ones are. The FT_UINT* variables all
represent unsigned integers, and the FT_INT* variables all represent
signed integers; the number on the end represent how many bits are used
to represent the number.

Some constraints are imposed on the header fields depending on the type
(e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use
'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the
'display, 'strings', and 'bitmask' fields, and all other non-integral
types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use
'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask'
fields. The reason is simply that the type itself implicitly defines the
nature of 'display', 'strings', 'bitmask'.

display (FIELDDISPLAY)
----------------------
The display field has a couple of overloaded uses. This is unfortunate,
but since we're using C as an application programming language, this sometimes
makes for cleaner programs. Right now I still think that overloading
this variable was okay.

For integer fields (FT_UINT* and FT_INT*), this variable represents the
base in which you would like the value displayed. The acceptable bases
are:

    BASE_DEC,
    BASE_HEX,
    BASE_OCT,
    BASE_DEC_HEX,
    BASE_HEX_DEC,
    BASE_CUSTOM

BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
respectively. BASE_DEC_HEX and BASE_HEX_DEC display value in two bases
(the 1st representation followed by the 2nd in parenthesis).

BASE_CUSTOM allows one to specify a callback function pointer that will
format the value.

For 32-bit and smaller values, custom_fmt_func_t can be used to declare
the callback function pointer. Specifically, this is defined as:

    void func(gchar *, guint32);

For values larger than 32-bits, custom_fmt_func_64_t can be used to declare
the callback function pointer. Specifically, this is defined as:

    void func(gchar *, guint64);

The first argument is a pointer to a buffer of the ITEM_LABEL_LENGTH size
and the second argument is the value to be formatted.

Both custom_fmt_func_t and custom_fmt_func_64_t are defined in epan/proto.h.

For FT_UINT16 'display' can be used to select a transport layer protocol using one
of BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP. If transport name
resolution is enabled the port field label is displayed in decimal and as a well-known
service name (if one is available).

For FT_BOOLEAN fields that are also bitfields (i.e., 'bitmask' is non-zero),
'display' is used specify a "field-width" (i.e., tell the proto_tree how
wide the parent bitfield is). (If the FT_BOOLEAN 'bitmask' is zero, then
'display' must be BASE_NONE).

For integer fields a "field-width" is not needed since the type of
integer itself (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT40,
FT_UINT48, FT_UINT56, FT_UINT64, etc) tells the proto_tree how wide the
parent bitfield is. The same is true of FT_CHAR, as it's an 8-bit
character.

For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the
time is to be displayed as a time in the time zone for the machine on
which Wireshark/TShark is running or as UTC and, for UTC, whether the
date should be displayed as "{monthname} {day_of_month}, {year}" or as
"{year/day_of_year}".

Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for
non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield
FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may
not use BASE_NONE for integers.

It is possible that in the future we will record the endianness of
integers. If so, it is likely that we'll use a bitmask on the display field
so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX.
But that has not happened yet; note that there are protocols for which
no endianness is specified, such as the X11 protocol and the DCE RPC
protocol, so it would not be possible to record the endianness of all
integral fields.

strings (FIELDCONVERT)
----------------------
-- value_string
Some integer fields, of type FT_UINT*, need labels to represent the true
value of a field. You could think of those fields as having an
enumerated data type, rather than an integral data type.

A 'value_string' structure is a way to map values to strings.

    typedef struct _value_string {
        guint32  value;
        gchar   *strptr;
    } value_string;

For fields of that type, you would declare an array of "value_string"s:

    static const value_string valstringname[] = {
        { INTVAL1, "Descriptive String 1" },
        { INTVAL2, "Descriptive String 2" },
        { 0,       NULL }
    };

(the last entry in the array must have a NULL 'strptr' value, to
indicate the end of the array). The 'strings' field would be set to
'VALS(valstringname)'.

If the field has a numeric rather than an enumerated type, the 'strings'
field would be set to NULL.

If BASE_SPECIAL_VALS is also applied to the display bitmask, then if the
numeric value of a field doesn't match any values in the value_string
then just the numeric value is displayed (i.e. no "Unknown"). This is
intended for use when the value_string only gives special names for
certain field values and values not in the value_string are expected.

-- Extended value strings
You can also use an extended version of the value_string for faster lookups.
It requires a value_string array as input.
If all of a contiguous range of values from min to max are present in the array
in ascending order the value will be used as a direct index into a value_string array.

If the values in the array are not contiguous (ie: there are "gaps"), but are
in ascending order a binary search will be used.

Note: "gaps" in a value_string array can be filled with "empty" entries eg:
{value, "Unknown"} so that direct access to the array is is possible.

Note: the value_string array values are *unsigned*; IOW: -1 is greater than 0.
      So:
      { -2, -1,  1,  2 }; wrong:   linear search will be used (note gap)
      {  1,  2, -2, -1 }; correct: binary search will be used

      As a special case:
      { -2, -1,  0,  1,  2 }; OK: direct(indexed) access will be used (note no gap)

The init macro (see below) will perform a check on the value string the first
time it is used to determine which search algorithm fits and fall back to a
linear search if the value_string does not meet the criteria above.

Use this macro to initialize the extended value_string at compile time:

static value_string_ext valstringname_ext = VALUE_STRING_EXT_INIT(valstringname);

Extended value strings can be created at run time by calling
   value_string_ext_new(<ptr to value_string array>,
                        <total number of entries in the value_string_array>, /* include {0, NULL} entry */
                        <value_string_name>);

For hf[] array FT_(U)INT* fields that need a 'valstringname_ext' struct, the
'strings' field would be set to '&valstringname_ext'. Furthermore, the 'display'
field must be ORed with 'BASE_EXT_STRING' (e.g. BASE_DEC|BASE_EXT_STRING).

-- val64_string

val64_strings are like value_strings, except that the integer type
used is a guint64 (instead of guint32). Instead of using the VALS()
macro for the 'strings' field in the header_field_info struct array,
'VALS64()' is used.

BASE_SPECIAL_VALS can also be used for val64_string.

-- val64_string_ext

val64_string_ext is like value_string_ext, except that the integer type
used is a guint64 (instead of guint32).

Use this macro to initialize the extended val64_string at compile time:

static val64_string_ext val64stringname_ext = VAL64_STRING_EXT_INIT(val64stringname);

Extended val64 strings can be created at run time by calling
   val64_string_ext_new(<ptr to val64_string array>,
                        <total number of entries in the val64_string_array>, /* include {0, NULL} entry */
                        <val64_string_name>);

For hf[] array FT_(U)INT* fields that need a 'val64stringname_ext' struct, the
'strings' field would be set to '&val64stringname_ext'. Furthermore, the 'display'
field must be ORed with both 'BASE_EXT_STRING' and 'BASE_VAL64_STRING'
(e.g. BASE_DEC|BASE_EXT_STRING|BASE_VAL64_STRING).

-- Unit string
Some integer fields, of type FT_UINT* and float fields, of type FT_FLOAT
or FT_DOUBLE, need units of measurement to help convey the field value.

A 'unit_name_string' structure is a way to add a unit suffix to a field.

    typedef struct unit_name_string {
        char *singular;     /* name to use for 1 unit */
        char *plural;       /* name to use for < 1 or > 1 units */
    } unit_name_string;

For fields with that unit name, you would declare a "unit_name_string":

    static const unit_name_string unitname[] =
        { "single item name" , "multiple item name" };

(the second entry can be NULL if there is no plural form of the unit name.
This is typically the case when abbreviations are used instead of full words.)

There are several "common" unit name structures already defined in
epan/unit_strings.h. Dissector authors may choose to add the unit name
structure there rather than locally in a dissector.

For hf[] array FT_(U)INT*, FT_FlOAT and FT_DOUBLE fields that need a
'unit_name_string' struct, the 'strings' field would be set to
'&units_second_seconds'. Furthermore, the 'display' field must be ORed
with 'BASE_UNIT_STRING' (e.g. BASE_DEC|BASE_UNIT_STRING).

-- Ranges
If the field has a numeric type that might logically fit in ranges of values
one can use a range_string struct.

Thus a 'range_string' structure is a way to map ranges to strings.

        typedef struct _range_string {
                guint32        value_min;
                guint32        value_max;
                const gchar   *strptr;
        } range_string;

For fields of that type, you would declare an array of "range_string"s:

    static const range_string rvalstringname[] = {
        { INTVAL_MIN1, INTVALMAX1, "Descriptive String 1" },
        { INTVAL_MIN2, INTVALMAX2, "Descriptive String 2" },
        { 0,           0,          NULL                   }
    };

If INTVAL_MIN equals INTVAL_MAX for a given entry the range_string
behavior collapses to the one of value_string. Note that each range_string
within the array is tested in order, so any 'catch-all' entries need to come
after specific individual entries.

For FT_(U)INT* fields that need a 'range_string' struct, the 'strings' field
would be set to 'RVALS(rvalstringname)'. Furthermore, 'display' field must be
ORed with 'BASE_RANGE_STRING' (e.g. BASE_DEC|BASE_RANGE_STRING).

-- Booleans
FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True".
Sometimes it is useful to change the labels for boolean values (e.g.,
to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
true_false_string is used.

    typedef struct true_false_string {
        char    *true_string;
        char    *false_string;
    } true_false_string;

For Boolean fields for which "False" and "True" aren't the desired
labels, you would declare a "true_false_string"s:

    static const true_false_string boolstringname = {
        "String for True",
        "String for False"
    };

Its two fields are pointers to the string representing truth, and the
string representing falsehood. For FT_BOOLEAN fields that need a
'true_false_string' struct, the 'strings' field would be set to
'TFS(&boolstringname)'.

If the Boolean field is to be displayed as "False" or "True", the
'strings' field would be set to NULL.

Wireshark predefines a whole range of ready made "true_false_string"s
in tfs.h, included via packet.h.

-- Custom
Custom fields (BASE_CUSTOM) should use CF_FUNC(&custom_format_func) for the
'strings' field.

-- Note to plugin authors
Data cannot get exported from DLLs. For this reason plugin authors cannot use
existing fieldconvert strings (e.g. from existing dissectors or those from
epan/unit_strings.h). Plugins must define value_strings, unit_name_strings,
range_strings and true_false_strings locally.

bitmask (BITMASK)
-----------------
If the field is a bitfield, then the bitmask is the mask which will
leave only the bits needed to make the field when ANDed with a value.
The proto_tree routines will calculate 'bitshift' automatically
from 'bitmask', by finding the rightmost set bit in the bitmask.
This shift is applied before applying string mapping functions or
filtering.

If the field is not a bitfield, then bitmask should be set to 0.

blurb (FIELDDESCR)
------------------
This is a string giving a proper description of the field. It should be
at least one grammatically complete sentence, or NULL in which case the
name field is used. (Please do not use "").

It is meant to provide a more detailed description of the field than the
name alone provides. This information will be used in the man page, and
in a future GUI display-filter creation tool. We might also add tooltips
to the labels in the GUI protocol tree, in which case the blurb would
be used as the tooltip text.


1.5.1 Field Registration.

Protocol registration is handled by creating an instance of the
header_field_info struct (or an array of such structs), and
calling the registration function along with the registration ID of
the protocol that is the parent of the fields. Here is a complete example:

    static int proto_eg = -1;
    static int hf_field_a = -1;
    static int hf_field_b = -1;

    static hf_register_info hf[] = {

        { &hf_field_a,
        { "Field A", "proto.field_a", FT_UINT8, BASE_HEX, NULL,
            0xf0, "Field A represents Apples", HFILL }},

        { &hf_field_b,
        { "Field B", "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs),
            0x0, "Field B represents Bananas", HFILL }}
    };

    proto_eg = proto_register_protocol("Example Protocol",
        "PROTO", "proto");
    proto_register_field_array(proto_eg, hf, array_length(hf));

Be sure that your array of hf_register_info structs is declared 'static',
since the proto_register_field_array() function does not create a copy
of the information in the array... it uses that static copy of the
information that the compiler created inside your array. Here's the
layout of the hf_register_info struct:

typedef struct hf_register_info {
    int            *p_id; /* pointer to parent variable */
    header_field_info hfinfo;
} hf_register_info;

Also be sure to use the handy array_length() macro found in packet.h
to have the compiler compute the array length for you at compile time.

If you don't have any fields to register, do *NOT* create a zero-length
"hf" array; not all compilers used to compile Wireshark support them.
Just omit the "hf" array, and the "proto_register_field_array()" call,
entirely.

It is OK to have header fields with a different format be registered with
the same abbreviation. For instance, the following is valid:

    static hf_register_info hf[] = {

        { &hf_field_8bit, /* 8-bit version of proto.field */
        { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL,
            0x00, "Field represents FOO", HFILL }},

        { &hf_field_32bit, /* 32-bit version of proto.field */
        { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL,
            0x00, "Field represents FOO", HFILL }}
    };

This way a filter expression can match a header field, irrespective of the
representation of it in the specific protocol context. This is interesting
for protocols with variable-width header fields.

Note that the formats used must all belong to the same group as defined below:
- FT_INT8, FT_INT16, FT_INT24 and FT_INT32
- FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_IPXNET and FT_FRAMENUM
- FT_INT40, FT_INT48, FT_INT56 and FT_INT64
- FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64 and FT_EUI64
- FT_ABSOLUTE_TIME and FT_RELATIVE_TIME
- FT_STRING, FT_STRINGZ, FT_UINT_STRING, FT_STRINGZPAD, and FT_STRINGZTRUNC
- FT_FLOAT and FT_DOUBLE
- FT_BYTES, FT_UINT_BYTES, FT_ETHER, FT_AX25, FT_VINES and FT_FCWWN
- FT_OID, FT_REL_OID and FT_SYSTEM_ID

Any field not in a grouping above should *NOT* be used in duplicate field
abbreviations. The current code does not prevent it, but someday in the future
it might.

The HFILL macro at the end of the struct will set reasonable default values
for internally used fields.

1.5.2 Adding Items and Values to the Protocol Tree.

A protocol item is added to an existing protocol tree with one of a
handful of proto_XXX_DO_YYY() functions.

Subtrees can be made with the proto_item_add_subtree() function:

    item = proto_tree_add_item(....);
    new_tree = proto_item_add_subtree(item, tree_type);

This will add a subtree under the item in question; a subtree can be
created under an item made by any of the "proto_tree_add_XXX" functions,
so that the tree can be given an arbitrary depth.

Subtree types are integers, assigned by
"proto_register_subtree_array()". To register subtree types, pass an
array of pointers to "gint" variables to hold the subtree type values to
"proto_register_subtree_array()":

    static gint ett_eg = -1;
    static gint ett_field_a = -1;

    static gint *ett[] = {
        &ett_eg,
        &ett_field_a
    };

    proto_register_subtree_array(ett, array_length(ett));

in your "register" routine, just as you register the protocol and the
fields for that protocol.

The ett_ variables identify particular type of subtree so that if you expand
one of them, Wireshark keeps track of that and, when you click on
another packet, it automatically opens all subtrees of that type.
If you close one of them, all subtrees of that type will be closed when
you move to another packet.

There are many functions that the programmer can use to add either
protocol or field labels to the proto_tree, for example:

    proto_item*
    proto_tree_add_item(tree, id, tvb, start, length, encoding);

    proto_item*
    proto_tree_add_item_ret_int(tree, id, tvb, start, length, encoding,
        *retval);

    proto_item*
    proto_tree_add_subtree(tree, tvb, start, length, idx, tree_item,
        text);

    proto_item *
    proto_tree_add_int_format_value(tree, id, tvb, start, length,
        value, format, ...);

    proto_item *
    proto_tree_add_checksum(proto_tree *tree, tvbuff_t *tvb, const guint offset,
        const int hf_checksum, const int hf_checksum_status,
        struct expert_field* bad_checksum_expert, packet_info *pinfo,
        guint32 computed_checksum, const guint encoding, const guint flags);

    proto_item *
    proto_tree_add_bitmask(tree, tvb, start, header, ett, fields,
        encoding);

    proto_item *
    proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits,
        encoding);

The 'tree' argument is the tree to which the item is to be added. The
'tvb' argument is the tvbuff from which the item's value is being
extracted; the 'start' argument is the offset from the beginning of that
tvbuff of the item being added, and the 'length' argument is the length,
in bytes, of the item, bit_offset is the offset in bits and no_of_bits
is the length in bits.

The length of some items cannot be determined until the item has been
dissected; to add such an item, add it with a length of -1, and, when the
dissection is complete, set the length with 'proto_item_set_len()':

    void
    proto_item_set_len(ti, length);

The "ti" argument is the value returned by the call that added the item
to the tree, and the "length" argument is the length of the item.

All available protocol tree functions are declared in epan/proto.h, with
their documentation. The details of these functions and their parameters
are described below.

proto_tree_add_item()
---------------------
proto_tree_add_item is used when you wish to do no special formatting.
The item added to the GUI tree will contain the name (as passed in the
proto_register_*() function) and a value. The value will be fetched
from the tvbuff by proto_tree_add_item(), based on the type of the field
and the encoding of the value as specified by the "encoding" argument.

For FT_NONE, FT_BYTES, FT_ETHER, FT_IPv6, FT_IPXNET, FT_OID, FT_REL_OID,
FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FCWWN fields, and 'protocol' fields
the encoding is not relevant; the 'encoding' argument should be
ENC_NA (Not Applicable).

For FT_UINT_BYTES fields, the byte order of the count must be specified
as well as the 'encoding' for bytes which should be ENC_NA,
i.e. ENC_LITTLE_ENDIAN|ENC_NA

For integral, floating-point, Boolean, FT_GUID, and FT_EUI64 fields,
the encoding specifies the byte order of the value; the 'encoding'
argument should be ENC_LITTLE_ENDIAN if the value is little-endian
and ENC_BIG_ENDIAN if it is big-endian.

For FT_IPv4 fields, the encoding also specifies the byte order of the
value. In almost all cases, the encoding is in network byte order,
hence big-endian, but in at least one protocol dissected by Wireshark,
at least one IPv4 address is byte-swapped, so it's in little-endian
order.

For string fields, the encoding specifies the character set used for the
string and the way individual code points in that character set are
encoded. For FT_UINT_STRING fields, the byte order of the count must be
specified; for UCS-2 and UTF-16, the byte order of the encoding must be
specified (for counted UCS-2 and UTF-16 strings, the byte order of the
count and the 16-bit values in the string must be the same). In other
cases, ENC_NA should be used. The character encodings that are
currently supported are:

    ENC_ASCII - ASCII (currently treated as UTF-8; in the future,
        all bytes with the 8th bit set will be treated as
        errors)
    ENC_UTF_8 - UTF-8-encoded Unicode
    ENC_UTF_16 - UTF-16-encoded Unicode, with surrogate pairs
    ENC_UCS_2 - UCS-2-encoded subset of Unicode, with no surrogate pairs
        and thus no code points above 0xFFFF
    ENC_UCS_4 - UCS-4-encoded Unicode
    ENC_WINDOWS_1250 - Windows-1250 code page
    ENC_WINDOWS_1251 - Windows-1251 code page
    ENC_WINDOWS_1252 - Windows-1252 code page
    ENC_ISO_646_BASIC - ISO 646 "basic code table"
    ENC_ISO_8859_1 - ISO 8859-1
    ENC_ISO_8859_2 - ISO 8859-2
    ENC_ISO_8859_3 - ISO 8859-3
    ENC_ISO_8859_4 - ISO 8859-4
    ENC_ISO_8859_5 - ISO 8859-5
    ENC_ISO_8859_6 - ISO 8859-6
    ENC_ISO_8859_7 - ISO 8859-7
    ENC_ISO_8859_8 - ISO 8859-8
    ENC_ISO_8859_9 - ISO 8859-9
    ENC_ISO_8859_10 - ISO 8859-10
    ENC_ISO_8859_11 - ISO 8859-11
    ENC_ISO_8859_13 - ISO 8859-13
    ENC_ISO_8859_14 - ISO 8859-14
    ENC_ISO_8859_15 - ISO 8859-15
    ENC_ISO_8859_16 - ISO 8859-16
    ENC_3GPP_TS_23_038_7BITS - GSM 7 bits alphabet as described
        in 3GPP TS 23.038
    ENC_3GPP_TS_23_038_7BITS_UNPACKED - GSM 7 bits alphabet where each
        7 bit character occupies a distinct octet
    ENC_ETSI_TS_102_221_ANNEX_A - Coding scheme for SIM cards with GSM 7 bit
        alphabet, UCS-2 characters, or a mixture of the two as described
        in ETSI TS 102 221 Annex A
    ENC_EBCDIC - EBCDIC
    ENC_EBCDIC_CP037 - EBCDIC code page 037
    ENC_MAC_ROMAN - MAC ROMAN
    ENC_CP437 - DOS code page 437
    ENC_CP855 - DOS code page 855
    ENC_CP866 - DOS code page 866
    ENC_ASCII_7BITS - 7 bits ASCII
    ENC_T61 - ITU T.61
    ENC_BCD_DIGITS_0_9 - packed BCD (one digit per nibble), digits 0-9
    ENC_KEYPAD_ABC_TBCD - keypad-with-a/b/c "telephony packed BCD" = 0-9, *, #, a, b, c
    ENC_KEYPAD_BC_TBCD - keypad-with-B/C "telephony packed BCD" = 0-9, B, C, *, #
    ENC_GB18030 - GB 18030
    ENC_EUC_KR - EUC-KR

Other encodings will be added in the future.

For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which
the time stamp is specified, as well as its byte order. The time stamp
encodings that are currently supported are:

    ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
        bytes are seconds and the next 4 bytes are nanoseconds; for 12
        bytes, the first 8 bytes are seconds and the next 4 bytes are
        nanoseconds; for 16 bytes, the first 8 bytes are seconds and
        the next 8 bytes are nanoseconds. The seconds are seconds
        since the UN*X epoch (1970-01-01 00:00:00 UTC). (I.e., a UN*X
        struct timespec with a 4-byte or 8-byte time_t or a structure
        with an 8-byte time_t and an 8-byte nanoseconds field.)

    ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP
        epoch (1900-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of
        a second since that second. (I.e., a 64-bit count of 1/2^32's of a
        second since the NTP epoch, with the upper 32 bits first and the
        lower 32 bits second, even when little-endian.)

    ENC_TIME_TOD - 8 bytes, as a count of microseconds since the System/3x0
        and z/Architecture epoch (1900-01-01 00:00:00 GMT).

    ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X
        epoch and the next 4 bytes are 1/2^32's of a second since that
        second. (I.e., it's the offspring of a mating between UN*X time and
        NTP time). It's used by the Object Management Group's Real-Time
        Publish-Subscribe Wire Protocol for the Data Distribution Service.

    ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds since the
        UN*X epoch and the next 4 bytes are microseconds since that
        second. (I.e., a UN*X struct timeval with a 4-byte time_t.)

    ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds since
        the UN*X epoch.

    ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds
        since the UN*X epoch.

    ENC_TIME_NSECS - 8 bytes, representing a value in nanoseconds since
        the UN*X epoch.

    ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since
        the NTP epoch.

    ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a
        second since the UN*X epoch; see section 5.3.1 "Timestamp Option"
        in RFC 3971.

    ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since
        the NTP epoch.

    ENC_MIP6 - 8 bytes; the first 48 bits are seconds since the UN*X epoch
        and the remaining 16 bits indicate the number of 1/65536's of a second
        since that second.

    ENC_TIME_CLASSIC_MAC_OS_SECS - 4-8 bytes, representing a count of seconds
        since January 1, 1904, 00:00:00 UTC.

For FT_RELATIVE_TIME fields, the encoding specifies the form in which
the time stamp is specified, as well as its byte order. The time stamp
encodings that are currently supported are:

    ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
        bytes are seconds and the next 4 bytes are nanoseconds; for 12
        bytes, the first 8 bytes are seconds and the next 4 bytes are
        nanoseconds; for 16 bytes, the first 8 bytes are seconds and
        the next 8 bytes are nanoseconds.

    ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds and the
        next 4 bytes are microseconds.

    ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds.

    ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds.

    ENC_TIME_NSECS - 8 bytes, representing a value in nanoseconds.

For other types, there is no support for proto_tree_add_item().

Now that definitions of fields have detailed information about bitfield
fields, you can use proto_tree_add_item() with no extra processing to
add bitfield values to your tree. Here's an example. Take the Format
Identifier (FID) field in the Transmission Header (TH) portion of the SNA
protocol. The FID is the high nibble of the first byte of the TH. The
FID would be registered like this:

    name        = "Format Identifier"
    abbrev      = "sna.th.fid"
    type        = FT_UINT8
    display     = BASE_HEX
    strings     = sna_th_fid_vals
    bitmask     = 0xf0

The bitmask contains the value which would leave only the FID if bitwise-ANDed
against the parent field, the first byte of the TH.

The code to add the FID to the tree would be;

    proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1,
        ENC_BIG_ENDIAN);

The definition of the field already has the information about bitmasking
and bitshifting, so it does the work of masking and shifting for us!
This also means that you no longer have to create value_string structs
with the values bitshifted. The value_string for FID looks like this,
even though the FID value is actually contained in the high nibble.
(You'd expect the values to be 0x0, 0x10, 0x20, etc.)

/* Format Identifier */
static const value_string sna_th_fid_vals[] = {
    { 0x0, "SNA device <--> Non-SNA Device" },
    { 0x1, "Subarea Node <--> Subarea Node" },
    { 0x2, "Subarea Node <--> PU2" },
    { 0x3, "Subarea Node or SNA host <--> Subarea Node" },
    { 0x4, "?" },
    { 0x5, "?" },
    { 0xf, "Adjacent Subarea Nodes" },
    { 0, NULL }
};

The final implication of this is that display filters work the way you'd
naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent
Subarea Nodes. The user does not have to shift the value of the FID to
the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
in the past.

proto_tree_add_item_ret_XXX()
------------------------------
proto_tree_add_item_ret_XXX is used when you want the displayed value returned
for further processing only integer and unsigned integer types up to 32 bits are
supported usage of proper FT_ is checked.

proto_tree_add_XXX_item()
---------------------
proto_tree_add_XXX_item is used when you wish to do no special formatting,
but also either wish for the retrieved value from the tvbuff to be handed
back (to avoid doing tvb_get_...), and/or wish to have the value be decoded
from the tvbuff in a string-encoded format.

The item added to the GUI tree will contain the name (as passed in the
proto_register_*() function) and a value. The value will be fetched
from the tvbuff, based on the type of the XXX name and the encoding of
the value as specified by the "encoding" argument.

This function retrieves the value even if the passed-in tree param is NULL,
so that it can be used by dissectors at all times to both get the value
and set the tree item to it.

Like other proto_tree_add functions, if there is a tree and the value cannot
be decoded from the tvbuff, then an expert info error is reported. For string
encoding, this means that a failure to decode the hex value from the string
results in an expert info error being added to the tree.

For string-decoding, the passed-in encoding argument needs to specify the
string encoding (e.g., ENC_ASCII, ENC_UTF_8) as well as the format. For
some XXX types, the format is constrained - for example for the encoding format
for proto_tree_add_time_item() can only be one of the ENC_ISO_8601_* ones
or ENC_RFC_822 or ENC_RFC_1123. For proto_tree_add_bytes_item() it can only
be ENC_STR_HEX bit-or'ed with one or more of the ENC_SEP_* separator types.

proto_tree_add_protocol_format()
--------------------------------
proto_tree_add_protocol_format is used to add the top-level item for the
protocol when the dissector routine wants complete control over how the
field and value will be represented on the GUI tree. The ID value for
the protocol is passed in as the "id" argument; the rest of the
arguments are a "printf"-style format and any arguments for that format.
The caller must include the name of the protocol in the format; it is
not added automatically as in proto_tree_add_item().

proto_tree_add_none_format()
----------------------------
proto_tree_add_none_format is used to add an item of type FT_NONE.
The caller must include the name of the field in the format; it is
not added automatically as in proto_tree_add_item().

proto_tree_add_bytes()
proto_tree_add_time()
proto_tree_add_ipxnet()
proto_tree_add_ipv4()
proto_tree_add_ipv6()
proto_tree_add_ether()
proto_tree_add_string()
proto_tree_add_boolean()
proto_tree_add_float()
proto_tree_add_double()
proto_tree_add_uint()
proto_tree_add_uint64()
proto_tree_add_int()
proto_tree_add_int64()
proto_tree_add_guid()
proto_tree_add_oid()
proto_tree_add_eui64()
------------------------
These routines are used to add items to the protocol tree if either:

    the value of the item to be added isn't just extracted from the
    packet data, but is computed from data in the packet;

    the value was fetched into a variable.

The 'value' argument has the value to be added to the tree.

NOTE: in all cases where the 'value' argument is a pointer, a copy is
made of the object pointed to; if you have dynamically allocated a
buffer for the object, that buffer will not be freed when the protocol
tree is freed - you must free the buffer yourself when you don't need it
any more.

For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a
sequence of bytes.


proto_tree_add_bytes_with_length() is similar to proto_tree_add_bytes,
except that the length is not derived from the tvb length. Instead,
the displayed data size is controlled by 'ptr_length'.

For proto_tree_add_bytes_format() and proto_tree_add_bytes_format_value(), the
'value_ptr' argument is a pointer to a sequence of bytes or NULL if the bytes
should be taken from the given TVB using the given offset and length.

For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
"nstime_t", which is a structure containing the time to be added; it has
'secs' and 'nsecs' members, giving the integral part and the fractional
part of a time in units of seconds, with 'nsecs' being the number of
nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
January 1, 1970, 00:00:00 GMT value.

For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
network address.

For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4
address, in network byte order.

For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a
128-bit IPv6 address.

For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a
48-bit MAC address.

For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a
text string; this string must be NULL terminated even if the string in the
TVB is not (as may be the case with FT_STRINGs).

For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer.
It is masked and shifted as defined by the field info after which zero
means "false", and non-zero means "true".

For proto_tree_add_float(), the 'value' argument is a 'float' in the
host's floating-point format.

For proto_tree_add_double(), the 'value' argument is a 'double' in the
host's floating-point format.

For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
integer value, in host byte order. (This routine cannot be used to add
64-bit integers.)

For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
integer value, in host byte order.

For proto_tree_add_int(), the 'value' argument is a 32-bit signed
integer value, in host byte order. (This routine cannot be used to add
64-bit integers.)

For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
integer value, in host byte order.

For proto_tree_add_guid(), the 'value_ptr' argument is a pointer to an
e_guid_t structure.

For proto_tree_add_oid(), the 'value_ptr' argument is a pointer to an
ASN.1 Object Identifier.

For proto_tree_add_eui64(), the 'value' argument is a 64-bit integer
value

proto_tree_add_bytes_format()
proto_tree_add_time_format()
proto_tree_add_ipxnet_format()
proto_tree_add_ipv4_format()
proto_tree_add_ipv6_format()
proto_tree_add_ether_format()
proto_tree_add_string_format()
proto_tree_add_boolean_format()
proto_tree_add_float_format()
proto_tree_add_double_format()
proto_tree_add_uint_format()
proto_tree_add_uint64_format()
proto_tree_add_int_format()
proto_tree_add_int64_format()
proto_tree_add_guid_format()
proto_tree_add_oid_format()
proto_tree_add_eui64_format()
----------------------------
These routines are used to add items to the protocol tree when the
dissector routine wants complete control over how the field and value
will be represented on the GUI tree. The argument giving the value is
the same as the corresponding proto_tree_add_XXX() function; the rest of
the arguments are a "printf"-style format and any arguments for that
format. The caller must include the name of the field in the format; it
is not added automatically as in the proto_tree_add_XXX() functions.

proto_tree_add_bytes_format_value()
proto_tree_add_time_format_value()
proto_tree_add_ipxnet_format_value()
proto_tree_add_ipv4_format_value()
proto_tree_add_ipv6_format_value()
proto_tree_add_ether_format_value()
proto_tree_add_string_format_value()
proto_tree_add_boolean_format_value()
proto_tree_add_float_format_value()
proto_tree_add_double_format_value()
proto_tree_add_uint_format_value()
proto_tree_add_uint64_format_value()
proto_tree_add_int_format_value()
proto_tree_add_int64_format_value()
proto_tree_add_guid_format_value()
proto_tree_add_oid_format_value()
proto_tree_add_eui64_format_value()
------------------------------------

These routines are used to add items to the protocol tree when the
dissector routine wants complete control over how the value will be
represented on the GUI tree. The argument giving the value is the same
as the corresponding proto_tree_add_XXX() function; the rest of the
arguments are a "printf"-style format and any arguments for that format.
With these routines, unlike the proto_tree_add_XXX_format() routines,
the name of the field is added automatically as in the
proto_tree_add_XXX() functions; only the value is added with the format.
One use case for this would be to add a unit of measurement string to
the value of the field, however using BASE_UNIT_STRING in the hf_
definition is now preferred.

proto_tree_add_checksum()
----------------------------
proto_tree_add_checksum is used to add a checksum field. The hf field
provided must be the correct size of the checksum (FT_UINT, FT_UINT16,
FT_UINT32, etc). Additional parameters are there to provide "status"
and expert info depending on whether the checksum matches the provided
value. The "status" and expert info can be used in cases except
where PROTO_CHECKSUM_NO_FLAGS is used.

proto_tree_add_subtree()
---------------------
proto_tree_add_subtree() is used to add a label to the GUI tree and create
a subtree for other fields. It will contain no value, so it is not searchable
in the display filter process.

This should only be used for items with subtrees, which may not
have values themselves - the items in the subtree are the ones with values.

For a subtree, the label on the subtree might reflect some of the items
in the subtree. This means the label can't be set until at least some
of the items in the subtree have been dissected. To do this, use
'proto_item_set_text()' or 'proto_item_append_text()':

    void
    proto_item_set_text(proto_item *ti, ...);

    void
    proto_item_append_text(proto_item *ti, ...);

'proto_item_set_text()' takes as an argument the proto_item value returned by
one of the parameters in 'proto_tree_add_subtree()', a 'printf'-style format
string, and a set of arguments corresponding to '%' format items in that string,
and replaces the text for the item created by 'proto_tree_add_subtree()' with the result
of applying the arguments to the format string.

'proto_item_append_text()' is similar, but it appends to the text for
the item the result of applying the arguments to the format string.

For example, early in the dissection, one might do:

    subtree = proto_tree_add_subtree(tree, tvb, offset, length, ett, &ti, <label>);

and later do

    proto_item_set_text(ti, "%s: %s", type, value);

after the "type" and "value" fields have been extracted and dissected.
<label> would be a label giving what information about the subtree is
available without dissecting any of the data in the subtree.

Note that an exception might be thrown when trying to extract the values of
the items used to set the label, if not all the bytes of the item are
available. Thus, one should create the item with text that is as
meaningful as possible, and set it or append additional information to
it as the values needed to supply that information are extracted.

proto_tree_add_subtree_format()
----------------------------
This is like proto_tree_add_subtree(), but uses printf-style arguments to
create the label; it is used to allow routines that take a printf-like
variable-length list of arguments to add a text item to the protocol
tree.

proto_tree_add_bits_item()
--------------------------
Adds a number of bits to the protocol tree which does not have to be byte
aligned. The offset and length is in bits.
Output format:

..10 1010 10.. .... "value" (formatted as FT_ indicates).

proto_tree_add_bits_ret_val()
-----------------------------
Works in the same way but also returns the value of the read bits.

proto_tree_add_split_bits_item_ret_val()
-----------------------------------
Similar, but is used for items that are made of 2 or more smaller sets of bits (crumbs)
which are not contiguous, but are concatenated to form the actual value. The size of
the crumbs and the order of assembly are specified in an array of crumb_spec structures.

proto_tree_add_split_bits_crumb()
---------------------------------
Helper function for the above, to add text for each crumb as it is encountered.

proto_tree_add_ts_23_038_7bits_item()
-------------------------------------
Adds a string of a given number of characters and encoded according to 3GPP TS 23.038 7 bits
alphabet.

proto_tree_add_bitmask() et al.
-------------------------------
These functions provide easy to use and convenient dissection of many types of common
bitmasks into individual fields.

header is an integer type and must be of type FT_[U]INT{8|16|24|32||40|48|56|64} and
represents the entire dissectable width of the bitmask.

'header' and 'ett' are the hf fields and ett field respectively to create an
expansion that covers the bytes of the bitmask.

'fields' is a NULL terminated array of pointers to hf fields representing
the individual subfields of the bitmask. These fields must either be integers
(usually of the same byte width as 'header') or of the type FT_BOOLEAN.
Each of the entries in 'fields' will be dissected as an item under the
'header' expansion and also IF the field is a boolean and IF it is set to 1,
then the name of that boolean field will be printed on the 'header' expansion
line. For integer type subfields that have a value_string defined, the
matched string from that value_string will be printed on the expansion line
as well.

Example: (from the SCSI dissector)
    static int hf_scsi_inq_peripheral        = -1;
    static int hf_scsi_inq_qualifier         = -1;
    static int hf_scsi_inq_devtype           = -1;
    ...
    static gint ett_scsi_inq_peripheral = -1;
    ...
    static int * const peripheral_fields[] = {
        &hf_scsi_inq_qualifier,
        &hf_scsi_inq_devtype,
        NULL
    };
    ...
    /* Qualifier and DeviceType */
    proto_tree_add_bitmask(tree, tvb, offset, hf_scsi_inq_peripheral,
        ett_scsi_inq_peripheral, peripheral_fields, ENC_BIG_ENDIAN);
    offset+=1;
    ...
        { &hf_scsi_inq_peripheral,
          {"Peripheral", "scsi.inquiry.peripheral", FT_UINT8, BASE_HEX,
           NULL, 0, NULL, HFILL}},
        { &hf_scsi_inq_qualifier,
          {"Qualifier", "scsi.inquiry.qualifier", FT_UINT8, BASE_HEX,
           VALS (scsi_qualifier_val), 0xE0, NULL, HFILL}},
        { &hf_scsi_inq_devtype,
          {"Device Type", "scsi.inquiry.devtype", FT_UINT8, BASE_HEX,
           VALS (scsi_devtype_val), SCSI_DEV_BITS, NULL, HFILL}},
    ...

Which provides very pretty dissection of this one byte bitmask.

    Peripheral: 0x05, Qualifier: Device type is connected to logical unit, Device Type: CD-ROM
        000. .... = Qualifier: Device type is connected to logical unit (0x00)
        ...0 0101 = Device Type: CD-ROM (0x05)

The proto_tree_add_bitmask_text() function is an extended version of
the proto_tree_add_bitmask() function. In addition, it allows to:
- Provide a leading text (e.g. "Flags: ") that will appear before
  the comma-separated list of field values
- Provide a fallback text (e.g. "None") that will be appended if
  no fields warranted a change to the top-level title.
- Using flags, specify which fields will affect the top-level title.

There are the following flags defined:

  BMT_NO_APPEND - the title is taken "as-is" from the 'name' argument.
  BMT_NO_INT - only boolean flags are added to the title.
  BMT_NO_FALSE - boolean flags are only added to the title if they are set.
  BMT_NO_TFS - only add flag name to the title, do not use true_false_string

The proto_tree_add_bitmask_with_flags() function is an extended version
of the proto_tree_add_bitmask() function. It allows using flags to specify
which fields will affect the top-level title. The flags are the
same BMT_NO_* flags as used in the proto_tree_add_bitmask_text() function.

The proto_tree_add_bitmask() behavior can be obtained by providing
both 'name' and 'fallback' arguments as NULL, and a flags of
(BMT_NO_FALSE|BMT_NO_TFS).

The proto_tree_add_bitmask_len() function is intended for protocols where
bitmask length is permitted to vary, so a length is specified explicitly
along with the bitmask value. USB Video "bmControl" and "bControlSize"
fields follow this pattern. The primary intent of this is "forward
compatibility," enabling an interpreter coded for version M of a structure
to comprehend fields in version N of the structure, where N > M and
bControlSize increases from version M to version N.

proto_tree_add_bitmask_len() is an extended version of proto_tree_add_bitmask()
that uses an explicitly specified (rather than inferred) length to control
dissection. Because of this, it may encounter two cases that
proto_tree_add_bitmask() and proto_tree_add_bitmask_text() may not:
- A length that exceeds that of the 'header' and bitmask subfields.
  In this case the least-significant bytes of the bitmask are dissected.
  An expert warning is generated in this case, because the dissection code
  likely needs to be updated for a new revision of the protocol.
- A length that is shorter than that of the 'header' and bitmask subfields.
  In this case, subfields whose data is fully present are dissected,
  and other subfields are not. No warning is generated in this case,
  because the dissection code is likely for a later revision of the protocol
  than the packet it was called to interpret.


proto_item_set_generated()
--------------------------
proto_item_set_generated is used to mark fields as not being read from the
captured data directly, but inferred from one or more values.

One of the primary uses of this is the presentation of verification of
checksums. Every IP packet has a checksum line, which can present the result
of the checksum verification, if enabled in the preferences. The result is
presented as a subtree, where the result is enclosed in square brackets
indicating a generated field.

  Header checksum: 0x3d42 [correct]
  [Checksum Status: Good (1)]

proto_item_set_hidden()
-----------------------
proto_item_set_hidden is used to hide fields, which have already been added
to the tree, from being visible in the displayed tree.

NOTE that creating hidden fields is actually quite a bad idea from a UI design
perspective because the user (someone who did not write nor has ever seen the
code) has no way of knowing that hidden fields are there to be filtered on
thus defeating the whole purpose of putting them there. A Better Way might
be to add the fields (that might otherwise be hidden) to a subtree where they
won't be seen unless the user opens the subtree--but they can be found if the
user wants.

One use for hidden fields (which would be better implemented using visible
fields in a subtree) follows: The caller may want a value to be
included in a tree so that the packet can be filtered on this field, but
the representation of that field in the tree is not appropriate. An
example is the token-ring routing information field (RIF). The best way
to show the RIF in a GUI is by a sequence of ring and bridge numbers.
Rings are 3-digit hex numbers, and bridges are single hex digits:

    RIF: 001-A-013-9-C0F-B-555

In the case of RIF, the programmer should use a field with no value and
use proto_tree_add_none_format() to build the above representation. The
programmer can then add the ring and bridge values, one-by-one, with
proto_tree_add_item() and hide them with proto_item_set_hidden() so that the
user can then filter on or search for a particular ring or bridge. Here's a
skeleton of how the programmer might code this.

    char *rif;
    rif = create_rif_string(...);

    proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);

    for(i = 0; i < num_rings; i++) {
        proto_item *pi;

        pi = proto_tree_add_item(tree, hf_tr_rif_ring, ...,
            ENC_BIG_ENDIAN);
        proto_item_set_hidden(pi);
    }
    for(i = 0; i < num_rings - 1; i++) {
        proto_item *pi;

        pi = proto_tree_add_item(tree, hf_tr_rif_bridge, ...,
            ENC_BIG_ENDIAN);
        proto_item_set_hidden(pi);
    }

The logical tree has these items:

    hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
    hf_tr_rif_ring,  hidden, value=0x001
    hf_tr_rif_bridge, hidden, value=0xA
    hf_tr_rif_ring,  hidden, value=0x013
    hf_tr_rif_bridge, hidden, value=0x9
    hf_tr_rif_ring,  hidden, value=0xC0F
    hf_tr_rif_bridge, hidden, value=0xB
    hf_tr_rif_ring,  hidden, value=0x555

GUI or print code will not display the hidden fields, but a display
filter or "packet grep" routine will still see the values. The possible
filter is then possible:

    tr.rif_ring eq 0x013

proto_item_set_url
------------------
proto_item_set_url is used to mark fields as containing a URL. This can only
be done with fields of type FT_STRING(Z). If these fields are presented they
are underlined, as could be done in a browser. These fields are sensitive to
clicks as well, launching the configured browser with this URL as parameter.

1.6 Utility routines.

1.6.1 val_to_str, val_to_str_const, try_val_to_str and try_val_to_str_idx

A dissector may need to convert a value to a string, using a
'value_string' structure, by hand, rather than by declaring a field with
an associated 'value_string' structure; this might be used, for example,
to generate a COL_INFO line for a frame.

val_to_str() handles the most common case:

    const gchar*
    val_to_str(guint32 val, const value_string *vs, const char *fmt)

If the value 'val' is found in the 'value_string' table pointed to by
'vs', 'val_to_str' will return the corresponding string; otherwise, it
will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
to generate a string, and will return a pointer to that string.
You can use it in a call to generate a COL_INFO line for a frame such as

    col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d"));

If you don't need to display 'val' in your fmt string, you can use
val_to_str_const() which just takes a string constant instead and returns it
unmodified when 'val' isn't found.

If you need to handle the failure case in some custom way, try_val_to_str()
will return NULL if val isn't found:

    const gchar*
    try_val_to_str(guint32 val, const value_string *vs)

Note that, you must check whether 'try_val_to_str()' returns NULL, and arrange
that its return value not be dereferenced if it's NULL. 'try_val_to_str_idx()'
behaves similarly, except it also returns an index into the value_string array,
or -1 if 'val' was not found.

The *_ext functions are "extended" versions of those already described. They
should be used for large value-string arrays which contain many entries. They
implement value to string conversions which will do either a direct access or
a binary search of the value string array if possible. See
"Extended Value Strings" under section 1.6 "Constructing the protocol tree" for
more information.

See epan/value_string.h for detailed information on the various value_string
functions.

To handle 64-bit values, there are an equivalent set of functions. These are:

    const gchar *
    val64_to_str(const guint64 val, const val64_string *vs, const char *fmt)

    const gchar *
    val64_to_str_const(const guint64 val, const val64_string *vs, const char *unknown_str);

    const gchar *
    try_val64_to_str(const guint64 val, const val64_string *vs);

    const gchar *
    try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx);


1.6.2 rval_to_str, try_rval_to_str and try_rval_to_str_idx

A dissector may need to convert a range of values to a string, using a
'range_string' structure.

Most of the same functions exist as with regular value_strings (see section
1.6.1) except with the names 'rval' instead of 'val'.


1.7 Calling Other Dissectors.

As each dissector completes its portion of the protocol analysis, it
is expected to create a new tvbuff of type TVBUFF_SUBSET which
contains the payload portion of the protocol (that is, the bytes
that are relevant to the next dissector).

To create a new TVBUFF_SUBSET that begins at a specified offset in a
parent tvbuff, and runs to the end of the parent tvbuff, the routine
tvbuff_new_subset_remaining() is used:

    next_tvb = tvb_new_subset_remaining(tvb, offset);

Where:
    tvb is the tvbuff that the dissector has been working on. It
    can be a tvbuff of any type.

    next_tvb is the new TVBUFF_SUBSET.

    offset is the byte offset of 'tvb' at which the new tvbuff
    should start. The first byte is the byte at offset 0.

To create a new TVBUFF_SUBSET that begins at a specified offset in a
parent tvbuff, with a specified number of bytes in the payload, the
routine tvbuff_new_subset_length() is used:

    next_tvb = tvb_new_subset_length(tvb, offset, reported_length);

Where:
    tvb is the tvbuff that the dissector has been working on. It
    can be a tvbuff of any type.

    next_tvb is the new TVBUFF_SUBSET.

    offset is the byte offset of 'tvb' at which the new tvbuff
    should start. The first byte is the byte at offset 0.

    reported_length is the number of bytes that the current protocol
    says should be in the payload.

In the few cases where the number of bytes available in the new subset
must be explicitly specified, rather than being calculated based on the
number of bytes in the payload, the routine tvb_new_subset_length_caplen()
is used:

    next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length);

Where:
    tvb is the tvbuff that the dissector has been working on. It
    can be a tvbuff of any type.

    next_tvb is the new TVBUFF_SUBSET.

    offset is the byte offset of 'tvb' at which the new tvbuff
    should start. The first byte is the byte at offset 0.

    length is the number of bytes in the new TVBUFF_SUBSET. A length
    argument of -1 says to use as many bytes as are available in
    'tvb'.

    reported_length is the number of bytes that the current protocol
    says should be in the payload. A reported_length of -1 says that
    the protocol doesn't say anything about the size of its payload.

To call a dissector you need to get the handle of the dissector using
find_dissector(), passing it the string name of the dissector. The setting
of the handle is usually done once at startup during the proto_reg_handoff
function within the calling dissector.

1.7.1 Dissector Tables

Another way to call a subdissector is to setup a dissector table. A dissector
table is a list of subdissectors grouped by a common identifier (integer or
string) in a dissector. Subdissectors will register themselves with the dissector
table using their unique identifier using one of the following APIs:

    void dissector_add_uint(const char *abbrev, const guint32 pattern,
                            dissector_handle_t handle);

    void dissector_add_uint_range(const char *abbrev, struct epan_range *range,
                            dissector_handle_t handle);

    void dissector_add_string(const char *name, const gchar *pattern,
                            dissector_handle_t handle);

    void dissector_add_for_decode_as(const char *name,
                            dissector_handle_t handle);

    dissector_add_for_decode_as doesn't add a unique identifier in the dissector
    table, but it lets the user add it from the command line or, in Wireshark,
    through the "Decode As" UI.

Then when the dissector hits the common identifier field, it will use one of the
following APIs to invoke the subdissector:

    int dissector_try_uint(dissector_table_t sub_dissectors,
        const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
        proto_tree *tree);

    int dissector_try_uint_new(dissector_table_t sub_dissectors,
        const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
        proto_tree *tree, const gboolean add_proto_name, void *data);

    int dissector_try_string(dissector_table_t sub_dissectors, const gchar *string,
        tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data);

These pass a subset of the remaining packet (typically the rest of the
packet) for the dissector table to determine which subdissector is called.
This allows dissection of a packet to be expanded outside of dissector without
having to modify the dissector directly.


1.8 Editing CMakeLists.txt to add your dissector.

To arrange that your dissector will be built as part of Wireshark, you
must add the name of the source file for your dissector to the DISSECTOR_SRC
section of epan/dissectors/CMakeLists.txt


1.9 Using the git source code tree.

  See <https://www.wireshark.org/develop.html>


1.10 Submitting code for your new dissector.

  See <https://www.wireshark.org/docs/wsdg_html_chunked/ChSrcContribute.html>
  and <https://gitlab.com/wireshark/wireshark/-/wikis/Development/SubmittingPatches>.

  - VERIFY that your dissector code does not use prohibited or deprecated APIs
    as follows:
    perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)>

  - VERIFY that your dissector code does not contain any header field related
    problems:
    perl <wireshark_root>/tools/checkhf.pl <source-filename(s)>

  - VERIFY that your dissector code does not contain any display filter related
    problems:
    perl <wireshark_root>/tools/checkfiltername.pl <source-filename(s)>

  - CHECK your dissector with CppCheck (http://cppcheck.sourceforge.net/) using
    Wireshark's customized configuration. This is particularly important on
    Windows, since Microsoft's compiler warnings are quite thin:
    ./tools/cppcheck/cppcheck.sh <source-filename(s)>

  - TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
    Use fuzz-test.sh and/or randpkt against your dissector. These are
    described at <https://gitlab.com/wireshark/wireshark/-/wikis/FuzzTesting>.

  - Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to
    <mailto:wireshark-dev-request[AT]wireshark.org?body="help"> or visiting
    <https://www.wireshark.org/lists/>.

  - 'git diff' to verify all your changes look good.

  - 'git add' all the files you changed.

  - 'git commit' to commit (locally) your changes. First line of commit message
    should be a summary of the changes followed by an empty line and a more
    verbose description.

  - 'git push downstream HEAD' to push the changes to GitLab. (This assumes
    that you have a remote named "downstream" that points to a fork of
    https://gitlab.com/wireshark/wireshark.)

  - Create a Wiki page on the protocol at <https://gitlab.com/wireshark/editor-wiki>.
    (You'll need to request access to https://gitlab.com/wireshark/wiki-editors.)
    A template is provided so it is easy to setup in a consistent style.
      See: <https://gitlab.com/wireshark/wireshark/-/wikis/HowToEdit>
      and  <https://gitlab.com/wireshark/wireshark/-/wikis/ProtocolReference>

  - If possible, add sample capture files to the sample captures page at
    <https://gitlab.com/wireshark/wireshark/-/wikis/SampleCaptures>. These
    files are used by the automated build system for fuzz testing.

  - If you don't think the wiki is the right place for your sample capture,
    submit a bug report to the Wireshark issue database, found at
    <https://gitlab.com/wireshark/wireshark/-/issues>, qualified as an
    enhancement and attach your sample capture there. Normally a new
    dissector won't be accepted without a sample capture! If you open a
    bug be sure to cross-link your GitLab merge request.

2. Advanced dissector topics.

2.1 Introduction.

Some of the advanced features are being worked on constantly. When using them
it is wise to check the relevant header and source files for additional details.

2.2 Following "conversations".

In Wireshark a conversation is defined as a series of data packets between two
address:port combinations. A conversation is not sensitive to the direction of
the packet. The same conversation will be returned for a packet bound from
ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.

2.2.1 Conversation Routines

There are seven routines that you will use to work with a conversation:
conversation_new, find_conversation, find_or_create_conversation,
conversation_add_proto_data, conversation_get_proto_data,
conversation_delete_proto_data, and conversation_set_dissector.


2.2.1.1 The conversation_init function.

This is an internal routine for the conversation code. As such you
will not have to call this routine. Just be aware that this routine is
called at the start of each capture and before the packets are filtered
with a display filter. The routine will destroy all stored
conversations. This routine does NOT clean up any data pointers that are
passed in the conversation_add_proto_data 'data' variable. You are
responsible for this clean up if you pass a malloc'ed pointer
in this variable.

See item 2.2.1.5 for more information about use of the 'data' pointer.


2.2.1.2 The conversation_new function.

This routine will create a new conversation based upon two address/port
pairs. If you want to associate with the conversation a pointer to a
private data structure you must use the conversation_add_proto_data
function. The ptype variable is used to differentiate between
conversations over different protocols, i.e. TCP and UDP. The options
variable is used to define a conversation that will accept any destination
address and/or port. Set options = 0 if the destination port and address
are known when conversation_new is called. See section 2.4 for more
information on usage of the options parameter.

The conversation_new prototype:
    conversation_t *conversation_new(guint32 setup_frame, address *addr1,
        address *addr2, port_type ptype, guint32 port1, guint32 port2,
        guint options);

Where:
    guint32 setup_frame = The lowest numbered frame for this conversation
    address* addr1      = first data packet address
    address* addr2      = second data packet address
    port_type ptype     = port type, this is defined in packet.h
    guint32 port1       = first data packet port
    guint32 port2       = second data packet port
    guint options       = conversation options, NO_ADDR2 and/or NO_PORT2

setup_frame indicates the first frame for this conversation, and is used to
distinguish multiple conversations with the same addr1/port1 and addr2/port2
pair that occur within the same capture session.

"addr1" and "port1" are the first address/port pair; "addr2" and "port2"
are the second address/port pair. A conversation doesn't have source
and destination address/port pairs - packets in a conversation go in
both directions - so "addr1"/"port1" may be the source or destination
address/port pair; "addr2"/"port2" would be the other pair.

If NO_ADDR2 is specified, the conversation is set up so that a
conversation lookup will match only the "addr1" address; if NO_PORT2 is
specified, the conversation is set up so that a conversation lookup will
match only the "port1" port; if both are specified, i.e.
NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
match only the "addr1"/"port1" address/port pair. This can be used if a
packet indicates that, later in the capture, a conversation will be
created using certain addresses and ports, in the case where the packet
doesn't specify the addresses and ports of both sides.

2.2.1.3 The find_conversation function.

Call this routine to look up a conversation. If no conversation is found,
the routine will return a NULL value.

The find_conversation prototype:

    conversation_t *find_conversation(guint32 frame_num, address *addr_a,
        address *addr_b, port_type ptype, guint32 port_a, guint32 port_b,
        guint options);

Where:
    guint32 frame_num = a frame number to match
    address* addr_a = first address
    address* addr_b = second address
    port_type ptype = port type
    guint32 port_a = first data packet port
    guint32 port_b = second data packet port
    guint options = conversation options, NO_ADDR_B and/or NO_PORT_B

frame_num is a frame number to match. The conversation returned is where
    (frame_num >= conversation->setup_frame
    && frame_num < conversation->next->setup_frame)
Suppose there are a total of 3 conversations (A, B, and C) that match
addr_a/port_a and addr_b/port_b, where the setup_frame used in
conversation_new() for A, B and C are 10, 50, and 100 respectively. The
frame_num passed in find_conversation is compared to the setup_frame of each
conversation. So if (frame_num >= 10 && frame_num < 50), conversation A is
returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned.
If (frame_num >= 100) conversation C is returned.

"addr_a" and "port_a" are the first address/port pair; "addr_b" and
"port_b" are the second address/port pair. Again, as a conversation
doesn't have source and destination address/port pairs, so
"addr_a"/"port_a" may be the source or destination address/port pair;
"addr_b"/"port_b" would be the other pair. The search will match the
"a" address/port pair against both the "1" and "2" address/port pairs,
and match the "b" address/port pair against both the "2" and "1"
address/port pairs; you don't have to worry about which side the "a" or
"b" pairs correspond to.

If the NO_ADDR_B flag was specified to "find_conversation()", the
"addr_b" address will be treated as matching any "wildcarded" address;
if the NO_PORT_B flag was specified, the "port_b" port will be treated
as matching any "wildcarded" port. If both flags are specified, i.e.
NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
any "wildcarded" address and the "port_b" port will be treated as
matching any "wildcarded" port.

2.2.1.4 The find_conversation_pinfo function.

This convenience function will find an existing conversation (by calling
find_conversation())

The find_conversation_pinfo prototype:

    extern conversation_t *find_conversation_pinfo(packet_info *pinfo, const guint options);

Where:
    packet_info *pinfo = the packet_info structure
    const guint options = conversation options, NO_ADDR_B and/or NO_PORT_B

The frame number and the addresses necessary for find_conversation() are
taken from the pinfo structure (as is commonly done).

2.2.1.5 The find_or_create_conversation function.

This convenience function will find an existing conversation (by calling
find_conversation()) and, if a conversation does not already exist, create a
new conversation by calling conversation_new().

The find_or_create_conversation prototype:

    extern conversation_t *find_or_create_conversation(packet_info *pinfo);

Where:
    packet_info *pinfo = the packet_info structure

The frame number and the addresses necessary for find_conversation() and
conversation_new() are taken from the pinfo structure (as is commonly done)
and no 'options' are used.


2.2.1.6 The conversation_add_proto_data function.

Once you have created a conversation with conversation_new, you can
associate data with it using this function.

The conversation_add_proto_data prototype:

    void conversation_add_proto_data(conversation_t *conv, int proto,
        void *proto_data);

Where:
    conversation_t *conv    = the conversation in question
    int proto               = registered protocol number
    void *data              = dissector data structure

"conversation" is the value returned by conversation_new. "proto" is a
unique protocol number created with proto_register_protocol. Protocols
are typically registered in the proto_register_XXXX section of your
dissector. "data" is a pointer to the data you wish to associate with the
conversation. "data" usually points to "wmem_alloc'd" memory; the
memory will be automatically freed each time a new dissection begins
and thus need not be managed (freed) by the dissector.
Using the protocol number allows several dissectors to
associate data with a given conversation.


2.2.1.7 The conversation_get_proto_data function.

After you have located a conversation with find_conversation, you can use
this function to retrieve any data associated with it.

The conversation_get_proto_data prototype:

    void *conversation_get_proto_data(conversation_t *conv, int proto);

Where:
    conversation_t *conv    = the conversation in question
    int proto               = registered protocol number

"conversation" is the conversation created with conversation_new. "proto"
is a unique protocol number created with proto_register_protocol,
typically in the proto_register_XXXX portion of a dissector. The function
returns a pointer to the data requested, or NULL if no data was found.


2.2.1.8 The conversation_delete_proto_data function.

After you are finished with a conversation, you can remove your association
with this function. Please note that ONLY the conversation entry is
removed. If you have allocated any memory for your data (other than with wmem_alloc),
 you must free it as well.

The conversation_delete_proto_data prototype:

    void conversation_delete_proto_data(conversation_t *conv, int proto);

Where:
    conversation_t *conv = the conversation in question
    int proto            = registered protocol number

"conversation" is the conversation created with conversation_new. "proto"
is a unique protocol number created with proto_register_protocol,
typically in the proto_register_XXXX portion of a dissector.

2.2.1.9 The conversation_set_dissector function

This function sets the protocol dissector to be invoked whenever
conversation parameters (addresses, port_types, ports, etc) are matched
during the dissection of a packet.

The conversation_set_dissector prototype:

    void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);

Where:
    conversation_t *conv = the conversation in question
    const dissector_handle_t handle = the dissector handle.


2.2.2 Using timestamps relative to the conversation

There is a framework to calculate timestamps relative to the start of the
conversation. First of all the timestamp of the first packet that has been
seen in the conversation must be kept in the protocol data to be able
to calculate the timestamp of the current packet relative to the start
of the conversation. The timestamp of the last packet that was seen in the
conversation should also be kept in the protocol data. This way the
delta time between the current packet and the previous packet in the
conversation can be calculated.

So add the following items to the struct that is used for the protocol data:

  nstime_t ts_first;
  nstime_t ts_prev;

The ts_prev value should only be set during the first run through the
packets (ie PINFO_FD_VISITED(pinfo) is false).

Next step is to use the per-packet information (described in section 2.5)
to keep the calculated delta timestamp, as it can only be calculated
on the first run through the packets. This is because a packet can be
selected in random order once the whole file has been read.

After calculating the conversation timestamps, it is time to put them in
the appropriate columns with the function 'col_set_time' (described in
section 1.5.9). The column used for relative timestamps is:

COL_REL_TIME, /* Delta time to last frame in conversation */

Last but not least, there MUST be a preference in each dissector that
uses conversation timestamps that makes it possible to enable and
disable the calculation of conversation timestamps. The main argument
for this is that a higher level conversation is able to overwrite
the values of lower level conversations in these two columns. Being
able to actively select which protocols may overwrite the conversation
timestamp columns gives the user the power to control these columns.
(A second reason is that conversation timestamps use the per-packet
data structure which uses additional memory, which should be avoided
if these timestamps are not needed)

Have a look at the differences to packet-tcp.[ch] in SVN 22966 and
SVN 23058 to see the implementation of conversation timestamps for
the tcp-dissector.


2.2.3 The example conversation code using wmem_file_scope memory.

For a conversation between two IP addresses and ports you can use this as an
example. This example uses wmem_alloc() with wmem_file_scope() to allocate
memory and stores the data pointer in the conversation 'data' variable.

/************************ Global values ************************/

/* define your structure here */
typedef struct {

} my_entry_t;

/* Registered protocol number */
static int my_proto = -1;

/********************* in the dissector routine *********************/

/* the local variables in the dissector */

conversation_t *conversation;
my_entry_t *data_ptr;


/* look up the conversation */

conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst,
        pinfo->ptype, pinfo->srcport, pinfo->destport, 0);

/* if conversation found get the data pointer that you stored */
if (conversation)
    data_ptr = (my_entry_t*)conversation_get_proto_data(conversation, my_proto);
else {

    /* new conversation create local data structure */

    data_ptr = wmem_alloc(wmem_file_scope(), sizeof(my_entry_t));

    /*** add your code here to setup the new data structure ***/

    /* create the conversation with your data pointer  */

    conversation = conversation_new(pinfo->num,  &pinfo->src, &pinfo->dst, pinfo->ptype,
        pinfo->srcport, pinfo->destport, 0);
    conversation_add_proto_data(conversation, my_proto, (void *)data_ptr);
}

/* at this point the conversation data is ready */

/***************** in the protocol register routine *****************/

my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto");


2.2.4 An example conversation code that starts at a specific frame number.

Sometimes a dissector has determined that a new conversation is needed that
starts at a specific frame number, when a capture session encompasses multiple
conversation that reuse the same src/dest ip/port pairs. You can use the
conversation->setup_frame returned by find_conversation with
pinfo->num to determine whether or not there already exists a conversation
that starts at the specific frame number.

/* in the dissector routine */

    conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst,
        pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
    if (conversation == NULL || (conversation->setup_frame != pinfo->num)) {
        /* It's not part of any conversation or the returned
         * conversation->setup_frame doesn't match the current frame
         * create a new one.
         */
        conversation = conversation_new(pinfo->num, &pinfo->src,
            &pinfo->dst, pinfo->ptype, pinfo->srcport, pinfo->destport,
            NULL, 0);
    }


2.2.5 The example conversation code using conversation index field.

Sometimes the conversation isn't enough to define a unique data storage
value for the network traffic. For example if you are storing information
about requests carried in a conversation, the request may have an
identifier that is used to  define the request. In this case the
conversation and the identifier are required to find the data storage
pointer. You can use the conversation data structure index value to
uniquely define the conversation.

See packet-afs.c for an example of how to use the conversation index. In
this dissector multiple requests are sent in the same conversation. To store
information for each request the dissector has an internal hash table based
upon the conversation index and values inside the request packets.


    /* in the dissector routine */

    /* to find a request value, first lookup conversation to get index */
    /* then used the conversation index, and request data to find data */
    /* in the local hash table */

    conversation = find_or_create_conversation(pinfo);

    request_key.conversation = conversation->index;
    request_key.service = pntoh16(&rxh->serviceId);
    request_key.callnumber = pntoh32(&rxh->callNumber);

    request_val = (struct afs_request_val *)g_hash_table_lookup(
        afs_request_hash, &request_key);

    /* only allocate a new hash element when it's a request */
    opcode = 0;
    if (!request_val && !reply)
    {
        new_request_key = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_key));
        *new_request_key = request_key;

        request_val = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_val));
        request_val -> opcode = pntoh32(&afsh->opcode);
        opcode = request_val->opcode;

        g_hash_table_insert(afs_request_hash, new_request_key,
            request_val);
    }



2.3 Dynamic conversation dissector registration.


NOTE:   This sections assumes that all information is available to
    create a complete conversation, source port/address and
    destination port/address. If either the destination port or
    address is known, see section 2.4 Dynamic server port dissector
    registration.

For protocols that negotiate a secondary port connection, for example
packet-msproxy.c, a conversation can install a dissector to handle
the secondary protocol dissection. After the conversation is created
for the negotiated ports use the conversation_set_dissector to define
the dissection routine.
Before we create these conversations or assign a dissector to them we should
first check that the conversation does not already exist and if it exists
whether it is registered to our protocol or not.
We should do this because it is uncommon but it does happen that multiple
different protocols can use the same socketpair during different stages of
an application cycle. By keeping track of the frame number a conversation
was started in Wireshark can still tell these different protocols apart.

The second argument to conversation_set_dissector is a dissector handle,
which is created with a call to create_dissector_handle or
register_dissector.

create_dissector_handle takes as arguments a pointer to the dissector
function and a protocol ID as returned by proto_register_protocol;
register_dissector takes as arguments a string giving a name for the
dissector, a pointer to the dissector function, and a protocol ID.

The protocol ID is the ID for the protocol dissected by the function.
The function will not be called if the protocol has been disabled by the
user; instead, the data for the protocol will be dissected as raw data.

An example -

/* the handle for the dynamic dissector *
static dissector_handle_t sub_dissector_handle;

/* prototype for the dynamic dissector */
static void sub_dissector(tvbuff_t *tvb, packet_info *pinfo,
                proto_tree *tree);

/* in the main protocol dissector, where the next dissector is setup */

/* if conversation has a data field, create it and load structure */

/* First check if a conversation already exists for this
    socketpair
*/
    conversation = find_conversation(pinfo->num,
                &pinfo->src, &pinfo->dst, protocol,
                src_port, dst_port,  0);

/* If there is no such conversation, or if there is one but for
   someone else's protocol then we just create a new conversation
   and assign our protocol to it.
*/
    if ( (conversation == NULL) ||
         (conversation->dissector_handle != sub_dissector_handle) ) {
        new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info));
        new_conv_info->data1 = value1;

/* create the conversation for the dynamic port */
            conversation = conversation_new(pinfo->num,
            &pinfo->src, &pinfo->dst, protocol,
                src_port, dst_port, new_conv_info, 0);

/* set the dissector for the new conversation */
            conversation_set_dissector(conversation, sub_dissector_handle);
    }
    ...

void
proto_register_PROTOABBREV(void)
{
    ...

    sub_dissector_handle = create_dissector_handle(sub_dissector,
        proto);

    ...
}

2.4 Dynamic server port dissector registration.

NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
conversation with only one port and address set, this isn't a
requirement. Either the second port or the second address can be set
when the conversation is created.

For protocols that define a server address and port for a secondary
protocol, a conversation can be used to link a protocol dissector to
the server port and address. The key is to create the new
conversation with the second address and port set to the "accept
any" values.

Some server applications can use the same port for different protocols during
different stages of a transaction. For example it might initially use SNMP
to perform some discovery and later switch to use TFTP using the same port.
In order to handle this properly we must first check whether such a
conversation already exists or not and if it exists we also check whether the
registered dissector_handle for that conversation is "our" dissector or not.
If not we create a new conversation on top of the previous one and set this new
conversation to use our protocol.
Since Wireshark keeps track of the frame number where a conversation started
wireshark will still be able to keep the packets apart even though they do use
the same socketpair.
        (See packet-tftp.c and packet-snmp.c for examples of this)

There are two support routines that will allow the second port and/or
address to be set later.

conversation_set_port2( conversation_t *conv, guint32 port);
conversation_set_addr2( conversation_t *conv, address addr);

These routines will change the second address or port for the
conversation. So, the server port conversation will be converted into a
more complete conversation definition. Don't use these routines if you
want to create a conversation between the server and client and retain the
server port definition, you must create a new conversation.


An example -

/* the handle for the dynamic dissector *
static dissector_handle_t sub_dissector_handle;

    ...

/* in the main protocol dissector, where the next dissector is setup */

/* if conversation has a data field, create it and load structure */

    new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info));
    new_conv_info->data1 = value1;

/* create the conversation for the dynamic server address and port      */
/* NOTE: The second address and port values don't matter because the    */
/* NO_ADDR2 and NO_PORT2 options are set.                               */

/* First check if a conversation already exists for this
    IP/protocol/port
*/
    conversation = find_conversation(pinfo->num,
                &server_src_addr, 0, protocol,
                server_src_port, 0, NO_ADDR2 | NO_PORT_B);
/* If there is no such conversation, or if there is one but for
   someone else's protocol then we just create a new conversation
   and assign our protocol to it.
*/
    if ( (conversation == NULL) ||
         (conversation->dissector_handle != sub_dissector_handle) ) {
        conversation = conversation_new(pinfo->num,
        &server_src_addr, 0, protocol,
        server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2);

/* set the dissector for the new conversation */
        conversation_set_dissector(conversation, sub_dissector_handle);
    }

2.5 Per-packet information.

Information can be stored for each data packet that is processed by the
dissector. The information is added with the p_add_proto_data function and
retrieved with the p_get_proto_data function. The data pointers passed into
the p_add_proto_data are not managed by the proto_data routines, however the
data pointer memory scope must match that of the scope parameter.
The two most common use cases for p_add_proto_data/p_get_proto_data are for
persistent data about the packet for the lifetime of the capture (file scope)
and to exchange data between dissectors across a single packet (packet scope).
It is also used to provide packet data for Decode As dialog (packet scope).

These functions are declared in <epan/proto_data.h>.

void
p_add_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32 key, void *proto_data)
void *
p_get_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32 key)

Where:
    scope      - Lifetime of the data to be stored, typically wmem_file_scope()
                 or pinfo->pool (packet scope). Must match scope of data
                 allocated.
    pinfo      - The packet info pointer.
    proto      - Protocol id returned by the proto_register_protocol call
                 during initialization
    key        - key associated with 'proto_data'
    proto_data - pointer to the dissector data.


2.6 User Preferences.

If the dissector has user options, there is support for adding these preferences
to a configuration dialog.

You must register the module with the preferences routine with -

       module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void))
       or
       module_t *prefs_register_protocol_subtree(const char *subtree, int id,
              void (*apply_cb)(void));


Where: proto_id   - the value returned by "proto_register_protocol()" when
                    the protocol was registered.
       apply_cb   - Callback routine that is called when preferences are
                    applied. It may be NULL, which inhibits the callback.
       subtree    - grouping preferences tree node name (several protocols can
                    be grouped under one preferences subtree)

Then you can register the fields that can be configured by the user with these
routines -

    /* Register a preference with an unsigned integral value. */
    void prefs_register_uint_preference(module_t *module, const char *name,
        const char *title, const char *description, guint base, guint *var);

    /* Register a preference with an Boolean value. */
    void prefs_register_bool_preference(module_t *module, const char *name,
        const char *title, const char *description, gboolean *var);

    /* Register a preference with an enumerated value. */
    void prefs_register_enum_preference(module_t *module, const char *name,
        const char *title, const char *description, gint *var,
        const enum_val_t *enumvals, gboolean radio_buttons)

    /* Register a preference with a character-string value. */
    void prefs_register_string_preference(module_t *module, const char *name,
        const char *title, const char *description, char **var)

    /* Register a preference with a file name (string) value.
    * File name preferences are basically like string preferences
    * except that the GUI gives the user the ability to browse for the
    * file. Set for_writing TRUE to show a Save dialog instead of normal Open.
    */
    void prefs_register_filename_preference(module_t *module, const char *name,
        const char *title, const char *description, char **var,
        gboolean for_writing)

    /* Register a preference with a range of unsigned integers (e.g.,
     * "1-20,30-40").
     */
    void prefs_register_range_preference(module_t *module, const char *name,
        const char *title, const char *description, range_t *var,
        guint32 max_value)

Where: module - Returned by the prefs_register_protocol routine
     name     - This is appended to the name of the protocol, with a
            "." between them, to construct a name that identifies
            the field in the preference file; the name itself
            should not include the protocol name, as the name in
            the preference file will already have it. Make sure that
            only lower-case ASCII letters, numbers, underscores and
            dots appear in the preference name.
     title    - Field title in the preferences dialog
     description - Comments added to the preference file above the
               preference value and shown as tooltip in the GUI, or NULL
     var      - pointer to the storage location that is updated when the
            field is changed in the preference dialog box. Note that
            with string preferences the given pointer is overwritten
            with a pointer to a new copy of the string during the
            preference registration. The passed-in string may be
            freed, but you must keep another pointer to the string
            in order to free it.
     base      - Base that the unsigned integer is expected to be in,
            see strtoul(3).
     enumvals - an array of enum_val_t structures. This must be
            NULL-terminated; the members of that structure are:

            a short name, to be used with the "-o" flag - it
            should not contain spaces or upper-case letters,
            so that it's easier to put in a command line;

            a description, which is used in the GUI (and
            which, for compatibility reasons, is currently
            what's written to the preferences file) - it can
            contain spaces, capital letters, punctuation,
            etc.;

            the numerical value corresponding to that name
            and description
     radio_buttons - TRUE if the field is to be displayed in the
             preferences dialog as a set of radio buttons,
             FALSE if it is to be displayed as an option
             menu
     max_value - The maximum allowed value for a range (0 is the minimum).

These functions are declared in <epan/prefs.h>.

An example from packet-rtpproxy.c -

    proto_rtpproxy = proto_register_protocol ( "Sippy RTPproxy Protocol", "RTPproxy", "rtpproxy");

    ...

    rtpproxy_module = prefs_register_protocol(proto_rtpproxy, proto_reg_handoff_rtpproxy);

    prefs_register_bool_preference(rtpproxy_module, "establish_conversation",
                                 "Establish Media Conversation",
                                 "Specifies that RTP/RTCP/T.38/MSRP/etc streams are decoded based "
                                 "upon port numbers found in RTPproxy answers",
                                 &rtpproxy_establish_conversation);

    prefs_register_uint_preference(rtpproxy_module, "reply.timeout",
                                 "RTPproxy reply timeout", /* Title */
                                 "Maximum timeout value in waiting for reply from RTPProxy (in milliseconds).", /* Descr */
                                 10,
                                 &rtpproxy_timeout);

This will create preferences "rtpproxy.establish_conversation" and
"rtpproxy.reply.timeout", the first of which is an Boolean and the
second of which is a unsigned integer.

Note that a warning will pop up if you've saved such preference to the
preference file and you subsequently take the code out. The way to make
a preference obsolete is to register it as such:

/* Register a preference that used to be supported but no longer is. */
    void prefs_register_obsolete_preference(module_t *module,
        const char *name);

2.7 Reassembly/desegmentation for protocols running atop TCP.

There are two main ways of reassembling a Protocol Data Unit (PDU) which
spans across multiple TCP segments. The first approach is simpler, but
assumes you are running atop of TCP when this occurs (but your dissector
might run atop of UDP, too, for example), and that your PDUs consist of a
fixed amount of data that includes enough information to determine the PDU
length, possibly followed by additional data. The second method is more
generic but requires more code and is less efficient.

2.7.1 Using tcp_dissect_pdus().

For the first method, you register two different dissection methods, one
for the TCP case, and one for the other cases. It is a good idea to
also have a dissect_PROTO_common function which will parse the generic
content that you can find in all PDUs which is called from
dissect_PROTO_tcp when the reassembly is complete and from
dissect_PROTO_udp (or dissect_PROTO_other).

To register the distinct dissector functions, consider the following
example, stolen from packet-hartip.c:

    #include "packet-tcp.h"

    dissector_handle_t hartip_tcp_handle;
    dissector_handle_t hartip_udp_handle;

    hartip_tcp_handle = create_dissector_handle(dissect_hartip_tcp, proto_hartip);
    hartip_udp_handle = create_dissector_handle(dissect_hartip_udp, proto_hartip);

    dissector_add_uint("udp.port", HARTIP_PORT, hartip_udp_handle);
    dissector_add_uint_with_preference("tcp.port", HARTIP_PORT, hartip_tcp_handle);

The dissect_hartip_udp function does very little work and calls
dissect_hartip_common, while dissect_hartip_tcp calls tcp_dissect_pdus with a
reference to a callback which will be called with reassembled data:

    static int
    dissect_hartip_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
                   void *data)
    {
        if (!tvb_bytes_exist(tvb, 0, HARTIP_HEADER_LENGTH))
            return 0;

        tcp_dissect_pdus(tvb, pinfo, tree, hartip_desegment, HARTIP_HEADER_LENGTH,
                   get_dissect_hartip_len, dissect_hartip_pdu, data);
        return tvb_reported_length(tvb);
    }

(The dissect_hartip_pdu function acts similarly to dissect_hartip_udp.)
The arguments to tcp_dissect_pdus are:

    the tvbuff pointer, packet_info pointer, and proto_tree pointer
    passed to the dissector;

    a gboolean flag indicating whether desegmentation is enabled for
    your protocol;

    the number of bytes of PDU data required to determine the length
    of the PDU;

    a routine that takes as arguments a packet_info pointer, a tvbuff
    pointer and an offset value representing the offset into the tvbuff
    at which a PDU begins, and a void pointer for user data, and should
    return the total length of the PDU in bytes (or 0 if more bytes are
    needed to determine the message length).
    The routine must not throw exceptions (it is guaranteed that the
    number of bytes specified by the previous argument to
    tcp_dissect_pdus is available, but more data might not be available,
    so don't refer to any data past that);

    a new_dissector_t routine to dissect the pdu that's passed a tvbuff
    pointer, packet_info pointer, proto_tree pointer and a void pointer for
    user data, with the tvbuff containing a possibly-reassembled PDU. (The
    "reported_length" of the tvbuff will be the length of the PDU);

    a void pointer to user data that is passed to the length-determining
    routine, and the dissector routine referenced in the previous parameter.

2.7.2 Modifying the pinfo struct.

The second reassembly mode is preferred when the dissector cannot determine
how many bytes it will need to read in order to determine the size of a PDU.
It may also be useful if your dissector needs to support reassembly from
protocols other than TCP.

Your dissect_PROTO will initially be passed a tvbuff containing the payload of
the first packet. It should dissect as much data as it can, noting that it may
contain more than one complete PDU. If the end of the provided tvbuff coincides
with the end of a PDU then all is well and your dissector can just return as
normal. (If it is a new-style dissector, it should return the number of bytes
successfully processed.)

If the dissector discovers that the end of the tvbuff does /not/ coincide with
the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can
indicate this to the parent dissector, by updating the pinfo struct. The
desegment_offset field is the offset in the tvbuff at which the dissector will
continue processing when next called. The desegment_len field should contain
the estimated number of additional bytes required for completing the PDU. Next
time your dissect_PROTO is called, it will be passed a tvbuff composed of the
end of the data from the previous tvbuff together with desegment_len more bytes.

If the dissector cannot tell how many more bytes it will need, it should set
desegment_len=DESEGMENT_ONE_MORE_SEGMENT; it will then be called again as soon
as any more data becomes available. Dissectors should set the desegment_len to a
reasonable value when possible rather than always setting
DESEGMENT_ONE_MORE_SEGMENT as it will generally be more efficient. Also, you
*must not* set desegment_len=1 in this case, in the hope that you can change
your mind later: once you return a positive value from desegment_len, your PDU
boundary is set in stone.

static hf_register_info hf[] = {
    {&hf_cstring,
     {"C String", "c.string", FT_STRING, BASE_NONE, NULL, 0x0,
      NULL, HFILL}
     }
   };

/**
*   Dissect a buffer containing ASCII C strings.
*
*   @param  tvb     The buffer to dissect.
*   @param  pinfo   Packet Info.
*   @param  tree    The protocol tree.
*   @param  data    Optional data parameter given by parent dissector.
**/
static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree, void *data _U_)
{
    guint offset = 0;
    while(offset < tvb_reported_length(tvb)) {
        gint available = tvb_reported_length_remaining(tvb, offset);
        gint len = tvb_strnlen(tvb, offset, available);

        if( -1 == len ) {
            /* we ran out of data: ask for more */
            pinfo->desegment_offset = offset;
            pinfo->desegment_len = DESEGMENT_ONE_MORE_SEGMENT;
            return (offset + available);
        }

        col_set_str(pinfo->cinfo, COL_INFO, "C String");

        len += 1; /* Add one for the '\0' */

        if (tree) {
            proto_tree_add_item(tree, hf_cstring, tvb, offset, len,
                ENC_ASCII|ENC_NA);
        }
        offset += (guint)len;
    }

    /* if we get here, then the end of the tvb coincided with the end of a
       string. Happy days. */
    return tvb_captured_length(tvb);
}

This simple dissector will repeatedly return DESEGMENT_ONE_MORE_SEGMENT
requesting more data until the tvbuff contains a complete C string. The C string
will then be added to the protocol tree. Note that there may be more
than one complete C string in the tvbuff, so the dissection is done in a
loop.

2.8 Using udp_dissect_pdus().

As noted in section 2.7.1, TCP has an API to dissect its PDU that can handle
a PDU spread across multiple packets or multiple PDUs spread across a single
packet. This section describes a similar mechanism for UDP, but is only
applicable for one or more PDUs in a single packet. If a protocol runs on top
of TCP as well as UDP, a common PDU dissection function can be created for both.

To register the distinct dissector functions, consider the following
example using UDP and TCP dissection, stolen from packet-dnp.c:

    #include "packet-tcp.h"
    #include "packet-udp.h"

    dissector_handle_t dnp3_tcp_handle;
    dissector_handle_t dnp3_udp_handle;

    dnp3_tcp_handle = create_dissector_handle(dissect_dnp3_tcp, proto_dnp3);
    dnp3_udp_handle = create_dissector_handle(dissect_dnp3_udp, proto_dnp3);

    dissector_add_uint("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle);
    dissector_add_uint("udp.port", UDP_PORT_DNP, dnp3_udp_handle);

Both dissect_dnp3_tcp and dissect_dnp3_udp call tcp_dissect_pdus and
udp_dissect_pdus respectively, with a reference to the same callbacks which
are called to handle PDU data.

    static int
    dissect_dnp3_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
    {
        return udp_dissect_pdus(tvb, pinfo, tree, DNP_HDR_LEN, dnp3_udp_check_header,
                   get_dnp3_message_len, dissect_dnp3_message, data);
    }

    static int
    dissect_dnp3_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
    {
        if (!check_dnp3_header(tvb, FALSE)) {
            return 0;
        }

        tcp_dissect_pdus(tvb, pinfo, tree, TRUE, DNP_HDR_LEN,
                   get_dnp3_message_len, dissect_dnp3_message, data);

        return tvb_captured_length(tvb);
    }

(udp_dissect_pdus has an option of a heuristic check function within it while
tcp_dissect_pdus does not, so it's done outside)

The arguments to udp_dissect_pdus are:

    the tvbuff pointer, packet_info pointer, and proto_tree pointer
    passed to the dissector;

    the number of bytes of PDU data required to determine the length
    of the PDU;

    an optional routine (passing NULL is okay) that takes as arguments a
    packet_info pointer, a tvbuff pointer and an offset value representing the
    offset into the tvbuff at which a PDU begins, and a void pointer for user
    data, and should return TRUE if the packet belongs to the dissector.
    The routine must not throw exceptions (it is guaranteed that the
    number of bytes specified by the previous argument to
    udp_dissect_pdus is available, but more data might not be available,
    so don't refer to any data past that);

    a routine that takes as arguments a packet_info pointer, a tvbuff
    pointer and an offset value representing the offset into the tvbuff
    at which a PDU begins, and a void pointer for user data, and should
    return the total length of the PDU in bytes. If return value is 0,
    it's treated the same as a failed heuristic.
    The routine must not throw exceptions (it is guaranteed that the
    number of bytes specified by the previous argument to
    tcp_dissect_pdus is available, but more data might not be available,
    so don't refer to any data past that);

    a new_dissector_t routine to dissect the pdu that's passed a tvbuff
    pointer, packet_info pointer, proto_tree pointer and a void pointer for
    user data, with the tvbuff containing a possibly-reassembled PDU. (The
    "reported_length" of the tvbuff will be the length of the PDU);

    a void pointer to user data that is passed to the length-determining
    routine, and the dissector routine referenced in the previous parameter.

2.9 PINOs (Protocols in name only)

For the typical dissector there is a 1-1 relationship between it and it's
protocol. However, there are times when a protocol needs multiple "names"
because it has multiple dissection functions going into the same dissector
table. The multiple names removes confusion when picking dissection through
Decode As functionality.

Once the "main" protocol name has been created through proto_register_protocol,
additional "pinos" can be created with proto_register_protocol_in_name_only.
These pinos have all of the naming conventions of a protocol, but are stored
separately as to remove confusion from real protocols. "pinos" the main
protocol's properties for things like enable/disable. i.e. If the "main"
protocol has been disabled, all of its pinos will be disabled as well.
Pinos should not have any fields registered with them or heuristic tables
associated with them.

Another use case for pinos is when a protocol contains a TLV design and it
wants to create a dissector table to handle dissection of the "V". Dissector
tables require a "protocol", but the dissection functions for that table
typically aren't a protocol. In this case proto_register_protocol_in_name_only
creates the necessary placeholder for the dissector table. In addition, because
a dissector table exists, "V"s of the TLVs can be dissected outside of the
original dissector file.

2.10 Creating Decode As functionality.

While the Decode As functionality is available through the GUI, the underlying
functionality is controlled by dissectors themselves. To create Decode As
functionality for a dissector, two things are required:
    1. A dissector table
    2. A series of structures to assist the GUI in how to present the dissector
       table data.

Consider the following example using IP dissection, stolen from packet-ip.c:

    static build_valid_func ip_da_build_value[1] = {ip_value};
    static decode_as_value_t ip_da_values = {ip_prompt, 1, ip_da_build_value};
    static decode_as_t ip_da = {"ip", "ip.proto", 1, 0, &ip_da_values, NULL, NULL,
                              decode_as_default_populate_list, decode_as_default_reset, decode_as_default_change, NULL};
    ...
    ip_dissector_table = register_dissector_table("ip.proto", "IP protocol", ip_proto, FT_UINT8, BASE_DEC);
    ...
    register_decode_as(&ip_da);

ip_da_build_value contains all of the function pointers (typically just 1) that
can be used to retrieve the value(s) that go into the dissector table. This is
usually data saved by the dissector during packet dissector with an API like
p_add_proto_data and retrieved in the "value" function with p_get_proto_data.

ip_da_values contains all of the function pointers (typically just 1) that
provide the text explaining the name and use of the value field that will
be passed to the dissector table to change the dissection output.

ip_da pulls everything together including the dissector (protocol) name, the
"layer type" of the dissector, the dissector table name, the function pointer
values as well as handlers for populating, applying and resetting the changes
to the dissector table through Decode As GUI functionality. For dissector
tables that are an integer or string type, the provided "default" handling
functions shown in the example should suffice.

All entries into a dissector table that use Decode As must have a unique
protocol ID. If a protocol wants multiple entries into a dissector table,
a pino should be used (see section 2.9)

2.11 ptvcursors.

The ptvcursor API allows a simpler approach to writing dissectors for
simple protocols. The ptvcursor API works best for protocols whose fields
are static and whose format does not depend on the value of other fields.
However, even if only a portion of your protocol is statically defined,
then that portion could make use of ptvcursors.

The ptvcursor API lets you extract data from a tvbuff, and add it to a
protocol tree in one step. It also keeps track of the position in the
tvbuff so that you can extract data again without having to compute any
offsets --- hence the "cursor" name of the API.

The three steps for a simple protocol are:
    1. Create a new ptvcursor with ptvcursor_new()
    2. Add fields with multiple calls of ptvcursor_add()
    3. Delete the ptvcursor with ptvcursor_free()

ptvcursor offers the possibility to add subtrees in the tree as well. It can be
done in very simple steps :
    1. Create a new subtree with ptvcursor_push_subtree(). The old subtree is
       pushed in a stack and the new subtree will be used by ptvcursor.
    2. Add fields with multiple calls of ptvcursor_add(). The fields will be
       added in the new subtree created at the previous step.
    3. Pop the previous subtree with ptvcursor_pop_subtree(). The previous
       subtree is again used by ptvcursor.
Note that at the end of the parsing of a packet you must have popped each
subtree you pushed. If it's not the case, the dissector will generate an error.

To use the ptvcursor API, include the "ptvcursor.h" file. The PGM dissector
is an example of how to use it. You don't need to look at it as a guide;
instead, the API description here should be good enough.

2.11.1 ptvcursor API.

ptvcursor_t*
ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset)
    This creates a new ptvcursor_t object for iterating over a tvbuff.
You must call this and use this ptvcursor_t object so you can use the
ptvcursor API.

proto_item*
ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, const guint encoding)
    This will extract 'length' bytes from the tvbuff and place it in
the proto_tree as field 'hf', which is a registered header_field. The
pointer to the proto_item that is created is passed back to you. Internally,
the ptvcursor advances its cursor so the next call to ptvcursor_add
starts where this call finished. The 'encoding' parameter is relevant for
certain type of fields (See above under proto_tree_add_item()).

proto_item*
ptvcursor_add_ret_uint(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, guint32 *retval);
    Like ptvcursor_add, but returns uint value retrieved

proto_item*
ptvcursor_add_ret_int(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, gint32 *retval);
    Like ptvcursor_add, but returns int value retrieved

proto_item*
ptvcursor_add_ret_string(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, wmem_allocator_t *scope, const guint8 **retval);
    Like ptvcursor_add, but returns string retrieved

proto_item*
ptvcursor_add_ret_boolean(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, gboolean *retval);
    Like ptvcursor_add, but returns boolean value retrieved

proto_item*
ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, const guint encoding)
    Like ptvcursor_add, but does not advance the internal cursor.

void
ptvcursor_advance(ptvcursor_t* ptvc, gint length)
    Advances the internal cursor without adding anything to the proto_tree.

void
ptvcursor_free(ptvcursor_t* ptvc)
    Frees the memory associated with the ptvcursor. You must call this
after your dissection with the ptvcursor API is completed.


proto_tree*
ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree)
    Pushes the current subtree in the tree stack of the cursor, creates a new
one and sets this one as the working tree.

void
ptvcursor_pop_subtree(ptvcursor_t* ptvc);
    Pops a subtree in the tree stack of the cursor

proto_tree*
ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, gint length,
                            const guint encoding, gint ett_subtree);
    Adds an item to the tree and creates a subtree.
If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
In this case, at the next pop, the item length will be equal to the advancement
of the cursor since the creation of the subtree.

proto_tree*
ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length,
                                gint ett_subtree, const char* format, ...);
    Add a text node to the tree and create a subtree.
If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
In this case, at the next pop, the item length will be equal to the advancement
of the cursor since the creation of the subtree.

2.11.2 Miscellaneous functions.

tvbuff_t*
ptvcursor_tvbuff(ptvcursor_t* ptvc)
    Returns the tvbuff associated with the ptvcursor.

gint
ptvcursor_current_offset(ptvcursor_t* ptvc)
    Returns the current offset.

proto_tree*
ptvcursor_tree(ptvcursor_t* ptvc)
    Returns the proto_tree associated with the ptvcursor.

void
ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree)
    Sets a new proto_tree for the ptvcursor.

proto_tree*
ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree);
    Creates a subtree and adds it to the cursor as the working tree but does
not save the old working tree.

2.12 Optimizations

A protocol dissector may be called in 2 different ways - with, or
without a non-null "tree" argument.

If the proto_tree argument is null, Wireshark does not need to use
the protocol tree information from your dissector, and therefore is
passing the dissector a null "tree" argument so that it doesn't
need to do work necessary to build the protocol tree.

In the interest of speed, if "tree" is NULL, avoid building a
protocol tree and adding stuff to it, or even looking at any packet
data needed only if you're building the protocol tree, if possible.

Note, however, that you must fill in column information, create
conversations, reassemble packets, do calls to "expert" functions,
build any other persistent state needed for dissection, and call
subdissectors regardless of whether "tree" is NULL or not.

This might be inconvenient to do without doing most of the
dissection work; the routines for adding items to the protocol tree
can be passed a null protocol tree pointer, in which case they'll
return a null item pointer, and "proto_item_add_subtree()" returns
a null tree pointer if passed a null item pointer, so, if you're
careful not to dereference any null tree or item pointers, you can
accomplish this by doing all the dissection work. This might not
be as efficient as skipping that work if you're not building a
protocol tree, but if the code would have a lot of tests whether
"tree" is null if you skipped that work, you might still be better
off just doing all that work regardless of whether "tree" is null
or not.

Note also that there is no guarantee, the first time the dissector is
called, whether "tree" will be null or not; your dissector must work
correctly, building or updating whatever state information is
necessary, in either case.

/*
 * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 *
 * Local variables:
 * c-basic-offset: 4
 * tab-width: 8
 * indent-tabs-mode: nil
 * End:
 *
 * vi: set shiftwidth=4 tabstop=8 expandtab:
 * :indentSize=4:tabSize=8:noTabs=true:
 */

This file is a HOWTO for Wireshark developers. It describes how Wireshark
heuristic protocol dissectors work and how to write them.

This file is compiled to give in depth information on Wireshark.
It is by no means all inclusive and complete. Please feel free to send
remarks and patches to the developer mailing list.


Prerequisites
-------------
As this file is an addition to README.dissector, it is essential to read
and understand that document first.


Why heuristic dissectors?
-------------------------
When Wireshark "receives" a packet, it has to find the right dissector to
start decoding the packet data. Often this can be done by known conventions,
e.g. the Ethernet type 0x0800 means "IP on top of Ethernet" - an easy and
reliable match for Wireshark.

Unfortunately, these conventions are not always available, or (accidentally
or knowingly) some protocols don't care about those conventions and "reuse"
existing "magic numbers / tokens".

For example TCP defines port 80 only for the use of HTTP traffic. But, this
convention doesn't prevent anyone from using TCP port 80 for some different
protocol, or on the other hand using HTTP on a port number different than 80.

To solve this problem, Wireshark introduced the so called heuristic dissector
mechanism to try to deal with these problems.


How Wireshark uses heuristic dissectors?
----------------------------------------
While Wireshark starts, heuristic dissectors (HD) register themselves slightly
different than "normal" dissectors, e.g. a HD can ask for any TCP packet, as
it *may* contain interesting packet data for this dissector. In reality more
than one HD will exist for e.g. TCP packet data.

So if Wireshark has to decode TCP packet data, it will first try to find a
dissector registered directly for the TCP port used in that packet. If it
finds such a registered dissector it will just hand over the packet data to it.

In case there is no such "normal" dissector, WS will hand over the packet data
to the first matching HD. Now the HD will look into the data and decide if that
data looks like something the dissector "is interested in". The return value
signals WS if the HD processed the data (so WS can stop working on that packet)
or if the heuristic didn't match (so WS tries the next HD until one matches -
or the data simply can't be processed).

Note that it is possible to configure WS through preference settings so that it
hands off a packet to the heuristic dissectors before the "normal" dissectors
are called. This allows the HD the chance to receive packets and process them
differently than they otherwise would be. Of course if no HD is interested in
the packet, then the packet will ultimately get handed off to the "normal"
dissector as if the HD wasn't involved at all. As of this writing, the DCCP,
SCTP, TCP, TIPC and UDP dissectors all provide this capability via their
"Try heuristic sub-dissectors first" preference, but none of them have this
option enabled by default.

Once a packet for a particular "connection" has been identified as belonging
to a particular protocol, Wireshark must then be set up to always directly
call the dissector for that protocol. This removes the overhead of having
to identify each packet of the connection heuristically.


How do these heuristics work?
-----------------------------
It's difficult to give a general answer here. The usual heuristic works as follows:

A HD looks into the first few packet bytes and searches for common patterns that
are specific to the protocol in question. Most protocols starts with a
specific header, so a specific pattern may look like (synthetic example):

1) first byte must be 0x42
2) second byte is a type field and can only contain values between 0x20 - 0x33
3) third byte is a flag field, where the lower 4 bits always contain the value 0
4) fourth and fifth bytes contain a 16 bit length field, where the value can't
   be larger than 10000 bytes

So the heuristic dissector will check incoming packet data for all of the
4 above conditions, and only if all of the four conditions are true there is a
good chance that the packet really contains the expected protocol - and the
dissector continues to decode the packet data. If one condition fails, it's
very certainly not the protocol in question and the dissector returns to WS
immediately "this is not my protocol" - maybe some other heuristic dissector
is interested!

Obviously, this is *not* 100% bullet proof, but it's the best WS can offer to
its users here - and improving the heuristic is always possible if it turns out
that it's not good enough to distinguish between two given protocols.

Note: The heuristic code in a dissector *must not* cause an exception
      (before returning FALSE) as this will prevent following
      heuristic dissector handoffs. In practice, this normally means
      that a test must be done to verify that the required data is
      available in the tvb before fetching from the tvb. (See the
      example below).


Heuristic Code Example
----------------------
You can find a lot of code examples in the Wireshark sources, e.g.:
grep -l heur_dissector_add epan/dissectors/*.c
returns 177 files (October 2015).

For the above example criteria, the following code example might do the work
(combine this with the dissector skeleton in README.developer):

XXX - please note: The following code examples were not tried in reality,
please report problems to the dev-list!

--------------------------------------------------------------------------------------------

static dissector_handle_t PROTOABBREV_tcp_handle;
static dissector_handle_t PROTOABBREV_pdu_handle;

/* Heuristics test */
static gboolean
test_PROTOABBREV(packet_info *pinfo _U_, tvbuff_t *tvb, int offset _U_, void *data _U_)
{
    /* 0) Verify needed bytes available in tvb so tvb_get...() doesn't cause exception.
    if (tvb_captured_length(tvb) < 5)
        return FALSE;

    /* 1) first byte must be 0x42 */
    if ( tvb_get_guint8(tvb, 0) != 0x42 )
        return FALSE;

    /* 2) second byte is a type field and only can contain values between 0x20-0x33 */
    if ( tvb_get_guint8(tvb, 1) < 0x20 || tvb_get_guint8(tvb, 1) > 0x33 )
        return FALSE;

    /* 3) third byte is a flag field, where the lower 4 bits always contain the value 0 */
    if ( tvb_get_guint8(tvb, 2) & 0x0f )
        return FALSE;

    /* 4) fourth and fifth bytes contains a 16 bit length field, where the value can't be longer than 10000 bytes */
    /* Assumes network byte order */
    if ( tvb_get_ntohs(tvb, 3) > 10000 )
        return FALSE;

    /* Assume it's your packet ... */
    return TRUE;
}

/* Dissect the complete PROTOABBREV pdu */
static int
dissect_PROTOABBREV_pdu(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_)
{
    /* Dissection ... */

    return tvb_reported_length(tvb);
}

/* For tcp_dissect_pdus() */
static guint
get_PROTOABBREV_len(packet_info *pinfo _U_, tvbuff_t *tvb, int offset, void *data _U_)
{
    return (guint) tvb_get_ntohs(tvb, offset+3);
}

static int
dissect_PROTOABBREV_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
{
    tcp_dissect_pdus(tvb, pinfo, tree, TRUE, 5,
                     get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data);
    return tvb_reported_length(tvb);
}

static gboolean
dissect_PROTOABBREV_heur_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
{
    if (!test_PROTOABBREV(pinfo, tvb, 0, data))
        return FALSE;

    /* specify that dissect_PROTOABBREV is to be called directly from now on for
     * packets for this "connection" ... but only do this if your heuristic sits directly
     * on top of (was called by) a dissector which established a conversation for the
     * protocol "port type". In other words: only directly over TCP, UDP, DCCP, ...
     * otherwise you'll be overriding the dissector that called your heuristic dissector.
     */
    conversation = find_or_create_conversation(pinfo);
    conversation_set_dissector(conversation, PROTOABBREV_tcp_handle);

    /*   and do the dissection */
    dissect_PROTOABBREV_tcp(tvb, pinfo, tree, data);

    return (TRUE);
}

static int
dissect_PROTOABBREV_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
{
    udp_dissect_pdus(tvb, pinfo, tree, TRUE, 5, NULL,
                     get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data);
    return tvb_reported_length(tvb);
}

static gboolean
dissect_PROTOABBREV_heur_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
{
...
    /*   and do the dissection */
    return (udp_dissect_pdus(tvb, pinfo, tree, TRUE, 5, test_PROTOABBREV,
                     get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data) != 0);
}

void
proto_reg_handoff_PROTOABBREV(void)
{
    PROTOABBREV_tcp_handle = create_dissector_handle(dissect_PROTOABBREV_tcp,
                                                         proto_PROTOABBREV);
    PROTOABBREV_pdu_handle = create_dissector_handle(dissect_PROTOABBREV_pdu,
                                                         proto_PROTOABBREV);

    /* register as heuristic dissector for both TCP and UDP */
    heur_dissector_add("tcp", dissect_PROTOABBREV_heur_tcp, "PROTOABBREV over TCP",
                       "PROTOABBREV_tcp", proto_PROTOABBREV, HEURISTIC_ENABLE);
    heur_dissector_add("udp", dissect_PROTOABBREV_heur_udp, "PROTOABBREV over UDP",
                       "PROTOABBREV_udp", proto_PROTOABBREV, HEURISTIC_ENABLE);

#ifdef OPTIONAL
    /* It's possible to write a dissector to be a dual heuristic/normal dissector */
    /*  by also registering the dissector "normally".                             */
    dissector_add_uint("ip.proto", IP_PROTO_PROTOABBREV, PROTOABBREV_pdu_handle);
#endif
}


Please note, that registering a heuristic dissector is only possible for a
small variety of protocols. In most cases a heuristic is not needed, and
adding the support would only add unused code to the dissector.

TCP and UDP are prominent examples that support HDs, as there seems to be a
tendency to re-use known port numbers for new protocols. But TCP and UDP are
not the only dissectors that provide support for HDs.  You can find more
examples by searching the Wireshark sources as follows:
grep -l register_heur_dissector_list epan/dissectors/packet-*.c

Copyright (C) 2001 Frank Singleton <frank.singleton@ericsson.com>


What is it ?
============

As you have probably guessed from the name, "idl2wrs" takes a
user specified IDL file and attempts to build a dissector that
can decode the IDL traffic over GIOP. The resulting file is
"C" code that should compile okay as a Wireshark dissector.

idl2wrs basically parses the data struct given to it by
the omniidl compiler, and using the GIOP API available in packet-giop.[ch],
generates get_CDR_xxx calls to decode the CORBA traffic on the wire.

It consists of 4 main files.

README.idl2wrs     - This document
wireshark_be.py    - The main compiler backend
wireshark_gen.py   - A helper class that generates the C code.
idl2wrs            - A simple shell script wrapper that the end user should
                     use to generate the dissector from the IDL file(s).

Why did you do this ?
=====================

It is important to understand how CORBA traffic looks
like over GIOP/IIOP, and to help build a tool that can assist
in troubleshooting CORBA interworking. This was especially the
case after seeing a lot of discussions about how particular
IDL types are represented inside an octet stream.

I have also had comments/feedback that this tool would be good for say
a CORBA class when teaching students how CORBA traffic looks like
"on the wire".

It is also COOL to work on a great Open Source project such as
the case with "Wireshark" (https://www.wireshark.org)


How to use idl2wrs
==================

To use the idl2wrs to generate Wireshark dissectors, you
need the following.


1. Python must be installed
   http://python.org/

2. omniidl from the omniORB package must be available.
   http://omniorb.sourceforge.net/

3. Of course you need Wireshark installed to compile the
   code and tweak it if required. idl2wrs is part of the
   standard Wireshark distribution.


Procedure
=========

1.  To write the C code to stdout.

    idl2wrs  <your_file.idl>

    eg: idl2wrs echo.idl


2. To write to a file, just redirect the output.

    idl2wrs echo.idl > packet-test-idl.c

   You may wish to comment out the register_giop_user_module() code
   and that will leave you with heuristic dissection.


If you don't want to use the shell script wrapper, then try
steps 3 or 4 instead.

3.  To write the C code to stdout.

    Usage: omniidl  -p ./ -b wireshark_be <your_file.idl>

    eg: omniidl  -p ./ -b wireshark_be echo.idl


4. To write to a file, just redirect the output.

    omniidl  -p ./ -b wireshark_be echo.idl > packet-test-idl.c

   You may wish to comment out the register_giop_user_module() code
   and that will leave you with heuristic dissection.


5. Copy the resulting C code to your Wireshark src directory, edit the
   following file to include the packet-test-idl.c

   cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/
   cp /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt.example \
     /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt
   nano /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt


6. Run CMake

   cmake /dir/where/wireshark/lives


7. Compile the code

   make


8. Good Luck !!


TODO
====

1. Exception code not generated  (yet), but can be added manually.
2. Enums not converted to symbolic values (yet), but can be added manually.
3. Add command line options, etc.
4. More I am sure :-)


Limitations
===========

See TODO list inside packet-giop.c


Notes
=====

1. The "-p ./" option passed to omniidl indicates that the wireshark_be.py
   and wireshark_gen.py are residing in the current directory. This may need
   tweaking if you place these files somewhere else.

2. If it complains about being unable to find some modules (eg tempfile.py),
   you may want to check if PYTHONPATH is set correctly.
   On my Linux box, it is  PYTHONPATH=/usr/lib/python1.5/

Frank Singleton.

0. Plugins

There are a multitude of plugin options available in Wireshark that allow to
extend its functionality without changing the source code itself.  Using the
available APIs gives you the means to do this.

Currently plugin APIs are available for dissectors (epan), capture file types
(wiretap) and media decoders (codecs).  This README focuses primarily on
dissector plugins; most of the descriptions are applicable to the other plugin
types as well.

1. Dissector plugins

Writing a "plugin" dissector is not very different from writing a standard
one.  In fact all of the functions described in README.dissector can be
used in the plugins exactly as they are used in standard dissectors.

(Note, however, that not all OSes on which Wireshark runs can support
plugins.)

If you've chosen "foo" as the name of your plugin (typically, that would
be a short name for your protocol, in all lower case), the following
instructions tell you how to implement it as a plugin.  All occurrences
of "foo" below should be replaced by the name of your plugin.

2. The directory for the plugin, and its files

The plugin should be placed in a new plugins/epan/foo directory which should
contain at least the following files:

CMakeLists.txt
README

The README can be brief but it should provide essential information relevant
to developers and users. Optionally AUTHORS and ChangeLog files can be added.
Optionally you can add your own plugin.rc.in.

And of course the source and header files for your dissector.

Examples of these files can be found in plugins/epan/gryphon.

2.1 CMakeLists.txt

For your plugins/epan/foo/CMakeLists.txt file, see the corresponding file in
plugins/epan/gryphon.  Replace all occurrences of "gryphon" in those files
with "foo" and add your source files to the DISSECTOR_SRC variable.

2.2 plugin.rc.in

Your plugins/epan/foo/plugin.rc.in is the Windows resource template file used
to add the plugin specific information as resources to the DLL.
If not provided the plugins/plugin.rc.in file will be used.

3. Changes to existing Wireshark files

There are two ways to add your plugin dissector to the build, as a custom
extension or as a permanent addition.  The custom extension is easy to
configure, but won't be used for inclusion in the distribution if that's
your goal.  Setting up the permanent addition is somewhat more involved.

3.1 Custom extension

For CMake builds, either pass the custom plugin dir on the CMake generation
step command line:

CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/epan/foo"

or copy the top-level file CMakeListsCustom.txt.example to CMakeListsCustom.txt
(also in the top-level source dir) and edit so that CUSTOM_PLUGIN_SRC_DIR is
set() to the relative path of your plugin, e.g.

set(CUSTOM_PLUGIN_SRC_DIR plugins/epan/foo)

and re-run the CMake generation step.

To build the plugin, run your normal Wireshark build step.

If you want to add the plugin to your own Windows installer add a text
file named custom_plugins.txt to the packaging/nsis directory, with a
"File" statement for NSIS:

File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll"

3.2 Permanent addition

In order to be able to permanently add a plugin take the following steps.
You will need to change the following files:
	CMakeLists.txt
	packaging/nsis/wireshark.nsi

You might also want to search your Wireshark development directory for
occurrences of an existing plugin name, in case this document is out of
date with the current directory structure.  For example,

	grep -rl gryphon .

could be used from a shell prompt.

3.2.1  Changes to CMakeLists.txt

Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:

if(ENABLE_PLUGINS)
        ...
        set(PLUGIN_SRC_DIRS
                ...
                plugins/epan/ethercat
                plugins/epan/foo
                plugins/epan/gryphon
                plugins/epan/irda
                ...

3.2.2  Changes to the installers

If you want to include your plugin in an installer you have to add lines
in the NSIS installer wireshark.nsi file.

3.2.2.1  Changes to packaging/nsis/wireshark.nsi

Add the relative path of your plugin DLL (in alphabetical order) to the
list of "File" statements in the "Dissector Plugins" section:

File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\ethercat.dll"
File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll"
File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\gryphon.dll"
File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\irda.dll"

3.2.2.2  Other installers

The PortableApps installer copies plugins from the build directory
and should not require configuration.

4. Development and plugins on Unix

Plugins make some aspects of development easier and some harder.

The first thing is that you'll have to run cmake once more to setup your
build environment.

The good news is that if you are working on a single plugin then you will
find recompiling the plugin MUCH faster than recompiling a dissector and
then linking it back into Wireshark. Use "make plugins" to compile just
your plugins.

The bad news is that Wireshark will not use the plugins unless the plugins
are installed in one of the places it expects them to find.

One way of dealing with this problem is to set an environment variable
when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.

Another way to deal with this problem is to set up a working root for
wireshark, say in $HOME/build/root and build Wireshark to install
there

cmake -D CMAKE_INSTALL_PREFIX=${HOME}/build/root && make install

then subsequent rebuilds/installs of your plugin can be accomplished
by going to the plugins/foo directory and running

make install

5. Update "old style" plugins

5.1 How to update an "old style" plugin (since Wireshark 2.5)

Plugins need exactly four visible symbols: plugin_version, plugin_want_major,
plugin_want_minor and plugin_register. Each plugin is either a codec plugin,
libwiretap plugin or libwireshark plugin and the library will call
"plugin_register" after loading the plugin. "plugin_register" in turn calls all
the hooks necessary to enable the plugin. So if you had two function like so:

    WS_DLL_PUBLIC void plugin_register(void);
    WS_DLL_PUBLIC void plugin_reg_handoff(void);

    void plugin_register(void) {...};
    void plugin_reg_handoff(void) {...};

You'll have to rewrite it as:

    WS_DLL_PUBLIC void plugin_register(void);

    static void proto_register_foo(void) {...};
    static void proto_reg_handoff_foo(void) {...};

    void plugin_register(void)
    {
	static proto_plugin plugin_foo;

	plugin_foo.register_protoinfo = proto_register_foo;
	plugin_foo.register_handoff = proto_reg_handoff_foo;
	proto_register_plugin(&plugin_foo);
    }

See doc/plugins.example for an example.

5.2 How to update an "old style" plugin (using plugin_register and
    plugin_reg_handoff functions).

The plugin registration has changed with the extension of the build
scripts. These now generate the additional code needed for plugin
encapsulation in plugin.c. When using the new style build scripts,
strips the parts outlined below:

    o Remove the following include statements:

        #include <gmodule.h>
        #include "moduleinfo.h"

    o Removed the definition:

        #ifndef ENABLE_STATIC
        WS_DLL_PUBLIC_DEF gchar version[] = VERSION;
        #endif

    o Move relevant code from the blocks and delete these functions:

        #ifndef ENABLE_STATIC
        plugin_reg_handoff()
        ....
        #endif

        #ifndef ENABLE_STATIC
        plugin_register()
        ....
        #endif

This will leave a clean dissector source file without plugin specifics.

5.3 How to update an "old style" plugin (using plugin_init function)

The plugin registering has changed between 0.10.9 and 0.10.10; everyone
is encouraged to update their plugins as outlined below:

    o Remove following include statements from all plugin sources:

	#include "plugins/plugin_api.h"
	#include "plugins/plugin_api_defs.h"

    o Remove the init function.

6 How to plugin related interface options

To demonstrate the functionality of the plugin interface options, a
demonstration plugin exists (pluginifdemo). To build it using cmake, the
build option ENABLE_PLUGIN_IFDEMO has to be enabled.

6.1 Implement a plugin GUI menu

A plugin (as well as built-in dissectors) may implement a menu within
Wireshark to be used to trigger options, start tools, open Websites, ...

This menu structure is built using the plugin_if.h interface and its
corresponding functions.

The menu items all call a callback provided by the plugin, which takes
a pointer to the menuitem entry as data. This pointer may be used to
provide userdata to each entry. The pointer must utilize WS_DLL_PUBLIC_DEF
and has the following structure:

    WS_DLL_PUBLIC_DEF void
    menu_cb(ext_menubar_gui_type gui_type, gpointer gui_data,
            gpointer user_data _U_)
    {
        ... Do something ...
    }

The menu entries themselves are generated with the following code structure:

    ext_menu_t * ext_menu, *os_menu = NULL;

    ext_menu = ext_menubar_register_menu (
            <your_proto_item>, "Some Menu Entry", TRUE );
    ext_menubar_add_entry(ext_menu, "Test Entry 1",
            "This is a tooltip", menu_cb, <user_data>);
    ext_menubar_add_entry(ext_menu, "Test Entry 2",
            NULL, menu_cb, <user_data>);

    os_menu = ext_menubar_add_submenu(ext_menu, "Sub Menu" );
    ext_menubar_add_entry(os_menu, "Test Entry A",
            NULL, menu_cb, <user_data>);
    ext_menubar_add_entry(os_menu, "Test Entry B",
            NULL, menu_cb, <user_data>);

For a more detailed information, please refer to plugin_if.h

6.2 Implement interactions with the main interface

Due to memory constraints on most platforms, plugin functionality cannot be
called directly from a DLL context. Instead special functions will be used,
which will implement certain options for plugins to utilize.

The following methods exist so far:

	/* Applies the given filter string as display filter */
	WS_DLL_PUBLIC void plugin_if_apply_filter
		(const char * filter_string, gboolean force);

	/* Saves the given preference to the main preference storage */
	WS_DLL_PUBLIC void plugin_if_save_preference
		(const char * pref_module, const char * pref_key, const char * pref_value);

	/* Jumps to the given frame number */
	WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr);

6.3 Implement a plugin specific toolbar

A toolbar may be registered which allows implementing an interactive user
interaction with the main application. The toolbar is generated using the following
code:

    ext_toolbar_t * tb = ext_toolbar_register_toolbar("Plugin Interface Demo Toolbar");

This registers a toolbar, which will be shown underneath "View->Additional Toolbars" in
the main menu, as well as the popup action window when right-clicking on any other tool-
or menubar.

It behaves identically to the existing toolbars and can be hidden as well as defined to
appear specific to selected profiles. The name with which it is being shown is the given
name in this function call.

6.3.1 Register elements for the toolbar

To add items to the toolbar, 4 different types of elements do exist.

  * BOOLEAN - a checkbox to select / unselect
  * BUTTON - a button to click
  * STRING - a text field with validation options
  * SELECTOR - a dropdown selection field

To add an element to the toolbar, the following function is being used:

    ext_toolbar_add_entry( ext_toolbar_t * parent, ext_toolbar_item_t type, const gchar *label,
        const gchar *defvalue, const gchar *tooltip, gboolean capture_only, GList * value_list,
        gboolean is_required, const gchar * regex, ext_toolbar_action_cb callback, gpointer user_data)

    parent_bar - the parent toolbar for this entry, to be registered by ext_toolbar_register_toolbar
    name - the entry name (the internal used one) for the item, used to send updates to the element
    label - the entry label (the displayed name) for the item, visible to the user
    defvalue - the default value for the toolbar element
        - EXT_TOOLBAR_BOOLEAN - 1 is for a checked element, 0 is unchecked
        - EXT_TOOLBAR_STRING - Text already entered upon initial display
    tooltip - a tooltip to be displayed on mouse-over
    capture_only - entry is only active, if a capture is active
    callback - the action which will be invoked after the item is activated
    value_list - a non-null list of values created by ext_toolbar_add_val(), if the item type
        is EXT_TOOLBAR_SELECTOR
    valid_regex - a validation regular expression for EXT_TOOLBAR_STRING
    is_required - a zero entry for EXT_TOOLBAR_STRING is not allowed
    user_data - a user defined pointer, which will be added to the toolbar callback

In case of the toolbar type EXT_TOOLBAR_SELECTOR a value list has to be provided. This list
is generated using ext_toolbar_add_val():

    GList * entries = 0;
    entries = ext_toolbar_add_val(entries, "1", "ABCD", FALSE );
    entries = ext_toolbar_add_val(entries, "2", "EFG", FALSE );
    entries = ext_toolbar_add_val(entries, "3", "HIJ", TRUE );
    entries = ext_toolbar_add_val(entries, "4", "KLM", FALSE );

6.3.2 Callback for activation of an item

If an item has been activated, the provided callback is being triggered.

    void toolbar_cb(gpointer toolbar_item, gpointer item_data, gpointer user_data)

For EXT_TOOLBAR_BUTTON the callback is triggered upon a click on the button, for
EXT_TOOLBAR_BOOLEAN and EXT_TOOLBAR_SELECTOR the callback is triggered with every change
of the selection.

For EXT_TOOLBAR_STRING either the return key has to be hit or the apply button pressed.

The parameters of the callback are defined as follows:

    toolbar_item - an element of the type ext_toolbar_t * representing the item that has been
                   activated
    item_data - the data of the item during activation. The content depends on the item type:
         - EXT_TOOLBAR_BUTTON - the entry is null
         - EXT_TOOLBAR_BOOLEAN - the entry is 0 if the checkbox is unchecked and 1 if it is checked
         - EXT_TOOLBAR_STRING - a string representing the context of the textbox. Only valid strings
                   are being passed, it can be safely assumed, that an applied regular expression has
                   been checked.
         - EXT_TOOLBAR_SELECTOR - the value of the selected entry
    user_data - the data provided during element registration

6.3.3 Sending updates to the toolbar items

A plugin may send updates to the toolbar entry, using one of the following methods. The parameter
silent defines, if the registered toolbar callback is triggered by the update or not.

    void ext_toolbar_update_value(ext_toolbar_t * entry, gpointer data, gboolean silent)

    - EXT_TOOLBAR_BUTTON, EXT_TOOLBAR_STRING - the displayed text (on the button or in the textbox)
        are being changed, in that case data is expected to be a string
    - EXT_TOOLBAR_BOOLEAN - the checkbox value is being changed, to either 0 or 1, in both cases
        data is expected to be an integer sent by GINT_TO_POINTER(n)
    - EXT_TOOLBAR_SELECTOR - the display text to be changed. If no element exists with this text,
        nothing will happen

    void ext_toolbar_update_data(ext_toolbar_t * entry, gpointer data, gboolean silent)

    - EXT_TOOLBAR_SELECTOR - change the value list to the one provided with data. Attention! this
        does not change the list stored within the item just the one in the displayed combobox

    void ext_toolbar_update_data_by_index(ext_toolbar_t * entry, gpointer data, gpointer value,
        gboolean silent)

    - EXT_TOOLBAR_SELECTOR - change the display text for the entry with the provided value. Both
        data and value must be gchar * pointer.


----------------

Ed Warnicke <hagbard@physics.rutgers.edu>
Guy Harris <guy@alum.mit.edu>

Derived and expanded from the plugin section of README.developers
which was originally written by

James Coe <jammer@cin.net>
Gilbert Ramirez <gram@alumni.rice.edu>
Jeff Foster <jfoste@woodward.com>
Olivier Abad <oabad@cybercable.fr>
Laurent Deniel <laurent.deniel@free.fr>
Jaap Keuter <jaap.keuter@xs4all.nl>

#
# Wireshark/TShark Regression Testing
#
# This is a sample Makefile for regression testing of the
# Wireshark engine. These tests use that uses 'tshark -V' to analyze all
# the frames of a capture file.
#
# You should probably rename this file as 'Makefile' in a separate directory
# set aside for the sole purpose of regression testing. Two text files will
# be created for each capture file you test, so expect to have lots of files.
#
# Set TSHARK, CAPTURE_DIR, and CAPTURE_FILES to values appropriate for
# your system. Run 'make' to create the initial datasets. Type 'make accept'
# to accept those files as the reference set.
#
# After you make changes to TShark, run 'make regress'. This will re-run
# the tests and compare them against the accepted reference set of data.
# The comparison, which is just an invocation of 'diff -u' for the output
# of each trace file, will be put into a file called 'regress'. Examine
# this file for any changes that you did or did not expect.
#
# If you have introduced a change to TShark that shows up in the tests, but
# it is a valid change, run 'make accept' to accept those new data as your
# reference set.
#
# Commands:
#
# 'make'		Creates tests
# 'make regress'	Checks tests against accepted reference test results
#			Report is put in file 'regress'
# 'make accept'		Accept current tests; make them the reference test results
# 'make clean'		Cleans any tests (but not references!)

TSHARK=/home/gram/prj/wireshark/debug/linux-ix86/tshark

CAPTURE_DIR=/home/gram/prj/sniff

CAPTURE_FILES=\
	dhcp-g.tr1	\
	genbroad.snoop	\
	ipv6-ripng.gz	\
	ipx.pcap	\
	pcmjh03.tr1	\
	strange.iptrace	\
	teardrop.toshiba.gz	\
	zlip-1.pcap	\
	zlip-2.pcap	\
	zlip-3.pcap

######################################## No need to modify below this line

TESTS = $(CAPTURE_FILES:=.tether)
REFERENCES = $(TESTS:.tether=.ref)

all:	$(TESTS)

clean:
	rm -f $(TESTS)

%.tether : $(CAPTURE_DIR)/% $(TSHARK)
	$(TSHARK) -V -n -r $< > $@

accept: $(REFERENCES)

%.ref : %.tether
	mv $< $@

regress: $(TESTS)
	@echo "Regression Report" 			> regress
	@date						>> regress
	@echo "BOF------------------------------------"	>> regress
	@for file in $(CAPTURE_FILES); do \
		echo Checking regression of $$file ; \
		diff -u $${file}.ref $${file}.tether	>> regress ; \
	done
	@echo "EOF------------------------------------"	>> regress

1. Introduction

It is often useful to enhance dissectors for request/response style protocols
to match requests with responses.
This allows you to display useful information in the decode tree such as which
requests are matched to which response and the response time for individual
transactions.

This is also useful if you want to pass some data from the request onto the
dissection of the actual response. The RPC dissector for example does
something like this to pass the actual command opcode from the request onto
the response dissector since the opcode itself is not part of the response
packet and without the opcode we would not know how to decode the data.

It is also useful when you need to track information on a per conversation
basis such as when some parameters are negotiated during a login phase of the
protocol and when these parameters affect how future commands on that session
are to be decoded. The iSCSI dissector does something similar to that to track
which sessions that HeaderDigest is activated for and which ones it is not.

2. Implementation

The example below shows how simple this is to add to the dissector IF:
1. there is something like a transaction id in the header,
2. it is very unlikely that the transaction identifier is reused for the
   same conversation.

The example is taken from the PANA dissector:

First we need to include the definitions for conversations.

	#include <epan/conversation.h>

Then we also need a few header fields to show the relations between request
and response as well as the response time.

	static int hf_pana_response_in = -1;
	static int hf_pana_response_to = -1;
	static int hf_pana_response_time = -1;

We need a structure that holds all the information we need to remember
between the request and the responses. One such structure will be allocated
for each unique transaction.
In the example we only keep the frame numbers of the request and the response
as well as the timestamp for the request.
But since this structure is persistent and also a unique one is allocated for
each request/response pair, this is a good place to store other additional
data you may want to keep track of from a request to a response.

	typedef struct _pana_transaction_t {
	        guint32 req_frame;
	        guint32 rep_frame;
	        nstime_t req_time;
	} pana_transaction_t;

We also need a structure that holds persistent information for each
conversation. A conversation is identified by SRC/DST address, protocol and
SRC/DST port, see README.dissector, section 2.2.
In this case we only want to have a hash table to track the actual
transactions that occur for this unique conversation.
Some protocols negotiate session parameters during a login phase and those
parameters may affect how later commands on the same session is to be decoded,
this would be a good place to store that additional info you may want to keep
around.

	typedef struct _pana_conv_info_t {
	        wmem_map_t *pdus;
	} pana_conv_info_t;

Finally for the meat of it, add the conversation and tracking code to the
actual dissector.

	...
	guint32 seq_num;
	conversation_t *conversation;
	pana_conv_info_t *pana_info;
	pana_transaction_t *pana_trans;

	...
	/* Get the transaction identifier */
	seq_num = tvb_get_ntohl(tvb, 8);
	...

	/*
	 * We need to track some state for this protocol on a per conversation
	 * basis so we can do neat things like request/response tracking
	 */
	conversation = find_or_create_conversation(pinfo);

	/*
	 * Do we already have a state structure for this conv
	 */
	pana_info = (pana_conv_info_t *)conversation_get_proto_data(conversation, proto_pana);
	if (!pana_info) {
		/*
                 * No.  Attach that information to the conversation, and add
		 * it to the list of information structures.
		 */
		pana_info = wmem_new(wmem_file_scope(), pana_conv_info_t);
		pana_info->pdus=wmem_map_new(wmem_file_scope(), g_direct_hash, g_direct_equal);

		conversation_add_proto_data(conversation, proto_pana, pana_info);
	}
	if (!PINFO_FD_VISITED(pinfo)) {
		if (flags&PANA_FLAG_R) {
			/* This is a request */
			pana_trans=wmem_new(wmem_file_scope(), pana_transaction_t);
			pana_trans->req_frame = pinfo->num;
			pana_trans->rep_frame = 0;
			pana_trans->req_time = pinfo->fd->abs_ts;
			wmem_map_insert(pana_info->pdus, GUINT_TO_POINTER(seq_num), (void *)pana_trans);
		} else {
			pana_trans=(pana_transaction_t *)wmem_map_lookup(pana_info->pdus, GUINT_TO_POINTER(seq_num));
			if (pana_trans) {
				pana_trans->rep_frame = pinfo->num;
			}
		}
	} else {
		pana_trans=(pana_transaction_t *)wmem_map_lookup(pana_info->pdus, GUINT_TO_POINTER(seq_num));
	}
	if (!pana_trans) {
		/* create a "fake" pana_trans structure */
		pana_trans=wmem_new(pinfo->pool, pana_transaction_t);
		pana_trans->req_frame = 0;
		pana_trans->rep_frame = 0;
		pana_trans->req_time = pinfo->fd->abs_ts;
	}

	/* print state tracking in the tree */
	if (flags&PANA_FLAG_R) {
		/* This is a request */
		if (pana_trans->rep_frame) {
			proto_item *it;

			it = proto_tree_add_uint(pana_tree, hf_pana_response_in,
					tvb, 0, 0, pana_trans->rep_frame);
			proto_item_set_generated(it);
		}
	} else {
		/* This is a reply */
		if (pana_trans->req_frame) {
			proto_item *it;
			nstime_t ns;

			it = proto_tree_add_uint(pana_tree, hf_pana_response_to,
					tvb, 0, 0, pana_trans->req_frame);
			proto_item_set_generated(it);

			nstime_delta(&ns, &pinfo->fd->abs_ts, &pana_trans->req_time);
			it = proto_tree_add_time(pana_tree, hf_pana_response_time, tvb, 0, 0, &ns);
			proto_item_set_generated(it);
		}
	}

Then we just need to declare the hf fields we used.

	{ &hf_pana_response_in,
		{ "Response In", "pana.response_in",
		FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_RESPONSE), 0x0,
		"The response to this PANA request is in this frame", HFILL }
	},
	{ &hf_pana_response_to,
		{ "Request In", "pana.response_to",
		FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_REQUEST), 0x0,
		"This is a response to the PANA request in this frame", HFILL }
	},
	{ &hf_pana_response_time,
		{ "Response Time", "pana.response_time",
		FT_RELATIVE_TIME, BASE_NONE, NULL, 0x0,
		"The time between the Call and the Reply", HFILL }
	},

tapping with stats_tree

Let's suppose that you want to write a tap only to keep counters, and you
don't want to get involved with GUI programming or maybe you'd like to make
it a plugin. A stats_tree might be the way to go. The stats_tree module takes
care of the representation (GUI for Wireshark and text for TShark) of the
tap data. So there's very little code to write to make a tap listener usable
from both Wireshark and TShark.

First, you should add the TAP to the dissector in question as described in
README.tapping .

Once the dissector in question is "tapped" you have to write the stats tree
code which is made of three parts:

The init callback routine:
   which will be executed before any packet is passed to the tap. Here you
   should create the "static" nodes of your tree. As well as initialize your
   data.

The (per)packet callback routine:
   As the tap_packet callback is going to be called for every packet, it
   should be used to increment the counters.

The cleanup callback:
   It is called at the destruction of the stats_tree and might be used to
   free ....

Other than that the stats_tree should be registered.

If you want to make it a plugin, stats_tree_register() should be called by
plugin_register_tap_listener() read README.plugins for other information
regarding Wireshark plugins.

If you want it as part of the dissector stats_tree_register() can be called
either by proto_register_xxx() or if you prefer by proto_reg_handoff_xxx().


A small example of a very basic stats_tree plugin follows.

----- example stats_tree plugin ------
/* udpterm_stats_tree.c
 * A small example of stats_tree plugin that counts udp packets by termination
 * 2005, Luis E. G. Ontanon
 *
 * Wireshark - Network traffic analyzer
 * By Gerald Combs <gerald@wireshark.org>
 * Copyright 1998 Gerald Combs
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#include "config.h"

#include <gmodule.h>

#include <epan/stats_tree.h>
#include <epan/dissectors/udp.h>

static int st_udp_term;
static gchar* st_str_udp_term = "UDP terminations";

/* this one initializes the tree, creating the root nodes */
extern void udp_term_stats_tree_init(stats_tree* st) {
	/* we create a node under which we'll add every termination */
	st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, TRUE);
}

/* this one will be called with every udp packet */
extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */
                                      packet_info *pinfo,  /* we'll fetch the addresses from here */
                                      epan_dissect_t *edt _U_, /* unused */
                                      const void *p) /* we'll use this to fetch the ports */
{
	static guint8 str[128];
	e_udphdr* udphdr = (e_udphdr*) p;

	/* we increment by one (tick) the root node */
	tick_stat_node(st, st_str_udp_term, 0, FALSE);

	/* we then tick a node for this src_addr:src_port
	   if the node doesn't exists it will be created */
	g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport);
	tick_stat_node(st, str, st_udp_term, FALSE);

	/* same thing for dst */
	g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport);
	tick_stat_node(st, str, st_udp_term, FALSE);

	return 1;
}

WS_DLL_PUBLIC_DEF const gchar version[] = "0.0";

WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) {

    stats_tree_register_plugin("udp", /* the proto we are going to "tap" */
                               "udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */
                               st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/
                               0, /* tap listener flags for per-packet callback */
                               udp_term_stats_tree_packet, /* the per packet callback */
                               udp_term_stats_tree_init, /* the init callback */
                               NULL ); /* the cleanup callback (in this case there isn't) */

}

----- END ------

the stats_tree API
==================
 every stats_tree callback has a stats_tree* parameter (st), stats_tree is an obscure
 data structure which should be passed to the api functions.

stats_tree_register(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
 registers a new stats tree

stats_tree_register_plugin(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
 registers a new stats tree from a plugin

stats_tree_parent_id_by_name( st, parent_name)
  returns the id of a candidate parent node given its name


Node functions
==============

All the functions that operate on nodes return a parent_id

stats_tree_create_node(st, name, parent_id, with_children)
  Creates a node in the tree (to be used in the in init_cb)
    name: the name of the new node
    parent_id: the id of the parent_node (NULL for root)
    with_children: TRUE if this node will have "dynamically created" children
                   (i.e. it will be a candidate parent)


stats_tree_create_node_by_pname(st, name, parent_name, with_children);
  As before but creates a node using its parent's name


stats_tree_create_range_node(st, name, parent_id, ...)
stats_tree_create_range_node_string(st, name, parent_id, num_str_ranges, str_ranges)
stats_tree_range_node_with_pname(st, name, parent_name, ...)
  Creates a node in the tree, that will contain a ranges list.
    example:
       stats_tree_create_range_node(st,name,parent_id,
				"-99","100-199","200-299","300-399","400-", NULL);

stats_tree_tick_range( st, name,  parent_id, value_in_range);
stats_tree_tick_range_by_pname(st,name,parent_name,value_in_range)
   Increases by one the ranged node and the sub node to whose range the value belongs


stats_tree_create_pivot(st, name, parent_id);
stats_tree_create_pivot_by_pname(st, name, parent_name);
  Creates a "pivot node"

stats_tree_tick_pivot(st, pivot_id, pivoted_string);
 Each time a pivot node will be ticked it will get increased, and, it will
 increase (or create) the children named as pivoted_string


the following will either increase or create a node (with value 1) when called

tick_stat_node(st,name,parent_id,with_children)
increases by one a stat_node

increase_stat_node(st,name,parent_id,with_children,value)
increases by value a stat_node

set_stat_node(st,name,parent_id,with_children,value)
sets the value of a stat_node

zero_stat_node(st,name,parent_id,with_children)
resets to zero a stat_node

Averages work by tracking both the number of items added to node (the ticking
action) and the value of each item added to the node. This is done
automatically for ranged nodes; for other node types you need to call one of
the functions below to associate item values with each tick.

avg_stat_node_add_value_notick(st,name,parent_id,with_children,value)
avg_stat_node_add_value(st,name,parent_id,with_children,value)

The difference between the above functions is whether the item count is
increased or not. To properly compute the average you need to either call
avg_stat_node_add_value or avg_stat_node_add_value_notick combined
tick_stat_node. The later sequence allows for plug-ins which are compatible
with older Wireshark versions which ignores avg_stat_node_add_value because
it does not understand the command. This would result in 0 counts for all
nodes. It is preferred to use avg_stat_node_add_value if you are not writing
a plug-in.

avg_stat_node_add_value is used the same way as tick_stat_node with the
exception that you now specify an additional value associated with the tick.

Do not mix increase_stat_node, set_stat_node or zero_stat_node
with avg_stat_node_add_value as this will lead to incorrect results for the
average value.

stats_tree now also support setting flags per node to control the behaviour
of these nodes. This can be done using the stat_node_set_flags and
stat_node_clear_flags functions. Currently these flags are defined:

	ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are
			automatically expanded in the GUI. Setting this flag on
			such a node	prevents the node from automatically expanding.
	ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes
			without this flag (in effect partitioning tree into a top and
			bottom half. Each half is sorted normally. Top always appear
			first :)

You can find more examples of these in $srcdir/plugins/epan/stats_tree/pinfo_stats_tree.c

Luis E. G. Ontanon.

The TAP system in Wireshark is a powerful and flexible mechanism to get event
driven notification on packets matching certain protocols and/or filters.
In order to use the tapping system, very little knowledge of Wireshark
internals are required.

As examples on how to use the tap system see the implementation of
tap-rpcprogs.c (tshark version)
ui/qt/rpc_service_response_time_dialog.cpp (wireshark version)

If all you need is to keep some counters, there's the stats_tree API,
which offers a simple way to make a GUI and tshark tap-listener; see
README.stats_tree.  However, keep reading, as you'll need much of what's
in this document.

The tap system consists of two parts:
1, code in the actual dissectors to allow tapping data from that particular
protocol dissector, and
2, event driven code in an extension such as tap-rpcstat.c that registers
a tap listener and processes received data.

So you want to hack together a tap application?

TAP
===
First you must decide which protocol you are interested in writing a tap
application for and check if that protocol has already got a tap installed
in it.
If it already has a tap device installed then you don't have to do anything.
If not, then you have to add a tap but don't worry, this is extremely easy to
do and is done in four easy steps;
(see packet-rpc.c and search for tap for an example)

1, We need tap.h so just add '#include "tap.h"' (preceded by packet.h) to
the includes.

2, We need a tap handler so just add 'static int <protocol>_tap = -1;'

3, Down in proto_register_<protocol>() you need to add
'<protocol>_tap = register_tap("<protocol>");'

4, In the actual dissector for that protocol, after any child dissectors
have returned, just add 'tap_queue_packet(<protocol>_tap, pinfo, <pointer>);'

<pointer> is used if the tap has any special additional data to provide to the
tap listeners. What this points to is dependent on the protocol that is tapped,
or if there are no useful extra data to provide just specify NULL.  For
packet-rpc.c what we specify there is the persistent structure 'rpc_call' which
contains lots of useful information from the rpc layer that a listener might
need.



TAP LISTENER
============
(see tap-rpcprogs.c as an example)
Interfacing your application is not that much harder either.
Only 4 callbacks and two functions.

The two functions to start or stop tapping are

register_tap_listener(const char *tapname, void *tapdata, const char *fstring,
	guint flags,
	void (*reset)(void *tapdata),
        tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data),
	void (*draw)(void *tapdata),
	void (*finish)(void *tapdata));

This function is used to register an instance of a tap application
to the tap system.

remove_tap_listener(void *tapdata);

This function is used to deregister and stop a tap listener.

The parameters have the following meanings:

*tapname
is the name of the tap we want to listen to. I.e. the name used in
step 3 above.

*tapdata
is the instance identifier. The tap system uses the value of this
pointer to distinguish between different instances of a tap.
Just make sure that it is unique by letting it be the pointer to a struct
holding all state variables. If you want to allow multiple concurrent
instances, just put ALL state variables inside a struct allocated by
g_malloc() and use that pointer.
(tap-rpcstat.c use this technique to allow multiple simultaneous instances)

*fstring
is a pointer to a filter string.
If this is NULL, then the tap system will provide ALL packets passing the
tapped protocol to your listener.
If you specify a filter string here the tap system will first try
to apply this string to the packet and then only pass those packets that
matched the filter to your listener.
The syntax for the filter string is identical to normal display filters.

NOTE: Specifying filter strings will have a significant performance impact
on your application and Wireshark. If possible it is MUCH better to take
unfiltered data and just filter it yourself in the packet-callback than
to specify a filter string.
ONLY use a filter string if no other option exist.

flags
is a set of flags for the tap listener.  The flags that can be set are:

    TL_REQUIRES_PROTO_TREE

	set if your tap listener "packet" routine requires a protocol
	tree to be built.  It will require a protocol tree to be
	built if either

		1) it looks at the protocol tree in edt->tree

	or

		2) the tap-specific data passed to it is constructed only if
		   the protocol tree is being built.

    TL_REQUIRES_COLUMNS

	set if your tap listener "packet" routine requires the column
	strings to be constructed.

    If no flags are needed, use TL_REQUIRES_NOTHING.

void (*reset)(void *tapdata)
This callback is called whenever Wireshark wants to inform your
listener that it is about to start [re]reading a capture file or a new capture
from an interface and that your application should reset any state it has
in the *tapdata instance.

tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data)
This callback is used whenever a new packet has arrived at the tap and that
it has passed the filter (if there were a filter).
The *data structure type is specific to each tap.
This function returns a tap_packet_status enum and it should return
 TAP_PACKET_REDRAW, if the data in the packet caused state to be updated
       (and thus a redraw of the window would later be required)
 TAP_PACKET_DONT_REDRAW, if we don't need to redraw the window
 TAP_PACKET_FAILED, if the tap failed and shouldn't be called again
       in this pass (for example, if it's writing to a file and gets
       an I/O error)
NOTE: that (*packet) should be as fast and efficient as possible. Use this
function ONLY to store data for later and do the CPU-intensive processing
or GUI updates down in (*draw) instead.


void (*draw)(void *tapdata)
This callback is used when Wireshark wants your application to redraw its
output. It will usually not be called unless your application has received
new data through the (*packet) callback.
On some ports of Wireshark (Qt) (*draw) will be called asynchronously
from a separate thread up to once every 2-3 seconds.
On other ports it might only be called once when the capture is finished
or the file has been [re]read completely.

void (*finish)(void *tapdata)
This callback is called when your listener is removed.


So, create four callbacks:
1, reset   to reset the state variables in the structure passed to it.
2, packet  to update these state variables.
3, draw    to take these state variables and draw them on the screen.
4, finish  to free all state variables.

then just make Wireshark call register_tap_listener() when you want to tap
and call remove_tap_listener() when you are finished.


WHEN DO TAP LISTENERS GET CALLED?
===================================
Tap listeners are only called when Wireshark reads a new capture for
the first time or whenever Wireshark needs to rescan/redissect
the capture.
Redissection occurs when you apply a new display filter or if you
change and Save/Apply a preference setting that might affect how
packets are dissected.
After each individual packet has been completely dissected and all
dissectors have returned, all the tap listeners that have been flagged
to receive tap data during the dissection of the frame will be called in
sequence.
The order in which the tap listeners will be called is not defined.
Not until all tap listeners for the frame has been called and returned
will Wireshark continue to dissect the next packet.
This is why it is important to make the *_packet() callbacks execute as
quickly as possible, else we create an extra delay until the next packet
is dissected.

Keep in mind though: for some protocols, such as IP, the protocol can
appear multiple times in different layers inside the same packet.
For example, IP encapsulated over IP which will call the ip dissector
twice for the same packet.
IF the tap is going to return private data using the last parameter to
tap_queue_packet() and IF the protocol can appear multiple times inside the
same packet, you will have to make sure that each instance of
tap_queue_packet() is using its own instance of private struct variable
so they don't overwrite each other.

See packet-ip.c which has a simple solution to the problem. It creates
a unique instance of the IP header using wmem_alloc().
Previous versions used a static struct of 4 instances of the IP header
struct and cycled through them each time the dissector was called. (4
was just a number taken out of the blue but it should be enough for most
cases.) This would fail if there were more than 4 IP headers in the same
packet, but that was unlikely.


TIPS
====
Of course, there is nothing that forces you to make (*draw) draw stuff
on the screen.
You can hand register_tap_listener() NULL for (*draw), (*reset) and (*finish)
(well also for (*packet) but that would be a very boring extension).

Perhaps you want an extension that will execute a certain command
every time it sees a certain packet?
Well, try this :
	tap_packet_status packet(void *tapdata,...) {
		...
		system("mail ...");
		return TAP_PACKET_DONT_REDRAW;
	}

	register_tap_listener("tcp", struct, "tcp.port==57", NULL, packet, NULL, NULL);

	Let struct contain an email address?
	Then you have something simple that will make Wireshark send an email
	out automagically for each and every time it dissects
	a packet containing TCP traffic to port 57.
	Please put in some rate limitation if you do this.

	Let struct contain a command line and make (*packet) execute it?
	The possibilities are rather large.

See tap.c as well. It contains lots of comments and descriptions on the tap
system.

1. Introduction

Vagrant is a virtual machine management program that makes it trivial to build
and configure reproducible virtual machines. Wireshark's source code includes
a Vagrantfile which can be used to set up a complete development environments
in a virtual machine, including all necessary compilers, dependent libraries,
and tools like valgrind.

Using vagrant can greatly simplify the creation of a Linux build environment
for new developers, at the cost of running your builds in a virtual machine,
thus with reduced performance.

2. Installation

The Vagrantfile included in Wireshark's source directory is configured to use
VirtualBox as the backing virtual machine technology provider. You must first
install VirtualBox from https://www.virtualbox.org/.

Now install vagrant itself from https://www.vagrantup.com/.

Please note that vagrant is a CLI command and should typically be installed in
your host system's $PATH. To better understand what vagrant is doing you may
want to review vagrant's `Getting Started` web pages.

3. Setup

By default vagrant looks for the file name Vagrantfile in the current
directory. Wireshark's Vagrantfile is located in the root of the Wireshark
source folder.

Once both VirtualBox and vagrant are installed, setting up an Ubuntu Wireshark
development VM is as simple as running `vagrant up ubuntu`.

The first time that the `vagrant up` command is executed vagrant will initiate
the download of a specific VM image (what they call a box) from HashiCorp's
Atlas box catalog. Once the box is downloaded a VM will be instantiated and
powered-on.

Use the command `vagrant status` to determine the state of the VMs.

The command `vagrant provision` will run any provisioning tasks defined in the
Vagrantfile. Wireshark's Vagrantfile is configured to provision the machine
and build the project using vagrant_build.sh.

The vagrant_build.sh script sets up a cmake
build environment which includes creating a ~/build folder initialized for an
out-of-tree cmake build and then triggering a build.

4. Usage

Running `vagrant ssh ubuntu` from the Wireshark source directory will log you
into Ubuntu VM as the userid vagrant.

The Ubuntu VM's build folder is located in ~/build. The Ubuntu VM's source
folder is actually the source folder from the host system mounted as
/home/vagrant/wireshark. Any changes made in the VM's ~/wireshark folder are
reflected in the host system's Wireshark source folder and vice-versa.

Installing the vagrant-vbguest plugin is strongly recommended to get synced
folders working on all boxes and other niceties. You can install it with the
command `vagrant plugin install vagrant-vbguest`.

Once logged into the VM issue the command `cd ~/build` followed by `make` to
trigger a new wireshark build based on whatever is in your host system's source
tree (the VM's ~/wireshark folder).

The various Wireshark applications can be run from the ~/build folder of the
VM with commands such as `./run/wireshark`, `./run/tshark`, etc.

To run the Wireshark GUI you will need an X server and the X authority file
utility (xauth) installed in the guest. For Ubuntu use `apt-get install xauth`,
Fedora use `dnf install xorg-x11-xauth`.

If you are using macOS ({Mac} OS X) as the host system then you would likely
use XQuartz as your X server. XQuartz can be downloaded from
https://www.xquartz.org/.

The VM can be shutdown or suspended from the host system with the
commands `vagrant halt` and `vagrant suspend` respectively. In either case the
VM can be brought back up with the command `vagrant up`.

5. Using Vagrant with multiple VMs
Wireshark's Vagrantfile is configured with more than one box so most vagrant
commands, those that apply to machines, need to be provided with the machine
name. You can list all machines and their state with the `vagrant status`
command.