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