Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 3723 insertions, 0 deletions

diff --git a/doc/README.dissector b/doc/README.dissector
new file mode 100644
index 00000000..464bba49
--- /dev/null
+++ b/doc/README.dissector
@@ -0,0 +1,3723 @@
+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 discuss on
+the developer mailing list or upload merge requests to gitlab.
+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:
+
+- doc/README.heuristic      - what are heuristic dissectors and how to write them
+- doc/README.plugins        - how to "pluginize" a dissector
+- doc/README.request_response_tracking - how to track req./resp. times and such
+- doc/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.
+PROTOFILTERNAME A name for the protocol for use in filter expressions;
+                it may contain only letters, digits, hyphens, underscores and
+                periods. Names should use lower case only. (Support for
+                upper/mixed case may be removed in the future.)
+PROTOABBREV     An abbreviation for the protocol; this is used in code and
+                must be a valid C identifier. Additionally it should follow
+                any applicable C style guidelines. It is usually the same as
+                PROTOFILTERNAME with all lower-case letters and
+                non-alphanumerics replaced with underscores.
+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.
+FIELDFILTERNAME A name for the header field for use in filter expressions;
+                it may contain only letters, digits, hyphens, underscores and
+                periods. It must start with PROTOFILTERNAME followed by a dot.
+                Names should use lower case only. (Support for upper/mixed case
+                may be removed in the future.)
+FIELDABBREV     An abbreviation for the header field; this is used in code and
+                must be a valid C identifier. Additionally it should follow
+                any applicable C style guidelines. It is usually the same as
+                FIELDFILTERNAME with all lower-case letters and
+                non-alphanumerics replaced with underscores.
+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_IEEE_11073_SFLOAT, FT_IEEE_11073_FLOAT,
+                FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME, FT_RELATIVE_TIME,
+                FT_STRING, FT_STRINGZ, FT_STRINGZPAD, FT_STRINGZTRUNC,
+                FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4,
+                FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_EUI64, FT_GUID,
+                FT_OID, FT_REL_OID, FT_AX25, FT_VINES, FT_SYSTEM_ID, 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, BASE_SHOW_ASCII_PRINTABLE, or
+                  BASE_SHOW_UTF_8_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_FLOAT, FT_DOUBLE:
+                  BASE_NONE, BASE_DEC, BASE_HEX, BASE_EXP or BASE_CUSTOM.
+
+                  BASE_NONE uses BASE_DEC or BASE_EXP, similarly to the
+                  %g double format for the printf() function.
+
+                --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:
+
+                  (must be) BASE_NONE
+
+                --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,
+                  BASE_SHOW_ASCII_PRINTABLE, or BASE_SHOW_UTF_8_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.
+                  BASE_SHOW_UTF_8_PRINTABLE will check whether the
+                  field's value is valid UTF-8 consisting entirely of
+                  printable 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 PROTOFILTERNAME 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:
+
+uint8_t tvb_get_bits8(tvbuff_t *tvb, int bit_offset, const int no_of_bits);
+uint16_t tvb_get_bits16(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding);
+uint32_t tvb_get_bits32(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding);
+uint64_t tvb_get_bits64(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding);
+
+Single-byte accessors for 8-bit unsigned integers (uint8_t) and 8-bit
+signed integers (int8_t):
+
+uint8_t tvb_get_guint8(tvbuff_t *tvb, const int offset);
+int8_t tvb_get_gint8(tvbuff_t *tvb, const int offset);
+
+Network-to-host-order accessors:
+
+16-bit unsigned (uint16_t) and signed (int16_t) integers:
+
+uint16_t tvb_get_ntohs(tvbuff_t *tvb, const int offset);
+int16_t tvb_get_ntohis(tvbuff_t *tvb, const int offset);
+
+24-bit unsigned and signed integers:
+
+uint32_t tvb_get_ntoh24(tvbuff_t *tvb, const int offset);
+int32_t tvb_get_ntohi24(tvbuff_t *tvb, const int offset);
+
+32-bit unsigned (uint32_t) and signed (int32_t) integers:
+
+uint32_t tvb_get_ntohl(tvbuff_t *tvb, const int offset);
+int32_t tvb_get_ntohil(tvbuff_t *tvb, const int offset);
+
+40-bit unsigned and signed integers:
+
+uint64_t tvb_get_ntoh40(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_ntohi40(tvbuff_t *tvb, const int offset);
+
+48-bit unsigned and signed integers:
+
+uint64_t tvb_get_ntoh48(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_ntohi48(tvbuff_t *tvb, const int offset);
+
+56-bit unsigned and signed integers:
+
+uint64_t tvb_get_ntoh56(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_ntohi56(tvbuff_t *tvb, const int offset);
+
+64-bit unsigned (uint64_t) and signed (int64_t) integers:
+
+uint64_t tvb_get_ntoh64(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_ntohi64(tvbuff_t *tvb, const int offset);
+
+Single-precision and double-precision IEEE floating-point numbers:
+
+float tvb_get_ntohieee_float(tvbuff_t *tvb, const int offset);
+double tvb_get_ntohieee_double(tvbuff_t *tvb, const int offset);
+
+Little-Endian-to-host-order accessors:
+
+16-bit unsigned (uint16_t) and signed (int16_t) integers:
+
+uint16_t tvb_get_letohs(tvbuff_t *tvb, const int offset);
+int16_t tvb_get_letohis(tvbuff_t *tvb, const int offset);
+
+24-bit unsigned and signed integers:
+
+uint32_t tvb_get_letoh24(tvbuff_t *tvb, const int offset);
+int32_t tvb_get_letohi24(tvbuff_t *tvb, const int offset);
+
+32-bit unsigned (uint32_t) and signed (int32_t) integers:
+
+uint32_t tvb_get_letohl(tvbuff_t *tvb, const int offset);
+int32_t tvb_get_letohil(tvbuff_t *tvb, const int offset);
+
+40-bit unsigned and signed integers:
+
+uint64_t tvb_get_letoh40(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_letohi40(tvbuff_t *tvb, const int offset);
+
+48-bit unsigned and signed integers:
+
+uint64_t tvb_get_letoh48(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_letohi48(tvbuff_t *tvb, const int offset);
+
+56-bit unsigned and signed integers:
+
+uint64_t tvb_get_letoh56(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_letohi56(tvbuff_t *tvb, const int offset);
+
+64-bit unsigned (uint64_t) and signed (int64_t) integers:
+
+uint64_t tvb_get_letoh64(tvbuff_t *tvb, const int offset);
+int64_t tvb_get_letohi64(tvbuff_t *tvb, const int 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 unsigned for 32-bit
+and smaller types, and int64_t or uint64_t 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:
+
+float tvb_get_letohieee_float(tvbuff_t *tvb, const int offset);
+double tvb_get_letohieee_double(tvbuff_t *tvb, const int offset);
+
+Encoding-to_host-order accessors:
+
+16-bit unsigned (uint16_t) and signed (int16_t) integers:
+
+uint16_t tvb_get_guint16(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int16_t tvb_get_gint16(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+24-bit unsigned and signed integers:
+
+uint32_t tvb_get_guint24(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int32_t tvb_get_gint24(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+32-bit unsigned (uint32_t) and signed (int32_t) integers:
+
+uint32_t tvb_get_guint32(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int32_t tvb_get_gint32(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+40-bit unsigned and signed integers:
+
+uint64_t tvb_get_guint40(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int64_t tvb_get_gint40(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+48-bit unsigned and signed integers:
+
+uint64_t tvb_get_guint48(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int64_t tvb_get_gint48(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+56-bit unsigned and signed integers:
+
+uint64_t tvb_get_guint56(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int64_t tvb_get_gint56(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+64-bit unsigned (uint64_t) and signed (int64_t) integers:
+
+uint64_t tvb_get_guint64(tvbuff_t *tvb, const int offset, const unsigned encoding);
+int64_t tvb_get_gint64(tvbuff_t *tvb, const int offset, const unsigned encoding);
+
+Single-precision and double-precision IEEE floating-point numbers:
+
+float tvb_get_ieee_float(tvbuff_t *tvb, const int offset, const unsigned encoding);
+double tvb_get_ieee_double(tvbuff_t *tvb, const int offset, const unsigned 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:
+
+uint32_t tvb_get_ipv4(tvbuff_t *tvb, const int offset);
+void tvb_get_ipv6(tvbuff_t *tvb, const int 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.
+
+char *tvb_ip_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset)
+char *tvb_ip6_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int 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 int offset, e_guid_t *guid);
+void tvb_get_letohguid(tvbuff_t *tvb, const int offset, e_guid_t *guid);
+void tvb_get_guid(tvbuff_t *tvb, const int offset, e_guid_t *guid, const unsigned encoding);
+
+String accessors:
+
+uint8_t *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, const int length, const unsigned 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).
+
+uint8_t *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, int *lengthp, const unsigned 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).
+
+int tvb_get_nstringz(tvbuff_t *tvb, const int offset, const unsigned bufsize, uint8_t* buffer);
+int tvb_get_nstringz0(tvbuff_t *tvb, const int offset, const unsigned bufsize, uint8_t* 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.
+
+char *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvbuff_t *tvb,
+                                      const int bit_offset, int 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:
+
+char *tvb_bytes_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, const int 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.
+
+char *tvb_bytes_to_str_punct(wmem_allocator_t *scope, tvbuff_t *tvb,
+                              const int offset, const int len, const char 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 int offset, const int length,
+                                 const unsigned encoding, GByteArray* bytes, int *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.
+
+char *tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const int offset, const int len, dgt_set_t *dgt, bool 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 int 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 int 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 uint8_t* tvb_get_ptr(tvbuff_t *tvb, const int offset, const int 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:
+
+    unsigned tvb_captured_length(const tvbuff_t *tvb);
+
+Get reported length of buffer:
+
+    unsigned 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 "PROTOFILTERNAME":
+
+    col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOFILTERNAME");
+
+
+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;
+    uint64_t        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 (FIELDFILTERNAME)
+--------------------
+A string with a filter name for the field. The name should start
+with the filter name 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 a filter name. 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 names
+follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc.
+It must be a non-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_IEEE_11073_SFLOAT    A 16-bit floating point number, consisting
+                of an 4-bit exponent and 12-bit mantissa.
+    FT_IEEE_11073_FLOAT     A 32-bit floating point number, consisting
+                of an 8-bit exponent and 24-bit mantissa.
+    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(char *, uint32_t);
+
+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(char *, uint64_t);
+
+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 {
+        uint32_t value;
+        char    *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 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 uint64_t (instead of uint32_t). 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 uint64_t (instead of uint32_t).
+
+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.)
+
+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
+'&unitname'. Furthermore, the 'display' field must be ORed
+with 'BASE_UNIT_STRING' (e.g. BASE_DEC|BASE_UNIT_STRING).
+
+There are several "common" unit name structures already defined in
+epan/unit_strings.h, e.g. 'units_second_seconds'. Dissector authors may choose
+to add the unit name structure there rather than locally in a dissector.
+
+-- 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 {
+                uint32_t       value_min;
+                uint32_t       value_max;
+                const char    *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.
+
+-- Frame numbers
+FT_FRAMENUMs can use the 'strings' field to indicate their purpose by
+setting the field to 'FRAMENUM_TYPE(x)', where x is one of the values of
+the ft_framenum_type enum:
+
+    FT_FRAMENUM_NONE
+    FT_FRAMENUM_REQUEST
+    FT_FRAMENUM_RESPONSE
+    FT_FRAMENUM_ACK
+    FT_FRAMENUM_DUP_ACK
+    FT_FRAMENUM_RETRANS_PREV
+    FT_FRAMENUM_RETRANS_NEXT
+
+The packet list uses the value to determine the related packet symbol to draw.
+Note that 'strings' field NULL is equal to FRAMENUM_TYPE(FT_FRAMENUM_NONE).
+
+-- 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, FT_DOUBLE, FT_IEEE_11073_SFLOAT and FT_IEEE_11073_FLOAT
+- 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 int ett_eg = -1;
+    static int ett_field_a = -1;
+
+    static int *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 unsigned offset,
+        const int hf_checksum, const int hf_checksum_status,
+        struct expert_field* bad_checksum_expert, packet_info *pinfo,
+        uint32_t computed_checksum, const unsigned encoding, const unsigned 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 UTF-16, UCS-2, and UCS-4, the byte order of the encoding
+must be specified, and optionally ENC_BOM can also be indicated to detect
+an initial BYTE ORDER MARK (the specified value is used if the field does
+not begin with a BOM.) For counted UTF-16, UCS-2, and UCS-4 strings, the
+byte order of the count and the characters in the string must be the same,
+unless a BOM overrides the value for the characters. In other cases the
+string encoding has no endianness or the endianness is implicitly specified
+and nothing 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 (aka UTF-32)
+    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_EBCDIC_CP500 - EBCDIC code page 500
+    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
+    ENC_DECT_STANDARD_8BITS - DECT standard 8 bit character set as defined in
+        ETSI EN 300 175-5
+    ENC_DECT_STANDARD_4BITS_TBCD - DECT standard 4 bit character set "telephony
+        packet BCD" = 0-9, 0xb = SPACE
+
+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_USECS - 8 bytes, representing a value in microseconds 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_TIME_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_USECS - 8 bytes, representing a value in microseconds.
+
+    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_IMF_DATE_TIME. 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 int 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 char*
+    val_to_str(uint32_t 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 char*
+    try_val_to_str(uint32_t 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 char *
+    val64_to_str(const uint64_t val, const val64_string *vs, const char *fmt)
+
+    const char *
+    val64_to_str_const(const uint64_t val, const val64_string *vs, const char *unknown_str);
+
+    const char *
+    try_val64_to_str(const uint64_t val, const val64_string *vs);
+
+    const char *
+    try_val64_to_str_idx(const uint64_t val, const val64_string *vs, int *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 uint32_t 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 char *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 uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo,
+        proto_tree *tree);
+
+    int dissector_try_uint_new(dissector_table_t sub_dissectors,
+        const uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo,
+        proto_tree *tree, const bool add_proto_name, void *data);
+
+    int dissector_try_string(dissector_table_t sub_dissectors, const char *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 nine routines that you will use to work with a conversation:
+conversation_new, conversation_new_full, find_conversation,
+find_conversation_full, 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 ctype 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(uint32_t setup_frame, address *addr1,
+        address *addr2, conversation_type ctype, uint32_t port1, uint32_t port2,
+        unsigned options);
+
+Where:
+    uint32_t setup_frame     = The lowest numbered frame for this conversation
+    address* addr1          = first data packet address
+    address* addr2          = second data packet address
+    conversation_type ctype = conversation type, defined in conversation.h
+    uint32_t port1           = first data packet port
+    uint32_t port2           = second data packet port
+    unsigned 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 conversation_new_full function.
+
+This routine will create a new conversation based upon an arbitrary
+lists of elements. Elements can be addresses, strings, unsigned
+integers, or unsigned 64-bit integers. Unlike conversation_new, element
+lists are matched strictly; wildcards aren't (yet) supported.
+
+The conversation_new_full prototype:
+    conversation_t *conversation_new_full(const uint32_t setup_frame,
+        conversation_element_t *elements);
+
+Where:
+    uint32_t setup_frame              = The lowest numbered frame for
+        this conversation
+    conversation_element_t *elements = An array of data types and
+        values which identify this conversation. The array MUST be
+        terminated with a CE_ENDPOINT element.
+
+2.2.1.4 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(uint32_t frame_num, address *addr_a,
+        address *addr_b, conversation_type ctype, uint32_t port_a, uint32_t port_b,
+        unsigned options);
+
+Where:
+    uint32_t frame_num       = a frame number to match
+    address* addr_a         = first address
+    address* addr_b         = second address
+    conversation_type ctype = conversation type
+    uint32_t port_a          = first data packet port
+    uint32_t port_b          = second data packet port
+    unsigned 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.5 The find_conversation_full function.
+
+Call this routine to look up a conversation based on an element list. If
+no conversation is found, the routine will return a NULL value.
+
+The find_conversation_full prototype:
+
+    conversation_t *find_conversation_full(uint32_t frame_num,
+        conversation_element_t *elements);
+
+Where:
+    uint32_t setup_frame              = The lowest numbered frame for
+        this conversation
+    conversation_element_t *elements = An array of data types and
+        values which identify this conversation. The array MUST be
+        terminated with a CE_ENDPOINT element.
+
+2.2.1.6 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 unsigned options);
+
+Where:
+    packet_info *pinfo  = the packet_info structure
+    const unsigned 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 addresses and ports in the pinfo structure,
+pinfo->conv_addr_port_endpoints if pinfo->use_conv_addr_port_endpoints is set,
+or pinfo->conv_elements if it is set.
+
+2.2.1.7 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.8 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.9 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.10 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.11 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,
+        conversation_pt_to_conversation_type(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,
+        conversation_pt_to_conversation_type(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,
+        conversation_pt_to_conversation_type(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,
+            conversation_pt_to_conversation_type(pinfo->ptype),
+            pinfo->srcport, pinfo->destport, 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,
+register_dissector, or register_dissector_with_description.
+
+register_dissector_with_description takes as arguments a string giving a name
+for the dissector, a string with a human-readable summary of the dissector, 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
+as returned by proto_register_protocol.
+
+create_dissector_handle takes as arguments a pointer to the dissector
+function and a protocol ID as returned by proto_register_protocol.
+It is recommended to use one of the above two functions instead of this one,
+since they allow the dissector to be referenced by name from the command line,
+by other dissectors via calls to find_dissector, etc.
+
+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, conversation_type,
+                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 = register_dissector("PROTOABBREV", 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, uint32_t 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, conversation_type,
+        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, uint32_t key, void *proto_data)
+void *
+p_get_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, uint32_t 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, unsigned base, unsigned *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, bool *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, int *var,
+        const enum_val_t *enumvals, bool 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 password (a character-string) value. */
+    /* The value is hold during runtime, only in memory. It is never written to disk */
+    void prefs_register_password_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,
+        bool 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,
+        uint32_t 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_udp_handle = register_dissector_with_description("hart_ip", "HART-IP over UDP", dissect_hartip_udp, proto_hartip);
+    hartip_tcp_handle = register_dissector_with_description("hart_ip.tcp", "HART-IP over TCP", dissect_hartip_tcp, proto_hartip);
+
+    dissector_add_uint_with_preference("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 bool 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_)
+{
+    unsigned offset = 0;
+    while(offset < tvb_reported_length(tvb)) {
+        int available = tvb_reported_length_remaining(tvb, offset);
+        int 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);
+        }
+        offset += (unsigned)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 = register_dissector("dnp3.tcp", dissect_dnp3_tcp, proto_dnp3);
+    dnp3_udp_handle = register_dissector("dnp3.udp", dissect_dnp3_udp, proto_dnp3);
+
+    dissector_add_uint_with_preference("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle);
+    dissector_add_uint_with_preference("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 its
+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, int 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, int length, const unsigned 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, int length, const unsigned encoding, uint32_t *retval);
+    Like ptvcursor_add, but returns uint value retrieved
+
+proto_item*
+ptvcursor_add_ret_int(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, int32_t *retval);
+    Like ptvcursor_add, but returns int value retrieved
+
+proto_item*
+ptvcursor_add_ret_string(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, wmem_allocator_t *scope, const uint8_t **retval);
+    Like ptvcursor_add, but returns string retrieved
+
+proto_item*
+ptvcursor_add_ret_boolean(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, bool *retval);
+    Like ptvcursor_add, but returns boolean value retrieved
+
+proto_item*
+ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding)
+    Like ptvcursor_add, but does not advance the internal cursor.
+
+void
+ptvcursor_advance(ptvcursor_t* ptvc, int 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, int 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, int length,
+                            const unsigned encoding, int 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, int length,
+                                int 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.
+
+int
+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, int 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:
+ */