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