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
  54 /** The header-field index for the special text pseudo-field. Exported by libwireshark.dll */
  55 WS_VAR_IMPORT int hf_text_only;
  56
  57 /** the maximum length of a protocol field string representation */
  58 #define ITEM_LABEL_LENGTH       240
  59
  60 struct _value_string;
  61
  62 /** Make a const value_string[] look like a _value_string pointer, used to set header_field_info.strings */
  63 #define VALS(x) (const struct _value_string*)(x)
  64
  65 /** Make a const true_false_string[] look like a _true_false_string pointer, used to set header_field_info.strings */
  66 #define TFS(x)  (const struct true_false_string*)(x)
  67
  68 struct _protocol;
  69
  70 /** Structure for information about a protocol */
  71 typedef struct _protocol protocol_t;
  72
  73 /** check protocol activation
  74  * @todo this macro looks like a hack */
  75 #define CHECK_DISPLAY_AS_X(x_handle,index, tvb, pinfo, tree) {  \
  76         if (!proto_is_protocol_enabled(find_protocol_by_id(index))) {   \
  77                 call_dissector(x_handle,tvb, pinfo, tree);              \
  78                 return;                                                 \
  79         }                                                               \
  80   }
  81
  82 /** Macro used for reporting errors in dissectors; it throws a
  83  * DissectorError exception, with the string passed as an argument
  84  * as the message for the exception, so that it can show up in
  85  * the Info column and the protocol tree.
  86  *
  87  * If that string is dynamically allocated, it should be allocated with
  88  * ep_alloc(); using ep_strdup_printf() would work.
  89  *
  90  * If the WIRESHARK_ABORT_ON_DISSECTOR_BUG environment variable is set,
  91  * it will call abort(), instead, to make it easier to get a stack trace.
  92  *
  93  * @param message string to use as the message
  94  */
  95 #define REPORT_DISSECTOR_BUG(message)  \
  96   ((getenv("WIRESHARK_ABORT_ON_DISSECTOR_BUG") != NULL) ? \
  97     abort() : \
  98     THROW_MESSAGE(DissectorError, message))
  99
 100 /** Macro used for assertions in dissectors; it doesn't abort, it just
 101  * throws a DissectorError exception, with the assertion failure
 102  * message as a parameter, so that it can show up in the protocol tree.
 103  *
 104  * @param expression expression to test in the assertion
 105  */
 106 #define DISSECTOR_ASSERT(expression)  \
 107   ((void) ((expression) ? (void)0 : \
 108    __DISSECTOR_ASSERT (expression, __FILE__, __LINE__)))
 109
 110 #if 0
 111 /* win32: using a debug breakpoint (int 3) can be very handy while debugging,
 112  * as the assert handling of GTK/GLib is currently not very helpful */
 113 #define DISSECTOR_ASSERT(expression)  \
 114 { if(!(expression)) _asm { int 3}; }
 115 #endif
 116
 117 /** Same as DISSECTOR_ASSERT(), but will throw DissectorError exception
 118  * unconditionally, much like GLIB's g_assert_not_reached works.
 119  */
 120 #define DISSECTOR_ASSERT_NOT_REACHED()  \
 121   (REPORT_DISSECTOR_BUG( \
 122     ep_strdup_printf("%s:%u: failed assertion \"DISSECTOR_ASSERT_NOT_REACHED\"", \
 123      __FILE__, __LINE__)))
 124
 125 #define __DISSECTOR_ASSERT_STRINGIFY(s) # s
 126
 127 #define __DISSECTOR_ASSERT(expression, file, lineno)  \
 128   (REPORT_DISSECTOR_BUG( \
 129     ep_strdup_printf("%s:%u: failed assertion \"%s\"", \
 130      file, lineno, __DISSECTOR_ASSERT_STRINGIFY(expression))))
 131
 132 /** radix for decimal values, used in header_field_info.display */
 133 typedef enum {
 134         BASE_NONE,      /**< none */
 135         BASE_DEC,       /**< decimal */
 136         BASE_HEX,       /**< hexadecimal */
 137         BASE_OCT,       /**< octal */
 138         BASE_DEC_HEX,   /**< decimal (hexadecimal) */
 139         BASE_HEX_DEC    /**< hexadecimal (decimal) */
 140 } base_display_e;
 141
 142 #define IS_BASE_DUAL(b) ((b)==BASE_DEC_HEX||(b)==BASE_HEX_DEC)
 143
 144 /** information describing a header field */
 145 typedef struct _header_field_info header_field_info;
 146
 147 /** information describing a header field */
 148 struct _header_field_info {
 149         /* ---------- set by dissector --------- */
 150         const char                              *name;      /**< full name of this field */
 151         const char                              *abbrev;    /**< abbreviated name of this field */
 152         enum ftenum                     type;       /**< field type, one of FT_ (from ftypes.h) */
 153         int                                     display;        /**< one of BASE_, or number of field bits for FT_BOOLEAN */
 154         const void                      *strings;       /**< _value_string (or true_false_string for FT_BOOLEAN), typically converted by VALS() or TFS() If this is an FT_PROTOCOL then it points to the associated protocol_t structure*/
 155         guint32                         bitmask;    /**< FT_BOOLEAN only: bitmask of interesting bits */
 156         const char                              *blurb;         /**< Brief description of field. */
 157
 158         /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */
 159         int                             id;             /**< Field ID */
 160         int                             parent;         /**< parent protocol tree */
 161                 /* This field keeps track of whether a field is
 162                  * referenced in any filter or not and if so how
 163                  * many times. If a filter is being referenced the
 164                  * refcount for the parent protocol is updated as well
 165                  */
 166         int                             ref_count;      /**< is this field referenced by a filter or not */
 167         int                             bitshift;       /**< bits to shift (FT_BOOLEAN only) */
 168         header_field_info               *same_name_next; /**< Link to next hfinfo with same abbrev*/
 169         header_field_info               *same_name_prev; /**< Link to previous hfinfo with same abbrev*/
 170 };
 171
 172 /**
 173  * HFILL initializes all the "set by proto routines" fields in a
 174  * _header_field_info. If new fields are added or removed, it should
 175  * be changed as necessary.
 176  */
 177 #define HFILL 0, 0, 0, 0, NULL, NULL
 178
 179 /** Used when registering many fields at once, using proto_register_field_array() */
 180 typedef struct hf_register_info {
 181         int                     *p_id;  /**< written to by register() function */
 182         header_field_info       hfinfo; /**< the field info to be registered */
 183 } hf_register_info;
 184
 185
 186
 187
 188 /** string representation, if one of the proto_tree_add_..._format() functions used */
 189 typedef struct _item_label_t {
 190         char representation[ITEM_LABEL_LENGTH];
 191 } item_label_t;
 192
 193
 194 /** Contains the field information for the proto_item. */
 195 typedef struct field_info {
 196         header_field_info       *hfinfo;    /**< pointer to registered field information */
 197         gint                            start;      /**< current start of data in field_info.ds_tvb */
 198         gint                            length;     /**< current data length of item in field_info.ds_tvb */
 199         gint                            tree_type;  /**< one of ETT_ or -1 */
 200         item_label_t            *rep;       /**< string for GUI tree */
 201         int                                     flags;      /**< bitfield like FI_GENERATED, ... */
 202         tvbuff_t                        *ds_tvb;    /**< data source tvbuff */
 203         fvalue_t                        value;
 204 } field_info;
 205
 206
 207 /** The protocol field should not be shown in the tree (it's used for filtering only),
 208  * used in field_info.flags. */
 209 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 210 #define FI_HIDDEN                       0x0001
 211 /** The protocol field should be displayed as "generated by Wireshark",
 212  * used in field_info.flags. */
 213 #define FI_GENERATED            0x0002
 214
 215
 216 /** convenience macro to get field_info.flags */
 217 #define FI_GET_FLAG(fi, flag) (fi->flags & flag)
 218 /** convenience macro to set field_info.flags */
 219 #define FI_SET_FLAG(fi, flag) (fi->flags = fi->flags | flag)
 220
 221 /** One of these exists for the entire protocol tree. Each proto_node
 222  * in the protocol tree points to the same copy. */
 223 typedef struct {
 224     GHashTable  *interesting_hfids;
 225     gboolean    visible;
 226 } tree_data_t;
 227
 228 /** Each proto_tree, proto_item is one of these. */
 229 typedef struct _proto_node {
 230         struct _proto_node *first_child;
 231         struct _proto_node *last_child;
 232         struct _proto_node *next;
 233         struct _proto_node *parent;
 234         field_info  *finfo;
 235         tree_data_t *tree_data;
 236 } proto_node;
 237
 238 /** A protocol tree element. */
 239 typedef proto_node proto_tree;
 240 /** A protocol item element. */
 241 typedef proto_node proto_item;
 242
 243 /* expert severities */
 244 #define PI_SEVERITY_MASK        0x001C  /* mask usually for internal use only! */
 245 /** Usual workflow, e.g. TCP connection establishing */
 246 #define PI_CHAT                         0x0004
 247 /** Notable messages, e.g. an application returned an "usual" error code like HTTP 404 */
 248 #define PI_NOTE                         0x0008
 249 /** Warning, e.g. application returned an "unusual" error code */
 250 #define PI_WARN                         0x000C
 251 /** Serious problems, e.g. [Malformed Packet] */
 252 #define PI_ERROR                        0x0010
 253
 254 /* expert "event groups" */
 255 #define PI_GROUP_MASK           0xFF00  /* mask usually for internal use only! */
 256 /** The protocol field has a bad checksum, usually PI_WARN */
 257 #define PI_CHECKSUM                     0x0100
 258 /** The protocol field indicates a sequence problem (e.g. TCP window is zero) */
 259 #define PI_SEQUENCE                     0x0200
 260 /** The protocol field indicates a bad application response code (e.g. HTTP 404), usually PI_NOTE */
 261 #define PI_RESPONSE_CODE        0x0400
 262 /** The protocol field indicates an application request (e.g. File Handle == xxxx), usually PI_CHAT */
 263 #define PI_REQUEST_CODE     0x0500
 264 /** The data is undecoded, the protocol dissection is incomplete here, usually PI_WARN */
 265 #define PI_UNDECODED            0x0800
 266 /** The protocol field indicates a reassemble (e.g. DCE/RPC defragmentation), usually PI_CHAT (or PI_ERROR) */
 267 #define PI_REASSEMBLE           0x1000
 268 /** The packet data is malformed, the dissector has "given up", usually PI_ERROR */
 269 #define PI_MALFORMED            0x2000
 270 /** A generic debugging message (shouldn't remain in production code!), usually PI_ERROR */
 271 #define PI_DEBUG                        0x4000
 272 /** The protocol field indicates a security probem (e.g. unsecure implementation) */
 273 /*#define PI_SECURITY                   0x8000*/
 274
 275 /* add more, see http://wiki.wireshark.org/Development/ExpertInfo */
 276
 277
 278 /** is this protocol field hidden from the protocol tree display (used for filtering only)? */
 279 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 280 #define PROTO_ITEM_IS_HIDDEN(proto_item)        \
 281         ((proto_item) ? FI_GET_FLAG((proto_item)->finfo, FI_HIDDEN) : 0)
 282 /** mark this protocol field to be hidden from the protocol tree display (used for filtering only) */
 283 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 284 #define PROTO_ITEM_SET_HIDDEN(proto_item)       \
 285         ((proto_item) ? FI_SET_FLAG((proto_item)->finfo, FI_HIDDEN) : 0)
 286 /** is this protocol field generated by Wireshark (and not read from the packet data)? */
 287 #define PROTO_ITEM_IS_GENERATED(proto_item)     \
 288         ((proto_item) ? FI_GET_FLAG((proto_item)->finfo, FI_GENERATED) : 0)
 289 /** mark this protocol field as generated by Wireshark (and not read from the packet data) */
 290 #define PROTO_ITEM_SET_GENERATED(proto_item)    \
 291         ((proto_item) ? FI_SET_FLAG((proto_item)->finfo, FI_GENERATED) : 0)
 292
 293 typedef void (*proto_tree_foreach_func)(proto_node *, gpointer);
 294
 295 extern void proto_tree_children_foreach(proto_tree *tree,
 296     proto_tree_foreach_func func, gpointer data);
 297
 298 /** Retrieve the field_info from a proto_item */
 299 #define PITEM_FINFO(proto_item)  ((proto_item)->finfo)
 300
 301 /** Retrieve the tree_data_t from a proto_tree */
 302 #define PTREE_DATA(proto_tree)   ((proto_tree)->tree_data)
 303
 304
 305
 306 /** Sets up memory used by proto routines. Called at program startup */
 307 extern void proto_init(const char *plugin_dir,
 308     void (register_all_protocols)(void), void (register_all_handoffs)(void));
 309
 310 /** Frees memory used by proto routines. Called at program shutdown */
 311 extern void proto_cleanup(void);
 312
 313 /** This function takes a tree and a protocol id as parameter and
 314     will return TRUE/FALSE for whether the protocol or any of the filterable
 315     fields in the protocol is referenced by any fitlers.
 316     If this function returns FALSE then it is safe to skip any
 317         proto_tree_add_...() calls and just treat the call as if the
 318     dissector was called with tree==NULL.
 319     If you reset the tree to NULL by this dissector returning FALSE,
 320     you will still need to call any subdissector with the original value of
 321     tree or filtering will break.
 322
 323     The purpose of this is to optimize wireshark for speed and make it
 324     faster for when filters are being used.
 325 */
 326 extern gboolean proto_field_is_referenced(proto_tree *tree, int proto_id);
 327
 328
 329
 330 /** Create a subtree under an existing item.
 331  @param ti the parent item of the new subtree
 332  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
 333  @return the new subtree */
 334 extern proto_tree* proto_item_add_subtree(proto_item *ti, gint idx);
 335
 336 /** Get an existing subtree under an item.
 337  @param ti the parent item of the subtree
 338  @return the subtree or NULL */
 339 extern proto_tree* proto_item_get_subtree(proto_item *ti);
 340
 341 /** Get the parent of a subtree item.
 342  @param ti the child item in the subtree
 343  @return parent item or NULL */
 344 extern proto_item* proto_item_get_parent(proto_item *ti);
 345
 346 /** Get Nth generation parent item.
 347  @param ti the child item in the subtree
 348  @param gen the generation to get (using 1 here is the same as using proto_item_get_parent())
 349  @return parent item */
 350 extern proto_item* proto_item_get_parent_nth(proto_item *ti, int gen);
 351
 352 /** Replace text of item after it already has been created.
 353  @param ti the item to set the text
 354  @param format printf like format string
 355  @param ... printf like parameters */
 356 extern void proto_item_set_text(proto_item *ti, const char *format, ...)
 357         GNUC_FORMAT_CHECK(printf, 2,3);
 358
 359 /** Append to text of item after it has already been created.
 360  @param ti the item to append the text to
 361  @param format printf like format string
 362  @param ... printf like parameters */
 363 extern void proto_item_append_text(proto_item *ti, const char *format, ...)
 364         GNUC_FORMAT_CHECK(printf, 2,3);
 365
 366 /** Set proto_item's length inside tvb, after it has already been created.
 367  @param ti the item to set the length
 368  @param length the new length ot the item */
 369 extern void proto_item_set_len(proto_item *ti, gint length);
 370
 371 /**
 372  * Sets the length of the item based on its start and on the specified
 373  * offset, which is the offset past the end of the item; as the start
 374  * in the item is relative to the beginning of the data source tvbuff,
 375  * we need to pass in a tvbuff.
 376  @param ti the item to set the length
 377  @param tvb end is relative to this tvbuff
 378  @param end this end offset is relative to the beginning of tvb
 379  @todo make usage clearer, I don't understand it!
 380  */
 381 extern void proto_item_set_end(proto_item *ti, tvbuff_t *tvb, gint end);
 382
 383 /** Get length of a proto_item. Useful after using proto_tree_add_item()
 384  * to add a variable-length field (e.g., FT_NSTRING_UINT8).
 385  @param ti the item to get the length from
 386  @return the current length */
 387 extern int proto_item_get_len(proto_item *ti);
 388
 389 /**
 390  * Sets an expert info to the proto_item.
 391  @param ti the item to set the expert info
 392  @param group the group of this info (e.g. PI_CHECKSUM)
 393  @param severity of this info (e.g. PI_ERROR)
 394  @return TRUE if value was written
 395  */
 396 extern gboolean proto_item_set_expert_flags(proto_item *ti, int group, int severity);
 397
 398
 399
 400
 401 /** Creates a new proto_tree root.
 402  @return the new tree root */
 403 extern proto_tree* proto_tree_create_root(void);
 404
 405 /** Clear memory for entry proto_tree. Clears proto_tree struct also.
 406  @param tree the tree to free */
 407 extern void proto_tree_free(proto_tree *tree);
 408
 409 /** Set the tree visible or invisible.
 410  Is the parsing being done for a visible proto_tree or an invisible one?
 411  By setting this correctly, the proto_tree creation is sped up by not
 412  having to call g_vsnprintf and copy strings around.
 413  @param tree the tree to be set
 414  @param visible ... or not  */
 415 extern void
 416 proto_tree_set_visible(proto_tree *tree, gboolean visible);
 417
 418 /** Mark a field/protocol ID as "interesting".
 419  @param tree the tree to be set
 420  @param hfid the interesting field id
 421  @todo what *does* interesting mean? */
 422 extern void
 423 proto_tree_prime_hfid(proto_tree *tree, int hfid);
 424
 425 /** Get a parent item of a subtree.
 426  @param tree the tree to get the parent from
 427  @return parent item */
 428 extern proto_item* proto_tree_get_parent(proto_tree *tree);
 429
 430 /** Get the root tree from any subtree.
 431  @param tree the tree to get the root from
 432  @return root tree */
 433 extern proto_tree* proto_tree_get_root(proto_tree *tree);
 434
 435 /** Move an existing item behind another existing item.
 436  @param tree the tree to which both items belong
 437  @param fixed_item the item which keeps it's position
 438  @param item_to_move the item which will be moved */
 439 extern void proto_tree_move_item(proto_tree *tree, proto_item *fixed_item, proto_item *item_to_move);
 440
 441
 442
 443 /** Add an item to a proto_tree, using the text label registered to that item.
 444    The item is extracted from the tvbuff handed to it.
 445  @param tree the tree to append this item to
 446  @param hfindex field index
 447  @param tvb the tv buffer of the current data
 448  @param start start of data in tvb
 449  @param length length of data in tvb
 450  @param little_endian big or little endian byte representation
 451  @return the newly created item */
 452 extern proto_item *
 453 proto_tree_add_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 454     gint start, gint length, gboolean little_endian);
 455
 456 /** Add a hidden item to a proto_tree.
 457  @deprecated use proto_tree_add_item() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 458 extern proto_item *
 459 proto_tree_add_item_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 460     gint start, gint length, gboolean little_endian);
 461
 462 /** Add a text-only node to a proto_tree.
 463  @param tree the tree to append this item to
 464  @param tvb the tv buffer of the current data
 465  @param start start of data in tvb
 466  @param length length of data in tvb
 467  @param format printf like format string
 468  @param ... printf like parameters
 469  @return the newly created item */
 470 extern proto_item *
 471 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
 472         ...) GNUC_FORMAT_CHECK(printf,5,6);
 473
 474 /** Add a text-only node to a proto_tree using a variable argument list.
 475  @param tree the tree to append this item to
 476  @param tvb the tv buffer of the current data
 477  @param start start of data in tvb
 478  @param length length of data in tvb
 479  @param format printf like format string
 480  @param ap variable argument list
 481  @return the newly created item */
 482 extern proto_item *
 483 proto_tree_add_text_valist(proto_tree *tree, tvbuff_t *tvb, gint start,
 484         gint length, const char *format, va_list ap);
 485
 486
 487 /** Add a FT_NONE field to a proto_tree.
 488  @param tree the tree to append this item to
 489  @param hfindex field index
 490  @param tvb the tv buffer of the current data
 491  @param start start of data in tvb
 492  @param length length of data in tvb
 493  @param format printf like format string
 494  @param ... printf like parameters
 495  @return the newly created item */
 496 extern proto_item *
 497 proto_tree_add_none_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 498         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 499
 500 /** Add a FT_PROTOCOL to a proto_tree.
 501  @param tree the tree to append this item to
 502  @param hfindex field index
 503  @param tvb the tv buffer of the current data
 504  @param start start of data in tvb
 505  @param length length of data in tvb
 506  @param format printf like format string
 507  @param ... printf like parameters
 508  @return the newly created item */
 509 extern proto_item *
 510 proto_tree_add_protocol_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 511         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 512
 513
 514
 515
 516 /** Add a FT_BYTES to a proto_tree.
 517  @param tree the tree to append this item to
 518  @param hfindex field index
 519  @param tvb the tv buffer of the current data
 520  @param start start of data in tvb
 521  @param length length of data in tvb
 522  @param start_ptr pointer to the data to display
 523  @return the newly created item */
 524 extern proto_item *
 525 proto_tree_add_bytes(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 526         gint length, const guint8* start_ptr);
 527
 528 /** Add a hidden FT_BYTES to a proto_tree.
 529  @deprecated use proto_tree_add_bytes() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 530 extern proto_item *
 531 proto_tree_add_bytes_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 532         gint length, const guint8* start_ptr);
 533
 534 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
 535     the string for the value and with the field name being included
 536     automatically.
 537  @param tree the tree to append this item to
 538  @param hfindex field index
 539  @param tvb the tv buffer of the current data
 540  @param start start of data in tvb
 541  @param length length of data in tvb
 542  @param start_ptr pointer to the data to display
 543  @param format printf like format string
 544  @param ... printf like parameters
 545  @return the newly created item */
 546 extern proto_item *
 547 proto_tree_add_bytes_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 548         gint start, gint length, const guint8* start_ptr, const char *format,
 549         ...) GNUC_FORMAT_CHECK(printf,7,8);
 550
 551 /** Add a formatted FT_BYTES to a proto_tree, with the format generating
 552     the entire string for the entry, including any field name.
 553  @param tree the tree to append this item to
 554  @param hfindex field index
 555  @param tvb the tv buffer of the current data
 556  @param start start of data in tvb
 557  @param length length of data in tvb
 558  @param start_ptr pointer to the data to display
 559  @param format printf like format string
 560  @param ... printf like parameters
 561  @return the newly created item */
 562 extern proto_item *
 563 proto_tree_add_bytes_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 564         gint length, const guint8* start_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 565
 566 /** Add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 567  @param tree the tree to append this item to
 568  @param hfindex field index
 569  @param tvb the tv buffer of the current data
 570  @param start start of data in tvb
 571  @param length length of data in tvb
 572  @param value_ptr pointer to the data to display
 573  @return the newly created item */
 574 extern proto_item *
 575 proto_tree_add_time(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 576         gint length, nstime_t* value_ptr);
 577
 578 /** Add a hidden FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 579  @deprecated use proto_tree_add_time() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 580 extern proto_item *
 581 proto_tree_add_time_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 582         gint length, nstime_t* value_ptr);
 583
 584 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
 585     the format generating the string for the value and with the field name
 586     being included automatically.
 587  @param tree the tree to append this item to
 588  @param hfindex field index
 589  @param tvb the tv buffer of the current data
 590  @param start start of data in tvb
 591  @param length length of data in tvb
 592  @param value_ptr pointer to the data to display
 593  @param format printf like format string
 594  @param ... printf like parameters
 595  @return the newly created item */
 596 extern proto_item *
 597 proto_tree_add_time_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 598         gint start, gint length, nstime_t* value_ptr, const char *format, ...)
 599         GNUC_FORMAT_CHECK(printf,7,8);
 600
 601 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree, with
 602     the format generating the entire string for the entry, including any field
 603     name.
 604  @param tree the tree to append this item to
 605  @param hfindex field index
 606  @param tvb the tv buffer of the current data
 607  @param start start of data in tvb
 608  @param length length of data in tvb
 609  @param value_ptr pointer to the data to display
 610  @param format printf like format string
 611  @param ... printf like parameters
 612  @return the newly created item */
 613 extern proto_item *
 614 proto_tree_add_time_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 615         gint length, nstime_t* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 616
 617 /** Add a FT_IPXNET to a proto_tree.
 618  @param tree the tree to append this item to
 619  @param hfindex field index
 620  @param tvb the tv buffer of the current data
 621  @param start start of data in tvb
 622  @param length length of data in tvb
 623  @param value data to display
 624  @return the newly created item */
 625 extern proto_item *
 626 proto_tree_add_ipxnet(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 627         gint length, guint32 value);
 628
 629 /** Add a hidden FT_IPXNET to a proto_tree.
 630  @deprecated use proto_tree_add_ipxnet() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 631 extern proto_item *
 632 proto_tree_add_ipxnet_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 633         gint length, guint32 value);
 634
 635 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
 636     the string for the value and with the field name being included
 637     automatically.
 638  @param tree the tree to append this item to
 639  @param hfindex field index
 640  @param tvb the tv buffer of the current data
 641  @param start start of data in tvb
 642  @param length length of data in tvb
 643  @param value data to display
 644  @param format printf like format string
 645  @param ... printf like parameters
 646  @return the newly created item */
 647 extern proto_item *
 648 proto_tree_add_ipxnet_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 649         gint start, gint length, guint32 value, const char *format, ...)
 650         GNUC_FORMAT_CHECK(printf,7,8);
 651
 652 /** Add a formatted FT_IPXNET to a proto_tree, with the format generating
 653     the entire string for the entry, including any field name.
 654  @param tree the tree to append this item to
 655  @param hfindex field index
 656  @param tvb the tv buffer of the current data
 657  @param start start of data in tvb
 658  @param length length of data in tvb
 659  @param value data to display
 660  @param format printf like format string
 661  @param ... printf like parameters
 662  @return the newly created item */
 663 extern proto_item *
 664 proto_tree_add_ipxnet_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 665         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 666
 667 /** Add a FT_IPv4 to a proto_tree.
 668  @param tree the tree to append this item to
 669  @param hfindex field index
 670  @param tvb the tv buffer of the current data
 671  @param start start of data in tvb
 672  @param length length of data in tvb
 673  @param value data to display
 674  @return the newly created item */
 675 extern proto_item *
 676 proto_tree_add_ipv4(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 677         gint length, guint32 value);
 678
 679 /** Add a hidden FT_IPv4 to a proto_tree.
 680  @deprecated use proto_tree_add_ipv4() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 681 extern proto_item *
 682 proto_tree_add_ipv4_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 683         gint length, guint32 value);
 684
 685 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
 686     the string for the value and with the field name being included
 687     automatically.
 688  @param tree the tree to append this item to
 689  @param hfindex field index
 690  @param tvb the tv buffer of the current data
 691  @param start start of data in tvb
 692  @param length length of data in tvb
 693  @param value data to display
 694  @param format printf like format string
 695  @param ... printf like parameters
 696  @return the newly created item */
 697 extern proto_item *
 698 proto_tree_add_ipv4_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 699         gint start, gint length, guint32 value, const char *format, ...)
 700         GNUC_FORMAT_CHECK(printf,7,8);
 701
 702 /** Add a formatted FT_IPv4 to a proto_tree, with the format generating
 703     the entire string for the entry, including any field name.
 704  @param tree the tree to append this item to
 705  @param hfindex field index
 706  @param tvb the tv buffer of the current data
 707  @param start start of data in tvb
 708  @param length length of data in tvb
 709  @param value data to display
 710  @param format printf like format string
 711  @param ... printf like parameters
 712  @return the newly created item */
 713 extern proto_item *
 714 proto_tree_add_ipv4_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 715         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 716
 717 /** Add a FT_IPv6 to a proto_tree.
 718  @param tree the tree to append this item to
 719  @param hfindex field index
 720  @param tvb the tv buffer of the current data
 721  @param start start of data in tvb
 722  @param length length of data in tvb
 723  @param value_ptr data to display
 724  @return the newly created item */
 725 extern proto_item *
 726 proto_tree_add_ipv6(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 727         gint length, const guint8* value_ptr);
 728
 729 /** Add a hidden FT_IPv6 to a proto_tree.
 730  @deprecated use proto_tree_add_ipv6() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 731 extern proto_item *
 732 proto_tree_add_ipv6_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 733         gint length, const guint8* value_ptr);
 734
 735 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
 736     the string for the value and with the field name being included
 737     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 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_ipv6_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 749         gint start, gint length, const guint8* value_ptr, const char *format,
 750         ...) GNUC_FORMAT_CHECK(printf,7,8);
 751
 752 /** Add a formatted FT_IPv6 to a proto_tree, with the format generating
 753     the entire string for the entry, including any field name.
 754  @param tree the tree to append this item to
 755  @param hfindex field index
 756  @param tvb the tv buffer of the current data
 757  @param start start of data in tvb
 758  @param length length of data in tvb
 759  @param value_ptr data to display
 760  @param format printf like format string
 761  @param ... printf like parameters
 762  @return the newly created item */
 763 extern proto_item *
 764 proto_tree_add_ipv6_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 765         gint length, const guint8* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 766
 767 /** Add a FT_ETHER to a proto_tree.
 768  @param tree the tree to append this item to
 769  @param hfindex field index
 770  @param tvb the tv buffer of the current data
 771  @param start start of data in tvb
 772  @param length length of data in tvb
 773  @param value data to display
 774  @return the newly created item */
 775 extern proto_item *
 776 proto_tree_add_ether(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 777         gint length, const guint8* value);
 778
 779 /** Add a hidden FT_ETHER to a proto_tree.
 780  @deprecated use proto_tree_add_ether() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 781 extern proto_item *
 782 proto_tree_add_ether_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 783         gint length, const guint8* value);
 784
 785 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
 786     the string for the value and with the field name being included
 787     automatically.
 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 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_ether_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 799         gint start, gint length, const guint8* value, const char *format, ...)
 800         GNUC_FORMAT_CHECK(printf,7,8);
 801
 802 /** Add a formatted FT_ETHER to a proto_tree, with the format generating
 803     the entire string for the entry, including any field name.
 804  @param tree the tree to append this item to
 805  @param hfindex field index
 806  @param tvb the tv buffer of the current data
 807  @param start start of data in tvb
 808  @param length length of data in tvb
 809  @param value data to display
 810  @param format printf like format string
 811  @param ... printf like parameters
 812  @return the newly created item */
 813 extern proto_item *
 814 proto_tree_add_ether_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 815         gint length, const guint8* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 816
 817 /** Add a FT_GUID to a proto_tree.
 818  @param tree the tree to append this item to
 819  @param hfindex field index
 820  @param tvb the tv buffer of the current data
 821  @param start start of data in tvb
 822  @param length length of data in tvb
 823  @param value_ptr data to display
 824  @return the newly created item */
 825 extern proto_item *
 826 proto_tree_add_guid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 827         gint length, const e_guid_t *value_ptr);
 828
 829 /** Add a hidden FT_GUID to a proto_tree.
 830  @deprecated use proto_tree_add_guid() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 831 extern proto_item *
 832 proto_tree_add_guid_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 833         gint length, const e_guid_t *value_ptr);
 834
 835 /** Add a formatted FT_GUID to a proto_tree, with the format generating
 836     the string for the value and with the field name being included
 837     automatically.
 838  @param tree the tree to append this item to
 839  @param hfindex field index
 840  @param tvb the tv buffer of the current data
 841  @param start start of data in tvb
 842  @param length length of data in tvb
 843  @param value_ptr data to display
 844  @param format printf like format string
 845  @param ... printf like parameters
 846  @return the newly created item */
 847 extern proto_item *
 848 proto_tree_add_guid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 849         gint start, gint length, const e_guid_t *value_ptr, const char *format,
 850         ...) GNUC_FORMAT_CHECK(printf,7,8);
 851
 852 /** Add a formatted FT_GUID to a proto_tree, with the format generating
 853     the entire string for the entry, including any field name.
 854  @param tree the tree to append this item to
 855  @param hfindex field index
 856  @param tvb the tv buffer of the current data
 857  @param start start of data in tvb
 858  @param length length of data in tvb
 859  @param value_ptr data to display
 860  @param format printf like format string
 861  @param ... printf like parameters
 862  @return the newly created item */
 863 extern proto_item *
 864 proto_tree_add_guid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 865         gint length, const e_guid_t *value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 866
 867 /** Add a FT_OID to a proto_tree.
 868  @param tree the tree to append this item to
 869  @param hfindex field index
 870  @param tvb the tv buffer of the current data
 871  @param start start of data in tvb
 872  @param length length of data in tvb
 873  @param value_ptr data to display
 874  @return the newly created item */
 875 extern proto_item *
 876 proto_tree_add_oid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 877         gint length, const guint8* value_ptr);
 878
 879 /** Add a hidden FT_OID to a proto_tree.
 880  @deprecated use proto_tree_add_oid() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 881 extern proto_item *
 882 proto_tree_add_oid_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 883         gint length, const guint8* value_ptr);
 884
 885 /** Add a formatted FT_OID to a proto_tree, with the format generating
 886     the string for the value and with the field name being included
 887     automatically.
 888  @param tree the tree to append this item to
 889  @param hfindex field index
 890  @param tvb the tv buffer of the current data
 891  @param start start of data in tvb
 892  @param length length of data in tvb
 893  @param value_ptr data to display
 894  @param format printf like format string
 895  @param ... printf like parameters
 896  @return the newly created item */
 897 extern proto_item *
 898 proto_tree_add_oid_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 899         gint start, gint length, const guint8* value_ptr, const char *format,
 900         ...) GNUC_FORMAT_CHECK(printf,7,8);
 901
 902 /** Add a formatted FT_OID to a proto_tree, with the format generating
 903     the entire string for the entry, including any field name.
 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(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 915         gint length, const guint8* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 916
 917 /** Add a FT_STRING to a proto_tree.
 918  @param tree the tree to append this item to
 919  @param hfindex field index
 920  @param tvb the tv buffer of the current data
 921  @param start start of data in tvb
 922  @param length length of data in tvb
 923  @param value data to display
 924  @return the newly created item */
 925 extern proto_item *
 926 proto_tree_add_string(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 927         gint length, const char* value);
 928
 929 /** Add a hidden FT_STRING to a proto_tree.
 930  @deprecated use proto_tree_add_string() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 931 extern proto_item *
 932 proto_tree_add_string_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 933         gint length, const char* value);
 934
 935 /** Add a formatted FT_STRING to a proto_tree, with the format generating
 936     the string for the value and with the field name being included
 937     automatically.
 938  @param tree the tree to append this item to
 939  @param hfindex field index
 940  @param tvb the tv buffer of the current data
 941  @param start start of data in tvb
 942  @param length length of data in tvb
 943  @param value data to display
 944  @param format printf like format string
 945  @param ... printf like parameters
 946  @return the newly created item */
 947 extern proto_item *
 948 proto_tree_add_string_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 949         gint start, gint length, const char* value, const char *format, ...)
 950         GNUC_FORMAT_CHECK(printf,7,8);
 951
 952 /** Add a formatted FT_STRING to a proto_tree, with the format generating
 953     the entire string for the entry, including any field name.
 954  @param tree the tree to append this item to
 955  @param hfindex field index
 956  @param tvb the tv buffer of the current data
 957  @param start start of data in tvb
 958  @param length length of data in tvb
 959  @param value data to display
 960  @param format printf like format string
 961  @param ... printf like parameters
 962  @return the newly created item */
 963 extern proto_item *
 964 proto_tree_add_string_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 965         gint length, const char* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 966
 967 /** Add a FT_BOOLEAN to a proto_tree.
 968  @param tree the tree to append this item to
 969  @param hfindex field index
 970  @param tvb the tv buffer of the current data
 971  @param start start of data in tvb
 972  @param length length of data in tvb
 973  @param value data to display
 974  @return the newly created item */
 975 extern proto_item *
 976 proto_tree_add_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 977         gint length, guint32 value);
 978
 979 /** Add a hidden FT_BOOLEAN to a proto_tree.
 980  @deprecated use proto_tree_add_boolean() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 981 extern proto_item *
 982 proto_tree_add_boolean_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 983         gint length, guint32 value);
 984
 985 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
 986     the string for the value and with the field name being included
 987     automatically.
 988  @param tree the tree to append this item to
 989  @param hfindex field index
 990  @param tvb the tv buffer of the current data
 991  @param start start of data in tvb
 992  @param length length of data in tvb
 993  @param value data to display
 994  @param format printf like format string
 995  @param ... printf like parameters
 996  @return the newly created item */
 997 extern proto_item *
 998 proto_tree_add_boolean_format_value(proto_tree *tree, int hfindex,
 999         tvbuff_t *tvb, gint start, gint length, guint32 value,
1000         const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1001
1002 /** Add a formatted FT_BOOLEAN to a proto_tree, with the format generating
1003     the entire string for the entry, including any field name.
1004  @param tree the tree to append this item to
1005  @param hfindex field index
1006  @param tvb the tv buffer of the current data
1007  @param start start of data in tvb
1008  @param length length of data in tvb
1009  @param value data to display
1010  @param format printf like format string
1011  @param ... printf like parameters
1012  @return the newly created item */
1013 extern proto_item *
1014 proto_tree_add_boolean_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1015         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1016
1017 /** Add a FT_FLOAT to a proto_tree.
1018  @param tree the tree to append this item to
1019  @param hfindex field index
1020  @param tvb the tv buffer of the current data
1021  @param start start of data in tvb
1022  @param length length of data in tvb
1023  @param value data to display
1024  @return the newly created item */
1025 extern proto_item *
1026 proto_tree_add_float(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1027         gint length, float value);
1028
1029 /** Add a hidden FT_FLOAT to a proto_tree.
1030  @deprecated use proto_tree_add_float() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
1031 extern proto_item *
1032 proto_tree_add_float_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1033         gint length, float value);
1034
1035 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1036     the string for the value and with the field name being included
1037     automatically.
1038  @param tree the tree to append this item to
1039  @param hfindex field index
1040  @param tvb the tv buffer of the current data
1041  @param start start of data in tvb
1042  @param length length of data in tvb
1043  @param value data to display
1044  @param format printf like format string
1045  @param ... printf like parameters
1046  @return the newly created item */
1047 extern proto_item *
1048 proto_tree_add_float_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1049         gint start, gint length, float value, const char *format, ...)
1050         GNUC_FORMAT_CHECK(printf,7,8);
1051
1052 /** Add a formatted FT_FLOAT to a proto_tree, with the format generating
1053     the entire string for the entry, including any field name.
1054  @param tree the tree to append this item to
1055  @param hfindex field index
1056  @param tvb the tv buffer of the current data
1057  @param start start of data in tvb
1058  @param length length of data in tvb
1059  @param value data to display
1060  @param format printf like format string
1061  @param ... printf like parameters
1062  @return the newly created item */
1063 extern proto_item *
1064 proto_tree_add_float_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1065         gint length, float value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1066
1067 /** Add a FT_DOUBLE to a proto_tree.
1068  @param tree the tree to append this item to
1069  @param hfindex field index
1070  @param tvb the tv buffer of the current data
1071  @param start start of data in tvb
1072  @param length length of data in tvb
1073  @param value data to display
1074  @return the newly created item */
1075 extern proto_item *
1076 proto_tree_add_double(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1077         gint length, double value);
1078
1079 /** Add a hidden FT_DOUBLE to a proto_tree.
1080  @deprecated use proto_tree_add_double() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
1081 extern proto_item *
1082 proto_tree_add_double_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1083         gint length, double value);
1084
1085 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1086     the string for the value and with the field name being included
1087     automatically.
1088  @param tree the tree to append this item to
1089  @param hfindex field index
1090  @param tvb the tv buffer of the current data
1091  @param start start of data in tvb
1092  @param length length of data in tvb
1093  @param value data to display
1094  @param format printf like format string
1095  @param ... printf like parameters
1096  @return the newly created item */
1097 extern proto_item *
1098 proto_tree_add_double_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1099         gint start, gint length, double value, const char *format, ...)
1100         GNUC_FORMAT_CHECK(printf,7,8);
1101
1102 /** Add a formatted FT_DOUBLE to a proto_tree, with the format generating
1103     the entire string for the entry, including any field name.
1104  @param tree the tree to append this item to
1105  @param hfindex field index
1106  @param tvb the tv buffer of the current data
1107  @param start start of data in tvb
1108  @param length length of data in tvb
1109  @param value data to display
1110  @param format printf like format string
1111  @param ... printf like parameters
1112  @return the newly created item */
1113 extern proto_item *
1114 proto_tree_add_double_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1115         gint length, double value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1116
1117 /** Add one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
1118  @param tree the tree to append this item to
1119  @param hfindex field index
1120  @param tvb the tv buffer of the current data
1121  @param start start of data in tvb
1122  @param length length of data in tvb
1123  @param value data to display
1124  @return the newly created item */
1125 extern proto_item *
1126 proto_tree_add_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1127         gint length, guint32 value);
1128
1129 /** Add a hidden FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
1130  @deprecated use proto_tree_add_uint() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
1131 extern proto_item *
1132 proto_tree_add_uint_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1133         gint length, guint32 value);
1134
1135 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1136     with the format generating the string for the value and with the field
1137     name being included automatically.
1138  @param tree the tree to append this item to
1139  @param hfindex field index
1140  @param tvb the tv buffer of the current data
1141  @param start start of data in tvb
1142  @param length length of data in tvb
1143  @param value data to display
1144  @param format printf like format string
1145  @param ... printf like parameters
1146  @return the newly created item */
1147 extern proto_item *
1148 proto_tree_add_uint_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1149         gint start, gint length, guint32 value, const char *format, ...)
1150         GNUC_FORMAT_CHECK(printf,7,8);
1151
1152 /** Add a formatted FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree,
1153     with the format generating the entire string for the entry, including any
1154     field name.
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  @param format printf like format string
1162  @param ... printf like parameters
1163  @return the newly created item */
1164 extern proto_item *
1165 proto_tree_add_uint_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1166         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1167
1168 /** Add an FT_UINT64 to a proto_tree.
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  @return the newly created item */
1176 extern proto_item *
1177 proto_tree_add_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1178         gint length, guint64 value);
1179
1180 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1181     the string for the value and with the field name being included
1182     automatically.
1183  @param tree the tree to append this item to
1184  @param hfindex field index
1185  @param tvb the tv buffer of the current data
1186  @param start start of data in tvb
1187  @param length length of data in tvb
1188  @param value data to display
1189  @param format printf like format string
1190  @param ... printf like parameters
1191  @return the newly created item */
1192 extern proto_item *
1193 proto_tree_add_uint64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1194         gint start, gint length, guint64 value, const char *format, ...)
1195         GNUC_FORMAT_CHECK(printf,7,8);
1196
1197 /** Add a formatted FT_UINT64 to a proto_tree, with the format generating
1198     the entire string for the entry, including any field name.
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  @param format printf like format string
1206  @param ... printf like parameters
1207  @return the newly created item */
1208 extern proto_item *
1209 proto_tree_add_uint64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1210         gint length, guint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1211
1212 /** Add one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
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  @return the newly created item */
1220 extern proto_item *
1221 proto_tree_add_int(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1222         gint length, gint32 value);
1223
1224 /** Add a hidden FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
1225  @deprecated use proto_tree_add_int() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
1226 extern proto_item *
1227 proto_tree_add_int_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1228         gint length, gint32 value);
1229
1230 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
1231     with the format generating the string for the value and with the field
1232     name being included automatically.
1233  @param tree the tree to append this item to
1234  @param hfindex field index
1235  @param tvb the tv buffer of the current data
1236  @param start start of data in tvb
1237  @param length length of data in tvb
1238  @param value data to display
1239  @param format printf like format string
1240  @param ... printf like parameters
1241  @return the newly created item */
1242 extern proto_item *
1243 proto_tree_add_int_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1244         gint start, gint length, gint32 value, const char *format, ...)
1245         GNUC_FORMAT_CHECK(printf,7,8);
1246
1247 /** Add a formatted FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree,
1248     with the format generating the entire string for the entry, including
1249     any field name.
1250  @param tree the tree to append this item to
1251  @param hfindex field index
1252  @param tvb the tv buffer of the current data
1253  @param start start of data in tvb
1254  @param length length of data in tvb
1255  @param value data to display
1256  @param format printf like format string
1257  @param ... printf like parameters
1258  @return the newly created item */
1259 extern proto_item *
1260 proto_tree_add_int_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1261         gint length, gint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1262
1263 /** Add an FT_INT64 to a proto_tree.
1264  @param tree the tree to append this item to
1265  @param hfindex field index
1266  @param tvb the tv buffer of the current data
1267  @param start start of data in tvb
1268  @param length length of data in tvb
1269  @param value data to display
1270  @return the newly created item */
1271 extern proto_item *
1272 proto_tree_add_int64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1273         gint length, gint64 value);
1274
1275 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
1276     the string for the value and with the field name being included
1277     automatically.
1278  @param tree the tree to append this item to
1279  @param hfindex field index
1280  @param tvb the tv buffer of the current data
1281  @param start start of data in tvb
1282  @param length length of data in tvb
1283  @param value data to display
1284  @param format printf like format string
1285  @param ... printf like parameters
1286  @return the newly created item */
1287 extern proto_item *
1288 proto_tree_add_int64_format_value(proto_tree *tree, int hfindex, tvbuff_t *tvb,
1289         gint start, gint length, gint64 value, const char *format, ...)
1290         GNUC_FORMAT_CHECK(printf,7,8);
1291
1292 /** Add a formatted FT_INT64 to a proto_tree, with the format generating
1293     the entire string for the entry, including any field name.
1294  @param tree the tree to append this item to
1295  @param hfindex field index
1296  @param tvb the tv buffer of the current data
1297  @param start start of data in tvb
1298  @param length length of data in tvb
1299  @param value data to display
1300  @param format printf like format string
1301  @param ... printf like parameters
1302  @return the newly created item */
1303 extern proto_item *
1304 proto_tree_add_int64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
1305         gint length, gint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
1306
1307 /** Useful for quick debugging. Also sends string to STDOUT, so don't
1308  * leave call to this function in production code.
1309  @param tree the tree to append the text to
1310  @param format printf like format string
1311  @param ... printf like parameters
1312  @return the newly created item */
1313 extern proto_item *
1314 proto_tree_add_debug_text(proto_tree *tree, const char *format,
1315         ...) GNUC_FORMAT_CHECK(printf,2,3);
1316
1317
1318
1319 /** Append a string to a protocol item.<br>
1320     NOTE: this function will break with the TRY_TO_FAKE_THIS_ITEM()
1321     speed optimization.
1322     Currently only WSP use this function so it is not that bad but try to
1323     avoid using this one if possible.
1324     IF you must use this function you MUST also disable the
1325     TRY_TO_FAKE_THIS_ITEM() optimization for your dissector/function
1326     using proto_item_append_string().
1327     Do that by faking that the tree is visible by setting :
1328     PTREE_DATA(tree)->visible=1;  (see packet-wsp.c)
1329     BEFORE you create the item you are later going to use
1330     proto_item_append_string() on.
1331
1332  @param pi the item to append the string to
1333  @param str the string to append */
1334 extern void
1335 proto_item_append_string(proto_item *pi, const char *str);
1336
1337
1338
1339 /** Fill given label_str with string representation of field
1340  @param fi the item to get the info from
1341  @param label_str the string to fill
1342  @todo think about changing the parameter profile */
1343 extern void
1344 proto_item_fill_label(field_info *fi, gchar *label_str);
1345
1346
1347 /** Register a new protocol.
1348  @param name the full name of the new protocol
1349  @param short_name abbreviated name of the new protocol
1350  @param filter_name protocol name used for a display filter string
1351  @return the new protocol handle */
1352 extern int
1353 proto_register_protocol(const char *name, const char *short_name, const char *filter_name);
1354
1355 /** Register a header_field array.
1356  @param parent the protocol handle from proto_register_protocol()
1357  @param hf the hf_register_info array
1358  @param num_records the number of records in hf */
1359 extern void
1360 proto_register_field_array(int parent, hf_register_info *hf, int num_records);
1361
1362 /** Register a protocol subtree (ett) array.
1363  @param indices array of ett indices
1364  @param num_indices the number of records in indices */
1365 extern void
1366 proto_register_subtree_array(gint *const *indices, int num_indices);
1367
1368 /** Returns number of items (protocols or header fields) registered.
1369  @return the number of items */
1370 extern int proto_registrar_n(void);
1371
1372 /** Get name of registered header_field number n.
1373  @param n item # n (0-indexed)
1374  @return the name of this registered item */
1375 extern const char* proto_registrar_get_name(int n);
1376
1377 /** Get abbreviation of registered header_field number n.
1378  @param n item # n (0-indexed)
1379  @return the abbreviation of this registered item */
1380 extern const char* proto_registrar_get_abbrev(int n);
1381
1382 /** Get the header_field information based upon a field or protocol id.
1383  @param hfindex item # n (0-indexed)
1384  @return the registered item */
1385 extern header_field_info* proto_registrar_get_nth(guint hfindex);
1386
1387 /** Get the header_field information based upon a field name.
1388  @param field_name the field name to search for
1389  @return the registered item */
1390 extern header_field_info* proto_registrar_get_byname(const char *field_name);
1391
1392 /** Get enum ftenum FT_ of registered header_field number n.
1393  @param n item # n (0-indexed)
1394  @return the registered item */
1395 extern int proto_registrar_get_ftype(int n);
1396
1397 /** Get parent protocol of registered header_field number n.
1398  @param n item # n (0-indexed)
1399  @return -1 if item _is_ a protocol */
1400 extern int proto_registrar_get_parent(int n);
1401
1402 /** Is item # n a protocol?
1403  @param n item # n (0-indexed)
1404  @return TRUE if it's a protocol, FALSE if it's not */
1405 extern gboolean proto_registrar_is_protocol(int n);
1406
1407 /* Get length of registered field according to field type.
1408  @param n item # n (0-indexed)
1409  @return 0 means undeterminable at registration time, * -1 means unknown field */
1410 extern gint proto_registrar_get_length(int n);
1411
1412
1413 /* Routines to use to iterate over the protocols and their fields;
1414  * they return the item number of the protocol in question or the
1415  * appropriate hfinfo pointer, and keep state in "*cookie". */
1416 extern int proto_get_first_protocol(void **cookie);
1417 extern int proto_get_next_protocol(void **cookie);
1418 extern header_field_info *proto_get_first_protocol_field(int proto_id, void **cookle);
1419 extern header_field_info *proto_get_next_protocol_field(void **cookle);
1420
1421 /** Given a protocol's filter_name.
1422  @param filter_name the filter name to search for
1423  @return proto_id */
1424 extern int proto_get_id_by_filter_name(const gchar* filter_name);
1425
1426 /** Can item # n decoding be disabled?
1427  @param proto_id protocol id (0-indexed)
1428  @return TRUE if it's a protocol, FALSE if it's not */
1429 extern gboolean proto_can_toggle_protocol(int proto_id);
1430
1431 /** Get the "protocol_t" structure for the given protocol's item number.
1432  @param proto_id protocol id (0-indexed) */
1433 extern protocol_t *find_protocol_by_id(int proto_id);
1434
1435 /** Get the protocol's name for the given protocol's item number.
1436  @param proto_id protocol id (0-indexed)
1437  @return its name */
1438 extern const char *proto_get_protocol_name(int proto_id);
1439
1440 /** Get the protocol's item number, for the given protocol's "protocol_t".
1441  @return its proto_id */
1442 extern int proto_get_id(protocol_t *protocol);
1443
1444 /** Get the protocol's short name, for the given protocol's "protocol_t".
1445  @return its short name. */
1446 extern const char *proto_get_protocol_short_name(protocol_t *protocol);
1447
1448 /** Is protocol's decoding enabled ?
1449  @param protocol
1450  @return TRUE if decoding is enabled, FALSE if not */
1451 extern gboolean proto_is_protocol_enabled(protocol_t *protocol);
1452
1453 /** Get a protocol's filter name by it's item number.
1454  @param proto_id protocol id (0-indexed)
1455  @return its filter name. */
1456 extern const char *proto_get_protocol_filter_name(int proto_id);
1457
1458 /** Enable / Disable protocol of the given item number.
1459  @param proto_id protocol id (0-indexed)
1460  @param enabled enable / disable the protocol */
1461 extern void proto_set_decoding(int proto_id, gboolean enabled);
1462
1463 /** Disable disabling/enabling of protocol of the given item number.
1464  @param proto_id protocol id (0-indexed) */
1465 extern void proto_set_cant_toggle(int proto_id);
1466
1467 /** Checks for existence any protocol or field within a tree.
1468  @param tree "Protocols" are assumed to be a child of the [empty] root node.
1469  @param id ???
1470  @return TRUE = found, FALSE = not found
1471  @todo add explanation of id parameter */
1472 extern gboolean proto_check_for_protocol_or_field(proto_tree* tree, int id);
1473
1474 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
1475  * tree. Only works with primed trees, and is fast. */
1476 extern GPtrArray* proto_get_finfo_ptr_array(proto_tree *tree, int hfindex);
1477
1478 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
1479  * tree. Works with any tree, primed or unprimed, and is slower than
1480  * proto_get_finfo_ptr_array because it has to search through the tree. */
1481 extern GPtrArray* proto_find_finfo(proto_tree *tree, int hfindex);
1482
1483 /* Return GPtrArray* of field_info pointers containg all hfindexes that appear in
1484 * tree. */
1485 extern GPtrArray* proto_all_finfos(proto_tree *tree);
1486
1487 /** Dumps a glossary of the protocol registrations to STDOUT */
1488 extern void proto_registrar_dump_protocols(void);
1489
1490 /** Dumps a glossary of the field value strings or true/false strings to STDOUT */
1491 extern void proto_registrar_dump_values(void);
1492
1493 /** Dumps a glossary of the protocol and field registrations to STDOUT.
1494  * Format 1 is the original format. Format 2 includes the base (for integers)
1495  * and the blurb. */
1496 extern void proto_registrar_dump_fields(int format);
1497
1498
1499
1500 /** Points to the first element of an array of Booleans, indexed by
1501    a subtree item type. That array element is TRUE if subtrees of
1502    an item of that type are to be expanded. With MSVC and a
1503    libwireshark.dll, we need a special declaration. */
1504 WS_VAR_IMPORT gboolean       *tree_is_expanded;
1505
1506 /** Number of elements in the tree_is_expanded array. With MSVC and a
1507  * libwireshark.dll, we need a special declaration. */
1508 WS_VAR_IMPORT int           num_tree_types;
1509
1510 /** glib doesn't have g_ptr_array_len of all things!*/
1511 #ifndef g_ptr_array_len
1512 #define g_ptr_array_len(a)      ((a)->len)
1513 #endif
1514
1515 /** Get number of bits of a header_field.
1516  @param hfinfo header_field
1517  @return the bitwidth */
1518 extern int
1519 hfinfo_bitwidth(header_field_info *hfinfo);
1520
1521
1522
1523
1524 #include "epan.h"
1525
1526 /** Can we do a "match selected" on this field.
1527  @param finfo field_info
1528  @param edt epan dissecting
1529  @return TRUE if we can do a "match selected" on the field, FALSE otherwise. */
1530 extern gboolean
1531 proto_can_match_selected(field_info *finfo, epan_dissect_t *edt);
1532
1533 /** Construct a display filter string.
1534  @param finfo field_info
1535  @param edt epan dissecting
1536  @return the display filter string */
1537 extern char*
1538 proto_construct_dfilter_string(field_info *finfo, epan_dissect_t *edt);
1539
1540 /** Find field from offset in tvb.
1541  @param tree
1542  @param offset offset in the tvb
1543  @param tvb the tv buffer
1544  @return the corresponding field_info */
1545 extern field_info*
1546 proto_find_field_from_offset(proto_tree *tree, guint offset, tvbuff_t *tvb);
1547
1548 #endif /* proto.h */