epan/proto.h

   1 /* proto.h
   2  * Definitions for protocol display
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11
  12 /*! @file proto.h
  13     The protocol tree related functions.<BR>
  14     A protocol tree will hold all necessary data to display the whole dissected packet.
  15     Creating a protocol tree is done in a two stage process:
  16     A static part at program startup, and a dynamic part when the dissection with the real packet data is done.<BR>
  17     The "static" information is provided by creating a hf_register_info hf[] array, and register it using the
  18     proto_register_field_array() function. This is usually done at dissector registering.<BR>
  19     The "dynamic" information is added to the protocol tree by calling one of the proto_tree_add_...() functions,
  20     e.g. proto_tree_add_bytes().
  21 */
  22
  23 #ifndef __PROTO_H__
  24 #define __PROTO_H__
  25
  26 #include <stdarg.h>
  27
  28 #include <glib.h>
  29
  30 #include <epan/wmem/wmem.h>
  31
  32 #include "ipv4.h"
  33 #include "wsutil/nstime.h"
  34 #include "time_fmt.h"
  35 #include "tvbuff.h"
  36 #include "value_string.h"
  37 #include "tfs.h"
  38 #include "packet_info.h"
  39 #include "ftypes/ftypes.h"
  40 #include "register.h"
  41 #include "ws_symbol_export.h"
  42 #include "ws_attributes.h"
  43 #ifdef HAVE_PLUGINS
  44 #include "wsutil/plugins.h"
  45 #endif
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif /* __cplusplus */
  50
  51 /** @defgroup prototree The Protocol Tree
  52  *
  53  * Dissectors use proto_tree_add_* to add items to the protocol tree. In
  54  * most cases you'll want to use proto_tree_add_item().
  55  *
  56  * @{
  57  */
  58
  59 /** The header-field index for the special text pseudo-field. Exported by libwireshark.dll */
  60 WS_DLL_PUBLIC int hf_text_only;
  61
  62 /** the maximum length of a protocol field string representation */
  63 #define ITEM_LABEL_LENGTH       240
  64
  65 #define ITEM_LABEL_UNKNOWN_STR  "Unknown"
  66
  67 struct expert_field;
  68
  69 /* Type-check that 'x' is compatible with 'type', should give compiler warnings otherwise. */
  70 #define cast_same(type, x) (0 ? (type)0 : (x))
  71
  72 /** Make a const value_string[] look like a _value_string pointer, used to set header_field_info.strings */
  73 #define VALS(x)     (cast_same(const struct _value_string*, (x)))
  74
  75 /** Make a const val64_string[] look like a _val64_string pointer, used to set header_field_info.strings */
  76 #define VALS64(x)   (cast_same(const struct _val64_string*, (x)))
  77
  78 /** Something to satisfy checkAPIs when you have a pointer to a value_string_ext (e.g., one built with value_string_ext_new()) */
  79 #define VALS_EXT_PTR(x) (cast_same(value_string_ext*, (x)))
  80
  81 /** Make a const true_false_string[] look like a _true_false_string pointer, used to set header_field_info.strings */
  82 #define TFS(x)      (cast_same(const struct true_false_string*, (x)))
  83
  84 typedef void (*custom_fmt_func_t)(gchar *, guint32);
  85
  86 typedef void (*custom_fmt_func_64_t)(gchar *, guint64);
  87
  88 /** Make a custom format function pointer look like a void pointer. Used to set header_field_info.strings.
  89  *
  90  * We cast to gsize first, which 1) is guaranteed to be wide enough to
  91  * hold a pointer and 2) lets us side-step warnings about casting function
  92  * pointers to 'void *'. This violates ISO C but should be fine on POSIX
  93  * and Windows.
  94  */
  95 #define CF_FUNC(x) ((const void *) (gsize) (x))
  96
  97 /** Make a const range_string[] look like a _range_string pointer, used to set
  98  * header_field_info.strings */
  99 #define RVALS(x) (cast_same(const struct _range_string*, (x)))
 100
 101 /** Cast a ft_framenum_type_t, used to set header_field_info.strings */
 102 #define FRAMENUM_TYPE(x) GINT_TO_POINTER(x)
 103
 104 struct _protocol;
 105
 106 /** Structure for information about a protocol */
 107 typedef struct _protocol protocol_t;
 108
 109 /** Function used for reporting errors in dissectors; it throws a
 110  * DissectorError exception, with a string generated from the format
 111  * and arguments to the format, as the message for the exception, so
 112  * that it can show up in the Info column and the protocol tree.
 113  *
 114  * If the WIRESHARK_ABORT_ON_DISSECTOR_BUG environment variable is set,
 115  * it will call abort(), instead, to make it easier to get a stack trace.
 116  *
 117  * @param format format string to use for the message
 118  */
 119 WS_DLL_PUBLIC WS_NORETURN
 120 void proto_report_dissector_bug(const char *format, ...)
 121     G_GNUC_PRINTF(1, 2);
 122
 123 #define REPORT_DISSECTOR_BUG(...)  \
 124     proto_report_dissector_bug(__VA_ARGS__)
 125
 126 /** Macro used to provide a hint to static analysis tools.
 127  * (Currently only Visual C++.)
 128  */
 129 #ifdef _MSC_VER
 130 /* XXX - Is there a way to say "quit checking at this point"? */
 131 #define __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(expression) \
 132   ; __analysis_assume(expression);
 133 #else
 134 #define __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(expression)
 135 #endif
 136
 137 /** Macro used for assertions in dissectors; it doesn't abort, it just
 138  * throws a DissectorError exception, with the assertion failure
 139  * message as a parameter, so that it can show up in the protocol tree.
 140  *
 141  * NOTE: this should only be used to detect bugs in the dissector (e.g., logic
 142  * conditions that shouldn't happen).  It should NOT be used for showing
 143  * that a packet is malformed.  For that, use expert_infos instead.
 144  *
 145  * @param s expression to test in the assertion
 146  */
 147
 148 #define __DISSECTOR_ASSERT_STRINGIFY(s) # s
 149
 150 #define __DISSECTOR_ASSERT(expression, file, lineno)  \
 151   (REPORT_DISSECTOR_BUG("%s:%u: failed assertion \"%s\"", \
 152         file, lineno, __DISSECTOR_ASSERT_STRINGIFY(expression)))
 153
 154 #define __DISSECTOR_ASSERT_HINT(expression, file, lineno, hint)  \
 155   (REPORT_DISSECTOR_BUG("%s:%u: failed assertion \"%s\" (%s)", \
 156         file, lineno, __DISSECTOR_ASSERT_STRINGIFY(expression), hint))
 157
 158 #define DISSECTOR_ASSERT(expression)  \
 159   ((void) ((expression) ? (void)0 : \
 160    __DISSECTOR_ASSERT (expression, __FILE__, __LINE__))) \
 161    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(expression)
 162
 163 /**
 164  * Same as DISSECTOR_ASSERT(), but takes an extra 'hint' parameter that
 165  * can be used to provide information as to why the assertion might fail.
 166  *
 167  * @param expression expression to test in the assertion
 168  * @param hint message providing extra information
 169  */
 170 #define DISSECTOR_ASSERT_HINT(expression, hint)  \
 171   ((void) ((expression) ? (void)0 : \
 172    __DISSECTOR_ASSERT_HINT (expression, __FILE__, __LINE__, hint))) \
 173    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(expression)
 174
 175 #if 0
 176 /* win32: using a debug breakpoint (int 3) can be very handy while debugging,
 177  * as the assert handling of GTK/GLib is currently not very helpful */
 178 #define DISSECTOR_ASSERT(expression)  \
 179 { if(!(expression)) _asm { int 3}; }
 180 #endif
 181
 182 /** Same as DISSECTOR_ASSERT(), but will throw DissectorError exception
 183  * unconditionally, much like GLIB's g_assert_not_reached works.
 184  *
 185  * NOTE: this should only be used to detect bugs in the dissector (e.g., logic
 186  * conditions that shouldn't happen).  It should NOT be used for showing
 187  * that a packet is malformed.  For that, use expert_infos instead.
 188  *
 189  */
 190 #define DISSECTOR_ASSERT_NOT_REACHED()  \
 191   (REPORT_DISSECTOR_BUG("%s:%u: failed assertion \"DISSECTOR_ASSERT_NOT_REACHED\"", \
 192         __FILE__, __LINE__))
 193
 194 /** Compare two integers.
 195  *
 196  * This is functionally the same as `DISSECTOR_ASSERT(a op b)` except that it
 197  * will display the values of a and b upon failure.
 198  *
 199  *     DISSECTOR_ASSERT_CMPINT(a, ==, b);
 200  *     DISSECTOR_ASSERT_CMPINT(min, <=, max);
 201  *
 202  * This function can currently compare values that fit inside a gint64.
 203  *
 204  * WARNING: The number of times the arguments are evaluated is undefined.  Do
 205  * not use expressions with side effects as arguments.
 206  *
 207  * @param a  The first integer.
 208  * @param op Any binary operator.
 209  * @param b  The second integer.
 210  * @param type the type operator
 211  * @param fmt the fmt operator
 212  */
 213 #define __DISSECTOR_ASSERT_CMPINT(a, op, b, type, fmt) \
 214   (REPORT_DISSECTOR_BUG("%s:%u: failed assertion " #a " " #op " " #b " (" fmt " " #op " " fmt ")", \
 215         __FILE__, __LINE__, (type)a, (type)b))
 216
 217 #define DISSECTOR_ASSERT_CMPINT(a, op, b)  \
 218   ((void) ((a op b) ? (void)0 : \
 219    __DISSECTOR_ASSERT_CMPINT (a, op, b, gint64, "%" G_GINT64_MODIFIER "d"))) \
 220    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(a op b)
 221
 222 /** Like DISSECTOR_ASSERT_CMPINT() except the arguments are treated as
 223  * unsigned values.
 224  *
 225  * This function can currently compare values that fit inside a guint64.
 226  */
 227 #define DISSECTOR_ASSERT_CMPUINT(a, op, b)  \
 228   ((void) ((a op b) ? (void)0 : \
 229    __DISSECTOR_ASSERT_CMPINT (a, op, b, guint64, "%" G_GINT64_MODIFIER "u"))) \
 230    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(a op b)
 231
 232 /** Like DISSECTOR_ASSERT_CMPUINT() except the values are displayed in
 233  * hexadecimal upon assertion failure.
 234  */
 235 #define DISSECTOR_ASSERT_CMPUINTHEX(a, op, b)  \
 236   ((void) ((a op b) ? (void)0 : \
 237    __DISSECTOR_ASSERT_CMPINT (a, op, b, guint64, "0x%" G_GINT64_MODIFIER "X"))) \
 238   __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(a op b)
 239
 240 /*
 241  * This is similar to DISSECTOR_ASSERT(hfinfo->type == type) except that
 242  * it will report the name of the field with the wrong type as well as
 243  * the type.
 244  *
 245  * @param hfinfo  The hfinfo for the field being tested
 246  * @param type    The type it's expected to have
 247  */
 248 #define __DISSECTOR_ASSERT_FIELD_TYPE(hfinfo, t) \
 249   (REPORT_DISSECTOR_BUG("%s:%u: field %s is not of type "#t, \
 250         __FILE__, __LINE__, (hfinfo)->abbrev))
 251
 252 #define DISSECTOR_ASSERT_FIELD_TYPE(hfinfo, t)  \
 253   ((void) (((hfinfo)->type == t) ? (void)0 : \
 254    __DISSECTOR_ASSERT_FIELD_TYPE ((hfinfo), t))) \
 255    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT((hfinfo)->type == t)
 256
 257 #define DISSECTOR_ASSERT_FIELD_TYPE_IS_INTEGRAL(hfinfo)  \
 258   ((void) ((IS_FT_INT((hfinfo)->type) || \
 259             IS_FT_UINT((hfinfo)->type)) ? (void)0 : \
 260    REPORT_DISSECTOR_BUG("%s:%u: field %s is not of type FT_CHAR or an FT_{U}INTn type", \
 261          __FILE__, __LINE__, (hfinfo)->abbrev))) \
 262    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT(IS_FT_INT((hfinfo)->type) || \
 263                                            IS_FT_UINT((hfinfo)->type))
 264
 265 #define __DISSECTOR_ASSERT_FIELD_TYPE_IS_STRING(hfinfo) \
 266   (REPORT_DISSECTOR_BUG("%s:%u: field %s is not of type FT_STRING, FT_STRINGZ, or FT_STRINGZPAD", \
 267         __FILE__, __LINE__, (hfinfo)->abbrev))
 268
 269 #define DISSECTOR_ASSERT_FIELD_TYPE_IS_STRING(hfinfo)  \
 270   ((void) (((hfinfo)->type == FT_STRING || (hfinfo)->type == FT_STRINGZ || \
 271             (hfinfo)->type == FT_STRINGZPAD) ? (void)0 : \
 272    __DISSECTOR_ASSERT_FIELD_TYPE_IS_STRING ((hfinfo)))) \
 273    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT((hfinfo)->type == FT_STRING || \
 274                                            (hfinfo)->type == FT_STRINGZ || \
 275                                            (hfinfo)->type == FT_STRINGZPAD)
 276
 277 #define __DISSECTOR_ASSERT_FIELD_TYPE_IS_TIME(hfinfo) \
 278   (REPORT_DISSECTOR_BUG("%s:%u: field %s is not of type FT_ABSOLUTE_TIME or FT_RELATIVE_TIME", \
 279         __FILE__, __LINE__, (hfinfo)->abbrev))
 280
 281 #define DISSECTOR_ASSERT_FIELD_TYPE_IS_TIME(hfinfo)  \
 282   ((void) (((hfinfo)->type == FT_ABSOLUTE_TIME || \
 283             (hfinfo)->type == FT_RELATIVE_TIME) ? (void)0 : \
 284    __DISSECTOR_ASSERT_FIELD_TYPE_IS_TIME ((hfinfo)))) \
 285    __DISSECTOR_ASSERT_STATIC_ANALYSIS_HINT((hfinfo)->type == FT_ABSOLUTE_TIME || \
 286                                            (hfinfo)->type == FT_RELATIVE_TIME)
 287
 288 /*
 289  * The encoding of a field of a particular type may involve more
 290  * than just whether it's big-endian or little-endian and its size.
 291  *
 292  * For integral values, that's it, as 99.9999999999999% of the machines
 293  * out there are 2's complement binary machines with 8-bit bytes,
 294  * so the protocols out there expect that and, for example, any Unisys
 295  * 2200 series machines out there just have to translate between 2's
 296  * complement and 1's complement (and nobody's put any IBM 709x's on
 297  * any networks lately :-)).
 298  *
 299  * However:
 300  *
 301  *  for floating-point numbers, in addition to IEEE decimal
 302  *  floating-point, there's also IBM System/3x0 and PDP-11/VAX
 303  *  floating-point - most protocols use IEEE binary, but DCE RPC
 304  *  can use other formats if that's what the sending host uses;
 305  *
 306  *  for character strings, there are various character encodings
 307  *  (various ISO 646 sets, ISO 8859/x, various other national
 308  *  standards, various DOS and Windows encodings, various Mac
 309  *  encodings, UTF-8, UTF-16, other extensions to ASCII, EBCDIC,
 310  *  etc.);
 311  *
 312  *  for absolute times, there's UNIX time_t, UNIX time_t followed
 313  *  by 32-bit microseconds, UNIX time_t followed by 32-bit
 314  *  nanoseconds, DOS date/time, Windows FILETIME, NTP time, etc..
 315  *
 316  * We might also, in the future, want to allow a field specifier to
 317  * indicate the encoding of the field, or at least its default
 318  * encoding, as most fields in most protocols always use the
 319  * same encoding (although that's not true of all fields, so we
 320  * still need to be able to specify that at run time).
 321  *
 322  * So, for now, we define ENC_BIG_ENDIAN and ENC_LITTLE_ENDIAN as
 323  * bit flags, to be combined, in the future, with other information
 324  * to specify the encoding in the last argument to
 325  * proto_tree_add_item(), and possibly to specify in a field
 326  * definition (e.g., ORed in with the type value).
 327  *
 328  * Currently, proto_tree_add_item() treats its last argument as a
 329  * Boolean - if it's zero, the field is big-endian, and if it's non-zero,
 330  * the field is little-endian - and other code in epan/proto.c does
 331  * the same.  We therefore define ENC_BIG_ENDIAN as 0x00000000 and
 332  * ENC_LITTLE_ENDIAN as 0x80000000 - we're using the high-order bit
 333  * so that we could put a field type and/or a value such as a character
 334  * encoding in the lower bits.
 335  */
 336 #define ENC_BIG_ENDIAN      0x00000000
 337 #define ENC_LITTLE_ENDIAN   0x80000000
 338
 339 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 340     #define ENC_HOST_ENDIAN ENC_LITTLE_ENDIAN
 341 #else
 342     #define ENC_HOST_ENDIAN ENC_BIG_ENDIAN
 343 #endif
 344
 345 /*
 346  * Historically FT_TIMEs were only timespecs; the only question was whether
 347  * they were stored in big- or little-endian format.
 348  *
 349  * For backwards compatibility, we interpret an encoding of 1 as meaning
 350  * "little-endian timespec", so that passing TRUE is interpreted as that.
 351  *
 352  * We now support:
 353  *
 354  *  ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes.  For 8 bytes, the first 4
 355  *  bytes are seconds and the next 4 bytes are nanoseconds; for 12 bytes,
 356  *  the first 8 bytes are seconds and the next 4 bytes are nanoseconds;
 357  *  for 16 bytes, the first 8 bytes are seconds and the next 8 bytes are
 358  *  nanoseconds.  If the time is absolute, the seconds are seconds since
 359  *  the UN*X epoch (1970-01-01 00:00:00 UTC).  (I.e., a UN*X struct
 360  *  timespec with a 4-byte or 8-byte time_t or a structure with an
 361  *  8-byte time_t and an 8-byte nanoseconds field.)
 362  *
 363  *  ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP
 364  *  epoch (1901-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of
 365  *  a second since that second.  (I.e., a 64-bit count of 1/2^32's of a
 366  *  second since the NTP epoch, with the upper 32 bits first and the
 367  *  lower 32 bits second, even when little-endian.)
 368  *
 369  *  ENC_TIME_TOD - 8 bytes, as a count of microseconds since the System/3x0
 370  *  and z/Architecture epoch (1900-01-01 00:00:00 GMT).
 371  *
 372  *  ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X
 373  *  epoch and the next 4 bytes are are 1/2^32's of a second since that
 374  *  second.  (I.e., it's the offspring of a mating between UN*X time and
 375  *  NTP time.)  It's used by the Object Management Group's Real-Time
 376  *  Publish-Subscribe Wire Protocol for the Data Distribution Service.
 377  *
 378  *  ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds and the
 379  *  next 4 bytes are microseconds.  If the time is absolute, the seconds
 380  *  are seconds since the UN*X epoch.  (I.e., a UN*X struct timeval with
 381  *  a 4-byte time_t.)
 382  *
 383  *  ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds.
 384  *  If the time is absolute, it's seconds since the UN*X epoch.
 385  *
 386  *  ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds.
 387  *  If the time is absolute, it's milliseconds since the UN*X epoch.
 388  *
 389  *  ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since
 390  *  the NTP epoch.  (I.e., seconds since the NTP epoch.)
 391  *
 392  *  ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a
 393  *  second since the UN*X epoch; see section 5.3.1 "Timestamp Option"
 394  *  in RFC 3971.
 395  *
 396  *  ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since
 397  *  the NTP epoch.  (I.e., milliseconds since the NTP epoch.)
 398  *
 399  * The backwards-compatibility names are defined as hex numbers so that
 400  * the script to generate init.lua will add them as global variables,
 401  * along with the new names.
 402  */
 403 #define ENC_TIME_SECS_NSECS    0x00000000
 404 #define ENC_TIME_TIMESPEC      0x00000000 /* for backwards source compatibility */
 405 #define ENC_TIME_NTP           0x00000002
 406 #define ENC_TIME_TOD           0x00000004
 407 #define ENC_TIME_RTPS          0x00000008
 408 #define ENC_TIME_NTP_BASE_ZERO 0x00000008 /* for backwards source compatibility */
 409 #define ENC_TIME_SECS_USECS    0x00000010
 410 #define ENC_TIME_TIMEVAL       0x00000010 /* for backwards source compatibility */
 411 #define ENC_TIME_SECS          0x00000012
 412 #define ENC_TIME_MSECS         0x00000014
 413 #define ENC_TIME_SECS_NTP      0x00000018
 414 #define ENC_TIME_RFC_3971      0x00000020
 415 #define ENC_TIME_MSEC_NTP      0x00000022
 416
 417 /*
 418  * Historically, the only place the representation mattered for strings
 419  * was with FT_UINT_STRINGs, where we had FALSE for the string length
 420  * being big-endian and TRUE for it being little-endian.
 421  *
 422  * We now have encoding values for the character encoding.  The encoding
 423  * values are encoded in all but the top bit (which is the byte-order
 424  * bit, required for FT_UINT_STRING and for UCS-2 and UTF-16 strings)
 425  * and the bottom bit (which we ignore for now so that programs that
 426  * pass TRUE for the encoding just do ASCII).  (The encodings are given
 427  * directly as even numbers in hex, so that make-init-lua.pl can just
 428  * turn them into numbers for use in init.lua.)
 429  *
 430  * We don't yet process ASCII and UTF-8 differently.  Ultimately, for
 431  * ASCII, all bytes with the 8th bit set should be mapped to some "this
 432  * is not a valid character" code point, as ENC_ASCII should mean "this
 433  * is ASCII, not some extended variant thereof".  We should also map
 434  * 0x00 to that as well - null-terminated and null-padded strings
 435  * never have NULs in them, but counted strings might.  (Either that,
 436  * or the values for strings should be counted, not null-terminated.)
 437  * For UTF-8, invalid UTF-8 sequences should be mapped to the same
 438  * code point.
 439  *
 440  * For display, perhaps we should also map control characters to the
 441  * Unicode glyphs showing the name of the control character in small
 442  * caps, diagonally.  (Unfortunately, those only exist for C0, not C1.)
 443  */
 444 #define ENC_CHARENCODING_MASK    0x7FFFFFFE  /* mask out byte-order bits */
 445 #define ENC_ASCII                0x00000000
 446 #define ENC_UTF_8                0x00000002
 447 #define ENC_UTF_16               0x00000004
 448 #define ENC_UCS_2                0x00000006
 449 #define ENC_UCS_4                0x00000008
 450 #define ENC_ISO_8859_1           0x0000000A
 451 #define ENC_ISO_8859_2           0x0000000C
 452 #define ENC_ISO_8859_3           0x0000000E
 453 #define ENC_ISO_8859_4           0x00000010
 454 #define ENC_ISO_8859_5           0x00000012
 455 #define ENC_ISO_8859_6           0x00000014
 456 #define ENC_ISO_8859_7           0x00000016
 457 #define ENC_ISO_8859_8           0x00000018
 458 #define ENC_ISO_8859_9           0x0000001A
 459 #define ENC_ISO_8859_10          0x0000001C
 460 #define ENC_ISO_8859_11          0x0000001E
 461 /* #define ENC_ISO_8859_12          0x00000020 ISO 8859-12 was abandoned */
 462 #define ENC_ISO_8859_13          0x00000022
 463 #define ENC_ISO_8859_14          0x00000024
 464 #define ENC_ISO_8859_15          0x00000026
 465 #define ENC_ISO_8859_16          0x00000028
 466 #define ENC_WINDOWS_1250         0x0000002A
 467 #define ENC_3GPP_TS_23_038_7BITS 0x0000002C
 468 #define ENC_EBCDIC               0x0000002E
 469 #define ENC_MAC_ROMAN            0x00000030
 470 #define ENC_CP437                0x00000032
 471 #define ENC_ASCII_7BITS          0x00000034
 472 #define ENC_T61                  0x00000036
 473 #define ENC_EBCDIC_CP037         0x00000038
 474 #define ENC_ZIGBEE               0x0000003A
 475 #define ENC_WINDOWS_1251         0x0000003C
 476 #define ENC_CP855                0x0000003E
 477 #define ENC_CP866                0x00000040
 478 /*
 479  * TODO:
 480  *
 481  * These could probably be used by existing code:
 482  *
 483  *  "IBM MS DBCS"
 484  *  JIS C 6226
 485  *
 486  * As those are added, change code such as the code in packet-bacapp.c
 487  * to use them.
 488  */
 489
 490 /*
 491  * For protocols (FT_PROTOCOL), aggregate items with subtrees (FT_NONE),
 492  * opaque byte-array fields (FT_BYTES), and other fields where there
 493  * is no choice of encoding (either because it's "just a bucket
 494  * of bytes" or because the encoding is completely fixed), we
 495  * have ENC_NA (for "Not Applicable").
 496  */
 497 #define ENC_NA          0x00000000
 498
 499 /* For cases where either native type or string encodings could both be
 500  * valid arguments, we need something to distinguish which one is being
 501  * passed as the argument, because ENC_BIG_ENDIAN and ENC_ASCII are both
 502  * 0x00000000. So we use ENC_STR_NUM or ENC_STR_HEX bit-or'ed with
 503  * ENC_ASCII and its ilk.
 504  */
 505 /* this is for strings as numbers "12345" */
 506 #define ENC_STR_NUM     0x01000000
 507 /* this is for strings as hex "1a2b3c" */
 508 #define ENC_STR_HEX     0x02000000
 509 /* a convenience macro for either of the above */
 510 #define ENC_STRING      0x03000000
 511 /* mask out ENC_STR_* and related bits - should this replace ENC_CHARENCODING_MASK? */
 512 #define ENC_STR_MASK    0x0000FFFE
 513
 514 /* for cases where the number is allowed to have a leading '+'/'-' */
 515 /* this can't collide with ENC_SEP_* because they can be used simultaneously */
 516 #define ENC_NUM_PREF    0x00200000
 517
 518 /* Use varint format as described in Protobuf protocol
 519  * https://developers.google.cn/protocol-buffers/docs/encoding
 520  */
 521 #define ENC_VARINT_PROTOBUF      0x00000002
 522 /*
 523  * Decodes a variable-length integer used in QUIC protocol
 524  * See https://tools.ietf.org/html/draft-ietf-quic-transport-08#section-8.1
 525  */
 526 #define ENC_VARINT_QUIC          0x00000004
 527
 528 /* For cases where a string encoding contains hex, bit-or one or more
 529  * of these for the allowed separator(s), as well as with ENC_STR_HEX.
 530  * See hex_str_to_bytes_encoding() in epan/strutil.h for details.
 531  */
 532 #define ENC_SEP_NONE    0x00010000
 533 #define ENC_SEP_COLON   0x00020000
 534 #define ENC_SEP_DASH    0x00040000
 535 #define ENC_SEP_DOT     0x00080000
 536 #define ENC_SEP_SPACE   0x00100000
 537 /* a convenience macro for the above */
 538 #define ENC_SEP_MASK    0x001F0000
 539
 540 /* For cases where a string encoding contains a timestamp, use one
 541  * of these (but only one). These values can collide with above, because
 542  * you can't do both at the same time.
 543  */
 544 #define ENC_ISO_8601_DATE       0x00010000
 545 #define ENC_ISO_8601_TIME       0x00020000
 546 #define ENC_ISO_8601_DATE_TIME  0x00030000
 547 #define ENC_RFC_822             0x00040000
 548 #define ENC_RFC_1123            0x00080000
 549 /* a convenience macro for the above - for internal use only */
 550 #define ENC_STR_TIME_MASK       0x000F0000
 551
 552 /* Values for header_field_info.display */
 553
 554 /* For integral types, the display format is a BASE_* field_display_e value
 555  * possibly ORed with BASE_*_STRING */
 556
 557 /** FIELD_DISPLAY_E_MASK selects the field_display_e value. */
 558 #define FIELD_DISPLAY_E_MASK 0xFF
 559
 560 /*
 561  * Note that this enum values are parsed in make-init-lua.pl so make sure
 562  * any changes here still makes valid entries in init.lua.
 563  */
 564 typedef enum {
 565 /* Integral types */
 566     BASE_NONE    = 0,   /**< none */
 567     BASE_DEC     = 1,   /**< decimal */
 568     BASE_HEX     = 2,   /**< hexadecimal */
 569     BASE_OCT     = 3,   /**< octal */
 570     BASE_DEC_HEX = 4,   /**< decimal (hexadecimal) */
 571     BASE_HEX_DEC = 5,   /**< hexadecimal (decimal) */
 572     BASE_CUSTOM  = 6,   /**< call custom routine (in ->strings) to format */
 573
 574 /* Float types */
 575     BASE_FLOAT   = BASE_NONE, /**< decimal-format float */
 576
 577 /* String types */
 578     STR_ASCII    = 0,   /**< shows non-printable ASCII characters as C-style escapes */
 579     /* XXX, support for format_text_wsp() ? */
 580     STR_UNICODE  = 7,   /**< shows non-printable UNICODE characters as \\uXXXX (XXX for now non-printable characters display depends on UI) */
 581
 582 /* Byte separators */
 583     SEP_DOT      = 8,   /**< hexadecimal bytes with a period (.) between each byte */
 584     SEP_DASH     = 9,   /**< hexadecimal bytes with a dash (-) between each byte */
 585     SEP_COLON    = 10,  /**< hexadecimal bytes with a colon (:) between each byte */
 586     SEP_SPACE    = 11,  /**< hexadecimal bytes with a space between each byte */
 587
 588 /* Address types */
 589     BASE_NETMASK = 12,  /**< Used for IPv4 address that shouldn't be resolved (like for netmasks) */
 590
 591 /* Port types */
 592     BASE_PT_UDP  = 13,  /**< UDP port */
 593     BASE_PT_TCP  = 14,  /**< TCP port */
 594     BASE_PT_DCCP = 15,  /**< DCCP port */
 595     BASE_PT_SCTP = 16,  /**< SCTP port */
 596
 597 /* OUI types */
 598     BASE_OUI     = 17   /**< OUI resolution */
 599
 600 } field_display_e;
 601
 602 #define FIELD_DISPLAY(d) ((d) & FIELD_DISPLAY_E_MASK)
 603
 604 /* Following constants have to be ORed with a field_display_e when dissector
 605  * want to use specials value-string MACROs for a header_field_info */
 606 #define BASE_RANGE_STRING     0x0100  /**< Use the supplied range string to convert the field to text */
 607 #define BASE_EXT_STRING       0x0200
 608 #define BASE_VAL64_STRING     0x0400
 609 #define BASE_ALLOW_ZERO       0x0800  /**< Display <none> instead of <MISSING> for zero sized byte array */
 610 #define BASE_UNIT_STRING      0x1000  /**< Add unit text to the field value */
 611 #define BASE_NO_DISPLAY_VALUE 0x2000  /**< Just display the field name with no value.  Intended for
 612                                            byte arrays or header fields above a subtree */
 613 #define BASE_PROTOCOL_INFO    0x4000  /**< protocol_t in [FIELDCONVERT].  Internal use only. */
 614 #define BASE_SPECIAL_VALS     0x8000  /**< field will not display "Unknown" if value_string match is not found */
 615
 616 /** BASE_ values that cause the field value to be displayed twice */
 617 #define IS_BASE_DUAL(b) ((b)==BASE_DEC_HEX||(b)==BASE_HEX_DEC)
 618
 619 /** BASE_PT_ values display decimal and transport port service name */
 620 #define IS_BASE_PORT(b) (((b)==BASE_PT_UDP||(b)==BASE_PT_TCP||(b)==BASE_PT_DCCP||(b)==BASE_PT_SCTP))
 621
 622 /* For FT_ABSOLUTE_TIME, the display format is an absolute_time_display_e
 623  * as per time_fmt.h. */
 624
 625 typedef enum {
 626     HF_REF_TYPE_NONE,       /**< Field is not referenced */
 627     HF_REF_TYPE_INDIRECT,   /**< Field is indirectly referenced (only applicable for FT_PROTOCOL) via. its child */
 628     HF_REF_TYPE_DIRECT      /**< Field is directly referenced */
 629 } hf_ref_type;
 630
 631 /** information describing a header field */
 632 typedef struct _header_field_info header_field_info;
 633
 634 /** information describing a header field */
 635 struct _header_field_info {
 636     /* ---------- set by dissector --------- */
 637     const char        *name;              /**< [FIELDNAME] full name of this field */
 638     const char        *abbrev;            /**< [FIELDABBREV] abbreviated name of this field */
 639     enum ftenum        type;              /**< [FIELDTYPE] field type, one of FT_ (from ftypes.h) */
 640     int                display;           /**< [FIELDDISPLAY] one of BASE_, or field bit-width if FT_BOOLEAN and non-zero bitmask */
 641     const void        *strings;           /**< [FIELDCONVERT] value_string, val64_string, range_string or true_false_string,
 642                                                typically converted by VALS(), RVALS() or TFS().
 643                                                If this is an FT_PROTOCOL or BASE_PROTOCOL_INFO then it points to the
 644                                                associated protocol_t structure */
 645     guint64            bitmask;           /**< [BITMASK] bitmask of interesting bits */
 646     const char        *blurb;             /**< [FIELDDESCR] Brief description of field */
 647
 648     /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */
 649     int                id;                /**< Field ID */
 650     int                parent;            /**< parent protocol tree */
 651     hf_ref_type        ref_type;          /**< is this field referenced by a filter */
 652     int                same_name_prev_id; /**< ID of previous hfinfo with same abbrev */
 653     header_field_info *same_name_next;    /**< Link to next hfinfo with same abbrev */
 654 };
 655
 656 /**
 657  * HFILL initializes all the "set by proto routines" fields in a
 658  * _header_field_info. If new fields are added or removed, it should
 659  * be changed as necessary.
 660  */
 661 #define HFILL -1, 0, HF_REF_TYPE_NONE, -1, NULL
 662
 663 #define HFILL_INIT(hf)   \
 664     (hf).hfinfo.id                = -1;   \
 665     (hf).hfinfo.parent            = 0;   \
 666     (hf).hfinfo.ref_type          = HF_REF_TYPE_NONE;   \
 667     (hf).hfinfo.same_name_prev_id = -1;   \
 668     (hf).hfinfo.same_name_next    = NULL;
 669
 670 /** Used when registering many fields at once, using proto_register_field_array() */
 671 typedef struct hf_register_info {
 672     int               *p_id;   /**< written to by register() function */
 673     header_field_info  hfinfo; /**< the field info to be registered */
 674 } hf_register_info;
 675
 676 /** string representation, if one of the proto_tree_add_..._format() functions used */
 677 typedef struct _item_label_t {
 678     char representation[ITEM_LABEL_LENGTH];
 679 } item_label_t;
 680
 681 /** Contains the field information for the proto_item. */
 682 typedef struct field_info {
 683     header_field_info   *hfinfo;          /**< pointer to registered field information */
 684     gint                 start;           /**< current start of data in field_info.ds_tvb */
 685     gint                 length;          /**< current data length of item in field_info.ds_tvb */
 686     gint                 appendix_start;  /**< start of appendix data */
 687     gint                 appendix_length; /**< length of appendix data */
 688     gint                 tree_type;       /**< one of ETT_ or -1 */
 689     guint32              flags;           /**< bitfield like FI_GENERATED, ... */
 690     item_label_t        *rep;             /**< string for GUI tree */
 691     tvbuff_t            *ds_tvb;          /**< data source tvbuff */
 692     fvalue_t             value;
 693 } field_info;
 694
 695
 696 /*
 697  * This structure describes one segment of a split-bits item
 698  * crumb_bit_offset is the bit offset in the input tvb of the first (most significant) bit of this crumb
 699  * crumb_bit_length is the number of contiguous bits of this crumb.
 700  * The first element of an array of bits_specs describes the most significant crumb of the output value.
 701  * The second element of an array of bits_specs describes the next-most significant crumb of the output value, etc.
 702  * The array is terminated by a sentinel entry with crumb_bit_length of 0.
 703 */
 704 typedef struct
 705 {
 706     guint  crumb_bit_offset;
 707     guint8 crumb_bit_length;
 708 } crumb_spec_t;
 709
 710 /*
 711  * Flag fields.  Do not assign values greater than 0x00000080 unless you
 712  * shuffle the expert information upward; see below.
 713  */
 714
 715 /** The protocol field should not be shown in the tree (it's used for filtering only),
 716  * used in field_info.flags. */
 717 /** HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN!
 718    A user cannot tell by looking at the packet detail that the field exists
 719    and that they can filter on its value. */
 720 #define FI_HIDDEN               0x00000001
 721 /** The protocol field should be displayed as "generated by Wireshark",
 722  * used in field_info.flags. */
 723 #define FI_GENERATED            0x00000002
 724 /** The protocol field is actually a URL */
 725 #define FI_URL                  0x00000004
 726
 727 /** The protocol field value is in little endian */
 728 #define FI_LITTLE_ENDIAN        0x00000008
 729 /** The protocol field value is in big endian */
 730 #define FI_BIG_ENDIAN           0x00000010
 731 /** Field value start from nth bit (values from 0x20 - 0x100) */
 732 #define FI_BITS_OFFSET(n)       (((n) & 7) << 5)
 733 /** Field value takes n bits (values from 0x100 - 0x4000) */
 734 /* if 0, it means that field takes fi->length * 8 */
 735 #define FI_BITS_SIZE(n)         (((n) & 63) << 8)
 736 /** The protocol field value is a varint */
 737 #define FI_VARINT               0x00004000
 738
 739 /** convenience macro to get field_info.flags */
 740 #define FI_GET_FLAG(fi, flag)   ((fi) ? ((fi)->flags & (flag)) : 0)
 741 /** convenience macro to set field_info.flags */
 742 #define FI_SET_FLAG(fi, flag) \
 743     do { \
 744       if (fi) \
 745         (fi)->flags = (fi)->flags | (flag); \
 746     } while(0)
 747 /** convenience macro to reset field_info.flags */
 748 #define FI_RESET_FLAG(fi, flag) \
 749     do { \
 750       if (fi) \
 751         (fi)->flags = (fi)->flags & ~(flag); \
 752     } while(0)
 753
 754 #define FI_GET_BITS_OFFSET(fi) (FI_GET_FLAG(fi, FI_BITS_OFFSET(7)) >> 5)
 755 #define FI_GET_BITS_SIZE(fi)   (FI_GET_FLAG(fi, FI_BITS_SIZE(63)) >> 8)
 756
 757 /** One of these exists for the entire protocol tree. Each proto_node
 758  * in the protocol tree points to the same copy. */
 759 typedef struct {
 760     GHashTable          *interesting_hfids;
 761     gboolean             visible;
 762     gboolean             fake_protocols;
 763     gint                 count;
 764     struct _packet_info *pinfo;
 765 } tree_data_t;
 766
 767 /** Each proto_tree, proto_item is one of these. */
 768 typedef struct _proto_node {
 769     struct _proto_node *first_child;
 770     struct _proto_node *last_child;
 771     struct _proto_node *next;
 772     struct _proto_node *parent;
 773     field_info         *finfo;
 774     tree_data_t        *tree_data;
 775 } proto_node;
 776
 777 /** A protocol tree element. */
 778 typedef proto_node proto_tree;
 779 /** A protocol item element. */
 780 typedef proto_node proto_item;
 781
 782 /*
 783  * Expert information.
 784  * This is in the flags field; we allocate this from the top down,
 785  * so as not to collide with FI_ flags, which are allocated from
 786  * the bottom up.
 787  */
 788
 789 /* do not modify the PI_SEVERITY_MASK name - it's used by make-init-lua.pl */
 790 /* expert severities */
 791 #define PI_SEVERITY_MASK        0x00F00000  /**< mask usually for internal use only! */
 792 /** Packet comment */
 793 #define PI_COMMENT              0x00100000
 794 /** Usual workflow, e.g. TCP connection establishing */
 795 #define PI_CHAT                 0x00200000
 796 /** Notable messages, e.g. an application returned an "unusual" error code like HTTP 404 */
 797 #define PI_NOTE                 0x00400000
 798 /** Warning, e.g. application returned an "unusual" error code */
 799 #define PI_WARN                 0x00600000
 800 /** Serious problems, e.g. a malformed packet */
 801 #define PI_ERROR                0x00800000
 802
 803 /* do not modify the PI_GROUP_MASK name - it's used by make-init-lua.pl */
 804 /* expert "event groups" */
 805 #define PI_GROUP_MASK           0xFF000000  /**< mask usually for internal use only! */
 806 /** The protocol field has a bad checksum, usually uses PI_WARN severity */
 807 #define PI_CHECKSUM             0x01000000
 808 /** The protocol field indicates a sequence problem (e.g. TCP window is zero) */
 809 #define PI_SEQUENCE             0x02000000
 810 /** The protocol field indicates a bad application response code (e.g. HTTP 404), usually PI_NOTE severity */
 811 #define PI_RESPONSE_CODE        0x03000000
 812 /** The protocol field indicates an application request (e.g. File Handle == xxxx), usually PI_CHAT severity */
 813 #define PI_REQUEST_CODE         0x04000000
 814 /** The data is undecoded, the protocol dissection is incomplete here, usually PI_WARN severity */
 815 #define PI_UNDECODED            0x05000000
 816 /** The protocol field indicates a reassemble (e.g. DCE/RPC defragmentation), usually PI_CHAT severity (or PI_ERROR) */
 817 #define PI_REASSEMBLE           0x06000000
 818 /** The packet data is malformed, the dissector has "given up", usually PI_ERROR severity */
 819 #define PI_MALFORMED            0x07000000
 820 /** A generic debugging message (shouldn't remain in production code!), usually PI_ERROR severity */
 821 #define PI_DEBUG                0x08000000
 822 /** The protocol field violates a protocol specification, usually PI_WARN severity */
 823 #define PI_PROTOCOL             0x09000000
 824 /** The protocol field indicates a security problem (e.g. insecure implementation) */
 825 #define PI_SECURITY             0x0a000000
 826 /** The protocol field indicates a packet comment */
 827 #define PI_COMMENTS_GROUP       0x0b000000
 828 /** The protocol field indicates a decryption problem */
 829 #define PI_DECRYPTION           0x0c000000
 830 /** The protocol field has incomplete data, decode based on assumed value */
 831 #define PI_ASSUMPTION           0x0d000000
 832 /** The protocol field has been deprecated, usually PI_NOTE severity */
 833 #define PI_DEPRECATED           0x0e000000
 834
 835 /* add more, see https://wiki.wireshark.org/Development/ExpertInfo */
 836
 837
 838 /** is this protocol field hidden from the protocol tree display (used for filtering only)? */
 839 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 840 #define PROTO_ITEM_IS_HIDDEN(proto_item)        \
 841     ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_HIDDEN) : 0)
 842 /** mark this protocol field to be hidden from the protocol tree display (used for filtering only) */
 843 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 844 #define PROTO_ITEM_SET_HIDDEN(proto_item)       \
 845   do { \
 846     if (proto_item) \
 847       FI_SET_FLAG(PITEM_FINFO(proto_item), FI_HIDDEN); \
 848   } while(0)
 849 /** mark this protocol field to be visible from the protocol tree display */
 850 #define PROTO_ITEM_SET_VISIBLE(proto_item)       \
 851   do { \
 852     if (proto_item) \
 853       FI_RESET_FLAG(PITEM_FINFO(proto_item), FI_HIDDEN); \
 854   } while(0)
 855
 856 /** is this protocol field generated by Wireshark (and not read from the packet data)? */
 857 #define PROTO_ITEM_IS_GENERATED(proto_item)     \
 858     ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_GENERATED) : 0)
 859 /** mark this protocol field as generated by Wireshark (and not read from the packet data) */
 860 #define PROTO_ITEM_SET_GENERATED(proto_item)    \
 861     do { \
 862       if (proto_item) \
 863         FI_SET_FLAG(PITEM_FINFO(proto_item), FI_GENERATED); \
 864     } while(0)
 865 /** is this protocol field actually a URL? */
 866 #define PROTO_ITEM_IS_URL(proto_item)   \
 867     ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_URL) : 0)
 868 /** mark this protocol field as a URL */
 869 #define PROTO_ITEM_SET_URL(proto_item)  \
 870     do { \
 871       if (proto_item) \
 872         FI_SET_FLAG(PITEM_FINFO(proto_item), FI_URL); \
 873     } while(0)
 874
 875 typedef void (*proto_tree_foreach_func)(proto_node *, gpointer);
 876 typedef gboolean (*proto_tree_traverse_func)(proto_node *, gpointer);
 877
 878 extern gboolean proto_tree_traverse_post_order(proto_tree *tree,
 879     proto_tree_traverse_func func, gpointer data);
 880
 881 WS_DLL_PUBLIC void proto_tree_children_foreach(proto_tree *tree,
 882     proto_tree_foreach_func func, gpointer data);
 883
 884 /** Retrieve the field_info from a proto_node */
 885 #define PNODE_FINFO(proto_node)  ((proto_node)->finfo)
 886
 887 /** Retrieve the field_info from a proto_item */
 888 #define PITEM_FINFO(proto_item)  PNODE_FINFO(proto_item)
 889
 890 /** Retrieve the field_info from a proto_tree */
 891 #define PTREE_FINFO(proto_tree)  PNODE_FINFO(proto_tree)
 892
 893 /** Retrieve the tree_data_t from a proto_tree */
 894 #define PTREE_DATA(proto_tree)   ((proto_tree)->tree_data)
 895
 896 /** Retrieve the wmem_allocator_t from a proto_node */
 897 #define PNODE_POOL(proto_node)   ((proto_node)->tree_data->pinfo->pool)
 898
 899 #ifdef HAVE_PLUGINS
 900 typedef struct {
 901     void (*register_protoinfo)(void);   /* routine to call to register protocol information */
 902     void (*register_handoff)(void);     /* routine to call to register dissector handoff */
 903 } proto_plugin;
 904
 905 /** Register dissector plugin with the plugin system. */
 906 WS_DLL_PUBLIC void proto_register_plugin(const proto_plugin *plugin);
 907 #endif
 908
 909 /** Sets up memory used by proto routines. Called at program startup */
 910 void proto_init(GSList *register_all_plugin_protocols_list,
 911     GSList *register_all_plugin_handoffs_list, register_cb cb, void *client_data);
 912
 913 /** Frees memory used by proto routines. Called at program shutdown */
 914 extern void proto_cleanup(void);
 915
 916 /** This function takes a tree and a protocol id as parameter and
 917     will return TRUE/FALSE for whether the protocol or any of the filterable
 918     fields in the protocol is referenced by any fitlers.
 919     If this function returns FALSE then it is safe to skip any
 920     proto_tree_add_...() calls and just treat the call as if the
 921     dissector was called with tree==NULL.
 922     If you reset the tree to NULL by this dissector returning FALSE,
 923     you will still need to call any subdissector with the original value of
 924     tree or filtering will break.
 925
 926     The purpose of this is to optimize wireshark for speed and make it
 927     faster for when filters are being used.
 928 */
 929 WS_DLL_PUBLIC gboolean proto_field_is_referenced(proto_tree *tree, int proto_id);
 930
 931 /** Create a subtree under an existing item.
 932  @param ti the parent item of the new subtree
 933  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
 934  @return the new subtree */
 935 WS_DLL_PUBLIC proto_tree* proto_item_add_subtree(proto_item *ti, const gint idx) G_GNUC_WARN_UNUSED_RESULT;
 936
 937 /** Get an existing subtree under an item.
 938  @param ti the parent item of the subtree
 939  @return the subtree or NULL */
 940 WS_DLL_PUBLIC proto_tree* proto_item_get_subtree(proto_item *ti);
 941
 942 /** Get the parent of a subtree item.
 943  @param ti the child item in the subtree
 944  @return parent item or NULL */
 945 WS_DLL_PUBLIC proto_item* proto_item_get_parent(const proto_item *ti);
 946
 947 /** Get Nth generation parent item.
 948  @param ti the child item in the subtree
 949  @param gen the generation to get (using 1 here is the same as using proto_item_get_parent())
 950  @return parent item */
 951 WS_DLL_PUBLIC proto_item* proto_item_get_parent_nth(proto_item *ti, int gen);
 952
 953 /** Replace text of item after it already has been created.
 954  @param ti the item to set the text
 955  @param format printf like format string
 956  @param ... printf like parameters */
 957 WS_DLL_PUBLIC void proto_item_set_text(proto_item *ti, const char *format, ...)
 958     G_GNUC_PRINTF(2,3);
 959
 960 /** Append to text of item after it has already been created.
 961  @param ti the item to append the text to
 962  @param format printf like format string
 963  @param ... printf like parameters */
 964 WS_DLL_PUBLIC void proto_item_append_text(proto_item *ti, const char *format, ...)
 965     G_GNUC_PRINTF(2,3);
 966
 967 /** Prepend to text of item after it has already been created.
 968  @param ti the item to prepend the text to
 969  @param format printf like format string
 970  @param ... printf like parameters */
 971 WS_DLL_PUBLIC void proto_item_prepend_text(proto_item *ti, const char *format, ...)
 972     G_GNUC_PRINTF(2,3);
 973
 974 /** Set proto_item's length inside tvb, after it has already been created.
 975  @param ti the item to set the length
 976  @param length the new length ot the item */
 977 WS_DLL_PUBLIC void proto_item_set_len(proto_item *ti, const gint length);
 978
 979 /**
 980  * Sets the length of the item based on its start and on the specified
 981  * offset, which is the offset past the end of the item; as the start
 982  * in the item is relative to the beginning of the data source tvbuff,
 983  * we need to pass in a tvbuff.
 984  @param ti the item to set the length
 985  @param tvb end is relative to this tvbuff
 986  @param end this end offset is relative to the beginning of tvb
 987  @todo make usage clearer, I don't understand it!
 988  */
 989 WS_DLL_PUBLIC void proto_item_set_end(proto_item *ti, tvbuff_t *tvb, gint end);
 990
 991 /** Get length of a proto_item. Useful after using proto_tree_add_item()
 992  * to add a variable-length field (e.g., FT_NSTRING_UINT8).
 993  @param ti the item to get the length from
 994  @return the current length */
 995 WS_DLL_PUBLIC int proto_item_get_len(const proto_item *ti);
 996
 997
 998
 999 /** Creates a new proto_tree root.
1000  @return the new tree root */
1001 extern proto_tree* proto_tree_create_root(struct _packet_info *pinfo);
1002
1003 void proto_tree_reset(proto_tree *tree);
1004
1005 /** Clear memory for entry proto_tree. Clears proto_tree struct also.
1006  @param tree the tree to free */
1007 WS_DLL_PUBLIC void proto_tree_free(proto_tree *tree);
1008
1009 /** Set the tree visible or invisible.
1010  Is the parsing being done for a visible proto_tree or an invisible one?
1011  By setting this correctly, the proto_tree creation is sped up by not
1012  having to call g_vsnprintf and copy strings around.
1013  @param tree the tree to be set
1014  @param visible ... or not
1015  @return the old value */
1016 WS_DLL_PUBLIC gboolean
1017 proto_tree_set_visible(proto_tree *tree, gboolean visible);
1018
1019 /** Indicate whether we should fake protocols during dissection (default = TRUE)
1020  @param tree the tree to be set
1021  @param fake_protocols TRUE if we should fake protocols */
1022 extern void
1023 proto_tree_set_fake_protocols(proto_tree *tree, gboolean fake_protocols);
1024
1025 /** Mark a field/protocol ID as "interesting".
1026  @param tree the tree to be set (currently ignored)
1027  @param hfid the interesting field id
1028  @todo what *does* interesting mean? */
1029 extern void
1030 proto_tree_prime_with_hfid(proto_tree *tree, const int hfid);
1031
1032 /** Get a parent item of a subtree.
1033  @param tree the tree to get the parent from
1034  @return parent item */
1035 WS_DLL_PUBLIC proto_item* proto_tree_get_parent(proto_tree *tree);
1036
1037 /** Get the parent tree of a subtree.
1038  @param tree the tree to get the parent from
1039  @return parent tree */
1040 WS_DLL_PUBLIC proto_tree *proto_tree_get_parent_tree(proto_tree *tree);
1041
1042 /** Get the root tree from any subtree.
1043  @param tree the tree to get the root from
1044  @return root tree */
1045 WS_DLL_PUBLIC proto_tree* proto_tree_get_root(proto_tree *tree);
1046
1047 /** Move an existing item behind another existing item.
1048  @param tree the tree to which both items belong
1049  @param fixed_item the item which keeps its position
1050  @param item_to_move the item which will be moved */
1051 WS_DLL_PUBLIC void proto_tree_move_item(proto_tree *tree, proto_item *fixed_item, proto_item *item_to_move);
1052
1053
1054 /** Set start and length of an appendix for a proto_tree.
1055  @param tree the tree to set the appendix start and length
1056  @param tvb the tv buffer of the current data
1057  @param start the start offset of the appendix
1058  @param length the length of the appendix */
1059 WS_DLL_PUBLIC void proto_tree_set_appendix(proto_tree *tree, tvbuff_t *tvb, gint start, const gint length);
1060
1061
1062 /** Add an item to a proto_tree, using the text label registered to that item.
1063    The item is extracted from the tvbuff handed to it.
1064  @param tree the tree to append this item to
1065  @param hfinfo field
1066  @param tvb the tv buffer of the current data
1067  @param start start of data in tvb
1068  @param length length of data in tvb
1069  @param encoding data encoding
1070  @return the newly created item */
1071 WS_DLL_PUBLIC proto_item *
1072 proto_tree_add_item_new(proto_tree *tree, header_field_info *hfinfo, tvbuff_t *tvb,
1073     const gint start, gint length, const guint encoding);
1074
1075 WS_DLL_PUBLIC proto_item *
1076 proto_tree_add_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1077     const gint start, gint length, const guint encoding);
1078
1079 /** Add an item to a proto_tree, using the text label registered to that item.
1080    The item is extracted from the tvbuff handed to it.
1081
1082    Return the length of the item through the pointer.
1083  @param tree the tree to append this item to
1084  @param hfinfo field
1085  @param tvb the tv buffer of the current data
1086  @param start start of data in tvb
1087  @param length length of data in tvb
1088  @param encoding data encoding
1089  @param[out] lenretval points to a gint that will be set to the item length
1090  @return the newly created item, and *lenretval is set to the item length */
1091 WS_DLL_PUBLIC proto_item *
1092 proto_tree_add_item_new_ret_length(proto_tree *tree, header_field_info *hfinfo, tvbuff_t *tvb,
1093     const gint start, gint length, const guint encoding, gint *lenretval);
1094
1095 WS_DLL_PUBLIC proto_item *
1096 proto_tree_add_item_ret_length(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1097     const gint start, gint length, const guint encoding, gint *lenretval);
1098
1099 /** Add an integer data item to a proto_tree, using the text label registered to that item.
1100 The item is extracted from the tvbuff handed to it, and the retrieved
1101 value is also set to *retval so the caller gets it back for other uses.
1102
1103 This function retrieves the value even if the passed-in tree param is NULL,
1104 so that it can be used by dissectors at all times to both get the value
1105 and set the tree item to it.
1106
1107 Like other proto_tree_add functions, if there is a tree and the value cannot
1108 be decoded from the tvbuff, then an expert info error is reported.
1109
1110 This function accepts ENC_LITTLE_ENDIAN and ENC_BIG_ENDIAN for native number
1111 encoding in the tvbuff
1112
1113 The length argument must
1114 be set to the appropriate size of the native type as in other proto_add routines.
1115
1116 Integers of 8, 16, 24 and 32 bits can be retrieved with the _ret_int and
1117 ret_uint functions; integers of 40, 48, 56, and 64 bits can be retrieved
1118 with the _ret_uint64 function; Boolean values of 8, 16, 24, 32, 40, 48,
1119 56, and 64 bits can be retrieved with the _ret_boolean function.
1120
1121 @param tree the tree to append this item to
1122 @param hfindex field
1123 @param tvb the tv buffer of the current data
1124 @param start start of data in tvb (cannot be negative)
1125 @param length length of data in tvb (for strings can be -1 for remaining)
1126 @param encoding data encoding (e.g, ENC_LITTLE_ENDIAN, ENC_BIG_ENDIAN, ENC_ASCII|ENC_STRING, etc.)
1127 @param[out] retval points to a gint32 or guint32 which will be set to the value
1128 @return the newly created item, and *retval is set to the decoded value masked/shifted according to bitmask
1129 */
1130 WS_DLL_PUBLIC proto_item *
1131 proto_tree_add_item_ret_int(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1132     const gint start, gint length, const guint encoding, gint32 *retval);
1133
1134 WS_DLL_PUBLIC proto_item *
1135 proto_tree_add_item_ret_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1136     const gint start, gint length, const guint encoding, guint32 *retval);
1137
1138 WS_DLL_PUBLIC proto_item *
1139 proto_tree_add_item_ret_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1140     const gint start, gint length, const guint encoding, guint64 *retval);
1141
1142 WS_DLL_PUBLIC proto_item *
1143 proto_tree_add_item_ret_varint(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1144     const gint start, gint length, const guint encoding, guint64 *retval, gint *lenretval);
1145
1146 WS_DLL_PUBLIC proto_item *
1147 proto_tree_add_item_ret_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1148     const gint start, gint length, const guint encoding, gboolean *retval);
1149
1150 /** Add an string item to a proto_tree, using the text label registered to
1151 that item.
1152
1153 The item is extracted from the tvbuff handed to it, and the retrieved
1154 value and its length are returned through pointers so the caller can use
1155 them.  The value is allocated using the wmem scope passed in.
1156
1157 This function retrieves the value and length even if the passed-in tree
1158 param is NULL, so that then can be used by dissectors at all times to
1159 both get the value and set the tree item to it.
1160
1161 Like other proto_tree_add functions, if there is a tree and the value cannot
1162 be decoded from the tvbuff, then an expert info error is reported.
1163
1164 This function accepts string encodings.
1165
1166 @param scope the wmem scope to use to allocate the string
1167 @param tree the tree to append this item to
1168 @param hfindex field
1169 @param tvb the tv buffer of the current data
1170 @param start start of data in tvb (cannot be negative)
1171 @param length length of data in tvb (for strings can be -1 for remaining)
1172 @param encoding data encoding (e.g, ENC_ASCII, ENC_UTF_8, etc.)
1173 @param[out] retval points to a guint8 * that will be set to point to the
1174 string value
1175 @param[out] lenretval points to a gint that will be set to the item length
1176 @return the newly created item, *retval is set to the decoded value,
1177 and *lenretval is set to the item length
1178 */
1179 WS_DLL_PUBLIC proto_item *
1180 proto_tree_add_item_ret_string_and_length(proto_tree *tree, int hfindex,
1181     tvbuff_t *tvb, const gint start, gint length, const guint encoding,
1182     wmem_allocator_t *scope, const guint8 **retval, gint *lenretval);
1183
1184 /** Add an string item to a proto_tree, using the text label registered to
1185 that item.
1186
1187 The item is extracted from the tvbuff handed to it, and the retrieved
1188 value is returned through a pointer so the caller can use it.  The value
1189 is allocated using the wmem scope passed in.
1190
1191 This function retrieves the value even if the passed-in tree param is NULL,
1192 so that it can be used by dissectors at all times to both get the value
1193 and set the tree item to it.
1194
1195 Like other proto_tree_add functions, if there is a tree and the value cannot
1196 be decoded from the tvbuff, then an expert info error is reported.
1197
1198 This function accepts string encodings.
1199
1200 @param scope the wmem scope to use to allocate the string
1201 @param tree the tree to append this item to
1202 @param hfindex field
1203 @param tvb the tv buffer of the current data
1204 @param start start of data in tvb (cannot be negative)
1205 @param length length of data in tvb (for strings can be -1 for remaining)
1206 @param encoding data encoding (e.g, ENC_ASCII, ENC_UTF_8, etc.)
1207 @param[out] retval points to a guint8 * that will be set to point to the
1208 string value
1209 @return the newly created item, and *retval is set to the decoded value
1210 */
1211 WS_DLL_PUBLIC proto_item *
1212 proto_tree_add_item_ret_string(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1213     const gint start, gint length, const guint encoding,
1214     wmem_allocator_t *scope, const guint8 **retval);
1215
1216 /** (INTERNAL USE ONLY) Add a text-only node to a proto_tree.
1217  @param tree the tree to append this item to
1218  @param tvb the tv buffer of the current data
1219  @param start start of data in tvb
1220  @param length length of data in tvb
1221  @param format printf like format string
1222  @param ... printf like parameters
1223  @return the newly created item */
1224 proto_item *
1225 proto_tree_add_text_internal(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
1226     ...) G_GNUC_PRINTF(5,6);
1227
1228 /** (INTERNAL USE ONLY) Add a text-only node to a proto_tree using a variable argument list.
1229  @param tree the tree to append this item to
1230  @param tvb the tv buffer of the current data
1231  @param start start of data in tvb
1232  @param length length of data in tvb
1233  @param format printf like format string
1234  @param ap variable argument list
1235  @return the newly created item */
1236 proto_item *
1237 proto_tree_add_text_valist_internal(proto_tree *tree, tvbuff_t *tvb, gint start,
1238     gint length, const char *format, va_list ap) G_GNUC_PRINTF(5, 0);
1239
1240 /** Add a text-only node that creates a subtree underneath.
1241  @param tree the tree to append this item to
1242  @param tvb the tv buffer of the current data
1243  @param start start of data in tvb
1244  @param length length of data in tvb
1245  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
1246  @param tree_item item returned with tree creation. Can be NULL if going to be unused
1247  @param text label for the tree
1248  @return the newly created tree */
1249 WS_DLL_PUBLIC proto_tree *
1250 proto_tree_add_subtree(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, gint idx,
1251     proto_item **tree_item, const char *text);
1252
1253 /** Add a text-only node that creates a subtree underneath.
1254  @param tree the tree to append this item to
1255  @param tvb the tv buffer of the current data
1256  @param start start of data in tvb
1257  @param length length of data in tvb
1258  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
1259  @param tree_item item returned with tree creation. Can be NULL if going to be unused
1260  @param format printf like format string
1261  @param ... printf like parameters
1262  @return the newly created tree */
1263 WS_DLL_PUBLIC proto_tree *
1264 proto_tree_add_subtree_format(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, gint idx,
1265     proto_item **tree_item, const char *format, ...) G_GNUC_PRINTF(7,8);
1266
1267 /** Add a text-only node to a proto_tree with tvb_format_text() string. */
1268 proto_item *
1269 proto_tree_add_format_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length);
1270
1271 /** Add a text-only node to a proto_tree with tvb_format_text_wsp() string. */
1272 proto_item *
1273 proto_tree_add_format_wsp_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length);
1274
1275 /** Add a FT_NONE field to a proto_tree.
1276  @param tree the tree to append this item to
1277  @param hfindex field index
1278  @param tvb the tv buffer of the current data
1279  @param start start of data in tvb
1280  @param length length of data in tvb
1281  @param format printf like format string
1282  @param ... printf like parameters
1283  @return the newly created item */
1284 WS_DLL_PUBLIC proto_item *
1285 proto_tree_add_none_format(proto_tree *tree, const int hfindex, tvbuff_t *tvb, const gint start,
1286     gint length, const char *format, ...) G_GNUC_PRINTF(6,7);
1287
1288 /** Add a FT_PROTOCOL to a proto_tree.
1289  @param tree the tree to append this item to
1290  @param hfindex field index
1291  @param tvb the tv buffer of the current data
1292  @param start start of data in tvb
1293  @param length length of data in tvb
1294  @param format printf like format string
1295  @param ... printf like parameters
1296  @return the newly created item */
1297 WS_DLL_PUBLIC proto_item *
1298 proto_tree_add_protocol_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1299     gint length, const char *format, ...) G_GNUC_PRINTF(6,7);
1300
1301 /** Add a FT_BYTES to a proto_tree.
1302  @param tree the tree to append this item to
1303  @param hfindex field index
1304  @param tvb the tv buffer of the current data
1305  @param start start of data in tvb
1306  @param length length of data in tvb
1307  @param start_ptr pointer to the data to display
1308  @return the newly created item */
1309 WS_DLL_PUBLIC proto_item *
1310 proto_tree_add_bytes(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1311     gint length, const guint8* start_ptr);
1312
1313 /** Add a FT_BYTES to a proto_tree like proto_tree_add_bytes,
1314  but used when the tvb data length does not match the bytes length.
1315  @param tree the tree to append this item to
1316  @param hfindex field index
1317  @param tvb the tv buffer of the current data
1318  @param start start of data in tvb
1319  @param length length of data in tvb
1320  @param start_ptr pointer to the data to display
1321  @param ptr_length length of data in start_ptr
1322  @return the newly created item */
1323 WS_DLL_PUBLIC proto_item *
1324 proto_tree_add_bytes_with_length(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1325     gint length, const guint8 *start_ptr, gint ptr_length);
1326
1327 /** Get and add a byte-array-based FT_* to a proto_tree.
1328
1329  Supported: FT_BYTES, FT_UINT_BYTES, FT_OID, FT_REL_OID, and FT_SYSTEM_ID.
1330
1331  The item is extracted from the tvbuff handed to it, based on the ENC_* passed
1332  in for the encoding, and the retrieved byte array is also set to *retval so the
1333  caller gets it back for other uses.
1334
1335  This function retrieves the value even if the passed-in tree param is NULL,
1336  so that it can be used by dissectors at all times to both get the value
1337  and set the tree item to it.
1338
1339  Like other proto_tree_add functions, if there is a tree and the value cannot
1340  be decoded from the tvbuff, then an expert info error is reported. For string
1341  encoding, this means that a failure to decode the hex value from the string
1342  results in an expert info error being added to the tree.
1343
1344  If encoding is string-based, it will convert using tvb_get_string_bytes(); see
1345  that function's comments for details.
1346
1347  @note The GByteArray retval must be pre-constructed using g_byte_array_new().
1348
1349  @param tree the tree to append this item to
1350  @param hfindex field index
1351  @param tvb the tv buffer of the current data
1352  @param start start of data in tvb
1353  @param length length of data in tvb
1354  @param encoding data encoding (e.g, ENC_LITTLE_ENDIAN, or ENC_UTF_8|ENC_STR_HEX)
1355  @param[in,out] retval points to a GByteArray which will be set to the bytes from the Tvb.
1356  @param[in,out] endoff if not NULL, gets set to the character after those consumed.
1357  @param[in,out] err if not NULL, gets set to 0 if no failure, else the errno code (e.g., EDOM, ERANGE).
1358  @return the newly created item, and retval is set to the decoded value
1359  */
1360 WS_DLL_PUBLIC proto_item *
1361 proto_tree_add_bytes_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1362     const gint start, gint length, const guint encoding,
1363     GByteArray *retval, gint *endoff, gint *err);
1364
1365 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
1366     the string for the value and with the field name being included
1367     automatically.
1368  @param tree the tree to append this item to
1369  @param hfindex field index
1370  @param tvb the tv buffer of the current data
1371  @param start start of data in tvb
1372  @param length length of data in tvb
1373  @param start_ptr pointer to the data to display
1374  @param format printf like format string
1375  @param ... printf like parameters
1376  @return the newly created item */
1377 WS_DLL_PUBLIC proto_item *
1378 proto_tree_add_bytes_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1379     gint start, gint length, const guint8* start_ptr, const char *format,
1380     ...) G_GNUC_PRINTF(7,8);
1381
1382 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
1383     the entire string for the entry, including any field name.
1384  @param tree the tree to append this item to
1385  @param hfindex field index
1386  @param tvb the tv buffer of the current data
1387  @param start start of data in tvb
1388  @param length length of data in tvb
1389  @param start_ptr pointer to the data to display
1390  @param format printf like format string
1391  @param ... printf like parameters
1392  @return the newly created item */
1393 WS_DLL_PUBLIC proto_item *
1394 proto_tree_add_bytes_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1395     gint length, const guint8* start_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1396
1397 /** Add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
1398  @param tree the tree to append this item to
1399  @param hfindex field index
1400  @param tvb the tv buffer of the current data
1401  @param start start of data in tvb
1402  @param length length of data in tvb
1403  @param value_ptr pointer to the data to display
1404  @return the newly created item */
1405 WS_DLL_PUBLIC proto_item *
1406 proto_tree_add_time(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1407     gint length, const nstime_t* value_ptr);
1408
1409 /** Get and add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
1410  The item is extracted from the tvbuff handed to it, based on the ENC_* passed
1411  in for the encoding, and the retrieved value is also set to *retval so the
1412  caller gets it back for other uses.
1413
1414  This function retrieves the value even if the passed-in tree param is NULL,
1415  so that it can be used by dissectors at all times to both get the value
1416  and set the tree item to it.
1417
1418  Like other proto_tree_add functions, if there is a tree and the value cannot
1419  be decoded from the tvbuff, then an expert info error is reported. For string
1420  encoding, this means that a failure to decode the time value from the string
1421  results in an expert info error being added to the tree.
1422
1423  If encoding is string-based, it will convert using tvb_get_string_time(); see
1424  that function's comments for details.
1425
1426  @note The nstime_t *retval must be pre-allocated as a nstime_t.
1427
1428  @param tree the tree to append this item to
1429  @param hfindex field index
1430  @param tvb the tv buffer of the current data
1431  @param start start of data in tvb
1432  @param length length of data in tvb
1433  @param encoding data encoding (e.g, ENC_LITTLE_ENDIAN, ENC_UTF_8|ENC_ISO_8601_DATE_TIME, etc.)
1434  @param[in,out] retval points to a nstime_t which will be set to the value
1435  @param[in,out] endoff if not NULL, gets set to the character after those consumed.
1436  @param[in,out] err if not NULL, gets set to 0 if no failure, else the errno code (e.g., EDOM, ERANGE).
1437  @return the newly created item, and retval is set to the decoded value
1438  */
1439 WS_DLL_PUBLIC proto_item *
1440 proto_tree_add_time_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1441     const gint start, gint length, const guint encoding,
1442     nstime_t *retval, gint *endoff, gint *err);
1443
1444
1445 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
1446     the format generating the string for the value and with the field name
1447     being included automatically.
1448  @param tree the tree to append this item to
1449  @param hfindex field index
1450  @param tvb the tv buffer of the current data
1451  @param start start of data in tvb
1452  @param length length of data in tvb
1453  @param value_ptr pointer to the data to display
1454  @param format printf like format string
1455  @param ... printf like parameters
1456  @return the newly created item */
1457 WS_DLL_PUBLIC proto_item *
1458 proto_tree_add_time_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1459     gint start, gint length, nstime_t* value_ptr, const char *format, ...)
1460     G_GNUC_PRINTF(7,8);
1461
1462 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
1463     the format generating the entire string for the entry, including any field
1464     name.
1465  @param tree the tree to append this item to
1466  @param hfindex field index
1467  @param tvb the tv buffer of the current data
1468  @param start start of data in tvb
1469  @param length length of data in tvb
1470  @param value_ptr pointer to the data to display
1471  @param format printf like format string
1472  @param ... printf like parameters
1473  @return the newly created item */
1474 WS_DLL_PUBLIC proto_item *
1475 proto_tree_add_time_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1476     gint length, nstime_t* value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1477
1478 /** Add a FT_IPXNET to a proto_tree.
1479  @param tree the tree to append this item to
1480  @param hfindex field index
1481  @param tvb the tv buffer of the current data
1482  @param start start of data in tvb
1483  @param length length of data in tvb
1484  @param value data to display
1485  @return the newly created item */
1486 WS_DLL_PUBLIC proto_item *
1487 proto_tree_add_ipxnet(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1488     gint length, guint32 value);
1489
1490 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
1491     the string for the value and with the field name being included
1492     automatically.
1493  @param tree the tree to append this item to
1494  @param hfindex field index
1495  @param tvb the tv buffer of the current data
1496  @param start start of data in tvb
1497  @param length length of data in tvb
1498  @param value data to display
1499  @param format printf like format string
1500  @param ... printf like parameters
1501  @return the newly created item */
1502 WS_DLL_PUBLIC proto_item *
1503 proto_tree_add_ipxnet_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1504     gint start, gint length, guint32 value, const char *format, ...)
1505     G_GNUC_PRINTF(7,8);
1506
1507 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
1508     the entire string for the entry, including any field name.
1509  @param tree the tree to append this item to
1510  @param hfindex field index
1511  @param tvb the tv buffer of the current data
1512  @param start start of data in tvb
1513  @param length length of data in tvb
1514  @param value data to display
1515  @param format printf like format string
1516  @param ... printf like parameters
1517  @return the newly created item */
1518 WS_DLL_PUBLIC proto_item *
1519 proto_tree_add_ipxnet_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1520     gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1521
1522 /** Add a FT_IPv4 to a proto_tree.
1523  @param tree the tree to append this item to
1524  @param hfindex field index
1525  @param tvb the tv buffer of the current data
1526  @param start start of data in tvb
1527  @param length length of data in tvb
1528  @param value data to display
1529  @return the newly created item */
1530 WS_DLL_PUBLIC proto_item *
1531 proto_tree_add_ipv4(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1532     gint length, guint32 value);
1533
1534 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
1535     the string for the value and with the field name being included
1536     automatically.
1537  @param tree the tree to append this item to
1538  @param hfindex field index
1539  @param tvb the tv buffer of the current data
1540  @param start start of data in tvb
1541  @param length length of data in tvb
1542  @param value data to display
1543  @param format printf like format string
1544  @param ... printf like parameters
1545  @return the newly created item */
1546 WS_DLL_PUBLIC proto_item *
1547 proto_tree_add_ipv4_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1548     gint start, gint length, guint32 value, const char *format, ...)
1549     G_GNUC_PRINTF(7,8);
1550
1551 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
1552     the entire string for the entry, including any field name.
1553  @param tree the tree to append this item to
1554  @param hfindex field index
1555  @param tvb the tv buffer of the current data
1556  @param start start of data in tvb
1557  @param length length of data in tvb
1558  @param value data to display
1559  @param format printf like format string
1560  @param ... printf like parameters
1561  @return the newly created item */
1562 WS_DLL_PUBLIC proto_item *
1563 proto_tree_add_ipv4_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1564     gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1565
1566 /** Add a FT_IPv6 to a proto_tree.
1567  @param tree the tree to append this item to
1568  @param hfindex field index
1569  @param tvb the tv buffer of the current data
1570  @param start start of data in tvb
1571  @param length length of data in tvb
1572  @param value_ptr data to display
1573  @return the newly created item */
1574 WS_DLL_PUBLIC proto_item *
1575 proto_tree_add_ipv6(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1576     gint length, const ws_in6_addr *value_ptr);
1577
1578 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
1579     the string for the value and with the field name being included
1580     automatically.
1581  @param tree the tree to append this item to
1582  @param hfindex field index
1583  @param tvb the tv buffer of the current data
1584  @param start start of data in tvb
1585  @param length length of data in tvb
1586  @param value_ptr data to display
1587  @param format printf like format string
1588  @param ... printf like parameters
1589  @return the newly created item */
1590 WS_DLL_PUBLIC proto_item *
1591 proto_tree_add_ipv6_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1592     gint start, gint length, const ws_in6_addr *value_ptr, const char *format,
1593     ...) G_GNUC_PRINTF(7,8);
1594
1595 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
1596     the entire string for the entry, including any field name.
1597  @param tree the tree to append this item to
1598  @param hfindex field index
1599  @param tvb the tv buffer of the current data
1600  @param start start of data in tvb
1601  @param length length of data in tvb
1602  @param value_ptr data to display
1603  @param format printf like format string
1604  @param ... printf like parameters
1605  @return the newly created item */
1606 WS_DLL_PUBLIC proto_item *
1607 proto_tree_add_ipv6_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1608     gint length, const ws_in6_addr *value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1609
1610 /** Add a FT_ETHER to a proto_tree.
1611  @param tree the tree to append this item to
1612  @param hfindex field index
1613  @param tvb the tv buffer of the current data
1614  @param start start of data in tvb
1615  @param length length of data in tvb
1616  @param value data to display
1617  @return the newly created item */
1618 WS_DLL_PUBLIC proto_item *
1619 proto_tree_add_ether(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1620     gint length, const guint8* value);
1621
1622 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
1623     the string for the value and with the field name being included
1624     automatically.
1625  @param tree the tree to append this item to
1626  @param hfindex field index
1627  @param tvb the tv buffer of the current data
1628  @param start start of data in tvb
1629  @param length length of data in tvb
1630  @param value data to display
1631  @param format printf like format string
1632  @param ... printf like parameters
1633  @return the newly created item */
1634 WS_DLL_PUBLIC proto_item *
1635 proto_tree_add_ether_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1636     gint start, gint length, const guint8* value, const char *format, ...)
1637     G_GNUC_PRINTF(7,8);
1638
1639 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
1640     the entire string for the entry, including any field name.
1641  @param tree the tree to append this item to
1642  @param hfindex field index
1643  @param tvb the tv buffer of the current data
1644  @param start start of data in tvb
1645  @param length length of data in tvb
1646  @param value data to display
1647  @param format printf like format string
1648  @param ... printf like parameters
1649  @return the newly created item */
1650 WS_DLL_PUBLIC proto_item *
1651 proto_tree_add_ether_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1652     gint length, const guint8* value, const char *format, ...) G_GNUC_PRINTF(7,8);
1653
1654 /** Add a FT_GUID to a proto_tree.
1655  @param tree the tree to append this item to
1656  @param hfindex field index
1657  @param tvb the tv buffer of the current data
1658  @param start start of data in tvb
1659  @param length length of data in tvb
1660  @param value_ptr data to display
1661  @return the newly created item */
1662 WS_DLL_PUBLIC proto_item *
1663 proto_tree_add_guid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1664     gint length, const e_guid_t *value_ptr);
1665
1666 /** Add a formatted FT_GUID to a proto_tree, with the format generating
1667     the string for the value and with the field name being included
1668     automatically.
1669  @param tree the tree to append this item to
1670  @param hfindex field index
1671  @param tvb the tv buffer of the current data
1672  @param start start of data in tvb
1673  @param length length of data in tvb
1674  @param value_ptr data to display
1675  @param format printf like format string
1676  @param ... printf like parameters
1677  @return the newly created item */
1678 WS_DLL_PUBLIC proto_item *
1679 proto_tree_add_guid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1680     gint start, gint length, const e_guid_t *value_ptr, const char *format,
1681     ...) G_GNUC_PRINTF(7,8);
1682
1683 /** Add a formatted FT_GUID to a proto_tree, with the format generating
1684     the entire string for the entry, including any field name.
1685  @param tree the tree to append this item to
1686  @param hfindex field index
1687  @param tvb the tv buffer of the current data
1688  @param start start of data in tvb
1689  @param length length of data in tvb
1690  @param value_ptr data to display
1691  @param format printf like format string
1692  @param ... printf like parameters
1693  @return the newly created item */
1694 WS_DLL_PUBLIC proto_item *
1695 proto_tree_add_guid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1696     gint length, const e_guid_t *value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1697
1698 /** Add a FT_OID to a proto_tree.
1699  @param tree the tree to append this item to
1700  @param hfindex field index
1701  @param tvb the tv buffer of the current data
1702  @param start start of data in tvb
1703  @param length length of data in tvb
1704  @param value_ptr data to display
1705  @return the newly created item */
1706 extern proto_item *
1707 proto_tree_add_oid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1708     gint length, const guint8* value_ptr);
1709
1710 /** Add a formatted FT_OID to a proto_tree, with the format generating
1711     the string for the value and with the field name being included
1712     automatically.
1713  @param tree the tree to append this item to
1714  @param hfindex field index
1715  @param tvb the tv buffer of the current data
1716  @param start start of data in tvb
1717  @param length length of data in tvb
1718  @param value_ptr data to display
1719  @param format printf like format string
1720  @param ... printf like parameters
1721  @return the newly created item */
1722 extern proto_item *
1723 proto_tree_add_oid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1724     gint start, gint length, const guint8* value_ptr, const char *format,
1725     ...) G_GNUC_PRINTF(7,8);
1726
1727 /** Add a formatted FT_OID to a proto_tree, with the format generating
1728     the entire string for the entry, including any field name.
1729  @param tree the tree to append this item to
1730  @param hfindex field index
1731  @param tvb the tv buffer of the current data
1732  @param start start of data in tvb
1733  @param length length of data in tvb
1734  @param value_ptr data to display
1735  @param format printf like format string
1736  @param ... printf like parameters
1737  @return the newly created item */
1738 extern proto_item *
1739 proto_tree_add_oid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1740     gint length, const guint8* value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1741
1742 /** Add a FT_STRING or FT_STRINGZPAD to a proto_tree.
1743  @param tree the tree to append this item to
1744  @param hfindex field index
1745  @param tvb the tv buffer of the current data
1746  @param start start of data in tvb
1747  @param length length of data in tvb
1748  @param value data to display
1749  @return the newly created item */
1750 WS_DLL_PUBLIC proto_item *
1751 proto_tree_add_string(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1752     gint length, const char* value);
1753
1754 /** Add a formatted FT_STRING or FT_STRINGZPAD to a proto_tree, with the
1755     format generating the string for the value and with the field name
1756     being included automatically.
1757  @param tree the tree to append this item to
1758  @param hfindex field index
1759  @param tvb the tv buffer of the current data
1760  @param start start of data in tvb
1761  @param length length of data in tvb
1762  @param value data to display
1763  @param format printf like format string
1764  @param ... printf like parameters
1765  @return the newly created item */
1766 WS_DLL_PUBLIC proto_item *
1767 proto_tree_add_string_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1768     gint start, gint length, const char* value, const char *format, ...)
1769     G_GNUC_PRINTF(7,8);
1770
1771 /** Add a formatted FT_STRING or FT_STRINGZPAD to a proto_tree, with the
1772     format generating the entire string for the entry, including any field
1773     name.
1774  @param tree the tree to append this item to
1775  @param hfindex field index
1776  @param tvb the tv buffer of the current data
1777  @param start start of data in tvb
1778  @param length length of data in tvb
1779  @param value data to display
1780  @param format printf like format string
1781  @param ... printf like parameters
1782  @return the newly created item */
1783 WS_DLL_PUBLIC proto_item *
1784 proto_tree_add_string_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1785     gint length, const char* value, const char *format, ...) G_GNUC_PRINTF(7,8);
1786
1787 /** Add a FT_BOOLEAN to a proto_tree.
1788  @param tree the tree to append this item to
1789  @param hfindex field index
1790  @param tvb the tv buffer of the current data
1791  @param start start of data in tvb
1792  @param length length of data in tvb
1793  @param value data to display
1794  @return the newly created item */
1795 WS_DLL_PUBLIC proto_item *
1796 proto_tree_add_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1797     gint length, guint32 value);
1798
1799 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
1800     the string for the value and with the field name being included
1801     automatically.
1802  @param tree the tree to append this item to
1803  @param hfindex field index
1804  @param tvb the tv buffer of the current data
1805  @param start start of data in tvb
1806  @param length length of data in tvb
1807  @param value data to display
1808  @param format printf like format string
1809  @param ... printf like parameters
1810  @return the newly created item */
1811 WS_DLL_PUBLIC proto_item *
1812 proto_tree_add_boolean_format_value(proto_tree *tree, int hfindex,
1813     tvbuff_t *tvb, gint start, gint length, guint32 value,
1814     const char *format, ...) G_GNUC_PRINTF(7,8);
1815
1816 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
1817     the entire string for the entry, including any field name.
1818  @param tree the tree to append this item to
1819  @param hfindex field index
1820  @param tvb the tv buffer of the current data
1821  @param start start of data in tvb
1822  @param length length of data in tvb
1823  @param value data to display
1824  @param format printf like format string
1825  @param ... printf like parameters
1826  @return the newly created item */
1827 WS_DLL_PUBLIC proto_item *
1828 proto_tree_add_boolean_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1829     gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1830
1831 /** Add a FT_FLOAT to a proto_tree.
1832  @param tree the tree to append this item to
1833  @param hfindex field index
1834  @param tvb the tv buffer of the current data
1835  @param start start of data in tvb
1836  @param length length of data in tvb
1837  @param value data to display
1838  @return the newly created item */
1839 WS_DLL_PUBLIC proto_item *
1840 proto_tree_add_float(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1841     gint length, float value);
1842
1843 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1844     the string for the value and with the field name being included
1845     automatically.
1846  @param tree the tree to append this item to
1847  @param hfindex field index
1848  @param tvb the tv buffer of the current data
1849  @param start start of data in tvb
1850  @param length length of data in tvb
1851  @param value data to display
1852  @param format printf like format string
1853  @param ... printf like parameters
1854  @return the newly created item */
1855 WS_DLL_PUBLIC proto_item *
1856 proto_tree_add_float_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1857     gint start, gint length, float value, const char *format, ...)
1858     G_GNUC_PRINTF(7,8);
1859
1860 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1861     the entire string for the entry, including any field name.
1862  @param tree the tree to append this item to
1863  @param hfindex field index
1864  @param tvb the tv buffer of the current data
1865  @param start start of data in tvb
1866  @param length length of data in tvb
1867  @param value data to display
1868  @param format printf like format string
1869  @param ... printf like parameters
1870  @return the newly created item */
1871 WS_DLL_PUBLIC proto_item *
1872 proto_tree_add_float_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1873     gint length, float value, const char *format, ...) G_GNUC_PRINTF(7,8);
1874
1875 /** Add a FT_DOUBLE to a proto_tree.
1876  @param tree the tree to append this item to
1877  @param hfindex field index
1878  @param tvb the tv buffer of the current data
1879  @param start start of data in tvb
1880  @param length length of data in tvb
1881  @param value data to display
1882  @return the newly created item */
1883 WS_DLL_PUBLIC proto_item *
1884 proto_tree_add_double(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1885     gint length, double value);
1886
1887 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1888     the string for the value and with the field name being included
1889     automatically.
1890  @param tree the tree to append this item to
1891  @param hfindex field index
1892  @param tvb the tv buffer of the current data
1893  @param start start of data in tvb
1894  @param length length of data in tvb
1895  @param value data to display
1896  @param format printf like format string
1897  @param ... printf like parameters
1898  @return the newly created item */
1899 WS_DLL_PUBLIC proto_item *
1900 proto_tree_add_double_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1901     gint start, gint length, double value, const char *format, ...)
1902     G_GNUC_PRINTF(7,8);
1903
1904 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1905     the entire string for the entry, including any field name.
1906  @param tree the tree to append this item to
1907  @param hfindex field index
1908  @param tvb the tv buffer of the current data
1909  @param start start of data in tvb
1910  @param length length of data in tvb
1911  @param value data to display
1912  @param format printf like format string
1913  @param ... printf like parameters
1914  @return the newly created item */
1915 WS_DLL_PUBLIC proto_item *
1916 proto_tree_add_double_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1917     gint length, double value, const char *format, ...) G_GNUC_PRINTF(7,8);
1918
1919 /** Add one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
1920  @param tree the tree to append this item to
1921  @param hfindex field index
1922  @param tvb the tv buffer of the current data
1923  @param start start of data in tvb
1924  @param length length of data in tvb
1925  @param value data to display
1926  @return the newly created item */
1927 WS_DLL_PUBLIC proto_item *
1928 proto_tree_add_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1929     gint length, guint32 value);
1930
1931 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1932     with the format generating the string for the value and with the field
1933     name being included automatically.
1934  @param tree the tree to append this item to
1935  @param hfindex field index
1936  @param tvb the tv buffer of the current data
1937  @param start start of data in tvb
1938  @param length length of data in tvb
1939  @param value data to display
1940  @param format printf like format string
1941  @param ... printf like parameters
1942  @return the newly created item */
1943 WS_DLL_PUBLIC proto_item *
1944 proto_tree_add_uint_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1945     gint start, gint length, guint32 value, const char *format, ...)
1946     G_GNUC_PRINTF(7,8);
1947
1948 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1949     with the format generating the entire string for the entry, including any
1950     field name.
1951  @param tree the tree to append this item to
1952  @param hfindex field index
1953  @param tvb the tv buffer of the current data
1954  @param start start of data in tvb
1955  @param length length of data in tvb
1956  @param value data to display
1957  @param format printf like format string
1958  @param ... printf like parameters
1959  @return the newly created item */
1960 WS_DLL_PUBLIC proto_item *
1961 proto_tree_add_uint_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1962     gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1963
1964 /** Add an FT_UINT64 to a proto_tree.
1965  @param tree the tree to append this item to
1966  @param hfindex field index
1967  @param tvb the tv buffer of the current data
1968  @param start start of data in tvb
1969  @param length length of data in tvb
1970  @param value data to display
1971  @return the newly created item */
1972 WS_DLL_PUBLIC proto_item *
1973 proto_tree_add_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1974     gint length, guint64 value);
1975
1976 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1977     the string for the value and with the field name being included
1978     automatically.
1979  @param tree the tree to append this item to
1980  @param hfindex field index
1981  @param tvb the tv buffer of the current data
1982  @param start start of data in tvb
1983  @param length length of data in tvb
1984  @param value data to display
1985  @param format printf like format string
1986  @param ... printf like parameters
1987  @return the newly created item */
1988 WS_DLL_PUBLIC proto_item *
1989 proto_tree_add_uint64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1990     gint start, gint length, guint64 value, const char *format, ...)
1991     G_GNUC_PRINTF(7,8);
1992
1993 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1994     the entire string for the entry, including any field name.
1995  @param tree the tree to append this item to
1996  @param hfindex field index
1997  @param tvb the tv buffer of the current data
1998  @param start start of data in tvb
1999  @param length length of data in tvb
2000  @param value data to display
2001  @param format printf like format string
2002  @param ... printf like parameters
2003  @return the newly created item */
2004 WS_DLL_PUBLIC proto_item *
2005 proto_tree_add_uint64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2006     gint length, guint64 value, const char *format, ...) G_GNUC_PRINTF(7,8);
2007
2008 /** Add one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
2009  @param tree the tree to append this item to
2010  @param hfindex field index
2011  @param tvb the tv buffer of the current data
2012  @param start start of data in tvb
2013  @param length length of data in tvb
2014  @param value data to display
2015  @return the newly created item */
2016 WS_DLL_PUBLIC proto_item *
2017 proto_tree_add_int(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2018     gint length, gint32 value);
2019
2020 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
2021     with the format generating the string for the value and with the field
2022     name being included automatically.
2023  @param tree the tree to append this item to
2024  @param hfindex field index
2025  @param tvb the tv buffer of the current data
2026  @param start start of data in tvb
2027  @param length length of data in tvb
2028  @param value data to display
2029  @param format printf like format string
2030  @param ... printf like parameters
2031  @return the newly created item */
2032 WS_DLL_PUBLIC proto_item *
2033 proto_tree_add_int_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
2034     gint start, gint length, gint32 value, const char *format, ...)
2035     G_GNUC_PRINTF(7,8);
2036
2037 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
2038     with the format generating the entire string for the entry, including
2039     any field name.
2040  @param tree the tree to append this item to
2041  @param hfindex field index
2042  @param tvb the tv buffer of the current data
2043  @param start start of data in tvb
2044  @param length length of data in tvb
2045  @param value data to display
2046  @param format printf like format string
2047  @param ... printf like parameters
2048  @return the newly created item */
2049 WS_DLL_PUBLIC proto_item *
2050 proto_tree_add_int_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2051     gint length, gint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
2052
2053 /** Add an FT_INT64 to a proto_tree.
2054  @param tree the tree to append this item to
2055  @param hfindex field index
2056  @param tvb the tv buffer of the current data
2057  @param start start of data in tvb
2058  @param length length of data in tvb
2059  @param value data to display
2060  @return the newly created item */
2061 WS_DLL_PUBLIC proto_item *
2062 proto_tree_add_int64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2063     gint length, gint64 value);
2064
2065 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
2066     the string for the value and with the field name being included
2067     automatically.
2068  @param tree the tree to append this item to
2069  @param hfindex field index
2070  @param tvb the tv buffer of the current data
2071  @param start start of data in tvb
2072  @param length length of data in tvb
2073  @param value data to display
2074  @param format printf like format string
2075  @param ... printf like parameters
2076  @return the newly created item */
2077 WS_DLL_PUBLIC proto_item *
2078 proto_tree_add_int64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
2079     gint start, gint length, gint64 value, const char *format, ...)
2080     G_GNUC_PRINTF(7,8);
2081
2082 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
2083     the entire string for the entry, including any field name.
2084  @param tree the tree to append this item to
2085  @param hfindex field index
2086  @param tvb the tv buffer of the current data
2087  @param start start of data in tvb
2088  @param length length of data in tvb
2089  @param value data to display
2090  @param format printf like format string
2091  @param ... printf like parameters
2092  @return the newly created item */
2093 WS_DLL_PUBLIC proto_item *
2094 proto_tree_add_int64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2095     gint length, gint64 value, const char *format, ...) G_GNUC_PRINTF(7,8);
2096
2097 /** Add a FT_EUI64 to a proto_tree.
2098  @param tree the tree to append this item to
2099  @param hfindex field index
2100  @param tvb the tv buffer of the current data
2101  @param start start of data in tvb
2102  @param length length of data in tvb
2103  @param value data to display
2104  @return the newly created item */
2105 WS_DLL_PUBLIC proto_item *
2106 proto_tree_add_eui64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2107     gint length, const guint64 value);
2108
2109 /** Add a formatted FT_EUI64 to a proto_tree, with the format generating
2110     the string for the value and with the field name being included
2111     automatically.
2112  @param tree the tree to append this item to
2113  @param hfindex field index
2114  @param tvb the tv buffer of the current data
2115  @param start start of data in tvb
2116  @param length length of data in tvb
2117  @param value data to display
2118  @param format printf like format string
2119  @param ... printf like parameters
2120  @return the newly created item */
2121 WS_DLL_PUBLIC proto_item *
2122 proto_tree_add_eui64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
2123     gint start, gint length, const guint64 value, const char *format, ...)
2124     G_GNUC_PRINTF(7,8);
2125
2126 /** Add a formatted FT_EUI64 to a proto_tree, with the format generating
2127     the entire string for the entry, including any field name.
2128  @param tree the tree to append this item to
2129  @param hfindex field index
2130  @param tvb the tv buffer of the current data
2131  @param start start of data in tvb
2132  @param length length of data in tvb
2133  @param value data to display
2134  @param format printf like format string
2135  @param ... printf like parameters
2136  @return the newly created item */
2137 WS_DLL_PUBLIC proto_item *
2138 proto_tree_add_eui64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
2139     gint length, const guint64 value, const char *format, ...) G_GNUC_PRINTF(7,8);
2140
2141 /** Useful for quick debugging. Also sends string to STDOUT, so don't
2142     leave call to this function in production code.
2143  @param tree the tree to append the text to
2144  @param format printf like format string
2145  @param ... printf like parameters
2146  @return the newly created item */
2147 WS_DLL_PUBLIC proto_item *
2148 proto_tree_add_debug_text(proto_tree *tree, const char *format,
2149     ...) G_GNUC_PRINTF(2,3);
2150
2151 /** Fill given label_str with string representation of field
2152  @param fi the item to get the info from
2153  @param label_str the string to fill
2154  @todo think about changing the parameter profile */
2155 WS_DLL_PUBLIC void
2156 proto_item_fill_label(field_info *fi, gchar *label_str);
2157
2158 /** Register a new protocol.
2159  @param name the full name of the new protocol
2160  @param short_name abbreviated name of the new protocol
2161  @param filter_name protocol name used for a display filter string
2162  @return the new protocol handle */
2163 WS_DLL_PUBLIC int
2164 proto_register_protocol(const char *name, const char *short_name, const char *filter_name);
2165
2166 /** Register a "helper" protocol (pino - protocol in name only).
2167  This is for dissectors that need distinguishing names and don't need the other
2168  features (like enable/disable).  One use case is a protocol with multiple dissection
2169  functions in a single dissector table needing unique "dissector names" to remove
2170  confusion with Decode As dialog.  Another use case is for a dissector table set
2171  up to handle TLVs within a single protocol (and allow "external" TLVs being
2172  registered through the dissector table).
2173  @param name the full name of the new protocol
2174  @param short_name abbreviated name of the new protocol
2175  @param filter_name protocol name used for a display filter string
2176  @param parent_proto the "real" protocol for the helper.  The parent decides enable/disable
2177  @param field_type FT_PROTOCOL or FT_BYTES.  Allows removal of "protocol highlighting" (FT_BYTES)
2178  if pino is part of TLV.
2179  @return the new protocol handle */
2180 WS_DLL_PUBLIC int
2181 proto_register_protocol_in_name_only(const char *name, const char *short_name, const char *filter_name,
2182     int parent_proto, enum ftenum field_type);
2183
2184 /** Deregister a protocol.
2185  @param short_name abbreviated name of the protocol
2186  @return TRUE if protocol is removed */
2187 gboolean
2188 proto_deregister_protocol(const char *short_name);
2189
2190 /** Register a protocol alias.
2191  This is for dissectors whose original name has changed, e.g. BOOTP to DHCP.
2192  @param proto_id protocol id returned by proto_register_protocol (0-indexed)
2193  @param alias_name alias for the protocol's filter name */
2194 WS_DLL_PUBLIC void
2195 proto_register_alias(const int proto_id, const char *alias_name);
2196
2197 /** This type of function can be registered to get called whenever
2198     a given field was not found but a its prefix is matched;
2199     It can be used to procrastinate the hf array registration.
2200    @param match  what's being matched */
2201 typedef void (*prefix_initializer_t)(const char* match);
2202
2203 /** Register a new prefix for delayed initialization of field arrays
2204     Note that the initializer function MAY NOT be called before the dissector
2205     is first called.  That is, dissectors using this function must be prepared
2206     to call the initializer before beginning dissection; they should do this by
2207     calling proto_registrar_get_byname() on one of the dissector's field names.
2208 @param prefix the prefix for the new protocol
2209 @param initializer function that will initialize the field array for the given prefix */
2210 WS_DLL_PUBLIC void
2211 proto_register_prefix(const char *prefix,  prefix_initializer_t initializer);
2212
2213 /** Initialize every remaining uninitialized prefix. */
2214 WS_DLL_PUBLIC void proto_initialize_all_prefixes(void);
2215
2216 WS_DLL_PUBLIC void proto_register_fields_manual(const int parent, header_field_info **hfi,
2217     const int num_records);
2218 WS_DLL_PUBLIC void proto_register_fields_section(const int parent, header_field_info *hfi,
2219     const int num_records);
2220
2221 /** Register a header_field array.
2222  @param parent the protocol handle from proto_register_protocol()
2223  @param hf the hf_register_info array
2224  @param num_records the number of records in hf */
2225 WS_DLL_PUBLIC void
2226 proto_register_field_array(const int parent, hf_register_info *hf, const int num_records);
2227
2228 /** Deregister an already registered field.
2229  @param parent the protocol handle from proto_register_protocol()
2230  @param hf_id the field to deregister */
2231 WS_DLL_PUBLIC void
2232 proto_deregister_field (const int parent, gint hf_id);
2233
2234 /** Add data to be freed when deregistered fields are freed.
2235  @param data a pointer to data to free */
2236 WS_DLL_PUBLIC void
2237 proto_add_deregistered_data (void *data);
2238
2239 /** Free fields deregistered in proto_deregister_field(). */
2240 WS_DLL_PUBLIC void
2241 proto_free_deregistered_fields (void);
2242
2243 /** Register a protocol subtree (ett) array.
2244  @param indices array of ett indices
2245  @param num_indices the number of records in indices */
2246 WS_DLL_PUBLIC void
2247 proto_register_subtree_array(gint *const *indices, const int num_indices);
2248
2249 /** Get name of registered header_field number n.
2250  @param n item # n (0-indexed)
2251  @return the name of this registered item */
2252 WS_DLL_PUBLIC const char* proto_registrar_get_name(const int n);
2253
2254 /** Get abbreviation of registered header_field number n.
2255  @param n item # n (0-indexed)
2256  @return the abbreviation of this registered item */
2257 WS_DLL_PUBLIC const char* proto_registrar_get_abbrev(const int n);
2258
2259 /** Get the header_field information based upon a field or protocol id.
2260  @param hfindex item # n (0-indexed)
2261  @return the registered item */
2262 WS_DLL_PUBLIC header_field_info* proto_registrar_get_nth(guint hfindex);
2263
2264 /** Get the header_field information based upon a field name.
2265  @param field_name the field name to search for
2266  @return the registered item */
2267 WS_DLL_PUBLIC header_field_info* proto_registrar_get_byname(const char *field_name);
2268
2269 /** Get the header_field information based upon a field alias.
2270  @param alias_name the aliased field name to search for
2271  @return the registered item */
2272 WS_DLL_PUBLIC header_field_info* proto_registrar_get_byalias(const char *alias_name);
2273
2274 /** Get the header_field id based upon a field name.
2275  @param field_name the field name to search for
2276  @return the field id for the registered item */
2277 WS_DLL_PUBLIC int proto_registrar_get_id_byname(const char *field_name);
2278
2279 /** Get enum ftenum FT_ of registered header_field number n.
2280  @param n item # n (0-indexed)
2281  @return the registered item */
2282 WS_DLL_PUBLIC enum ftenum proto_registrar_get_ftype(const int n);
2283
2284 /** Get parent protocol of registered header_field number n.
2285  @param n item # n (0-indexed)
2286  @return -1 if item _is_ a protocol */
2287 WS_DLL_PUBLIC int proto_registrar_get_parent(const int n);
2288
2289 /** Is item # n a protocol?
2290  @param n item # n (0-indexed)
2291  @return TRUE if it's a protocol, FALSE if it's not */
2292 WS_DLL_PUBLIC gboolean proto_registrar_is_protocol(const int n);
2293
2294 /** Get length of registered field according to field type.
2295  @param n item # n (0-indexed)
2296  @return 0 means undeterminable at registration time, -1 means unknown field */
2297 extern gint proto_registrar_get_length(const int n);
2298
2299
2300 /** Routines to use to iterate over the protocols and their fields;
2301  * they return the item number of the protocol in question or the
2302  * appropriate hfinfo pointer, and keep state in "*cookie". */
2303 WS_DLL_PUBLIC int proto_get_first_protocol(void **cookie);
2304 WS_DLL_PUBLIC int proto_get_data_protocol(void *cookie);
2305 WS_DLL_PUBLIC int proto_get_next_protocol(void **cookie);
2306 WS_DLL_PUBLIC header_field_info *proto_get_first_protocol_field(const int proto_id, void **cookie);
2307 WS_DLL_PUBLIC header_field_info *proto_get_next_protocol_field(const int proto_id, void **cookie);
2308
2309 /** Check if a protocol name is already registered.
2310  @param name the name to search for
2311  @return proto_id */
2312 WS_DLL_PUBLIC int proto_name_already_registered(const gchar *name);
2313
2314 /** Given a protocol's filter_name.
2315  @param filter_name the filter name to search for
2316  @return proto_id */
2317 WS_DLL_PUBLIC int proto_get_id_by_filter_name(const gchar* filter_name);
2318
2319 /** Given a protocol's short name.
2320  @param short_name the protocol short name to search for
2321  @return proto_id */
2322 WS_DLL_PUBLIC int proto_get_id_by_short_name(const gchar* short_name);
2323
2324 /** Can item # n decoding be disabled?
2325  @param proto_id protocol id (0-indexed)
2326  @return TRUE if it's a protocol, FALSE if it's not */
2327 WS_DLL_PUBLIC gboolean proto_can_toggle_protocol(const int proto_id);
2328
2329 /** Get the "protocol_t" structure for the given protocol's item number.
2330  @param proto_id protocol id (0-indexed) */
2331 WS_DLL_PUBLIC protocol_t *find_protocol_by_id(const int proto_id);
2332
2333 /** Get the protocol's name for the given protocol's item number.
2334  @param proto_id protocol id (0-indexed)
2335  @return its name */
2336 WS_DLL_PUBLIC const char *proto_get_protocol_name(const int proto_id);
2337
2338 /** Get the protocol's item number, for the given protocol's "protocol_t".
2339  @return its proto_id */
2340 WS_DLL_PUBLIC int proto_get_id(const protocol_t *protocol);
2341
2342 /** Get the protocol's short name, for the given protocol's "protocol_t".
2343  @return its short name. */
2344 WS_DLL_PUBLIC const char *proto_get_protocol_short_name(const protocol_t *protocol);
2345
2346 /** Get the protocol's long name, for the given protocol's "protocol_t".
2347  @return its long name. */
2348 WS_DLL_PUBLIC const char *proto_get_protocol_long_name(const protocol_t *protocol);
2349
2350 /** Is protocol's decoding enabled ?
2351  @return TRUE if decoding is enabled, FALSE if not */
2352 WS_DLL_PUBLIC gboolean proto_is_protocol_enabled(const protocol_t *protocol);
2353
2354 /** Is protocol's enabled by default (most are)?
2355  @return TRUE if decoding is enabled by default, FALSE if not */
2356 WS_DLL_PUBLIC gboolean proto_is_protocol_enabled_by_default(const protocol_t *protocol);
2357
2358 /** Is this a protocol in name only (i.e. not a real one)?
2359  @return TRUE if helper, FALSE if not */
2360 WS_DLL_PUBLIC gboolean proto_is_pino(const protocol_t *protocol);
2361
2362 /** Get a protocol's filter name by its item number.
2363  @param proto_id protocol id (0-indexed)
2364  @return its filter name. */
2365 WS_DLL_PUBLIC const char *proto_get_protocol_filter_name(const int proto_id);
2366
2367 /** Associate a heuristic dissector with a protocol
2368  * INTERNAL USE ONLY!!!
2369  * @param protocol to associate the heuristic with
2370  * @param short_name heuristic dissector's short name
2371  */
2372 extern void proto_add_heuristic_dissector(protocol_t *protocol, const char *short_name);
2373
2374 /** Apply func to all heuristic dissectors of a protocol
2375  * @param protocol to iterate over heuristics
2376  * @param func function to execute on heuristics
2377  * @param user_data user-specific data for function
2378  */
2379 WS_DLL_PUBLIC void proto_heuristic_dissector_foreach(const protocol_t *protocol, GFunc func,
2380     gpointer user_data);
2381
2382 /** Find commonly-used protocols in a layer list.
2383  * @param layers Protocol layer list
2384  * @param is_ip Set to TRUE if the layer list contains IPv4 or IPv6, otherwise
2385  * unchanged. May be NULL.
2386  * @param is_tcp Set to TRUE if the layer list contains TCP, otherwise
2387  * unchanged. May be NULL.
2388  * @param is_udp Set to TRUE if the layer list contains UDP, otherwise
2389  * unchanged. May be NULL.
2390  * @param is_sctp Set to TRUE if the layer list contains SCTP, otherwise
2391  * unchanged. May be NULL.
2392  * @param is_tls Set to TRUE if the layer list contains SSL/TLS, otherwise
2393  * unchanged. May be NULL.
2394  * @param is_rtp Set to TRUE if the layer list contains RTP, otherwise
2395  * unchanged. May be NULL.
2396  * @param is_lte_rlc Set to TRUE if the layer list contains LTE RLC, otherwise
2397  * unchanged. May be NULL.
2398  */
2399 WS_DLL_PUBLIC void proto_get_frame_protocols(const wmem_list_t *layers,
2400       gboolean *is_ip, gboolean *is_tcp, gboolean *is_udp, gboolean *is_sctp,
2401       gboolean *is_tls, gboolean *is_rtp, gboolean *is_lte_rlc);
2402
2403 /** Check whether a protocol, specified by name, is in a layer list.
2404  * @param layers Protocol layer list
2405  * @param proto_name Name of protocol to find
2406  * @return TRUE if the protocol is found, FALSE if it isn't
2407  */
2408 WS_DLL_PUBLIC gboolean proto_is_frame_protocol(const wmem_list_t *layers, const char* proto_name);
2409
2410 /** Mark protocol with the given item number as disabled by default.
2411  @param proto_id protocol id (0-indexed) */
2412 WS_DLL_PUBLIC void proto_disable_by_default(const int proto_id);
2413
2414 /** Enable / Disable protocol of the given item number.
2415  @param proto_id protocol id (0-indexed)
2416  @param enabled enable / disable the protocol */
2417 WS_DLL_PUBLIC void proto_set_decoding(const int proto_id, const gboolean enabled);
2418
2419 /** Re-enable all protocols that are not marked as disabled by default. */
2420 WS_DLL_PUBLIC void proto_reenable_all(void);
2421
2422 /** Disable disabling/enabling of protocol of the given item number.
2423  @param proto_id protocol id (0-indexed) */
2424 WS_DLL_PUBLIC void proto_set_cant_toggle(const int proto_id);
2425
2426 /** Checks for existence any protocol or field within a tree.
2427  @param tree "Protocols" are assumed to be a child of the [empty] root node.
2428  @param id hfindex of protocol or field
2429  @return TRUE = found, FALSE = not found
2430  @todo add explanation of id parameter */
2431 extern gboolean proto_check_for_protocol_or_field(const proto_tree* tree, const int id);
2432
2433 /** Return GPtrArray* of field_info pointers for all hfindex that appear in
2434     tree. Only works with primed trees, and is fast.
2435  @param tree tree of interest
2436  @param hfindex primed hfindex
2437  @return GPtrArray pointer */
2438 WS_DLL_PUBLIC GPtrArray* proto_get_finfo_ptr_array(const proto_tree *tree, const int hfindex);
2439
2440 /** Return whether we're tracking any interesting fields.
2441     Only works with primed trees, and is fast.
2442  @param tree tree of interest
2443  @return TRUE if we're tracking interesting fields */
2444 WS_DLL_PUBLIC gboolean proto_tracking_interesting_fields(const proto_tree *tree);
2445
2446 /** Return GPtrArray* of field_info pointers for all hfindex that appear in
2447     tree. Works with any tree, primed or unprimed, and is slower than
2448     proto_get_finfo_ptr_array because it has to search through the tree.
2449  @param tree tree of interest
2450  @param hfindex index of field info of interest
2451  @return GPtrArry pointer */
2452 WS_DLL_PUBLIC GPtrArray* proto_find_finfo(proto_tree *tree, const int hfindex);
2453
2454 /** Return GPtrArray* of field_info pointer for first hfindex that appear in
2455 tree. Works with any tree, primed or unprimed, and is slower than
2456 proto_get_finfo_ptr_array because it has to search through the tree.
2457 @param tree tree of interest
2458 @param hfindex index of field info of interest
2459 @return GPtrArry pointer */
2460 WS_DLL_PUBLIC GPtrArray* proto_find_first_finfo(proto_tree *tree, const int hfindex);
2461
2462 /** Return GPtrArray* of field_info pointers containg all hfindexes that appear
2463     in tree.
2464  @param tree tree of interest
2465  @return GPtrArry pointer */
2466 WS_DLL_PUBLIC GPtrArray* proto_all_finfos(proto_tree *tree);
2467
2468 /** Dumps a glossary of the protocol registrations to STDOUT */
2469 WS_DLL_PUBLIC void proto_registrar_dump_protocols(void);
2470
2471 /** Dumps a glossary of the field value strings or true/false strings to STDOUT */
2472 WS_DLL_PUBLIC void proto_registrar_dump_values(void);
2473
2474 /** Dumps a mapping file for loading tshark output into ElasticSearch */
2475 WS_DLL_PUBLIC void proto_registrar_dump_elastic(const gchar* filter);
2476
2477 /** Dumps the number of protocol and field registrations to STDOUT.
2478  @return FALSE if we pre-allocated enough fields, TRUE otherwise. */
2479 WS_DLL_PUBLIC gboolean proto_registrar_dump_fieldcount(void);
2480
2481 /** Dumps a glossary of the protocol and field registrations to STDOUT. */
2482 WS_DLL_PUBLIC void proto_registrar_dump_fields(void);
2483
2484 /** Dumps a glossary field types and descriptive names to STDOUT */
2485 WS_DLL_PUBLIC void proto_registrar_dump_ftypes(void);
2486
2487 /** Get string representation of display field value
2488  @param field_display field display value (one of BASE_ values)
2489  @return string representation of display field value or "Unknown" if doesn't exist */
2490 WS_DLL_PUBLIC const char* proto_field_display_to_string(int field_display);
2491
2492 /** Number of elements in the tree_is_expanded array. With MSVC and a
2493  * libwireshark.dll, we need a special declaration. */
2494 WS_DLL_PUBLIC int num_tree_types;
2495
2496 /** Returns TRUE if subtrees of that type are to be expanded. */
2497 WS_DLL_PUBLIC gboolean tree_expanded(int tree_type);
2498
2499 /** Sets if subtrees of that type are to be expanded. */
2500 WS_DLL_PUBLIC void tree_expanded_set(int tree_type, gboolean value);
2501
2502 /** glib doesn't have g_ptr_array_len of all things!*/
2503 #ifndef g_ptr_array_len
2504 #define g_ptr_array_len(a)      ((a)?(a)->len:0)
2505 #endif
2506
2507 WS_DLL_PUBLIC int
2508 hfinfo_bitshift(const header_field_info *hfinfo);
2509
2510 struct epan_dissect;
2511
2512 /** Can we do a "match selected" on this field.
2513  @param finfo field_info
2514  @param edt epan dissecting
2515  @return TRUE if we can do a "match selected" on the field, FALSE otherwise. */
2516 WS_DLL_PUBLIC gboolean
2517 proto_can_match_selected(field_info *finfo, struct epan_dissect *edt);
2518
2519 /** Construct a "match selected" display filter string.
2520  @param finfo field_info
2521  @param edt epan dissecting
2522  @return the wmem NULL alloced display filter string.  Needs to be freed with wmem_free(NULL, ...) */
2523 WS_DLL_PUBLIC char*
2524 proto_construct_match_selected_string(field_info *finfo, struct epan_dissect *edt);
2525
2526 /** Find field from offset in tvb.
2527  @param tree tree of interest
2528  @param offset offset in the tvb
2529  @param tvb the tv buffer
2530  @return the corresponding field_info */
2531 WS_DLL_PUBLIC field_info*
2532 proto_find_field_from_offset(proto_tree *tree, guint offset, tvbuff_t *tvb);
2533
2534 /** Find undecoded bytes in a tree
2535  @param tree tree of interest
2536  @param length the length of the frame
2537  @return an array to be used as bitmap of decoded bytes */
2538 WS_DLL_PUBLIC gchar*
2539 proto_find_undecoded_data(proto_tree *tree, guint length);
2540
2541 /** This function will dissect a sequence of bytes that describe a bitmask.
2542  @param tree the tree to append this item to
2543  @param tvb the tv buffer of the current data
2544  @param offset start of data in tvb
2545  @param hf_hdr an 8/16/24/32/40/48/56/64 bit integer that describes the
2546         bitmask to be dissected.
2547         This field will form an expansion under which the individual fields
2548         of the bitmask are dissected and displayed.
2549         This field must be of the type FT_[U]INT{8|16|24|32|40|48|56|64}.
2550  @param ett subtree index
2551  @param fields an array of pointers to int that lists all the fields of the
2552         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2553         or another integer of the same type/size as hf_hdr with a mask specified.
2554         This array is terminated by a NULL entry.
2555         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2556         FT_integer fields that have a value_string attached will have the
2557         matched string displayed on the expansion line.
2558  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2559  @return the newly created item */
2560 WS_DLL_PUBLIC proto_item *
2561 proto_tree_add_bitmask(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2562         const int hf_hdr, const gint ett, const int **fields, const guint encoding);
2563
2564 /** This function will dissect a sequence of bytes that describe a bitmask.
2565     The value of the integer containing the bitmask is returned through
2566     a pointer.
2567  @param tree the tree to append this item to
2568  @param tvb the tv buffer of the current data
2569  @param offset start of data in tvb
2570  @param hf_hdr an 8/16/24/32/40/48/56/64 bit integer that describes the
2571         bitmask to be dissected.
2572         This field will form an expansion under which the individual fields
2573         of the bitmask are dissected and displayed.
2574         This field must be of the type FT_[U]INT{8|16|24|32|40|48|56|64}.
2575  @param ett subtree index
2576  @param fields an array of pointers to int that lists all the fields of the
2577         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2578         or another integer of the same type/size as hf_hdr with a mask specified.
2579         This array is terminated by a NULL entry.
2580         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2581         FT_integer fields that have a value_string attached will have the
2582         matched string displayed on the expansion line.
2583  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2584  @param[out] retval points to a guint64 which will be set
2585  @return the newly created item, and *retval is set to the decoded value masked/shifted according to bitmask */
2586 WS_DLL_PUBLIC proto_item *
2587 proto_tree_add_bitmask_ret_uint64(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2588         const int hf_hdr, const gint ett, const int **fields,
2589         const guint encoding, guint64 *retval);
2590
2591 /** This function will dissect a sequence of bytes that describe a bitmask.
2592     This has "filterable" bitmask header functionality of proto_tree_add_bitmask
2593     with the ability to control what data is appended to the header like
2594     proto_tree_add_bitmask_text
2595  @param tree the tree to append this item to
2596  @param tvb the tv buffer of the current data
2597  @param offset start of data in tvb
2598  @param hf_hdr an 8/16/24/32/40/48/56/64 bit integer that describes the
2599         bitmask to be dissected.
2600         This field will form an expansion under which the individual fields
2601         of the bitmask are dissected and displayed.
2602         This field must be of the type FT_[U]INT{8|16|24|32|40|48|56|64}.
2603  @param ett subtree index
2604  @param fields an array of pointers to int that lists all the fields of the
2605         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2606         or another integer of the same type/size as hf_hdr with a mask specified.
2607         This array is terminated by a NULL entry.
2608         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2609         FT_integer fields that have a value_string attached will have the
2610         matched string displayed on the expansion line.
2611  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2612  @param flags bitmask field using BMT_NO_* flags to determine behavior
2613  @return the newly created item */
2614 WS_DLL_PUBLIC proto_item *
2615 proto_tree_add_bitmask_with_flags(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2616         const int hf_hdr, const gint ett, const int **fields, const guint encoding, const int flags);
2617
2618 /** This function will dissect a sequence of bytes that describe a bitmask.
2619     This has "filterable" bitmask header functionality of proto_tree_add_bitmask
2620     with the ability to control what data is appended to the header like
2621     proto_tree_add_bitmask_text
2622     The value of the integer containing the bitmask is returned through
2623     a pointer.
2624  @param tree the tree to append this item to
2625  @param tvb the tv buffer of the current data
2626  @param offset start of data in tvb
2627  @param hf_hdr an 8/16/24/32/40/48/56/64 bit integer that describes the
2628         bitmask to be dissected.
2629         This field will form an expansion under which the individual fields
2630         of the bitmask are dissected and displayed.
2631         This field must be of the type FT_[U]INT{8|16|24|32|40|48|56|64}.
2632  @param ett subtree index
2633  @param fields an array of pointers to int that lists all the fields of the
2634         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2635         or another integer of the same type/size as hf_hdr with a mask specified.
2636         This array is terminated by a NULL entry.
2637         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2638         FT_integer fields that have a value_string attached will have the
2639         matched string displayed on the expansion line.
2640  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2641  @param flags bitmask field using BMT_NO_* flags to determine behavior
2642  @param[out] retval points to a guint64 which will be set
2643  @return the newly created item, and *retval is set to the decoded value masked/shifted according to bitmask */
2644 WS_DLL_PUBLIC proto_item *
2645 proto_tree_add_bitmask_with_flags_ret_uint64(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2646         const int hf_hdr, const gint ett, const int **fields,
2647         const guint encoding, const int flags, guint64 *retval);
2648
2649 /** This function will dissect a value that describe a bitmask. Similar to proto_tree_add_bitmask(),
2650     but with a passed in value (presumably because it can't be retrieved directly from tvb)
2651  @param tree the tree to append this item to
2652  @param tvb the tv buffer of the current data
2653  @param offset start of data in tvb
2654  @param hf_hdr an 8/16/24/32/64 bit integer that describes the bitmask to be dissected.
2655         This field will form an expansion under which the individual fields of the
2656         bitmask is dissected and displayed.
2657         This field must be of the type FT_[U]INT{8|16|24|32|64}.
2658  @param ett subtree index
2659  @param fields an array of pointers to int that lists all the fields of the
2660         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2661         or another integer of the same type/size as hf_hdr with a mask specified.
2662         This array is terminated by a NULL entry.
2663         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2664         FT_integer fields that have a value_string attached will have the
2665         matched string displayed on the expansion line.
2666  @param value bitmask value
2667  @return the newly created item */
2668 WS_DLL_PUBLIC proto_item *
2669 proto_tree_add_bitmask_value(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2670         const int hf_hdr, const gint ett, const int **fields, const guint64 value);
2671
2672 /** This function will dissect a value that describe a bitmask. Similar to proto_tree_add_bitmask(),
2673     but with a passed in value (presumably because it can't be retrieved directly from tvb)
2674     This has "filterable" bitmask header functionality of proto_tree_add_bitmask_value
2675     with the ability to control what data is appended to the header like
2676     proto_tree_add_bitmask_text
2677  @param tree the tree to append this item to
2678  @param tvb the tv buffer of the current data
2679  @param offset start of data in tvb
2680  @param hf_hdr an 8/16/24/32/64 bit integer that describes the bitmask to be dissected.
2681         This field will form an expansion under which the individual fields of the
2682         bitmask is dissected and displayed.
2683         This field must be of the type FT_[U]INT{8|16|24|32|64}.
2684  @param ett subtree index
2685  @param fields an array of pointers to int that lists all the fields of the
2686         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2687         or another integer of the same type/size as hf_hdr with a mask specified.
2688         This array is terminated by a NULL entry.
2689         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2690         FT_integer fields that have a value_string attached will have the
2691         matched string displayed on the expansion line.
2692  @param value bitmask value
2693  @param flags bitmask field using BMT_NO_* flags to determine behavior
2694  @return the newly created item */
2695 WS_DLL_PUBLIC proto_item *
2696 proto_tree_add_bitmask_value_with_flags(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2697         const int hf_hdr, const gint ett, const int **fields, const guint64 value, const int flags);
2698
2699 /** This function will dissect a sequence of bytes that describe a bitmask. Similar
2700     to proto_tree_add_bitmask(), but with no "header" item to group all of the fields
2701  @param tree the tree to append this item to
2702  @param tvb the tv buffer of the current data
2703  @param offset start of data in tvb
2704  @param len number of bytes of data
2705  @param fields an array of pointers to int that lists all the fields of the
2706         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2707         or another integer of the same type/size as hf_hdr with a mask specified.
2708         This array is terminated by a NULL entry.
2709         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2710         FT_integer fields that have a value_string attached will have the
2711         matched string displayed on the expansion line.
2712  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN) */
2713 WS_DLL_PUBLIC void
2714 proto_tree_add_bitmask_list(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2715                                 const int len, const int **fields, const guint encoding);
2716
2717 /** This function will dissect a value that describe a bitmask. Similar to proto_tree_add_bitmask_list(),
2718     but with a passed in value (presumably because it can't be retrieved directly from tvb)
2719  @param tree the tree to append this item to
2720  @param tvb the tv buffer of the current data
2721  @param offset start of data in tvb
2722  @param len number of bytes of data
2723  @param fields an array of pointers to int that lists all the fields of the
2724         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2725         or another integer of the same type/size as hf_hdr with a mask specified.
2726         This array is terminated by a NULL entry.
2727         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2728         FT_integer fields that have a value_string attached will have the
2729         matched string displayed on the expansion line.
2730  @param value bitmask value */
2731 WS_DLL_PUBLIC void
2732 proto_tree_add_bitmask_list_value(proto_tree *tree, tvbuff_t *tvb, const guint offset,
2733                                 const int len, const int **fields, const guint64 value);
2734
2735
2736 /** This function will dissect a sequence of bytes that describe a bitmask.
2737  @param tree the tree to append this item to
2738  @param tvb the tv buffer of the current data
2739  @param offset start of data in tvb
2740  @param len number of bytes of data
2741  @param hf_hdr an 8/16/24/32 bit integer that describes the bitmask to be dissected.
2742         This field will form an expansion under which the individual fields of the
2743         bitmask are dissected and displayed.
2744         This field must be of the type FT_[U]INT{8|16|24|32}.
2745  @param ett subtree index
2746  @param fields an array of pointers to int that lists all the fields of the
2747         bitmask. These fields can be either of the type FT_BOOLEAN for flags
2748         or another integer with a mask specified.
2749         This array is terminated by a NULL entry.
2750         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
2751         FT_integer fields that have a value_string attached will have the
2752         matched string displayed on the expansion line.
2753  @param exp expert info field used when decodable_len < len.  This also means this function
2754         should be called even when tree == NULL
2755  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2756  @return the newly created item */
2757 WS_DLL_PUBLIC proto_item *
2758 proto_tree_add_bitmask_len(proto_tree *tree, tvbuff_t *tvb, const guint offset, const guint len,
2759         const int hf_hdr, const gint ett, const int **fields, struct expert_field* exp, const guint encoding);
2760
2761 /** Add a text with a subtree of bitfields.
2762  @param tree the tree to append this item to
2763  @param tvb the tv buffer of the current data
2764  @param offset start of data in tvb
2765  @param len length of the field name
2766  @param name field name (NULL if bitfield contents should be used)
2767  @param fallback field name if none of bitfields were usable
2768  @param ett subtree index
2769  @param fields NULL-terminated array of bitfield indexes
2770  @param encoding big or little endian byte representation (ENC_BIG_ENDIAN/ENC_LITTLE_ENDIAN/ENC_HOST_ENDIAN)
2771  @param flags bitmask field
2772  @return the newly created item */
2773 WS_DLL_PUBLIC proto_item *
2774 proto_tree_add_bitmask_text(proto_tree *tree, tvbuff_t *tvb, const guint offset, const guint len,
2775         const char *name, const char *fallback,
2776         const gint ett, const int **fields, const guint encoding, const int flags);
2777
2778 #define BMT_NO_FLAGS    0x00    /**< Don't use any flags */
2779 #define BMT_NO_APPEND   0x01    /**< Don't change the title at all */
2780 #define BMT_NO_INT      0x02    /**< Don't add integral (non-boolean) fields to title */
2781 #define BMT_NO_FALSE    0x04    /**< Don't add booleans unless they're TRUE */
2782 #define BMT_NO_TFS      0x08    /**< Don't use true_false_string while formatting booleans */
2783
2784 /** Add bits to a proto_tree, using the text label registered to that item.
2785    The item is extracted from the tvbuff handed to it.
2786  @param tree the tree to append this item to
2787  @param hf_index field index. Fields for use with this function should have bitmask==0.
2788  @param tvb the tv buffer of the current data
2789  @param bit_offset start of data in tvb expressed in bits
2790  @param no_of_bits length of data in tvb expressed in bits
2791  @param encoding data encoding
2792  @return the newly created item */
2793 WS_DLL_PUBLIC proto_item *
2794 proto_tree_add_bits_item(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const guint bit_offset,
2795     const gint no_of_bits, const guint encoding);
2796
2797 /** Add bits to a proto_tree, using the text label registered to that item.
2798 *  The item is extracted from the tvbuff handed to it as a set
2799 *  of crumbs (segments) of contiguous bits, specified by an
2800 *  array of crumb_spec elements.  The crumbs are assembled to
2801 *  create the value.  There may be any number of crumbs
2802 *  specifying up to a total of 64 bits which may occur anywhere
2803 *  within the tvb. If the span of the crumbs within the tvb is 4
2804 *  octets or less, a bitmap of the crumbs is produced.
2805  @param tree the tree to append this item to
2806  @param hf_index field index. Fields for use with this function should have bitmask==0.
2807  @param tvb the tv buffer of the current data
2808  @param bit_offset of the first crumb in tvb expressed in bits
2809  @param crumb_spec pointer to crumb_spec array
2810  @param return_value if a pointer is passed here the value is returned.
2811  @return the newly created item */
2812 WS_DLL_PUBLIC proto_item *
2813 proto_tree_add_split_bits_item_ret_val(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2814     const guint bit_offset, const crumb_spec_t *crumb_spec, guint64 *return_value);
2815
2816 /** Add bitmap text for a split-bits crumb to a proto_tree,
2817 *  using the text label registered to an item. The bitmap is
2818 *  extracted from the tvbuff handed to it as a crumb (segment)
2819 *  of contiguous bits, specified by one of an array of
2820 *  crumb_spec elements. This function is normally called once
2821 *  per crumb, after the call to
2822    proto_tree_add_split_bits_item_ret_val
2823  @param tree the tree to append this item to
2824  @param hf_index field index. Fields for use with this function should have bitmask==0.
2825  @param tvb the tv buffer of the current data
2826  @param bit_offset of the first crumb in tvb expressed in bits
2827  @param crumb_spec pointer to crumb_spec array
2828  @param crumb_index into the crumb_spec array for this crumb */
2829 void
2830 proto_tree_add_split_bits_crumb(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2831     const guint bit_offset, const crumb_spec_t *crumb_spec, guint16 crumb_index);
2832
2833 /** Add bits to a proto_tree, using the text label registered to that item.
2834    The item is extracted from the tvbuff handed to it.
2835  @param tree the tree to append this item to
2836  @param hf_index field index. Fields for use with this function should have bitmask==0.
2837  @param tvb the tv buffer of the current data
2838  @param bit_offset start of data in tvb expressed in bits
2839  @param no_of_bits length of data in tvb expressed in bits
2840  @param return_value if a pointer is passed here the value is returned.
2841  @param encoding data encoding
2842  @return the newly created item */
2843 WS_DLL_PUBLIC proto_item *
2844 proto_tree_add_bits_ret_val(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2845     const guint bit_offset, const gint no_of_bits, guint64 *return_value, const guint encoding);
2846
2847 /** Add bits for a FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32
2848     header field to a proto_tree, with the format generating the
2849     string for the value and with the field name being included automatically.
2850  @param tree the tree to append this item to
2851  @param hf_index field index
2852  @param tvb the tv buffer of the current data
2853  @param bit_offset start of data in tvb expressed in bits
2854  @param no_of_bits length of data in tvb expressed in bit
2855  @param value data to display
2856  @param format printf like format string
2857  @return the newly created item */
2858 WS_DLL_PUBLIC proto_item *
2859 proto_tree_add_uint_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2860     const guint bit_offset, const gint no_of_bits, guint32 value, const char *format, ...)
2861     G_GNUC_PRINTF(7,8);
2862
2863 /** Add bits for a FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32
2864     header field to a proto_tree, with the format generating the
2865     string for the value and with the field name being included automatically.
2866  @param tree the tree to append this item to
2867  @param hf_index field index
2868  @param tvb the tv buffer of the current data
2869  @param bit_offset start of data in tvb expressed in bits
2870  @param no_of_bits length of data in tvb expressed in bit
2871  @param value data to display
2872  @param format printf like format string
2873  @return the newly created item */
2874 WS_DLL_PUBLIC proto_item *
2875 proto_tree_add_uint64_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2876     const guint bit_offset, const gint no_of_bits, guint64 value, const char *format, ...)
2877     G_GNUC_PRINTF(7,8);
2878
2879 /** Add bits for a FT_BOOLEAN header field to a proto_tree, with
2880     the format generating the string for the value and with the field
2881     name being included automatically.
2882  @param tree the tree to append this item to
2883  @param hf_index field index
2884  @param tvb the tv buffer of the current data
2885  @param bit_offset start of data in tvb expressed in bits
2886  @param no_of_bits length of data in tvb expressed in bit
2887  @param value data to display
2888  @param format printf like format string
2889  @param ... printf like parameters
2890  @return the newly created item */
2891 proto_item *
2892 proto_tree_add_boolean_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2893     const guint bit_offset, const gint no_of_bits, guint32 value, const char *format, ...)
2894     G_GNUC_PRINTF(7,8);
2895
2896 /** Add bits for a FT_BOOLEAN header field to a proto_tree, with
2897     the format generating the string for the value and with the field
2898     name being included automatically.
2899  @param tree the tree to append this item to
2900  @param hf_index field index
2901  @param tvb the tv buffer of the current data
2902  @param bit_offset start of data in tvb expressed in bits
2903  @param no_of_bits length of data in tvb expressed in bit
2904  @param value data to display
2905  @param format printf like format string
2906  @param ... printf like parameters
2907  @return the newly created item */
2908 proto_item *
2909 proto_tree_add_boolean_bits_format_value64(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2910     const guint bit_offset, const gint no_of_bits, guint64 value, const char *format, ...)
2911     G_GNUC_PRINTF(7,8);
2912
2913 /** Add bits for a FT_INT8, FT_INT16, FT_INT24 or FT_INT32
2914     header field to a proto_tree, with the format generating the
2915     string for the value and with the field name being included automatically.
2916  @param tree the tree to append this item to
2917  @param hf_index field index
2918  @param tvb the tv buffer of the current data
2919  @param bit_offset start of data in tvb expressed in bits
2920  @param no_of_bits length of data in tvb expressed in bit
2921  @param value data to display
2922  @param format printf like format string
2923  @param ... printf like parameters
2924  @return the newly created item */
2925 proto_item *
2926 proto_tree_add_int_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2927     const guint bit_offset, const gint no_of_bits, gint32 value, const char *format, ...)
2928     G_GNUC_PRINTF(7,8);
2929
2930 /** Add bits for a FT_INT8, FT_INT16, FT_INT24 or FT_INT32
2931     header field to a proto_tree, with the format generating the
2932     string for the value and with the field name being included automatically.
2933  @param tree the tree to append this item to
2934  @param hf_index field index
2935  @param tvb the tv buffer of the current data
2936  @param bit_offset start of data in tvb expressed in bits
2937  @param no_of_bits length of data in tvb expressed in bit
2938  @param value data to display
2939  @param format printf like format string
2940  @param ... printf like parameters
2941  @return the newly created item */
2942 proto_item *
2943 proto_tree_add_int64_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2944     const guint bit_offset, const gint no_of_bits, gint64 value, const char *format, ...)
2945     G_GNUC_PRINTF(7,8);
2946
2947 /** Add bits for a FT_FLOAT header field to a proto_tree, with
2948     the format generating the string for the value and with the field
2949     name being included automatically.
2950  @param tree the tree to append this item to
2951  @param hf_index field index
2952  @param tvb the tv buffer of the current data
2953  @param bit_offset start of data in tvb expressed in bits
2954  @param no_of_bits length of data in tvb expressed in bit
2955  @param value data to display
2956  @param format printf like format string
2957  @param ... printf like parameters
2958  @return the newly created item */
2959 proto_item *
2960 proto_tree_add_float_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb,
2961     const guint bit_offset, const gint no_of_bits, float value, const char *format, ...)
2962     G_GNUC_PRINTF(7,8);
2963
2964
2965 /** Add a FT_STRING with ENC_3GPP_TS_23_038_7BITS encoding to a proto_tree.
2966  @param tree the tree to append this item to
2967  @param hfindex field index
2968  @param tvb the tv buffer of the current data
2969  @param bit_offset start of data in tvb expressed in bits
2970  @param no_of_chars number of 7bits characters to display
2971  @return the newly created item */
2972 WS_DLL_PUBLIC proto_item *
2973 proto_tree_add_ts_23_038_7bits_item(proto_tree *tree, const int hfindex, tvbuff_t *tvb,
2974     const guint bit_offset, const gint no_of_chars);
2975
2976 /** Add a FT_STRING with ENC_ASCII_7BITS encoding to a proto_tree.
2977  @param tree the tree to append this item to
2978  @param hfindex field index
2979  @param tvb the tv buffer of the current data
2980  @param bit_offset start of data in tvb expressed in bits
2981  @param no_of_chars number of 7bits characters to display
2982  @return the newly created item */
2983 WS_DLL_PUBLIC proto_item *
2984 proto_tree_add_ascii_7bits_item(proto_tree *tree, const int hfindex, tvbuff_t *tvb,
2985     const guint bit_offset, const gint no_of_chars);
2986
2987 /** Add a checksum filed to a proto_tree.
2988  This standardizes the display of a checksum field as well as any
2989  status and expert info supporting it.
2990  @param tree the tree to append this item to
2991  @param tvb the tv buffer of the current data
2992  @param offset start of data in tvb
2993  @param hf_checksum checksum field index
2994  @param hf_checksum_status optional checksum status field index.  If none
2995  exists, just pass -1
2996  @param bad_checksum_expert optional expert info for a bad checksum.  If
2997  none exists, just pass NULL
2998  @param pinfo Packet info used for optional expert info.  If unused, NULL can
2999  be passed
3000  @param computed_checksum Checksum to verify against
3001  @param encoding data encoding of checksum from tvb
3002  @param flags bitmask field of PROTO_CHECKSUM_ options
3003  @return the newly created item */
3004 WS_DLL_PUBLIC proto_item *
3005 proto_tree_add_checksum(proto_tree *tree, tvbuff_t *tvb, const guint offset,
3006         const int hf_checksum, const int hf_checksum_status, struct expert_field* bad_checksum_expert,
3007         packet_info *pinfo, guint32 computed_checksum, const guint encoding, const guint flags);
3008
3009 typedef enum
3010 {
3011     PROTO_CHECKSUM_E_BAD = 0,
3012     PROTO_CHECKSUM_E_GOOD,
3013     PROTO_CHECKSUM_E_UNVERIFIED,
3014     PROTO_CHECKSUM_E_NOT_PRESENT
3015 } proto_checksum_enum_e;
3016
3017 #define PROTO_CHECKSUM_NO_FLAGS     0x00    /**< Don't use any flags */
3018 #define PROTO_CHECKSUM_VERIFY       0x01    /**< Compare against computed checksum */
3019 #define PROTO_CHECKSUM_GENERATED    0x02    /**< Checksum is generated only */
3020 #define PROTO_CHECKSUM_IN_CKSUM     0x04    /**< Internet checksum routine used for computation */
3021 #define PROTO_CHECKSUM_ZERO         0x08    /**< Computed checksum must be zero (but correct checksum can't be calculated) */
3022 #define PROTO_CHECKSUM_NOT_PRESENT  0x10    /**< Checksum field is not present (Just populates status field) */
3023
3024 WS_DLL_PUBLIC const value_string proto_checksum_vals[];
3025
3026 /** Check if given string is a valid field name
3027  @param field_name the field name to check
3028  @return 0 if valid, else first illegal character */
3029 WS_DLL_PUBLIC guchar
3030 proto_check_field_name(const gchar *field_name);
3031
3032
3033 /** Check if given string is a valid field name
3034  @param tree the tree to append this item to
3035  @param field_id the field id used for custom column
3036  @param occurrence the occurrence of the field used for custom column
3037  @param result the buffer to fill with the field string
3038  @param expr the filter expression
3039  @param size the size of the string buffer */
3040 const gchar *
3041 proto_custom_set(proto_tree* tree, GSList *field_id,
3042                              gint occurrence,
3043                              gchar *result,
3044                              gchar *expr, const int size );
3045
3046 /* #define HAVE_HFI_SECTION_INIT */
3047
3048 #ifdef HAVE_HFI_SECTION_INIT
3049  #define HFI_INIT(proto) __attribute__((section( "_data_" G_STRINGIFY(proto)))) __attribute__((aligned(sizeof(void *))))
3050
3051  #define proto_register_fields(proto, hfi, count) \
3052     do { \
3053     extern header_field_info __start__data_ ##proto[]; \
3054     extern header_field_info __stop__data_ ##proto[]; \
3055 \
3056     proto_register_fields_section(proto, __start__data_ ##proto, (int) (__stop__data_ ##proto - __start__data_ ##proto)); \
3057     } while(0)
3058 #else
3059  #define HFI_INIT(proto)
3060  #define proto_register_fields(proto, hfi, count) \
3061     proto_register_fields_manual(proto, hfi, count)
3062 #endif
3063
3064 #ifdef NEW_PROTO_TREE_API
3065 #define proto_tree_add_item(tree, hfinfo, tvb, start, length, encoding) \
3066     proto_tree_add_item_new(tree, hfinfo, tvb, start, length, encoding)
3067
3068 #define proto_tree_add_item_ret_length(tree, hfinfo, tvb, start, length, encoding, retval) \
3069     proto_tree_add_item_new_ret_length(tree, hfinfo, tvb, start, length, encoding, retval)
3070
3071 #define proto_tree_add_boolean(tree, hfinfo, tvb, start, length, value) \
3072     proto_tree_add_boolean(tree, (hfinfo)->id, tvb, start, length, value)
3073
3074 #define proto_tree_add_boolean_format(tree, hfinfo, tvb, start, length, value, format, ...) \
3075     proto_tree_add_boolean_format(tree, (hfinfo)->id, tvb, start, length, value, format, __VA_ARGS__)
3076
3077 #define proto_tree_add_string(tree, hfinfo, tvb, start, length, value) \
3078     proto_tree_add_string(tree, (hfinfo)->id, tvb, start, length, value)
3079
3080 #define proto_tree_add_string_format(tree, hfinfo, tvb, start, length, value, format, ...) \
3081     proto_tree_add_string_format(tree, (hfinfo)->id, tvb, start, length, value, format,  __VA_ARGS__)
3082
3083 #define proto_tree_add_item_ret_string(tree, hfinfo, tvb, start, length, encoding, scope, retval) \
3084     proto_tree_add_item_ret_string(tree, (hfinfo)->id, tvb, start, length, encoding, scope, retval)
3085
3086 #define proto_tree_add_time(tree, hfinfo, tvb, start, length, value) \
3087     proto_tree_add_time(tree, (hfinfo)->id, tvb, start, length, value)
3088
3089 #define proto_tree_add_int(tree, hfinfo, tvb, start, length, value) \
3090     proto_tree_add_int(tree, (hfinfo)->id, tvb, start, length, value)
3091
3092 #define proto_tree_add_int_format(tree, hfinfo, tvb, start, length, value, format, ...) \
3093     proto_tree_add_int_format(tree, (hfinfo)->id, tvb, start, length, value, format, __VA_ARGS__)
3094
3095 #define proto_tree_add_uint(tree, hfinfo, tvb, start, length, value) \
3096     proto_tree_add_uint(tree, (hfinfo)->id, tvb, start, length, value)
3097
3098 #define proto_tree_add_uint_format(tree, hfinfo, tvb, start, length, value, format, ...) \
3099     proto_tree_add_uint_format(tree, (hfinfo)->id, tvb, start, length, value, format, __VA_ARGS__)
3100
3101 #define proto_tree_add_uint_format_value(tree, hfinfo, tvb, start, length, value, format, ...) \
3102     proto_tree_add_uint_format_value(tree, (hfinfo)->id, tvb, start, length, value, format, __VA_ARGS__)
3103
3104 #define proto_tree_add_item_ret_uint(tree, hfinfo, tvb, start, length, encoding, retval) \
3105     proto_tree_add_item_ret_uint(tree, (hfinfo)->id, tvb, start, length, encoding, retval)
3106
3107 #define proto_tree_add_uint64(tree, hfinfo, tvb, start, length, value) \
3108     proto_tree_add_uint64(tree, (hfinfo)->id, tvb, start, length, value)
3109
3110 #define proto_tree_add_float(tree, hfinfo, tvb, start, length, value) \
3111     proto_tree_add_float(tree, (hfinfo)->id, tvb, start, length, value)
3112
3113 #define proto_tree_add_float_format_value(tree, hfinfo, tvb, start, length, value, format, ...) \
3114     proto_tree_add_float_format_value(tree, (hfinfo)->id, tvb, start, length, value, format, __VA_ARGS__)
3115
3116 #define proto_tree_add_double(tree, hfinfo, tvb, start, length, value) \
3117     proto_tree_add_double(tree, (hfinfo)->id, tvb, start, length, value)
3118
3119 #define proto_tree_add_bytes_format(tree, hfinfo, tvb, start, length, format, ...) \
3120     proto_tree_add_bytes_format(tree, (hfinfo)->id, tvb, start, length, format, __VA_ARGS__)
3121
3122 #define proto_tree_add_bytes_format_value(tree, hfinfo, tvb, start, length, format, ...) \
3123     proto_tree_add_bytes_format_value(tree, (hfinfo)->id, tvb, start, length, format, __VA_ARGS__)
3124
3125 #define proto_tree_add_bitmask(tree, tvb, start, hfinfo, ett, fields, encoding) \
3126     proto_tree_add_bitmask(tree, tvb, start, (hfinfo)->id, ett, fields, encoding)
3127
3128 #define proto_tree_add_bitmask_with_flags(tree, tvb, start, hfinfo, ett, fields, encoding, flags) \
3129     proto_tree_add_bitmask_with_flags(tree, tvb, start, (hfinfo)->id, ett, fields, encoding, flags)
3130
3131 #define proto_tree_add_bitmask_with_flags_ret_uint64(tree, tvb, start, hfinfo, ett, fields, encoding, flags, retval) \
3132     proto_tree_add_bitmask_with_flags_ret_uint64(tree, tvb, start, (hfinfo)->id, ett, fields, encoding, flags, retval)
3133
3134 #define proto_tree_add_none_format(tree, hfinfo, tvb, start, length, format, ...) \
3135     proto_tree_add_none_format(tree, (hfinfo)->id, tvb, start, length, format, __VA_ARGS__)
3136
3137 #define proto_tree_add_checksum(tree, tvb, offset, hf_checksum, hf_checksum_status, \
3138         bad_checksum_expert, pinfo, computed_checksum, encoding, flags) \
3139     proto_tree_add_checksum(tree, tvb, offset, (hf_checksum)->id, hf_checksum_status, \
3140         bad_checksum_expert, pinfo, computed_checksum, encoding, flags)
3141
3142 #endif
3143
3144 /** @} */
3145
3146 #ifdef __cplusplus
3147 }
3148 #endif /* __cplusplus */
3149
3150 #endif /* proto.h */
3151
3152 /*
3153  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
3154  *
3155  * Local variables:
3156  * c-basic-offset: 4
3157  * tab-width: 8
3158  * indent-tabs-mode: nil
3159  * End:
3160  *
3161  * vi: set shiftwidth=4 tabstop=8 expandtab:
3162  * :indentSize=4:tabSize=8:noTabs=true:
3163  */