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