epan/proto.h

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