epan/proto.h

   1 /* proto.h
   2  * Definitions for protocol display
   3  *
   4  * $Id$
   5  *
   6  * Wireshark - Network traffic analyzer
   7  * By Gerald Combs <gerald@wireshark.org>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23  */
  24
  25
  26 /*! @file proto.h
  27     The protocol tree related functions.<BR>
  28     A protocol tree will hold all necessary data to display the whole dissected packet.
  29     Creating a protocol tree is done in a two stage process:
  30     A static part at program startup, and a dynamic part when the dissection with the real packet data is done.<BR>
  31     The "static" information is provided by creating a hf_register_info hf[] array, and register it using the
  32     proto_register_field_array() function. This is usually done at dissector registering.<BR>
  33     The "dynamic" information is added to the protocol tree by calling one of the proto_tree_add_...() functions,
  34     e.g. proto_tree_add_bytes().
  35 */
  36
  37 #ifndef __PROTO_H__
  38 #define __PROTO_H__
  39
  40 #ifdef HAVE_STDARG_H
  41 # include <stdarg.h>
  42 #else
  43 # include <varargs.h>
  44 #endif
  45
  46 #include <glib.h>
  47
  48 #include "ipv4.h"
  49 #include "nstime.h"
  50 #include "time_fmt.h"
  51 #include "tvbuff.h"
  52 #include "ftypes/ftypes.h"
  53 #include "register.h"
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif /* __cplusplus */
  58
  59 /** The header-field index for the special text pseudo-field. Exported by libwireshark.dll */
  60 WS_VAR_IMPORT int hf_text_only;
  61
  62 /** the maximum length of a protocol field string representation */
  63 #define ITEM_LABEL_LENGTH       240
  64
  65 struct _value_string;
  66
  67 /** Make a const value_string[] look like a _value_string pointer, used to set header_field_info.strings */
  68 #define VALS(x) (const struct _value_string*)(x)
  69
  70 /** Make a const true_false_string[] look like a _true_false_string pointer, used to set header_field_info.strings */
  71 #define TFS(x)  (const struct true_false_string*)(x)
  72
  73 typedef void (*custom_fmt_func_t)(gchar *, guint32);
  74
  75 /** Make a const range_string[] look like a _range_string pointer, used to set
  76  * header_field_info.strings */
  77 #define RVALS(x) (const struct _range_string*)(x)
  78
  79 struct _protocol;
  80
  81 /** Structure for information about a protocol */
  82 typedef struct _protocol protocol_t;
  83
  84 /** check protocol activation
  85  * @todo this macro looks like a hack */
  86 #define CHECK_DISPLAY_AS_X(x_handle,index, tvb, pinfo, tree) {  \
  87         if (!proto_is_protocol_enabled(find_protocol_by_id(index))) {   \
  88                 call_dissector(x_handle,tvb, pinfo, tree);              \
  89                 return;                                                 \
  90         }                                                               \
  91   }
  92
  93 /** Macro used for reporting errors in dissectors; it throws a
  94  * DissectorError exception, with the string passed as an argument
  95  * as the message for the exception, so that it can show up in
  96  * the Info column and the protocol tree.
  97  *
  98  * If that string is dynamically allocated, it should be allocated with
  99  * ep_alloc(); using ep_strdup_printf() would work.
 100  *
 101  * If the WIRESHARK_ABORT_ON_DISSECTOR_BUG environment variable is set,
 102  * it will call abort(), instead, to make it easier to get a stack trace.
 103  *
 104  * @param message string to use as the message
 105  */
 106 #define REPORT_DISSECTOR_BUG(message)  \
 107   ((getenv("WIRESHARK_ABORT_ON_DISSECTOR_BUG") != NULL) ? \
 108     abort() : \
 109     THROW_MESSAGE(DissectorError, message))
 110
 111 /** Macro used for assertions in dissectors; it doesn't abort, it just
 112  * throws a DissectorError exception, with the assertion failure
 113  * message as a parameter, so that it can show up in the protocol tree.
 114  *
 115  * @param expression expression to test in the assertion
 116  */
 117 #define DISSECTOR_ASSERT(expression)  \
 118   ((void) ((expression) ? (void)0 : \
 119    __DISSECTOR_ASSERT (expression, __FILE__, __LINE__)))
 120
 121 #if 0
 122 /* win32: using a debug breakpoint (int 3) can be very handy while debugging,
 123  * as the assert handling of GTK/GLib is currently not very helpful */
 124 #define DISSECTOR_ASSERT(expression)  \
 125 { if(!(expression)) _asm { int 3}; }
 126 #endif
 127
 128 /** Same as DISSECTOR_ASSERT(), but will throw DissectorError exception
 129  * unconditionally, much like GLIB's g_assert_not_reached works.
 130  */
 131 #define DISSECTOR_ASSERT_NOT_REACHED()  \
 132   (REPORT_DISSECTOR_BUG( \
 133     ep_strdup_printf("%s:%u: failed assertion \"DISSECTOR_ASSERT_NOT_REACHED\"", \
 134      __FILE__, __LINE__)))
 135
 136 #define __DISSECTOR_ASSERT_STRINGIFY(s) # s
 137
 138 #define __DISSECTOR_ASSERT(expression, file, lineno)  \
 139   (REPORT_DISSECTOR_BUG( \
 140     ep_strdup_printf("%s:%u: failed assertion \"%s\"", \
 141      file, lineno, __DISSECTOR_ASSERT_STRINGIFY(expression))))
 142
 143 /*
 144  * The representation of a field of a particular type may involve more
 145  * than just whether it's big-endian or little-endian and its size.
 146  *
 147  * For integral values, that's it, as 99.9999999999999% of the machines
 148  * out there are 2's complement binary machines with 8-bit bytes,
 149  * so the protocols out there expect that and, for example, any Unisys
 150  * 2200 series machines out there just have to translate between 2's
 151  * complement and 1's complement (and nobody's put any IBM 709x's on
 152  * any networks lately :-)).
 153  *
 154  * However:
 155  *
 156  *      for floating-point numbers, in addition to IEEE decimal
 157  *      floating-point, there's also IBM System/3x0 and PDP-11/VAX
 158  *      floating-point - most protocols use IEEE binary, but DCE RPC
 159  *      can use other formats if that's what the sending host uses;
 160  *
 161  *      for character strings, there are various character encodings
 162  *      (various ISO 646 sets, ISO 8859/x, various other national
 163  *      standards, various DOS and Windows encodings, various Mac
 164  *      encodings, UTF-8, UTF-16, other extensions to ASCII, EBCDIC,
 165  *      etc.);
 166  *
 167  *      for absolute times, there's UNIX time_t, UNIX time_t followed
 168  *      by 32-bit microseconds, UNIX time_t followed by 32-bit
 169  *      nanoseconds, DOS date/time, Windows FILETIME, NTP time, etc..
 170  *
 171  * We might also, in the future, want to allow a field specifier to
 172  * indicate the representation of the field, or at least its default
 173  * representation, as most fields in most protocols always use the
 174  * same representation (although that's not true of all fields, so we
 175  * still need to be able to specify that at run time).
 176  *
 177  * So, for now, we define REP_BIG_ENDIAN and REP_LITTLE_ENDIAN as
 178  * bit flags, to be combined, in the future, with other information
 179  * to specify the representation in the last argument to
 180  * proto_tree_add_item(), and possibly to specify in a field
 181  * definition (e.g., ORed in with the type value).
 182  *
 183  * Currently, proto_tree_add_item() treats its last argument as a
 184  * Boolean - if it's zero, the field is big-endian, and if it's non-zero,
 185  * the field is little-endian - and other code in epan/proto.c does
 186  * the same.  We therefore define REP_BIG_ENDIAN as 0x00000000 and
 187  * REP_LITTLE_ENDIAN as 0x80000000 - we're using the high-order bit
 188  * so that we could put a field type and/or a value such as a character
 189  * encoding in the lower bits.
 190  *
 191  * For protocols (FT_PROTOCOL), aggregate items with subtrees (FT_NONE),
 192  * opaque byte-array fields (FT_BYTES), and other fields where there
 193  * is no choice of representation (either because it's "just a bucket
 194  * of bytes" or because the representation is completely fixed), we
 195  * have REP_NA (for "Not Applicable").
 196  */
 197 #define REP_BIG_ENDIAN          0x00000000
 198 #define REP_LITTLE_ENDIAN       0x80000000
 199
 200 #define REP_NA                  0x00000000
 201
 202 /* Values for header_field_info.display */
 203
 204 /* For integral types, the display format is a base_display_e value
 205  * possibly ORed with BASE_RANGE_STRING. */
 206
 207 /* BASE_DISPLAY_E_MASK selects the base_display_e value.  Its current
 208  * value means that we may have at most 16 base_display_e values. */
 209 #define BASE_DISPLAY_E_MASK 0x0F
 210
 211 typedef enum {
 212         BASE_NONE,      /**< none */
 213         BASE_DEC,       /**< decimal */
 214         BASE_HEX,       /**< hexadecimal */
 215         BASE_OCT,       /**< octal */
 216         BASE_DEC_HEX,   /**< decimal (hexadecimal) */
 217         BASE_HEX_DEC,   /**< hexadecimal (decimal) */
 218         BASE_CUSTOM     /**< call custom routine (in ->strings) to format */
 219 } base_display_e;
 220
 221 /* Following constants have to be ORed with a base_display_e when dissector
 222  * want to use specials MACROs (for the moment, only RVALS) for a
 223  * header_field_info */
 224 #define BASE_RANGE_STRING 0x10
 225 #define BASE_EXT_STRING 0x20
 226
 227 /* BASE_ values that cause the field value to be displayed twice */
 228 #define IS_BASE_DUAL(b) ((b)==BASE_DEC_HEX||(b)==BASE_HEX_DEC)
 229
 230 /* For FT_ABSOLUTE_TIME, the display format is an absolute_time_display_e
 231  * as per time_fmt.h. */
 232
 233 typedef enum {
 234     HF_REF_TYPE_NONE,       /**< Field is not referenced */
 235     HF_REF_TYPE_INDIRECT,   /**< Field is indirectly referenced (only applicable for FT_PROTOCOL) via. its child */
 236     HF_REF_TYPE_DIRECT      /**< Field is directly referenced */
 237 } hf_ref_type;
 238
 239 /** information describing a header field */
 240 typedef struct _header_field_info header_field_info;
 241
 242 /** information describing a header field */
 243 struct _header_field_info {
 244         /* ---------- set by dissector --------- */
 245         const char              *name;           /**< full name of this field */
 246         const char              *abbrev;         /**< abbreviated name of this field */
 247         enum ftenum              type;           /**< field type, one of FT_ (from ftypes.h) */
 248         int                      display;        /**< one of BASE_, or field bit-width if FT_BOOLEAN and non-zero bitmask */
 249         const void              *strings;        /**< value_string, range_string or true_false_string,
 250                                                       typically converted by VALS(), RVALS() or TFS().
 251                                                       If this is an FT_PROTOCOL then it points to the
 252                                                       associated protocol_t structure */
 253         guint32                  bitmask;        /**< bitmask of interesting bits */
 254         const char              *blurb;          /**< Brief description of field */
 255
 256         /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */
 257         int                      id;             /**< Field ID */
 258         int                      parent;         /**< parent protocol tree */
 259         hf_ref_type              ref_type;       /**< is this field referenced by a filter */
 260         int                      bitshift;       /**< bits to shift */
 261         header_field_info       *same_name_next; /**< Link to next hfinfo with same abbrev */
 262         header_field_info       *same_name_prev; /**< Link to previous hfinfo with same abbrev */
 263 };
 264
 265 /**
 266  * HFILL initializes all the "set by proto routines" fields in a
 267  * _header_field_info. If new fields are added or removed, it should
 268  * be changed as necessary.
 269  */
 270 #define HFILL 0, 0, HF_REF_TYPE_NONE, 0, NULL, NULL
 271
 272 /** Used when registering many fields at once, using proto_register_field_array() */
 273 typedef struct hf_register_info {
 274         int                     *p_id;           /**< written to by register() function */
 275         header_field_info        hfinfo;         /**< the field info to be registered */
 276 } hf_register_info;
 277
 278
 279
 280
 281 /** string representation, if one of the proto_tree_add_..._format() functions used */
 282 typedef struct _item_label_t {
 283         char representation[ITEM_LABEL_LENGTH];
 284 } item_label_t;
 285
 286
 287 /** Contains the field information for the proto_item. */
 288 typedef struct field_info {
 289         header_field_info       *hfinfo;          /**< pointer to registered field information */
 290         gint                     start;           /**< current start of data in field_info.ds_tvb */
 291         gint                     length;          /**< current data length of item in field_info.ds_tvb */
 292         gint                     appendix_start;  /**< start of appendix data */
 293         gint                     appendix_length; /**< length of appendix data */
 294         gint                     tree_type;       /**< one of ETT_ or -1 */
 295         item_label_t            *rep;             /**< string for GUI tree */
 296         guint32                  flags;           /**< bitfield like FI_GENERATED, ... */
 297         tvbuff_t                *ds_tvb;          /**< data source tvbuff */
 298         fvalue_t                 value;
 299 } field_info;
 300
 301
 302 /*
 303  * Flag fields.  Do not assign values greater than 0x00000080 unless you
 304  * shuffle the expert information upward; see below.
 305  */
 306
 307 /** The protocol field should not be shown in the tree (it's used for filtering only),
 308  * used in field_info.flags. */
 309 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN!
 310    A user cannot tell by looking at the packet detail that the field exists
 311    and that they can filter on its value. */
 312 #define FI_HIDDEN               0x00000001
 313 /** The protocol field should be displayed as "generated by Wireshark",
 314  * used in field_info.flags. */
 315 #define FI_GENERATED            0x00000002
 316 /** The protocol field is actually a URL */
 317 #define FI_URL                  0x00000004
 318
 319 /** The protocol field value is in little endian */
 320 #define FI_LITTLE_ENDIAN        0x00000008
 321 /** The protocol field value is in big endian */
 322 #define FI_BIG_ENDIAN           0x00000010
 323 /** Field value start from nth bit (values from 0x20 - 0x100) */
 324 #define FI_BITS_OFFSET(n)        ((n & 7) << 5)
 325 /** Field value takes n bits (values from 0x100 - 0x4000) */
 326 /* if 0, it means that field takes fi->length * 8 */
 327 #define FI_BITS_SIZE(n)         ((n & 63) << 8)
 328
 329 /** convenience macro to get field_info.flags */
 330 #define FI_GET_FLAG(fi, flag) ((fi) ? (fi->flags & flag) : 0)
 331 /** convenience macro to set field_info.flags */
 332 #define FI_SET_FLAG(fi, flag) \
 333     do { \
 334       if (fi) \
 335         (fi)->flags = (fi)->flags | (flag); \
 336     } while(0)
 337
 338 #define FI_GET_BITS_OFFSET(fi) (FI_GET_FLAG(fi, FI_BITS_OFFSET(7)) >> 5)
 339 #define FI_GET_BITS_SIZE(fi)   (FI_GET_FLAG(fi, FI_BITS_SIZE(63)) >> 8)
 340
 341 /** One of these exists for the entire protocol tree. Each proto_node
 342  * in the protocol tree points to the same copy. */
 343 typedef struct {
 344     GHashTable  *interesting_hfids;
 345     gboolean    visible;
 346     gboolean    fake_protocols;
 347     gint        count;
 348 } tree_data_t;
 349
 350 /** Each proto_tree, proto_item is one of these. */
 351 typedef struct _proto_node {
 352         struct _proto_node *first_child;
 353         struct _proto_node *last_child;
 354         struct _proto_node *next;
 355         struct _proto_node *parent;
 356         field_info  *finfo;
 357         tree_data_t *tree_data;
 358 } proto_node;
 359
 360 /** A protocol tree element. */
 361 typedef proto_node proto_tree;
 362 /** A protocol item element. */
 363 typedef proto_node proto_item;
 364
 365 /*
 366  * Expert information.
 367  * This is in the flags field; we allocate this from the top down,
 368  * so as not to collide with FI_ flags, which are allocated from
 369  * the bottom up.
 370  */
 371
 372 /* expert severities */
 373 #define PI_SEVERITY_MASK        0x00000E00      /* mask usually for internal use only! */
 374 /** Usual workflow, e.g. TCP connection establishing */
 375 #define PI_CHAT                 0x00000200
 376 /** Notable messages, e.g. an application returned an "usual" error code like HTTP 404 */
 377 #define PI_NOTE                 0x00000400
 378 /** Warning, e.g. application returned an "unusual" error code */
 379 #define PI_WARN                 0x00000600
 380 /** Serious problems, e.g. [Malformed Packet] */
 381 #define PI_ERROR                0x00000800
 382
 383 /* expert "event groups" */
 384 #define PI_GROUP_MASK           0xFFFFF000      /* mask usually for internal use only! */
 385 /** The protocol field has a bad checksum, usually PI_WARN */
 386 #define PI_CHECKSUM             0x00001000
 387 /** The protocol field indicates a sequence problem (e.g. TCP window is zero) */
 388 #define PI_SEQUENCE             0x00002000
 389 /** The protocol field indicates a bad application response code (e.g. HTTP 404), usually PI_NOTE */
 390 #define PI_RESPONSE_CODE        0x00004000
 391 /** The protocol field indicates an application request (e.g. File Handle == xxxx), usually PI_CHAT */
 392 #define PI_REQUEST_CODE         0x00005000
 393 /** The data is undecoded, the protocol dissection is incomplete here, usually PI_WARN */
 394 #define PI_UNDECODED            0x00008000
 395 /** The protocol field indicates a reassemble (e.g. DCE/RPC defragmentation), usually PI_CHAT (or PI_ERROR) */
 396 #define PI_REASSEMBLE           0x00010000
 397 /** The packet data is malformed, the dissector has "given up", usually PI_ERROR */
 398 #define PI_MALFORMED            0x00020000
 399 /** A generic debugging message (shouldn't remain in production code!), usually PI_ERROR */
 400 #define PI_DEBUG                0x00040000
 401 /** The protocol field violates a protocol specification, usually PI_WARN */
 402 #define PI_PROTOCOL             0x00080000
 403 /* The protocol field indicates a security probem (e.g. unsecure implementation) */
 404 #define PI_SECURITY             0x00100000
 405
 406 /* add more, see http://wiki.wireshark.org/Development/ExpertInfo */
 407
 408
 409 /** is this protocol field hidden from the protocol tree display (used for filtering only)? */
 410 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 411 #define PROTO_ITEM_IS_HIDDEN(proto_item)        \
 412         ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_HIDDEN) : 0)
 413 /** mark this protocol field to be hidden from the protocol tree display (used for filtering only) */
 414 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 415 #define PROTO_ITEM_SET_HIDDEN(proto_item)       \
 416   do { \
 417     if (proto_item) \
 418       FI_SET_FLAG(PITEM_FINFO(proto_item), FI_HIDDEN); \
 419         } while(0)
 420 /** is this protocol field generated by Wireshark (and not read from the packet data)? */
 421 #define PROTO_ITEM_IS_GENERATED(proto_item)     \
 422         ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_GENERATED) : 0)
 423 /** mark this protocol field as generated by Wireshark (and not read from the packet data) */
 424 #define PROTO_ITEM_SET_GENERATED(proto_item)    \
 425     do { \
 426       if (proto_item) \
 427         FI_SET_FLAG(PITEM_FINFO(proto_item), FI_GENERATED); \
 428     } while(0)
 429 /** is this protocol field actually a URL? */
 430 #define PROTO_ITEM_IS_URL(proto_item)   \
 431         ((proto_item) ? FI_GET_FLAG(PITEM_FINFO(proto_item), FI_URL) : 0)
 432 /** mark this protocol field as a URL */
 433 #define PROTO_ITEM_SET_URL(proto_item)  \
 434     do { \
 435       if (proto_item) \
 436         FI_SET_FLAG(PITEM_FINFO(proto_item), FI_URL); \
 437     } while(0)
 438
 439 typedef void (*proto_tree_foreach_func)(proto_node *, gpointer);
 440 typedef gboolean (*proto_tree_traverse_func)(proto_node *, gpointer);
 441
 442 extern gboolean proto_tree_traverse_post_order(proto_tree *tree,
 443     proto_tree_traverse_func func, gpointer data);
 444 extern void proto_tree_children_foreach(proto_tree *tree,
 445     proto_tree_foreach_func func, gpointer data);
 446
 447 /** Retrieve the field_info from a proto_node */
 448 #define PNODE_FINFO(proto_node)  ((proto_node)->finfo)
 449
 450 /** Retrieve the field_info from a proto_item */
 451 #define PITEM_FINFO(proto_item)  PNODE_FINFO(proto_item)
 452
 453 /** Retrieve the field_info from a proto_tree */
 454 #define PTREE_FINFO(proto_tree)  PNODE_FINFO(proto_tree)
 455
 456 /** Retrieve the tree_data_t from a proto_tree */
 457 #define PTREE_DATA(proto_tree)   ((proto_tree)->tree_data)
 458
 459 /** Sets up memory used by proto routines. Called at program startup */
 460 extern void proto_init(void (register_all_protocols_func)(register_cb cb, gpointer client_data),
 461                        void (register_all_handoffs_func)(register_cb cb, gpointer client_data),
 462                        register_cb cb, void *client_data);
 463
 464
 465 /** Frees memory used by proto routines. Called at program shutdown */
 466 extern void proto_cleanup(void);
 467
 468 /** This function takes a tree and a protocol id as parameter and
 469     will return TRUE/FALSE for whether the protocol or any of the filterable
 470     fields in the protocol is referenced by any fitlers.
 471     If this function returns FALSE then it is safe to skip any
 472     proto_tree_add_...() calls and just treat the call as if the
 473     dissector was called with tree==NULL.
 474     If you reset the tree to NULL by this dissector returning FALSE,
 475     you will still need to call any subdissector with the original value of
 476     tree or filtering will break.
 477
 478     The purpose of this is to optimize wireshark for speed and make it
 479     faster for when filters are being used.
 480 */
 481 extern gboolean proto_field_is_referenced(proto_tree *tree, int proto_id);
 482
 483
 484
 485 /** Create a subtree under an existing item.
 486  @param ti the parent item of the new subtree
 487  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
 488  @return the new subtree */
 489 extern proto_tree* proto_item_add_subtree(proto_item *ti, const gint idx);
 490
 491 /** Get an existing subtree under an item.
 492  @param ti the parent item of the subtree
 493  @return the subtree or NULL */
 494 extern proto_tree* proto_item_get_subtree(const proto_item *ti);
 495
 496 /** Get the parent of a subtree item.
 497  @param ti the child item in the subtree
 498  @return parent item or NULL */
 499 extern proto_item* proto_item_get_parent(const proto_item *ti);
 500
 501 /** Get Nth generation parent item.
 502  @param ti the child item in the subtree
 503  @param gen the generation to get (using 1 here is the same as using proto_item_get_parent())
 504  @return parent item */
 505 extern proto_item* proto_item_get_parent_nth(proto_item *ti, int gen);
 506
 507 /** Replace text of item after it already has been created.
 508  @param ti the item to set the text
 509  @param format printf like format string
 510  @param ... printf like parameters */
 511 extern void proto_item_set_text(proto_item *ti, const char *format, ...)
 512         G_GNUC_PRINTF(2,3);
 513
 514 /** Append to text of item after it has already been created.
 515  @param ti the item to append the text to
 516  @param format printf like format string
 517  @param ... printf like parameters */
 518 extern void proto_item_append_text(proto_item *ti, const char *format, ...)
 519         G_GNUC_PRINTF(2,3);
 520
 521 /** Set proto_item's length inside tvb, after it has already been created.
 522  @param ti the item to set the length
 523  @param length the new length ot the item */
 524 extern void proto_item_set_len(proto_item *ti, const gint length);
 525
 526 /**
 527  * Sets the length of the item based on its start and on the specified
 528  * offset, which is the offset past the end of the item; as the start
 529  * in the item is relative to the beginning of the data source tvbuff,
 530  * we need to pass in a tvbuff.
 531  @param ti the item to set the length
 532  @param tvb end is relative to this tvbuff
 533  @param end this end offset is relative to the beginning of tvb
 534  @todo make usage clearer, I don't understand it!
 535  */
 536 extern void proto_item_set_end(proto_item *ti, tvbuff_t *tvb, gint end);
 537
 538 /** Get length of a proto_item. Useful after using proto_tree_add_item()
 539  * to add a variable-length field (e.g., FT_NSTRING_UINT8).
 540  @param ti the item to get the length from
 541  @return the current length */
 542 extern int proto_item_get_len(const proto_item *ti);
 543
 544 /**
 545  * Sets an expert info to the proto_item.
 546  @param ti the item to set the expert info
 547  @param group the group of this info (e.g. PI_CHECKSUM)
 548  @param severity of this info (e.g. PI_ERROR)
 549  @return TRUE if value was written
 550  */
 551 extern gboolean proto_item_set_expert_flags(proto_item *ti, const int group, const guint severity);
 552
 553
 554
 555
 556 /** Creates a new proto_tree root.
 557  @return the new tree root */
 558 extern proto_tree* proto_tree_create_root(void);
 559
 560 /** Clear memory for entry proto_tree. Clears proto_tree struct also.
 561  @param tree the tree to free */
 562 extern void proto_tree_free(proto_tree *tree);
 563
 564 /** Set the tree visible or invisible.
 565  Is the parsing being done for a visible proto_tree or an invisible one?
 566  By setting this correctly, the proto_tree creation is sped up by not
 567  having to call g_vsnprintf and copy strings around.
 568  @param tree the tree to be set
 569  @param visible ... or not
 570  @return the old value */
 571 extern gboolean
 572 proto_tree_set_visible(proto_tree *tree, gboolean visible);
 573
 574 /** Indicate whether we should fake protocols during dissection (default = TRUE)
 575  @param tree the tree to be set
 576  @param fake_protocols TRUE if we should fake protocols */
 577 extern void
 578 proto_tree_set_fake_protocols(proto_tree *tree, gboolean fake_protocols);
 579
 580 /** Mark a field/protocol ID as "interesting".
 581  @param tree the tree to be set
 582  @param hfid the interesting field id
 583  @todo what *does* interesting mean? */
 584 extern void
 585 proto_tree_prime_hfid(proto_tree *tree, const int hfid);
 586
 587 /** Get a parent item of a subtree.
 588  @param tree the tree to get the parent from
 589  @return parent item */
 590 extern proto_item* proto_tree_get_parent(const proto_tree *tree);
 591
 592 /** Get the root tree from any subtree.
 593  @param tree the tree to get the root from
 594  @return root tree */
 595 extern proto_tree* proto_tree_get_root(proto_tree *tree);
 596
 597 /** Move an existing item behind another existing item.
 598  @param tree the tree to which both items belong
 599  @param fixed_item the item which keeps it's position
 600  @param item_to_move the item which will be moved */
 601 extern void proto_tree_move_item(proto_tree *tree, proto_item *fixed_item, proto_item *item_to_move);
 602
 603
 604 /** Set start and length of an appendix for a proto_tree.
 605   @param tree the tree to set the appendix start and length
 606   @param tvb the tv buffer of the current data
 607   @param start the start offset of the appendix
 608   @param length the length of the appendix */
 609 extern void proto_tree_set_appendix(proto_tree *tree, tvbuff_t *tvb, gint start, const gint length);
 610
 611
 612 /** Add an item to a proto_tree, using the text label registered to that item.
 613    The item is extracted from the tvbuff handed to it.
 614  @param tree the tree to append this item to
 615  @param hfindex field index
 616  @param tvb the tv buffer of the current data
 617  @param start start of data in tvb
 618  @param length length of data in tvb
 619  @param little_endian big or little endian byte representation
 620  @return the newly created item */
 621 extern proto_item *
 622 proto_tree_add_item(proto_tree *tree, const int hfindex, tvbuff_t *tvb,
 623     const gint start, gint length, const gboolean little_endian);
 624
 625 /** Add a text-only node to a proto_tree.
 626  @param tree the tree to append this item to
 627  @param tvb the tv buffer of the current data
 628  @param start start of data in tvb
 629  @param length length of data in tvb
 630  @param format printf like format string
 631  @param ... printf like parameters
 632  @return the newly created item */
 633 extern proto_item *
 634 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
 635         ...) G_GNUC_PRINTF(5,6);
 636
 637 /** Add a text-only node to a proto_tree using a variable argument list.
 638  @param tree the tree to append this item to
 639  @param tvb the tv buffer of the current data
 640  @param start start of data in tvb
 641  @param length length of data in tvb
 642  @param format printf like format string
 643  @param ap variable argument list
 644  @return the newly created item */
 645 extern proto_item *
 646 proto_tree_add_text_valist(proto_tree *tree, tvbuff_t *tvb, gint start,
 647         gint length, const char *format, va_list ap);
 648
 649
 650 /** Add a FT_NONE field to a proto_tree.
 651  @param tree the tree to append this item to
 652  @param hfindex field index
 653  @param tvb the tv buffer of the current data
 654  @param start start of data in tvb
 655  @param length length of data in tvb
 656  @param format printf like format string
 657  @param ... printf like parameters
 658  @return the newly created item */
 659 extern proto_item *
 660 proto_tree_add_none_format(proto_tree *tree, const int hfindex, tvbuff_t *tvb, const gint start,
 661         gint length, const char *format, ...) G_GNUC_PRINTF(6,7);
 662
 663 /** Add a FT_PROTOCOL to a proto_tree.
 664  @param tree the tree to append this item to
 665  @param hfindex field index
 666  @param tvb the tv buffer of the current data
 667  @param start start of data in tvb
 668  @param length length of data in tvb
 669  @param format printf like format string
 670  @param ... printf like parameters
 671  @return the newly created item */
 672 extern proto_item *
 673 proto_tree_add_protocol_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 674         gint length, const char *format, ...) G_GNUC_PRINTF(6,7);
 675
 676
 677
 678
 679 /** Add a FT_BYTES to a proto_tree.
 680  @param tree the tree to append this item to
 681  @param hfindex field index
 682  @param tvb the tv buffer of the current data
 683  @param start start of data in tvb
 684  @param length length of data in tvb
 685  @param start_ptr pointer to the data to display
 686  @return the newly created item */
 687 extern proto_item *
 688 proto_tree_add_bytes(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 689         gint length, const guint8* start_ptr);
 690
 691 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
 692     the string for the value and with the field name being included
 693     automatically.
 694  @param tree the tree to append this item to
 695  @param hfindex field index
 696  @param tvb the tv buffer of the current data
 697  @param start start of data in tvb
 698  @param length length of data in tvb
 699  @param start_ptr pointer to the data to display
 700  @param format printf like format string
 701  @param ... printf like parameters
 702  @return the newly created item */
 703 extern proto_item *
 704 proto_tree_add_bytes_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 705         gint start, gint length, const guint8* start_ptr, const char *format,
 706         ...) G_GNUC_PRINTF(7,8);
 707
 708 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
 709     the entire string for the entry, including any field name.
 710  @param tree the tree to append this item to
 711  @param hfindex field index
 712  @param tvb the tv buffer of the current data
 713  @param start start of data in tvb
 714  @param length length of data in tvb
 715  @param start_ptr pointer to the data to display
 716  @param format printf like format string
 717  @param ... printf like parameters
 718  @return the newly created item */
 719 extern proto_item *
 720 proto_tree_add_bytes_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 721         gint length, const guint8* start_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
 722
 723 /** Add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 724  @param tree the tree to append this item to
 725  @param hfindex field index
 726  @param tvb the tv buffer of the current data
 727  @param start start of data in tvb
 728  @param length length of data in tvb
 729  @param value_ptr pointer to the data to display
 730  @return the newly created item */
 731 extern proto_item *
 732 proto_tree_add_time(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 733         gint length, nstime_t* value_ptr);
 734
 735 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
 736     the format generating the string for the value and with the field name
 737     being included automatically.
 738  @param tree the tree to append this item to
 739  @param hfindex field index
 740  @param tvb the tv buffer of the current data
 741  @param start start of data in tvb
 742  @param length length of data in tvb
 743  @param value_ptr pointer to the data to display
 744  @param format printf like format string
 745  @param ... printf like parameters
 746  @return the newly created item */
 747 extern proto_item *
 748 proto_tree_add_time_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 749         gint start, gint length, nstime_t* value_ptr, const char *format, ...)
 750         G_GNUC_PRINTF(7,8);
 751
 752 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
 753     the format generating the entire string for the entry, including any field
 754     name.
 755  @param tree the tree to append this item to
 756  @param hfindex field index
 757  @param tvb the tv buffer of the current data
 758  @param start start of data in tvb
 759  @param length length of data in tvb
 760  @param value_ptr pointer to the data to display
 761  @param format printf like format string
 762  @param ... printf like parameters
 763  @return the newly created item */
 764 extern proto_item *
 765 proto_tree_add_time_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 766         gint length, nstime_t* value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
 767
 768 /** Add a FT_IPXNET to a proto_tree.
 769  @param tree the tree to append this item to
 770  @param hfindex field index
 771  @param tvb the tv buffer of the current data
 772  @param start start of data in tvb
 773  @param length length of data in tvb
 774  @param value data to display
 775  @return the newly created item */
 776 extern proto_item *
 777 proto_tree_add_ipxnet(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 778         gint length, guint32 value);
 779
 780 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
 781     the string for the value and with the field name being included
 782     automatically.
 783  @param tree the tree to append this item to
 784  @param hfindex field index
 785  @param tvb the tv buffer of the current data
 786  @param start start of data in tvb
 787  @param length length of data in tvb
 788  @param value data to display
 789  @param format printf like format string
 790  @param ... printf like parameters
 791  @return the newly created item */
 792 extern proto_item *
 793 proto_tree_add_ipxnet_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 794         gint start, gint length, guint32 value, const char *format, ...)
 795         G_GNUC_PRINTF(7,8);
 796
 797 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
 798     the entire string for the entry, including any field name.
 799  @param tree the tree to append this item to
 800  @param hfindex field index
 801  @param tvb the tv buffer of the current data
 802  @param start start of data in tvb
 803  @param length length of data in tvb
 804  @param value data to display
 805  @param format printf like format string
 806  @param ... printf like parameters
 807  @return the newly created item */
 808 extern proto_item *
 809 proto_tree_add_ipxnet_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 810         gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
 811
 812 /** Add a FT_IPv4 to a proto_tree.
 813  @param tree the tree to append this item to
 814  @param hfindex field index
 815  @param tvb the tv buffer of the current data
 816  @param start start of data in tvb
 817  @param length length of data in tvb
 818  @param value data to display
 819  @return the newly created item */
 820 extern proto_item *
 821 proto_tree_add_ipv4(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 822         gint length, guint32 value);
 823
 824 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
 825     the string for the value and with the field name being included
 826     automatically.
 827  @param tree the tree to append this item to
 828  @param hfindex field index
 829  @param tvb the tv buffer of the current data
 830  @param start start of data in tvb
 831  @param length length of data in tvb
 832  @param value data to display
 833  @param format printf like format string
 834  @param ... printf like parameters
 835  @return the newly created item */
 836 extern proto_item *
 837 proto_tree_add_ipv4_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 838         gint start, gint length, guint32 value, const char *format, ...)
 839         G_GNUC_PRINTF(7,8);
 840
 841 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
 842     the entire string for the entry, including any field name.
 843  @param tree the tree to append this item to
 844  @param hfindex field index
 845  @param tvb the tv buffer of the current data
 846  @param start start of data in tvb
 847  @param length length of data in tvb
 848  @param value data to display
 849  @param format printf like format string
 850  @param ... printf like parameters
 851  @return the newly created item */
 852 extern proto_item *
 853 proto_tree_add_ipv4_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 854         gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
 855
 856 /** Add a FT_IPv6 to a proto_tree.
 857  @param tree the tree to append this item to
 858  @param hfindex field index
 859  @param tvb the tv buffer of the current data
 860  @param start start of data in tvb
 861  @param length length of data in tvb
 862  @param value_ptr data to display
 863  @return the newly created item */
 864 extern proto_item *
 865 proto_tree_add_ipv6(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 866         gint length, const guint8* value_ptr);
 867
 868 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
 869     the string for the value and with the field name being included
 870     automatically.
 871  @param tree the tree to append this item to
 872  @param hfindex field index
 873  @param tvb the tv buffer of the current data
 874  @param start start of data in tvb
 875  @param length length of data in tvb
 876  @param value_ptr data to display
 877  @param format printf like format string
 878  @param ... printf like parameters
 879  @return the newly created item */
 880 extern proto_item *
 881 proto_tree_add_ipv6_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 882         gint start, gint length, const guint8* value_ptr, const char *format,
 883         ...) G_GNUC_PRINTF(7,8);
 884
 885 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
 886     the entire string for the entry, including any field name.
 887  @param tree the tree to append this item to
 888  @param hfindex field index
 889  @param tvb the tv buffer of the current data
 890  @param start start of data in tvb
 891  @param length length of data in tvb
 892  @param value_ptr data to display
 893  @param format printf like format string
 894  @param ... printf like parameters
 895  @return the newly created item */
 896 extern proto_item *
 897 proto_tree_add_ipv6_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 898         gint length, const guint8* value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
 899
 900 /** Add a FT_ETHER to a proto_tree.
 901  @param tree the tree to append this item to
 902  @param hfindex field index
 903  @param tvb the tv buffer of the current data
 904  @param start start of data in tvb
 905  @param length length of data in tvb
 906  @param value data to display
 907  @return the newly created item */
 908 extern proto_item *
 909 proto_tree_add_ether(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 910         gint length, const guint8* value);
 911
 912 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
 913     the string for the value and with the field name being included
 914     automatically.
 915  @param tree the tree to append this item to
 916  @param hfindex field index
 917  @param tvb the tv buffer of the current data
 918  @param start start of data in tvb
 919  @param length length of data in tvb
 920  @param value data to display
 921  @param format printf like format string
 922  @param ... printf like parameters
 923  @return the newly created item */
 924 extern proto_item *
 925 proto_tree_add_ether_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 926         gint start, gint length, const guint8* value, const char *format, ...)
 927         G_GNUC_PRINTF(7,8);
 928
 929 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
 930     the entire string for the entry, including any field name.
 931  @param tree the tree to append this item to
 932  @param hfindex field index
 933  @param tvb the tv buffer of the current data
 934  @param start start of data in tvb
 935  @param length length of data in tvb
 936  @param value data to display
 937  @param format printf like format string
 938  @param ... printf like parameters
 939  @return the newly created item */
 940 extern proto_item *
 941 proto_tree_add_ether_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 942         gint length, const guint8* value, const char *format, ...) G_GNUC_PRINTF(7,8);
 943
 944 /** Add a FT_GUID to a proto_tree.
 945  @param tree the tree to append this item to
 946  @param hfindex field index
 947  @param tvb the tv buffer of the current data
 948  @param start start of data in tvb
 949  @param length length of data in tvb
 950  @param value_ptr data to display
 951  @return the newly created item */
 952 extern proto_item *
 953 proto_tree_add_guid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 954         gint length, const e_guid_t *value_ptr);
 955
 956 /** Add a formatted FT_GUID to a proto_tree, with the format generating
 957     the string for the value and with the field name being included
 958     automatically.
 959  @param tree the tree to append this item to
 960  @param hfindex field index
 961  @param tvb the tv buffer of the current data
 962  @param start start of data in tvb
 963  @param length length of data in tvb
 964  @param value_ptr data to display
 965  @param format printf like format string
 966  @param ... printf like parameters
 967  @return the newly created item */
 968 extern proto_item *
 969 proto_tree_add_guid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 970         gint start, gint length, const e_guid_t *value_ptr, const char *format,
 971         ...) G_GNUC_PRINTF(7,8);
 972
 973 /** Add a formatted FT_GUID to a proto_tree, with the format generating
 974     the entire string for the entry, including any field name.
 975  @param tree the tree to append this item to
 976  @param hfindex field index
 977  @param tvb the tv buffer of the current data
 978  @param start start of data in tvb
 979  @param length length of data in tvb
 980  @param value_ptr data to display
 981  @param format printf like format string
 982  @param ... printf like parameters
 983  @return the newly created item */
 984 extern proto_item *
 985 proto_tree_add_guid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 986         gint length, const e_guid_t *value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
 987
 988 /** Add a FT_OID to a proto_tree.
 989  @param tree the tree to append this item to
 990  @param hfindex field index
 991  @param tvb the tv buffer of the current data
 992  @param start start of data in tvb
 993  @param length length of data in tvb
 994  @param value_ptr data to display
 995  @return the newly created item */
 996 extern proto_item *
 997 proto_tree_add_oid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 998         gint length, const guint8* value_ptr);
 999
1000 /** Add a formatted FT_OID to a proto_tree, with the format generating
1001     the string for the value and with the field name being included
1002     automatically.
1003  @param tree the tree to append this item to
1004  @param hfindex field index
1005  @param tvb the tv buffer of the current data
1006  @param start start of data in tvb
1007  @param length length of data in tvb
1008  @param value_ptr data to display
1009  @param format printf like format string
1010  @param ... printf like parameters
1011  @return the newly created item */
1012 extern proto_item *
1013 proto_tree_add_oid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1014         gint start, gint length, const guint8* value_ptr, const char *format,
1015         ...) G_GNUC_PRINTF(7,8);
1016
1017 /** Add a formatted FT_OID to a proto_tree, with the format generating
1018     the entire string for the entry, including any field name.
1019  @param tree the tree to append this item to
1020  @param hfindex field index
1021  @param tvb the tv buffer of the current data
1022  @param start start of data in tvb
1023  @param length length of data in tvb
1024  @param value_ptr data to display
1025  @param format printf like format string
1026  @param ... printf like parameters
1027  @return the newly created item */
1028 extern proto_item *
1029 proto_tree_add_oid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1030         gint length, const guint8* value_ptr, const char *format, ...) G_GNUC_PRINTF(7,8);
1031
1032 /** Add a FT_STRING to a proto_tree.
1033  @param tree the tree to append this item to
1034  @param hfindex field index
1035  @param tvb the tv buffer of the current data
1036  @param start start of data in tvb
1037  @param length length of data in tvb
1038  @param value data to display
1039  @return the newly created item */
1040 extern proto_item *
1041 proto_tree_add_string(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1042         gint length, const char* value);
1043
1044 /** Add a formatted FT_STRING to a proto_tree, with the format generating
1045     the string for the value and with the field name being included
1046     automatically.
1047  @param tree the tree to append this item to
1048  @param hfindex field index
1049  @param tvb the tv buffer of the current data
1050  @param start start of data in tvb
1051  @param length length of data in tvb
1052  @param value data to display
1053  @param format printf like format string
1054  @param ... printf like parameters
1055  @return the newly created item */
1056 extern proto_item *
1057 proto_tree_add_string_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1058         gint start, gint length, const char* value, const char *format, ...)
1059         G_GNUC_PRINTF(7,8);
1060
1061 /** Add a formatted FT_STRING to a proto_tree, with the format generating
1062     the entire string for the entry, including any field name.
1063  @param tree the tree to append this item to
1064  @param hfindex field index
1065  @param tvb the tv buffer of the current data
1066  @param start start of data in tvb
1067  @param length length of data in tvb
1068  @param value data to display
1069  @param format printf like format string
1070  @param ... printf like parameters
1071  @return the newly created item */
1072 extern proto_item *
1073 proto_tree_add_string_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1074         gint length, const char* value, const char *format, ...) G_GNUC_PRINTF(7,8);
1075
1076 /** Add a FT_BOOLEAN to a proto_tree.
1077  @param tree the tree to append this item to
1078  @param hfindex field index
1079  @param tvb the tv buffer of the current data
1080  @param start start of data in tvb
1081  @param length length of data in tvb
1082  @param value data to display
1083  @return the newly created item */
1084 extern proto_item *
1085 proto_tree_add_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1086         gint length, guint32 value);
1087
1088 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
1089     the string for the value and with the field name being included
1090     automatically.
1091  @param tree the tree to append this item to
1092  @param hfindex field index
1093  @param tvb the tv buffer of the current data
1094  @param start start of data in tvb
1095  @param length length of data in tvb
1096  @param value data to display
1097  @param format printf like format string
1098  @param ... printf like parameters
1099  @return the newly created item */
1100 extern proto_item *
1101 proto_tree_add_boolean_format_value(proto_tree *tree, int hfindex,
1102         tvbuff_t *tvb, gint start, gint length, guint32 value,
1103         const char *format, ...) G_GNUC_PRINTF(7,8);
1104
1105 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
1106     the entire string for the entry, including any field name.
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 value data to display
1113  @param format printf like format string
1114  @param ... printf like parameters
1115  @return the newly created item */
1116 extern proto_item *
1117 proto_tree_add_boolean_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1118         gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1119
1120 /** Add a FT_FLOAT to a proto_tree.
1121  @param tree the tree to append this item to
1122  @param hfindex field index
1123  @param tvb the tv buffer of the current data
1124  @param start start of data in tvb
1125  @param length length of data in tvb
1126  @param value data to display
1127  @return the newly created item */
1128 extern proto_item *
1129 proto_tree_add_float(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1130         gint length, float value);
1131
1132 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1133     the string for the value and with the field name being included
1134     automatically.
1135  @param tree the tree to append this item to
1136  @param hfindex field index
1137  @param tvb the tv buffer of the current data
1138  @param start start of data in tvb
1139  @param length length of data in tvb
1140  @param value data to display
1141  @param format printf like format string
1142  @param ... printf like parameters
1143  @return the newly created item */
1144 extern proto_item *
1145 proto_tree_add_float_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1146         gint start, gint length, float value, const char *format, ...)
1147         G_GNUC_PRINTF(7,8);
1148
1149 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1150     the entire string for the entry, including any field name.
1151  @param tree the tree to append this item to
1152  @param hfindex field index
1153  @param tvb the tv buffer of the current data
1154  @param start start of data in tvb
1155  @param length length of data in tvb
1156  @param value data to display
1157  @param format printf like format string
1158  @param ... printf like parameters
1159  @return the newly created item */
1160 extern proto_item *
1161 proto_tree_add_float_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1162         gint length, float value, const char *format, ...) G_GNUC_PRINTF(7,8);
1163
1164 /** Add a FT_DOUBLE to a proto_tree.
1165  @param tree the tree to append this item to
1166  @param hfindex field index
1167  @param tvb the tv buffer of the current data
1168  @param start start of data in tvb
1169  @param length length of data in tvb
1170  @param value data to display
1171  @return the newly created item */
1172 extern proto_item *
1173 proto_tree_add_double(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1174         gint length, double value);
1175
1176 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1177     the string for the value and with the field name being included
1178     automatically.
1179  @param tree the tree to append this item to
1180  @param hfindex field index
1181  @param tvb the tv buffer of the current data
1182  @param start start of data in tvb
1183  @param length length of data in tvb
1184  @param value data to display
1185  @param format printf like format string
1186  @param ... printf like parameters
1187  @return the newly created item */
1188 extern proto_item *
1189 proto_tree_add_double_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1190         gint start, gint length, double value, const char *format, ...)
1191         G_GNUC_PRINTF(7,8);
1192
1193 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1194     the entire string for the entry, including any field name.
1195  @param tree the tree to append this item to
1196  @param hfindex field index
1197  @param tvb the tv buffer of the current data
1198  @param start start of data in tvb
1199  @param length length of data in tvb
1200  @param value data to display
1201  @param format printf like format string
1202  @param ... printf like parameters
1203  @return the newly created item */
1204 extern proto_item *
1205 proto_tree_add_double_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1206         gint length, double value, const char *format, ...) G_GNUC_PRINTF(7,8);
1207
1208 /** Add one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
1209  @param tree the tree to append this item to
1210  @param hfindex field index
1211  @param tvb the tv buffer of the current data
1212  @param start start of data in tvb
1213  @param length length of data in tvb
1214  @param value data to display
1215  @return the newly created item */
1216 extern proto_item *
1217 proto_tree_add_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1218         gint length, guint32 value);
1219
1220 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1221     with the format generating the string for the value and with the field
1222     name being included automatically.
1223  @param tree the tree to append this item to
1224  @param hfindex field index
1225  @param tvb the tv buffer of the current data
1226  @param start start of data in tvb
1227  @param length length of data in tvb
1228  @param value data to display
1229  @param format printf like format string
1230  @param ... printf like parameters
1231  @return the newly created item */
1232 extern proto_item *
1233 proto_tree_add_uint_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1234         gint start, gint length, guint32 value, const char *format, ...)
1235         G_GNUC_PRINTF(7,8);
1236
1237 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1238     with the format generating the entire string for the entry, including any
1239     field name.
1240  @param tree the tree to append this item to
1241  @param hfindex field index
1242  @param tvb the tv buffer of the current data
1243  @param start start of data in tvb
1244  @param length length of data in tvb
1245  @param value data to display
1246  @param format printf like format string
1247  @param ... printf like parameters
1248  @return the newly created item */
1249 extern proto_item *
1250 proto_tree_add_uint_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1251         gint length, guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1252
1253 /** Add an FT_UINT64 to a proto_tree.
1254  @param tree the tree to append this item to
1255  @param hfindex field index
1256  @param tvb the tv buffer of the current data
1257  @param start start of data in tvb
1258  @param length length of data in tvb
1259  @param value data to display
1260  @return the newly created item */
1261 extern proto_item *
1262 proto_tree_add_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1263         gint length, guint64 value);
1264
1265 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1266     the string for the value and with the field name being included
1267     automatically.
1268  @param tree the tree to append this item to
1269  @param hfindex field index
1270  @param tvb the tv buffer of the current data
1271  @param start start of data in tvb
1272  @param length length of data in tvb
1273  @param value data to display
1274  @param format printf like format string
1275  @param ... printf like parameters
1276  @return the newly created item */
1277 extern proto_item *
1278 proto_tree_add_uint64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1279         gint start, gint length, guint64 value, const char *format, ...)
1280         G_GNUC_PRINTF(7,8);
1281
1282 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1283     the entire string for the entry, including any field name.
1284  @param tree the tree to append this item to
1285  @param hfindex field index
1286  @param tvb the tv buffer of the current data
1287  @param start start of data in tvb
1288  @param length length of data in tvb
1289  @param value data to display
1290  @param format printf like format string
1291  @param ... printf like parameters
1292  @return the newly created item */
1293 extern proto_item *
1294 proto_tree_add_uint64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1295         gint length, guint64 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1296
1297 /** Add one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
1298  @param tree the tree to append this item to
1299  @param hfindex field index
1300  @param tvb the tv buffer of the current data
1301  @param start start of data in tvb
1302  @param length length of data in tvb
1303  @param value data to display
1304  @return the newly created item */
1305 extern proto_item *
1306 proto_tree_add_int(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1307         gint length, gint32 value);
1308
1309 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
1310     with the format generating the string for the value and with the field
1311     name being included automatically.
1312  @param tree the tree to append this item to
1313  @param hfindex field index
1314  @param tvb the tv buffer of the current data
1315  @param start start of data in tvb
1316  @param length length of data in tvb
1317  @param value data to display
1318  @param format printf like format string
1319  @param ... printf like parameters
1320  @return the newly created item */
1321 extern proto_item *
1322 proto_tree_add_int_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1323         gint start, gint length, gint32 value, const char *format, ...)
1324         G_GNUC_PRINTF(7,8);
1325
1326 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
1327     with the format generating the entire string for the entry, including
1328     any field name.
1329  @param tree the tree to append this item to
1330  @param hfindex field index
1331  @param tvb the tv buffer of the current data
1332  @param start start of data in tvb
1333  @param length length of data in tvb
1334  @param value data to display
1335  @param format printf like format string
1336  @param ... printf like parameters
1337  @return the newly created item */
1338 extern proto_item *
1339 proto_tree_add_int_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1340         gint length, gint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1341
1342 /** Add an FT_INT64 to a proto_tree.
1343  @param tree the tree to append this item to
1344  @param hfindex field index
1345  @param tvb the tv buffer of the current data
1346  @param start start of data in tvb
1347  @param length length of data in tvb
1348  @param value data to display
1349  @return the newly created item */
1350 extern proto_item *
1351 proto_tree_add_int64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1352         gint length, gint64 value);
1353
1354 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
1355     the string for the value and with the field name being included
1356     automatically.
1357  @param tree the tree to append this item to
1358  @param hfindex field index
1359  @param tvb the tv buffer of the current data
1360  @param start start of data in tvb
1361  @param length length of data in tvb
1362  @param value data to display
1363  @param format printf like format string
1364  @param ... printf like parameters
1365  @return the newly created item */
1366 extern proto_item *
1367 proto_tree_add_int64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1368         gint start, gint length, gint64 value, const char *format, ...)
1369         G_GNUC_PRINTF(7,8);
1370
1371 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
1372     the entire string for the entry, including any field name.
1373  @param tree the tree to append this item to
1374  @param hfindex field index
1375  @param tvb the tv buffer of the current data
1376  @param start start of data in tvb
1377  @param length length of data in tvb
1378  @param value data to display
1379  @param format printf like format string
1380  @param ... printf like parameters
1381  @return the newly created item */
1382 extern proto_item *
1383 proto_tree_add_int64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1384         gint length, gint64 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1385
1386 /** Useful for quick debugging. Also sends string to STDOUT, so don't
1387     leave call to this function in production code.
1388  @param tree the tree to append the text to
1389  @param format printf like format string
1390  @param ... printf like parameters
1391  @return the newly created item */
1392 extern proto_item *
1393 proto_tree_add_debug_text(proto_tree *tree, const char *format,
1394         ...) G_GNUC_PRINTF(2,3);
1395
1396
1397
1398 /** Append a string to a protocol item.<br>
1399     NOTE: this function will break with the TRY_TO_FAKE_THIS_ITEM()
1400     speed optimization.
1401     Currently only WSP use this function so it is not that bad but try to
1402     avoid using this one if possible.
1403     IF you must use this function you MUST also disable the
1404     TRY_TO_FAKE_THIS_ITEM() optimization for your dissector/function
1405     using proto_item_append_string().
1406     Do that by faking that the tree is visible by calling
1407     proto_tree_set_visible(tree, TRUE) (see packet-wsp.c)
1408     BEFORE you create the item you are later going to use
1409     proto_item_append_string() on.
1410  @param pi the item to append the string to
1411  @param str the string to append */
1412 extern void
1413 proto_item_append_string(proto_item *pi, const char *str);
1414
1415
1416
1417 /** Fill given label_str with string representation of field
1418  @param fi the item to get the info from
1419  @param label_str the string to fill
1420  @todo think about changing the parameter profile */
1421 extern void
1422 proto_item_fill_label(field_info *fi, gchar *label_str);
1423
1424
1425 /** Register a new protocol.
1426  @param name the full name of the new protocol
1427  @param short_name abbreviated name of the new protocol
1428  @param filter_name protocol name used for a display filter string
1429  @return the new protocol handle */
1430 extern int
1431 proto_register_protocol(const char *name, const char *short_name, const char *filter_name);
1432
1433 /** Mark protocol as private
1434  @param proto_id the handle of the protocol */
1435 extern void
1436 proto_mark_private(const int proto_id);
1437
1438 /** Return if protocol is private
1439  @param proto_id the handle of the protocol
1440  @return TRUE if it is a private protocol, FALSE is not. */
1441 extern gboolean
1442 proto_is_private(const int proto_id);
1443
1444 /** This is the type of function can be registered to get called whenever
1445     a given field was not found but a its prefix is matched
1446         it can be used to procrastinate the hf array registration
1447    @param match  what's being matched */
1448 typedef void (*prefix_initializer_t)(const char* match);
1449
1450 /** Register a new prefix for delayed initialization of field arrays
1451 @param prefix the prefix for the new protocol
1452 @param initializer function that will initialize the field array for the given prefix */
1453 extern void
1454 proto_register_prefix(const char *prefix,  prefix_initializer_t initializer);
1455
1456 /** Initialize every remaining uninitialized prefix. */
1457 extern void proto_initialize_all_prefixes(void);
1458
1459 /** Register a header_field array.
1460  @param parent the protocol handle from proto_register_protocol()
1461  @param hf the hf_register_info array
1462  @param num_records the number of records in hf */
1463 extern void
1464 proto_register_field_array(const int parent, hf_register_info *hf, const int num_records);
1465
1466 /** Register a protocol subtree (ett) array.
1467  @param indices array of ett indices
1468  @param num_indices the number of records in indices */
1469 extern void
1470 proto_register_subtree_array(gint *const *indices, const int num_indices);
1471
1472 /** Returns number of items (protocols or header fields) registered.
1473  @return the number of items */
1474 extern int proto_registrar_n(void);
1475
1476 /** Get name of registered header_field number n.
1477  @param n item # n (0-indexed)
1478  @return the name of this registered item */
1479 extern const char* proto_registrar_get_name(const int n);
1480
1481 /** Get abbreviation of registered header_field number n.
1482  @param n item # n (0-indexed)
1483  @return the abbreviation of this registered item */
1484 extern const char* proto_registrar_get_abbrev(const int n);
1485
1486 /** Get the header_field information based upon a field or protocol id.
1487  @param hfindex item # n (0-indexed)
1488  @return the registered item */
1489 extern header_field_info* proto_registrar_get_nth(guint hfindex);
1490
1491 /** Get the header_field information based upon a field name.
1492  @param field_name the field name to search for
1493  @return the registered item */
1494 extern header_field_info* proto_registrar_get_byname(const char *field_name);
1495
1496 /** Get enum ftenum FT_ of registered header_field number n.
1497  @param n item # n (0-indexed)
1498  @return the registered item */
1499 extern int proto_registrar_get_ftype(const int n);
1500
1501 /** Get parent protocol of registered header_field number n.
1502  @param n item # n (0-indexed)
1503  @return -1 if item _is_ a protocol */
1504 extern int proto_registrar_get_parent(const int n);
1505
1506 /** Is item # n a protocol?
1507  @param n item # n (0-indexed)
1508  @return TRUE if it's a protocol, FALSE if it's not */
1509 extern gboolean proto_registrar_is_protocol(const int n);
1510
1511 /** Get length of registered field according to field type.
1512  @param n item # n (0-indexed)
1513  @return 0 means undeterminable at registration time, -1 means unknown field */
1514 extern gint proto_registrar_get_length(const int n);
1515
1516
1517 /** Routines to use to iterate over the protocols and their fields;
1518  * they return the item number of the protocol in question or the
1519  * appropriate hfinfo pointer, and keep state in "*cookie". */
1520 extern int proto_get_first_protocol(void **cookie);
1521 extern int proto_get_next_protocol(void **cookie);
1522 extern header_field_info *proto_get_first_protocol_field(const int proto_id, void **cookle);
1523 extern header_field_info *proto_get_next_protocol_field(void **cookle);
1524
1525 /** Given a protocol's filter_name.
1526  @param filter_name the filter name to search for
1527  @return proto_id */
1528 extern int proto_get_id_by_filter_name(const gchar* filter_name);
1529
1530 /** Can item # n decoding be disabled?
1531  @param proto_id protocol id (0-indexed)
1532  @return TRUE if it's a protocol, FALSE if it's not */
1533 extern gboolean proto_can_toggle_protocol(const int proto_id);
1534
1535 /** Get the "protocol_t" structure for the given protocol's item number.
1536  @param proto_id protocol id (0-indexed) */
1537 extern protocol_t *find_protocol_by_id(const int proto_id);
1538
1539 /** Get the protocol's name for the given protocol's item number.
1540  @param proto_id protocol id (0-indexed)
1541  @return its name */
1542 extern const char *proto_get_protocol_name(const int proto_id);
1543
1544 /** Get the protocol's item number, for the given protocol's "protocol_t".
1545  @return its proto_id */
1546 extern int proto_get_id(const protocol_t *protocol);
1547
1548 /** Get the protocol's short name, for the given protocol's "protocol_t".
1549  @return its short name. */
1550 extern const char *proto_get_protocol_short_name(const protocol_t *protocol);
1551
1552 /** Get the protocol's long name, for the given protocol's "protocol_t".
1553  @return its long name. */
1554 extern const char *proto_get_protocol_long_name(const protocol_t *protocol);
1555
1556 /** Is protocol's decoding enabled ?
1557  @param protocol
1558  @return TRUE if decoding is enabled, FALSE if not */
1559 extern gboolean proto_is_protocol_enabled(const protocol_t *protocol);
1560
1561 /** Get a protocol's filter name by it's item number.
1562  @param proto_id protocol id (0-indexed)
1563  @return its filter name. */
1564 extern const char *proto_get_protocol_filter_name(const int proto_id);
1565
1566 /** Enable / Disable protocol of the given item number.
1567  @param proto_id protocol id (0-indexed)
1568  @param enabled enable / disable the protocol */
1569 extern void proto_set_decoding(const int proto_id, const gboolean enabled);
1570
1571 /** Enable all protocols */
1572 extern void proto_enable_all(void);
1573
1574 /** Disable disabling/enabling of protocol of the given item number.
1575  @param proto_id protocol id (0-indexed) */
1576 extern void proto_set_cant_toggle(const int proto_id);
1577
1578 /** Checks for existence any protocol or field within a tree.
1579  @param tree "Protocols" are assumed to be a child of the [empty] root node.
1580  @param id hfindex of protocol or field
1581  @return TRUE = found, FALSE = not found
1582  @todo add explanation of id parameter */
1583 extern gboolean proto_check_for_protocol_or_field(const proto_tree* tree, const int id);
1584
1585 /** Return GPtrArray* of field_info pointers for all hfindex that appear in
1586     tree. Only works with primed trees, and is fast.
1587  @param tree tree of interest
1588  @param hfindex primed hfindex
1589  @return GPtrArry pointer */
1590 extern GPtrArray* proto_get_finfo_ptr_array(const proto_tree *tree, const int hfindex);
1591
1592 /** Return whether we're tracking any interesting fields.
1593     Only works with primed trees, and is fast.
1594  @param tree tree of interest
1595  @return TRUE if we're tracking interesting fields */
1596 extern gboolean proto_tracking_interesting_fields(const proto_tree *tree);
1597
1598 /** Return GPtrArray* of field_info pointers for all hfindex that appear in
1599     tree. Works with any tree, primed or unprimed, and is slower than
1600     proto_get_finfo_ptr_array because it has to search through the tree.
1601  @param tree tree of interest
1602  @param hfidex index of field info of interest
1603  @return GPtrArry pointer */
1604 extern GPtrArray* proto_find_finfo(proto_tree *tree, const int hfindex);
1605
1606 /** Return GPtrArray* of field_info pointers containg all hfindexes that appear
1607     in tree.
1608  @param tree tree of interest
1609  @return GPtrArry pointer */
1610 extern GPtrArray* proto_all_finfos(proto_tree *tree);
1611
1612 /** Dumps a glossary of the protocol registrations to STDOUT */
1613 extern void proto_registrar_dump_protocols(void);
1614
1615 /** Dumps a glossary of the field value strings or true/false strings to STDOUT */
1616 extern void proto_registrar_dump_values(void);
1617
1618 /** Dumps a glossary of the protocol and field registrations to STDOUT.
1619  * Format 1 is the original format. Format 2 includes the base (for integers)
1620  * and the blurb. */
1621 extern void proto_registrar_dump_fields(const int format);
1622
1623
1624
1625 /** Points to the first element of an array of Booleans, indexed by
1626    a subtree item type. That array element is TRUE if subtrees of
1627    an item of that type are to be expanded. With MSVC and a
1628    libwireshark.dll, we need a special declaration. */
1629 WS_VAR_IMPORT gboolean       *tree_is_expanded;
1630
1631 /** Number of elements in the tree_is_expanded array. With MSVC and a
1632  * libwireshark.dll, we need a special declaration. */
1633 WS_VAR_IMPORT int           num_tree_types;
1634
1635 /** glib doesn't have g_ptr_array_len of all things!*/
1636 #ifndef g_ptr_array_len
1637 #define g_ptr_array_len(a)      ((a)?(a)->len:0)
1638 #endif
1639
1640 /** Get number of bits of a header_field.
1641  @param hfinfo header_field
1642  @return the bitwidth */
1643 extern int
1644 hfinfo_bitwidth(const header_field_info *hfinfo);
1645
1646
1647
1648
1649 #include "epan.h"
1650
1651 /** Can we do a "match selected" on this field.
1652  @param finfo field_info
1653  @param edt epan dissecting
1654  @return TRUE if we can do a "match selected" on the field, FALSE otherwise. */
1655 extern gboolean
1656 proto_can_match_selected(field_info *finfo, epan_dissect_t *edt);
1657
1658 /** Construct a "match selected" display filter string.
1659  @param finfo field_info
1660  @param edt epan dissecting
1661  @return the display filter string */
1662 extern char*
1663 proto_construct_match_selected_string(field_info *finfo, epan_dissect_t *edt);
1664
1665 /** Find field from offset in tvb.
1666  @param tree tree of interest
1667  @param offset offset in the tvb
1668  @param tvb the tv buffer
1669  @return the corresponding field_info */
1670 extern field_info*
1671 proto_find_field_from_offset(proto_tree *tree, guint offset, tvbuff_t *tvb);
1672
1673 /** This function will dissect a sequence of bytes that describe a bitmask.
1674  @param tree the tree to append this item to
1675  @param tvb the tv buffer of the current data
1676  @param offset start of data in tvb
1677  @param hf_hdr an 8/16/24/32 bit integer that describes the bitmask to be dissected.
1678         This field will form an expansion under which the individual fields of the
1679         bitmask is dissected and displayed.
1680         This field must be of the type FT_[U]INT{8|16|24|32}.
1681  @param ett subtree index
1682  @param fields an array of pointers to int that lists all the fields of the
1683         bitmask. These fields can be either of the type FT_BOOLEAN for flags
1684         or another integer of the same type/size as hf_hdr with a mask specified.
1685         This array is terminated by a NULL entry.
1686         FT_BOOLEAN bits that are set to 1 will have the name added to the expansion.
1687         FT_integer fields that have a value_string attached will have the
1688         matched string displayed on the expansion line.
1689  @param little_endian big or little endian byte representation
1690  @return the newly created item */
1691 extern proto_item *
1692 proto_tree_add_bitmask(proto_tree *tree, tvbuff_t *tvb, const guint offset,
1693                 const int hf_hdr, const gint ett, const int **fields, const gboolean little_endian);
1694
1695 /** Add a text with a subtree of bitfields.
1696  @param tree the tree to append this item to
1697  @param tvb the tv buffer of the current data
1698  @param offset start of data in tvb
1699  @param name field name (NULL if bitfield contents should be used)
1700  @param fallback field name if none of bitfields were usable
1701  @param ett subtree index
1702  @param fields NULL-terminated array of bitfield indexes
1703  @param little_endian big or little endian byte representation
1704  @return the newly created item */
1705 extern proto_item *
1706 proto_tree_add_bitmask_text(proto_tree *tree, tvbuff_t *tvb, const guint offset, const guint len,
1707                 const char *name, const char *fallback,
1708                 const gint ett, const int **fields, const gboolean little_endian, const int flags);
1709
1710 #define BMT_NO_APPEND   0x01    /**< Don't change the title at all */
1711 #define BMT_NO_INT      0x02    /**< Don't add integral (non-boolean) fields to title */
1712 #define BMT_NO_FALSE    0x04    /**< Don't add booleans unless they're TRUE */
1713 #define BMT_NO_TFS      0x08    /**< Don't use true_false_string while formatting booleans */
1714
1715 /** Add bits to a proto_tree, using the text label registered to that item.
1716    The item is extracted from the tvbuff handed to it.
1717  @param tree the tree to append this item to
1718  @param hfindex field index. Fields for use with this function should have bitmask==0.
1719  @param tvb the tv buffer of the current data
1720  @param bit_offset start of data in tvb expressed in bits
1721  @param no_of_bits length of data in tvb expressed in bits
1722  @param little_endian big or little endian byte representation
1723  @return the newly created item */
1724 extern proto_item *
1725 proto_tree_add_bits_item(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits, const gboolean little_endian);
1726
1727 /** Add bits to a proto_tree, using the text label registered to that item.
1728    The item is extracted from the tvbuff handed to it.
1729  @param tree the tree to append this item to
1730  @param hfindex field index. Fields for use with this function should have bitmask==0.
1731  @param tvb the tv buffer of the current data
1732  @param bit_offset start of data in tvb expressed in bits
1733  @param no_of_bits length of data in tvb expressed in bits
1734  @param return_value if a pointer is passed here the value is returned.
1735  @param little_endian big or little endian byte representation
1736  @return the newly created item */
1737 extern proto_item *
1738 proto_tree_add_bits_ret_val(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits, guint64 *return_value, const gboolean little_endian);
1739
1740 /** Add bits for a FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32
1741     header field to a proto_tree, with the format generating the
1742     string for the value and with the field name being included automatically.
1743  @param tree the tree to append this item to
1744  @param hfindex field index
1745  @param tvb the tv buffer of the current data
1746  @param bit_offset start of data in tvb expressed in bits
1747  @param no_of_bits length of data in tvb expressed in bit
1748  @param value data to display
1749  @param format printf like format string
1750  @param ... printf like parameters
1751  @return the newly created item */
1752 extern proto_item *
1753 proto_tree_add_uint_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits,
1754         guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1755
1756 /** Add bits for a FT_BOOLEAN header field to a proto_tree, with
1757     the format generating the string for the value and with the field
1758     name being included automatically.
1759  @param tree the tree to append this item to
1760  @param hfindex field index
1761  @param tvb the tv buffer of the current data
1762  @param bit_offset start of data in tvb expressed in bits
1763  @param no_of_bits length of data in tvb expressed in bit
1764  @param value data to display
1765  @param format printf like format string
1766  @param ... printf like parameters
1767  @return the newly created item */
1768 extern proto_item *
1769 proto_tree_add_boolean_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits,
1770         guint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1771
1772 /** Add bits for a FT_INT8, FT_INT16, FT_INT24 or FT_INT32
1773     header field to a proto_tree, with the format generating the
1774     string for the value and with the field name being included automatically.
1775  @param tree the tree to append this item to
1776  @param hfindex field index
1777  @param tvb the tv buffer of the current data
1778  @param bit_offset start of data in tvb expressed in bits
1779  @param no_of_bits length of data in tvb expressed in bit
1780  @param value data to display
1781  @param format printf like format string
1782  @param ... printf like parameters
1783  @return the newly created item */
1784 extern proto_item *
1785 proto_tree_add_int_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits,
1786         gint32 value, const char *format, ...) G_GNUC_PRINTF(7,8);
1787
1788 /** Add bits for a FT_FLOAT header field to a proto_tree, with
1789     the format generating the string for the value and with the field
1790     name being included automatically.
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 bit_offset start of data in tvb expressed in bits
1795  @param no_of_bits length of data in tvb expressed in bit
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 extern proto_item *
1801 proto_tree_add_float_bits_format_value(proto_tree *tree, const int hf_index, tvbuff_t *tvb, const gint bit_offset, const gint no_of_bits,
1802         float value, const char *format, ...) G_GNUC_PRINTF(7,8);
1803
1804 /** Check if given string is a valid field name
1805  @param field_name the field name to check
1806  @return 0 if valid, else first illegal character */
1807 extern guchar
1808 proto_check_field_name(const gchar *field_name);
1809
1810
1811 /** Check if given string is a valid field name
1812  @param field_id the field id used for custom column
1813  @param result the buffer to fill with the field string
1814  @param expr the filter expression
1815  @param aize the size of the string buffer */
1816 const gchar *
1817 proto_custom_set(proto_tree* tree, const int field_id,
1818                              gchar *result,
1819                              gchar *expr, const int size );
1820
1821 #ifdef __cplusplus
1822 }
1823 #endif /* __cplusplus */
1824
1825 #endif /* proto.h */