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