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