epan/proto.h

   1 /* proto.h
   2  * Definitions for protocol display
   3  *
   4  * $Id$
   5  *
   6  * Ethereal - Network traffic analyzer
   7  * By Gerald Combs <gerald@ethereal.com>
   8  * Copyright 1998 Gerald Combs
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public License
  12  * as published by the Free Software Foundation; either version 2
  13  * of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  23  */
  24
  25
  26 /*! @file proto.h
  27     The protocol tree related functions.<BR>
  28     A protocol tree will hold all necessary data to display the whole dissected packet.
  29     Creating a protocol tree is done in a two stage process:
  30     A static part at program startup, and a dynamic part when the dissection with the real packet data is done.<BR>
  31     The "static" information is provided by creating a hf_register_info hf[] array, and register it using the
  32     proto_register_field_array() function. This is usually done at dissector registering.<BR>
  33     The "dynamic" information is added to the protocol tree by calling one of the proto_tree_add_...() functions,
  34     e.g. proto_tree_add_bytes().
  35 */
  36
  37 #ifndef __PROTO_H__
  38 #define __PROTO_H__
  39
  40 #ifdef HAVE_STDARG_H
  41 # include <stdarg.h>
  42 #else
  43 # include <varargs.h>
  44 #endif
  45
  46 #include <glib.h>
  47
  48 #include "gnuc_format_check.h"
  49 #include "ipv4.h"
  50 #include "nstime.h"
  51 #include "tvbuff.h"
  52 #include "ftypes/ftypes.h"
  53
  54 /** The header-field index for the special text pseudo-field. Exported by libethereal.dll */
  55 ETH_VAR_IMPORT int hf_text_only;
  56
  57 /** the maximum length of a protocol field string representation */
  58 #define ITEM_LABEL_LENGTH       240
  59
  60 struct _value_string;
  61
  62 /** Make a const value_string[] look like a _value_string pointer, used to set header_field_info.strings */
  63 #define VALS(x) (const struct _value_string*)(x)
  64
  65 /** Make a const true_false_string[] look like a _true_false_string pointer, used to set header_field_info.strings */
  66 #define TFS(x)  (const struct true_false_string*)(x)
  67
  68 struct _protocol;
  69
  70 /** Structure for information about a protocol */
  71 typedef struct _protocol protocol_t;
  72
  73 /** check protocol activation
  74  * @todo this macro looks like a hack */
  75 #define CHECK_DISPLAY_AS_X(x_handle,index, tvb, pinfo, tree) {  \
  76         if (!proto_is_protocol_enabled(find_protocol_by_id(index))) {   \
  77                 call_dissector(x_handle,tvb, pinfo, tree);              \
  78                 return;                                                 \
  79         }                                                               \
  80   }
  81
  82 /** Macro used for reporting errors in dissectors; it throws a
  83  * DissectorError exception, with the string passed as an argument
  84  * as the message for the exception, so that it can show up in
  85  * the Info column and the protocol tree.
  86  *
  87  * That string should be allocated with g_malloc(); using
  88  * "g_strdup_printf()" would work.
  89  *
  90  * @param message string to use as the message
  91  */
  92 #define REPORT_DISSECTOR_BUG(message)  \
  93   (THROW_MESSAGE(DissectorError, message))
  94
  95 /** Macro used for assertions in dissectors; it doesn't abort, it just
  96  * throws a DissectorError exception, with the assertion failure
  97  * message as a parameter, so that it can show up in the protocol tree.
  98  *
  99  * @param expression expression to test in the assertion
 100  */
 101 #define DISSECTOR_ASSERT(expression)  \
 102   ((void) ((expression) ? (void)0 : \
 103    __DISSECTOR_ASSERT (expression, __FILE__, __LINE__)))
 104
 105 #if 0
 106 /* win32: using a debug breakpoint (int 3) can be very handy while debugging,
 107  * as the assert handling of GTK/GLib is currently not very helpful */
 108 #define DISSECTOR_ASSERT(expression)  \
 109 { if(!(expression)) _asm { int 3}; }
 110 #endif
 111
 112 /** Same as DISSECTOR_ASSERT(), but will throw DissectorError exception
 113  * unconditionally, much like GLIB's g_assert_not_reached works.
 114  */
 115 #define DISSECTOR_ASSERT_NOT_REACHED()  \
 116   (REPORT_DISSECTOR_BUG( \
 117     g_strdup_printf("%s:%u: failed assertion \"DISSECTOR_ASSERT_NOT_REACHED\"", \
 118      __FILE__, __LINE__)))
 119
 120 #define __DISSECTOR_ASSERT_STRINGIFY(s) # s
 121
 122 #define __DISSECTOR_ASSERT(expression, file, lineno)  \
 123   (REPORT_DISSECTOR_BUG( \
 124     g_strdup_printf("%s:%u: failed assertion \"%s\"", \
 125      file, lineno, __DISSECTOR_ASSERT_STRINGIFY(expression))))
 126
 127 /** radix for decimal values, used in header_field_info.display */
 128 typedef enum {
 129         BASE_NONE,      /**< none */
 130         BASE_DEC,       /**< decimal */
 131         BASE_HEX,       /**< hexadecimal */
 132         BASE_OCT,       /**< octal */
 133         BASE_DEC_HEX,   /**< decimal (hexadecimal) */
 134         BASE_HEX_DEC    /**< hexadecimal (decimal) */
 135 } base_display_e;
 136
 137 #define IS_BASE_DUAL(b) ((b)==BASE_DEC_HEX||(b)==BASE_HEX_DEC)
 138
 139 /** information describing a header field */
 140 typedef struct _header_field_info header_field_info;
 141
 142 /** information describing a header field */
 143 struct _header_field_info {
 144         /* ---------- set by dissector --------- */
 145         const char                              *name;      /**< full name of this field */
 146         const char                              *abbrev;    /**< abbreviated name of this field */
 147         enum ftenum                     type;       /**< field type, one of FT_ (from ftypes.h) */
 148         int                                     display;        /**< one of BASE_, or number of field bits for FT_BOOLEAN */
 149         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*/
 150         guint32                         bitmask;    /**< FT_BOOLEAN only: bitmask of interesting bits */
 151         const char                              *blurb;         /**< Brief description of field. */
 152
 153         /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */
 154         int                             id;             /**< Field ID */
 155         int                             parent;         /**< parent protocol tree */
 156                 /* This field keeps track of whether a field is
 157                  * referenced in any filter or not and if so how
 158                  * many times. If a filter is being referenced the
 159                  * refcount for the parent protocol is updated as well
 160                  */
 161         int                             ref_count;      /**< is this field referenced by a filter or not */
 162         int                             bitshift;       /**< bits to shift (FT_BOOLEAN only) */
 163         header_field_info               *same_name_next; /**< Link to next hfinfo with same abbrev*/
 164         header_field_info               *same_name_prev; /**< Link to previous hfinfo with same abbrev*/
 165 };
 166
 167 /**
 168  * HFILL initializes all the "set by proto routines" fields in a
 169  * _header_field_info. If new fields are added or removed, it should
 170  * be changed as necessary.
 171  */
 172 #define HFILL 0, 0, 0, 0, NULL, NULL
 173
 174 /** Used when registering many fields at once, using proto_register_field_array() */
 175 typedef struct hf_register_info {
 176         int                     *p_id;  /**< written to by register() function */
 177         header_field_info       hfinfo; /**< the field info to be registered */
 178 } hf_register_info;
 179
 180
 181
 182
 183 /** string representation, if one of the proto_tree_add_..._format() functions used */
 184 typedef struct _item_label_t {
 185         char representation[ITEM_LABEL_LENGTH];
 186 } item_label_t;
 187
 188
 189 /** Contains the field information for the proto_item. */
 190 typedef struct field_info {
 191         header_field_info       *hfinfo;    /**< pointer to registered field information */
 192         gint                            start;      /**< current start of data in field_info.ds_tvb */
 193         gint                            length;     /**< current data length of item in field_info.ds_tvb */
 194         gint                            tree_type;  /**< one of ETT_ or -1 */
 195         item_label_t            *rep;       /**< string for GUI tree */
 196         int                                     flags;      /**< bitfield like FI_GENERATED, ... */
 197         tvbuff_t                        *ds_tvb;    /**< data source tvbuff */
 198         fvalue_t                        value;
 199 } field_info;
 200
 201
 202 /** The protocol field should not be shown in the tree (it's used for filtering only),
 203  * used in field_info.flags. */
 204 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 205 #define FI_HIDDEN                       0x0001
 206 /** The protocol field should be displayed as "generated by Ethereal",
 207  * used in field_info.flags. */
 208 #define FI_GENERATED            0x0002
 209
 210
 211 /** convenience macro to get field_info.flags */
 212 #define FI_GET_FLAG(fi, flag) (fi->flags & flag)
 213 /** convenience macro to set field_info.flags */
 214 #define FI_SET_FLAG(fi, flag) (fi->flags = fi->flags | flag)
 215
 216 /** One of these exists for the entire protocol tree. Each proto_node
 217  * in the protocol tree points to the same copy. */
 218 typedef struct {
 219     GHashTable  *interesting_hfids;
 220     gboolean    visible;
 221 } tree_data_t;
 222
 223 /** Each proto_tree, proto_item is one of these. */
 224 typedef struct _proto_node {
 225         struct _proto_node *first_child;
 226         struct _proto_node *last_child;
 227         struct _proto_node *next;
 228         struct _proto_node *parent;
 229         field_info  *finfo;
 230         tree_data_t *tree_data;
 231 } proto_node;
 232
 233 /** A protocol tree element. */
 234 typedef proto_node proto_tree;
 235 /** A protocol item element. */
 236 typedef proto_node proto_item;
 237
 238 /* expert severities */
 239 #define PI_SEVERITY_MASK        0x001C  /* mask usually for internal use only! */
 240 /** Usual workflow, e.g. TCP connection establishing */
 241 #define PI_CHAT                         0x0004
 242 /** Notable messages, e.g. an application returned an "usual" error code like HTTP 404 */
 243 #define PI_NOTE                         0x0008
 244 /** Warning, e.g. application returned an "unusual" error code */
 245 #define PI_WARN                         0x000C
 246 /** Serious problems, e.g. [Malformed Packet] */
 247 #define PI_ERROR                        0x0010
 248
 249 /* expert "event groups" */
 250 #define PI_GROUP_MASK           0xFF00  /* mask usually for internal use only! */
 251 /** The protocol field has a bad checksum, usually PI_WARN */
 252 #define PI_CHECKSUM                     0x0100
 253 /** The protocol field indicates a sequence problem (e.g. TCP window is zero) */
 254 #define PI_SEQUENCE                     0x0200
 255 /** The protocol field indicates a bad application response code (e.g. HTTP 404), usually PI_NOTE */
 256 #define PI_RESPONSE_CODE        0x0400
 257 /** The data is undecoded, the protocol dissection is incomplete here, usually PI_WARN */
 258 #define PI_UNDECODED            0x0800
 259 /** The protocol field indicates a reassemble (e.g. DCE/RPC defragmentation), usually PI_CHAT (or PI_ERROR) */
 260 #define PI_REASSEMBLE           0x1000
 261 /** The packet data is malformed, the dissector has "given up", usually PI_ERROR */
 262 #define PI_MALFORMED            0x2000
 263 /** A generic debugging message (shouldn't remain in production code!), usually PI_ERROR */
 264 #define PI_DEBUG                        0x4000
 265 /** The protocol field indicates a security probem (e.g. unsecure implementation) */
 266 /*#define PI_SECURITY                   0x8000*/
 267
 268 /* add more, see http://wiki.ethereal.com/Development/ExpertInfo */
 269
 270
 271 /** is this protocol field hidden from the protocol tree display (used for filtering only)? */
 272 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 273 #define PROTO_ITEM_IS_HIDDEN(proto_item)        \
 274         ((proto_item) ? FI_GET_FLAG((proto_item)->finfo, FI_HIDDEN) : 0)
 275 /** mark this protocol field to be hidden from the protocol tree display (used for filtering only) */
 276 /* HIDING PROTOCOL FIELDS IS DEPRECATED, IT'S CONSIDERED TO BE BAD GUI DESIGN! */
 277 #define PROTO_ITEM_SET_HIDDEN(proto_item)       \
 278         ((proto_item) ? FI_SET_FLAG((proto_item)->finfo, FI_HIDDEN) : 0)
 279 /** is this protocol field generated by Ethereal (and not read from the packet data)? */
 280 #define PROTO_ITEM_IS_GENERATED(proto_item)     \
 281         ((proto_item) ? FI_GET_FLAG((proto_item)->finfo, FI_GENERATED) : 0)
 282 /** mark this protocol field as generated by Ethereal (and not read from the packet data) */
 283 #define PROTO_ITEM_SET_GENERATED(proto_item)    \
 284         ((proto_item) ? FI_SET_FLAG((proto_item)->finfo, FI_GENERATED) : 0)
 285
 286 typedef void (*proto_tree_foreach_func)(proto_node *, gpointer);
 287
 288 extern void proto_tree_children_foreach(proto_tree *tree,
 289     proto_tree_foreach_func func, gpointer data);
 290
 291 /** Retrieve the field_info from a proto_item */
 292 #define PITEM_FINFO(proto_item)  ((proto_item)->finfo)
 293
 294 /** Retrieve the tree_data_t from a proto_tree */
 295 #define PTREE_DATA(proto_tree)   ((proto_tree)->tree_data)
 296
 297
 298
 299 /** Sets up memory used by proto routines. Called at program startup */
 300 extern void proto_init(const char *plugin_dir,
 301     void (register_all_protocols)(void), void (register_all_handoffs)(void));
 302
 303 /** Frees memory used by proto routines. Called at program shutdown */
 304 extern void proto_cleanup(void);
 305
 306 /** This function takes a tree and a protocol id as parameter and
 307     will return TRUE/FALSE for whether the protocol or any of the filterable
 308     fields in the protocol is referenced by any fitlers.
 309     If this function returns FALSE then it is safe to skip any
 310         proto_tree_add_...() calls and just treat the call as if the
 311     dissector was called with tree==NULL.
 312     If you reset the tree to NULL by this dissector returning FALSE,
 313     you will still need to call any subdissector with the original value of
 314     tree or filtering will break.
 315
 316     The purpose of this is to optimize ethereal for speed and make it
 317     faster for when filters are being used.
 318 */
 319 extern gboolean proto_field_is_referenced(proto_tree *tree, int proto_id);
 320
 321
 322
 323 /** Create a subtree under an existing item.
 324  @param ti the parent item of the new subtree
 325  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
 326  @return the new subtree */
 327 extern proto_tree* proto_item_add_subtree(proto_item *ti, gint idx);
 328
 329 /** Get an existing subtree under an item.
 330  @param ti the parent item of the subtree
 331  @return the subtree or NULL */
 332 extern proto_tree* proto_item_get_subtree(proto_item *ti);
 333
 334 /** Get the parent of a subtree item.
 335  @param ti the child item in the subtree
 336  @return parent item or NULL */
 337 extern proto_item* proto_item_get_parent(proto_item *ti);
 338
 339 /** Get Nth generation parent item.
 340  @param ti the child item in the subtree
 341  @param gen the generation to get (using 1 here is the same as using proto_item_get_parent())
 342  @return parent item */
 343 extern proto_item* proto_item_get_parent_nth(proto_item *ti, int gen);
 344
 345 /** Replace text of item after it already has been created.
 346  @param ti the item to set the text
 347  @param format printf like format string
 348  @param ... printf like parameters */
 349 extern void proto_item_set_text(proto_item *ti, const char *format, ...)
 350         GNUC_FORMAT_CHECK(printf, 2,3);
 351
 352 /** Append to text of item after it has already been created.
 353  @param ti the item to append the text to
 354  @param format printf like format string
 355  @param ... printf like parameters */
 356 extern void proto_item_append_text(proto_item *ti, const char *format, ...)
 357         GNUC_FORMAT_CHECK(printf, 2,3);
 358
 359 /** Set proto_item's length inside tvb, after it has already been created.
 360  @param ti the item to set the length
 361  @param length the new length ot the item */
 362 extern void proto_item_set_len(proto_item *ti, gint length);
 363
 364 /**
 365  * Sets the length of the item based on its start and on the specified
 366  * offset, which is the offset past the end of the item; as the start
 367  * in the item is relative to the beginning of the data source tvbuff,
 368  * we need to pass in a tvbuff.
 369  @param ti the item to set the length
 370  @param tvb end is relative to this tvbuff
 371  @param end this end offset is relative to the beginning of tvb
 372  @todo make usage clearer, I don't understand it!
 373  */
 374 extern void proto_item_set_end(proto_item *ti, tvbuff_t *tvb, gint end);
 375
 376 /** Get length of a proto_item. Useful after using proto_tree_add_item()
 377  * to add a variable-length field (e.g., FT_NSTRING_UINT8).
 378  @param ti the item to get the length from
 379  @return the current length */
 380 extern int proto_item_get_len(proto_item *ti);
 381
 382 /**
 383  * Sets an expert info to the proto_item.
 384  @param ti the item to set the expert info
 385  @param group the group of this info (e.g. FI_CHECKSUM)
 386  @param severity of this info (e.g. FI_ERROR)
 387  @return TRUE if value was written
 388  */
 389 extern gboolean proto_item_set_expert_flags(proto_item *ti, int group, int severity);
 390
 391
 392
 393
 394 /** Creates a new proto_tree root.
 395  @return the new tree root */
 396 extern proto_tree* proto_tree_create_root(void);
 397
 398 /** Clear memory for entry proto_tree. Clears proto_tree struct also.
 399  @param tree the tree to free */
 400 extern void proto_tree_free(proto_tree *tree);
 401
 402 /** Set the tree visible or invisible.
 403  Is the parsing being done for a visible proto_tree or an invisible one?
 404  By setting this correctly, the proto_tree creation is sped up by not
 405  having to call g_vsnprintf and copy strings around.
 406  @param tree the tree to be set
 407  @param visible ... or not  */
 408 extern void
 409 proto_tree_set_visible(proto_tree *tree, gboolean visible);
 410
 411 /** Mark a field/protocol ID as "interesting".
 412  @param tree the tree to be set
 413  @param hfid the interesting field id
 414  @todo what *does* interesting mean? */
 415 extern void
 416 proto_tree_prime_hfid(proto_tree *tree, int hfid);
 417
 418 /** Get a parent item of a subtree.
 419  @param tree the tree to get the parent from
 420  @return parent item */
 421 extern proto_item* proto_tree_get_parent(proto_tree *tree);
 422
 423 /** Move an existing item behind another existing item.
 424  @param tree the tree to which both items belong
 425  @param fixed_item the item which keeps it's position
 426  @param item_to_move the item which will be moved */
 427 extern void proto_tree_move_item(proto_tree *tree, proto_item *fixed_item, proto_item *item_to_move);
 428
 429
 430
 431 /** Add an item to a proto_tree, using the text label registered to that item.
 432    The item is extracted from the tvbuff handed to it.
 433  @param tree the tree to append this item to
 434  @param hfindex field index
 435  @param tvb the tv buffer of the current data
 436  @param start start of data in tvb
 437  @param length length of data in tvb
 438  @param little_endian big or little endian byte representation
 439  @return the newly created item */
 440 extern proto_item *
 441 proto_tree_add_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 442     gint start, gint length, gboolean little_endian);
 443
 444 /** Add a hidden item to a proto_tree.
 445  @deprecated use proto_tree_add_item() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 446 extern proto_item *
 447 proto_tree_add_item_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 448     gint start, gint length, gboolean little_endian);
 449
 450 /** Add a text-only node to a proto_tree.
 451  @param tree the tree to append this item to
 452  @param tvb the tv buffer of the current data
 453  @param start start of data in tvb
 454  @param length length of data in tvb
 455  @param format printf like format string
 456  @param ... printf like parameters
 457  @return the newly created item */
 458 extern proto_item *
 459 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
 460         ...) GNUC_FORMAT_CHECK(printf,5,6);
 461
 462 /** Add a text-only node to a proto_tree using a variable argument list.
 463  @param tree the tree to append this item to
 464  @param tvb the tv buffer of the current data
 465  @param start start of data in tvb
 466  @param length length of data in tvb
 467  @param format printf like format string
 468  @param ap variable argument list
 469  @return the newly created item */
 470 extern proto_item *
 471 proto_tree_add_text_valist(proto_tree *tree, tvbuff_t *tvb, gint start,
 472         gint length, const char *format, va_list ap);
 473
 474
 475 /** Add a FT_NONE field to a proto_tree.
 476  @param tree the tree to append this item to
 477  @param hfindex field index
 478  @param tvb the tv buffer of the current data
 479  @param start start of data in tvb
 480  @param length length of data in tvb
 481  @param format printf like format string
 482  @param ... printf like parameters
 483  @return the newly created item */
 484 extern proto_item *
 485 proto_tree_add_none_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 486         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 487
 488 /** Add a FT_PROTOCOL to a proto_tree.
 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 format printf like format string
 495  @param ... printf like parameters
 496  @return the newly created item */
 497 extern proto_item *
 498 proto_tree_add_protocol_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 499         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 500
 501
 502
 503
 504 /** Add a FT_BYTES to a proto_tree.
 505  @param tree the tree to append this item to
 506  @param hfindex field index
 507  @param tvb the tv buffer of the current data
 508  @param start start of data in tvb
 509  @param length length of data in tvb
 510  @param start_ptr pointer to the data to display
 511  @return the newly created item */
 512 extern proto_item *
 513 proto_tree_add_bytes(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 514         gint length, const guint8* start_ptr);
 515
 516 /** Add a hidden FT_BYTES to a proto_tree.
 517  @deprecated use proto_tree_add_bytes() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 518 extern proto_item *
 519 proto_tree_add_bytes_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 520         gint length, const guint8* start_ptr);
 521
 522 /** Add a formatted FT_BYTES to a proto_tree.
 523  @param tree the tree to append this item to
 524  @param hfindex field index
 525  @param tvb the tv buffer of the current data
 526  @param start start of data in tvb
 527  @param length length of data in tvb
 528  @param start_ptr pointer to the data to display
 529  @param format printf like format string
 530  @param ... printf like parameters
 531  @return the newly created item */
 532 extern proto_item *
 533 proto_tree_add_bytes_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 534         gint length, const guint8* start_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 535
 536 /** Add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 537  @param tree the tree to append this item to
 538  @param hfindex field index
 539  @param tvb the tv buffer of the current data
 540  @param start start of data in tvb
 541  @param length length of data in tvb
 542  @param value_ptr pointer to the data to display
 543  @return the newly created item */
 544 extern proto_item *
 545 proto_tree_add_time(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 546         gint length, nstime_t* value_ptr);
 547
 548 /** Add a hidden FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 549  @deprecated use proto_tree_add_time() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 550 extern proto_item *
 551 proto_tree_add_time_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 552         gint length, nstime_t* value_ptr);
 553
 554 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 555  @param tree the tree to append this item to
 556  @param hfindex field index
 557  @param tvb the tv buffer of the current data
 558  @param start start of data in tvb
 559  @param length length of data in tvb
 560  @param value_ptr pointer to the data to display
 561  @param format printf like format string
 562  @param ... printf like parameters
 563  @return the newly created item */
 564 extern proto_item *
 565 proto_tree_add_time_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 566         gint length, nstime_t* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 567
 568 /** Add a FT_IPXNET to a proto_tree.
 569  @param tree the tree to append this item to
 570  @param hfindex field index
 571  @param tvb the tv buffer of the current data
 572  @param start start of data in tvb
 573  @param length length of data in tvb
 574  @param value data to display
 575  @return the newly created item */
 576 extern proto_item *
 577 proto_tree_add_ipxnet(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 578         gint length, guint32 value);
 579
 580 /** Add a hidden FT_IPXNET to a proto_tree.
 581  @deprecated use proto_tree_add_ipxnet() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 582 extern proto_item *
 583 proto_tree_add_ipxnet_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 584         gint length, guint32 value);
 585
 586 /** Add a formatted FT_IPXNET to a proto_tree.
 587  @param tree the tree to append this item to
 588  @param hfindex field index
 589  @param tvb the tv buffer of the current data
 590  @param start start of data in tvb
 591  @param length length of data in tvb
 592  @param value data to display
 593  @param format printf like format string
 594  @param ... printf like parameters
 595  @return the newly created item */
 596 extern proto_item *
 597 proto_tree_add_ipxnet_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 598         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 599
 600 /** Add a FT_IPv4 to a proto_tree.
 601  @param tree the tree to append this item to
 602  @param hfindex field index
 603  @param tvb the tv buffer of the current data
 604  @param start start of data in tvb
 605  @param length length of data in tvb
 606  @param value data to display
 607  @return the newly created item */
 608 extern proto_item *
 609 proto_tree_add_ipv4(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 610         gint length, guint32 value);
 611
 612 /** Add a hidden FT_IPv4 to a proto_tree.
 613  @deprecated use proto_tree_add_ipv4() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 614 extern proto_item *
 615 proto_tree_add_ipv4_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 616         gint length, guint32 value);
 617
 618 /** Add a formatted FT_IPv4 to a proto_tree.
 619  @param tree the tree to append this item to
 620  @param hfindex field index
 621  @param tvb the tv buffer of the current data
 622  @param start start of data in tvb
 623  @param length length of data in tvb
 624  @param value data to display
 625  @param format printf like format string
 626  @param ... printf like parameters
 627  @return the newly created item */
 628 extern proto_item *
 629 proto_tree_add_ipv4_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 630         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 631
 632 /** Add a FT_IPv6 to a proto_tree.
 633  @param tree the tree to append this item to
 634  @param hfindex field index
 635  @param tvb the tv buffer of the current data
 636  @param start start of data in tvb
 637  @param length length of data in tvb
 638  @param value_ptr data to display
 639  @return the newly created item */
 640 extern proto_item *
 641 proto_tree_add_ipv6(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 642         gint length, const guint8* value_ptr);
 643
 644 /** Add a hidden FT_IPv6 to a proto_tree.
 645  @deprecated use proto_tree_add_ipv6() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 646 extern proto_item *
 647 proto_tree_add_ipv6_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 648         gint length, const guint8* value_ptr);
 649
 650 /** Add a formatted FT_IPv6 to a proto_tree.
 651  @param tree the tree to append this item to
 652  @param hfindex field index
 653  @param tvb the tv buffer of the current data
 654  @param start start of data in tvb
 655  @param length length of data in tvb
 656  @param value_ptr data to display
 657  @param format printf like format string
 658  @param ... printf like parameters
 659  @return the newly created item */
 660 extern proto_item *
 661 proto_tree_add_ipv6_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 662         gint length, const guint8* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 663
 664 /** Add a FT_ETHER to a proto_tree.
 665  @param tree the tree to append this item to
 666  @param hfindex field index
 667  @param tvb the tv buffer of the current data
 668  @param start start of data in tvb
 669  @param length length of data in tvb
 670  @param value data to display
 671  @return the newly created item */
 672 extern proto_item *
 673 proto_tree_add_ether(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 674         gint length, const guint8* value);
 675
 676 /** Add a hidden FT_ETHER to a proto_tree.
 677  @deprecated use proto_tree_add_ether() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 678 extern proto_item *
 679 proto_tree_add_ether_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 680         gint length, const guint8* value);
 681
 682 /** Add a formatted FT_ETHER 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  @param format printf like format string
 690  @param ... printf like parameters
 691  @return the newly created item */
 692 extern proto_item *
 693 proto_tree_add_ether_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 694         gint length, const guint8* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 695
 696 /** Add a FT_GUID to a proto_tree.
 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_ptr data to display
 703  @return the newly created item */
 704 extern proto_item *
 705 proto_tree_add_guid(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 706         gint length, const guint8* value_ptr);
 707
 708 /** Add a hidden FT_GUID to a proto_tree.
 709  @deprecated use proto_tree_add_guid() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 710 extern proto_item *
 711 proto_tree_add_guid_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 712         gint length, const guint8* value_ptr);
 713
 714 /** Add a formatted FT_GUID to a proto_tree.
 715  @param tree the tree to append this item to
 716  @param hfindex field index
 717  @param tvb the tv buffer of the current data
 718  @param start start of data in tvb
 719  @param length length of data in tvb
 720  @param value_ptr data to display
 721  @param format printf like format string
 722  @param ... printf like parameters
 723  @return the newly created item */
 724 extern proto_item *
 725 proto_tree_add_guid_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 726         gint length, const guint8* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 727
 728 /** Add a FT_STRING to a proto_tree.
 729  @param tree the tree to append this item to
 730  @param hfindex field index
 731  @param tvb the tv buffer of the current data
 732  @param start start of data in tvb
 733  @param length length of data in tvb
 734  @param value data to display
 735  @return the newly created item */
 736 extern proto_item *
 737 proto_tree_add_string(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 738         gint length, const char* value);
 739
 740 /** Add a hidden FT_STRING to a proto_tree.
 741  @deprecated use proto_tree_add_string() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 742 extern proto_item *
 743 proto_tree_add_string_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 744         gint length, const char* value);
 745
 746 /** Add a formatted FT_STRING to a proto_tree.
 747  @param tree the tree to append this item to
 748  @param hfindex field index
 749  @param tvb the tv buffer of the current data
 750  @param start start of data in tvb
 751  @param length length of data in tvb
 752  @param value data to display
 753  @param format printf like format string
 754  @param ... printf like parameters
 755  @return the newly created item */
 756 extern proto_item *
 757 proto_tree_add_string_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 758         gint length, const char* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 759
 760 /** Add a FT_BOOLEAN to a proto_tree.
 761  @param tree the tree to append this item to
 762  @param hfindex field index
 763  @param tvb the tv buffer of the current data
 764  @param start start of data in tvb
 765  @param length length of data in tvb
 766  @param value data to display
 767  @return the newly created item */
 768 extern proto_item *
 769 proto_tree_add_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 770         gint length, guint32 value);
 771
 772 /** Add a hidden FT_BOOLEAN to a proto_tree.
 773  @deprecated use proto_tree_add_boolean() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 774 extern proto_item *
 775 proto_tree_add_boolean_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 776         gint length, guint32 value);
 777
 778 /** Add a formatted FT_BOOLEAN to a proto_tree.
 779  @param tree the tree to append this item to
 780  @param hfindex field index
 781  @param tvb the tv buffer of the current data
 782  @param start start of data in tvb
 783  @param length length of data in tvb
 784  @param value data to display
 785  @param format printf like format string
 786  @param ... printf like parameters
 787  @return the newly created item */
 788 extern proto_item *
 789 proto_tree_add_boolean_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 790         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 791
 792 /** Add a FT_FLOAT to a proto_tree.
 793  @param tree the tree to append this item to
 794  @param hfindex field index
 795  @param tvb the tv buffer of the current data
 796  @param start start of data in tvb
 797  @param length length of data in tvb
 798  @param value data to display
 799  @return the newly created item */
 800 extern proto_item *
 801 proto_tree_add_float(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 802         gint length, float value);
 803
 804 /** Add a hidden FT_FLOAT to a proto_tree.
 805  @deprecated use proto_tree_add_float() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 806 extern proto_item *
 807 proto_tree_add_float_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 808         gint length, float value);
 809
 810 /** Add a formatted FT_FLOAT to a proto_tree.
 811  @param tree the tree to append this item to
 812  @param hfindex field index
 813  @param tvb the tv buffer of the current data
 814  @param start start of data in tvb
 815  @param length length of data in tvb
 816  @param value data to display
 817  @param format printf like format string
 818  @param ... printf like parameters
 819  @return the newly created item */
 820 extern proto_item *
 821 proto_tree_add_float_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 822         gint length, float value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 823
 824 /** Add a FT_DOUBLE to a proto_tree.
 825  @param tree the tree to append this item to
 826  @param hfindex field index
 827  @param tvb the tv buffer of the current data
 828  @param start start of data in tvb
 829  @param length length of data in tvb
 830  @param value data to display
 831  @return the newly created item */
 832 extern proto_item *
 833 proto_tree_add_double(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 834         gint length, double value);
 835
 836 /** Add a hidden FT_DOUBLE to a proto_tree.
 837  @deprecated use proto_tree_add_double() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 838 extern proto_item *
 839 proto_tree_add_double_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 840         gint length, double value);
 841
 842 /** Add a formatted FT_DOUBLE to a proto_tree.
 843  @param tree the tree to append this item to
 844  @param hfindex field index
 845  @param tvb the tv buffer of the current data
 846  @param start start of data in tvb
 847  @param length length of data in tvb
 848  @param value data to display
 849  @param format printf like format string
 850  @param ... printf like parameters
 851  @return the newly created item */
 852 extern proto_item *
 853 proto_tree_add_double_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 854         gint length, double value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 855
 856 /** Add one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 857  @param tree the tree to append this item to
 858  @param hfindex field index
 859  @param tvb the tv buffer of the current data
 860  @param start start of data in tvb
 861  @param length length of data in tvb
 862  @param value data to display
 863  @return the newly created item */
 864 extern proto_item *
 865 proto_tree_add_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 866         gint length, guint32 value);
 867
 868 /** Add a hidden of one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 869  @deprecated use proto_tree_add_uint() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 870 extern proto_item *
 871 proto_tree_add_uint_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 872         gint length, guint32 value);
 873
 874 /** Add a formatted of one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 875  @param tree the tree to append this item to
 876  @param hfindex field index
 877  @param tvb the tv buffer of the current data
 878  @param start start of data in tvb
 879  @param length length of data in tvb
 880  @param value data to display
 881  @param format printf like format string
 882  @param ... printf like parameters
 883  @return the newly created item */
 884 extern proto_item *
 885 proto_tree_add_uint_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 886         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 887
 888 /** Add an FT_UINT64 to a proto_tree.
 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 data to display
 895  @return the newly created item */
 896 extern proto_item *
 897 proto_tree_add_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 898         gint length, guint64 value);
 899
 900 /** Add a formatted FT_UINT64 to a proto_tree.
 901  @param tree the tree to append this item to
 902  @param hfindex field index
 903  @param tvb the tv buffer of the current data
 904  @param start start of data in tvb
 905  @param length length of data in tvb
 906  @param value data to display
 907  @param format printf like format string
 908  @param ... printf like parameters
 909  @return the newly created item */
 910 extern proto_item *
 911 proto_tree_add_uint64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 912         gint length, guint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 913
 914 /** Add one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 915  @param tree the tree to append this item to
 916  @param hfindex field index
 917  @param tvb the tv buffer of the current data
 918  @param start start of data in tvb
 919  @param length length of data in tvb
 920  @param value data to display
 921  @return the newly created item */
 922 extern proto_item *
 923 proto_tree_add_int(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 924         gint length, gint32 value);
 925
 926 /** Add a hidden of one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 927  @deprecated use proto_tree_add_int() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 928 extern proto_item *
 929 proto_tree_add_int_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 930         gint length, gint32 value);
 931
 932 /** Add a formatted of one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 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 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_int_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 944         gint length, gint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 945
 946 /** Add an FT_INT64 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_int64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 956         gint length, gint64 value);
 957
 958 /** Add a formatted FT_INT64 to a proto_tree.
 959  @param tree the tree to append this item to
 960  @param hfindex field index
 961  @param tvb the tv buffer of the current data
 962  @param start start of data in tvb
 963  @param length length of data in tvb
 964  @param value data to display
 965  @param format printf like format string
 966  @param ... printf like parameters
 967  @return the newly created item */
 968 extern proto_item *
 969 proto_tree_add_int64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 970         gint length, gint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 971
 972 /** Useful for quick debugging. Also sends string to STDOUT, so don't
 973  * leave call to this function in production code.
 974  @param tree the tree to append the text to
 975  @param format printf like format string
 976  @param ... printf like parameters
 977  @return the newly created item */
 978 extern proto_item *
 979 proto_tree_add_debug_text(proto_tree *tree, const char *format,
 980         ...) GNUC_FORMAT_CHECK(printf,2,3);
 981
 982
 983
 984 /** Append a string to a protocol item.<br>
 985     NOTE: this function will break with the TRY_TO_FAKE_THIS_ITEM()
 986     speed optimization.
 987     Currently only WSP use this function so it is not that bad but try to
 988     avoid using this one if possible.
 989     IF you must use this function you MUST also disable the
 990     TRY_TO_FAKE_THIS_ITEM() optimization for your dissector/function
 991     using proto_item_append_string().
 992     Do that by faking that the tree is visible by setting :
 993     PTREE_DATA(tree)->visible=1;  (see packet-wsp.c)
 994     BEFORE you create the item you are later going to use
 995     proto_item_append_string() on.
 996
 997  @param pi the item to append the string to
 998  @param str the string to append */
 999 extern void
1000 proto_item_append_string(proto_item *pi, const char *str);
1001
1002
1003
1004 /** Fill given label_str with string representation of field
1005  @param fi the item to get the info from
1006  @param label_str the string to fill
1007  @todo think about changing the parameter profile */
1008 extern void
1009 proto_item_fill_label(field_info *fi, gchar *label_str);
1010
1011
1012 /** Register a new protocol.
1013  @param name the full name of the new protocol
1014  @param short_name abbreviated name of the new protocol
1015  @param filter_name protocol name used for a display filter string
1016  @return the new protocol handle */
1017 extern int
1018 proto_register_protocol(const char *name, const char *short_name, const char *filter_name);
1019
1020 /** Register a header_field array.
1021  @param parent the protocol handle from proto_register_protocol()
1022  @param hf the hf_register_info array
1023  @param num_records the number of records in hf */
1024 extern void
1025 proto_register_field_array(int parent, hf_register_info *hf, int num_records);
1026
1027 /** Register a protocol subtree (ett) array.
1028  @param indices array of ett indices
1029  @param num_indices the number of records in indices */
1030 extern void
1031 proto_register_subtree_array(gint *const *indices, int num_indices);
1032
1033 /** Returns number of items (protocols or header fields) registered.
1034  @return the number of items */
1035 extern int proto_registrar_n(void);
1036
1037 /** Get name of registered header_field number n.
1038  @param n item # n (0-indexed)
1039  @return the name of this registered item */
1040 extern const char* proto_registrar_get_name(int n);
1041
1042 /** Get abbreviation of registered header_field number n.
1043  @param n item # n (0-indexed)
1044  @return the abbreviation of this registered item */
1045 extern const char* proto_registrar_get_abbrev(int n);
1046
1047 /** Get the header_field information based upon a field or protocol id.
1048  @param hfindex item # n (0-indexed)
1049  @return the registered item */
1050 extern header_field_info* proto_registrar_get_nth(guint hfindex);
1051
1052 /** Get the header_field information based upon a field name.
1053  @param field_name the field name to search for
1054  @return the registered item */
1055 extern header_field_info* proto_registrar_get_byname(const char *field_name);
1056
1057 /** Get enum ftenum FT_ of registered header_field number n.
1058  @param n item # n (0-indexed)
1059  @return the registered item */
1060 extern int proto_registrar_get_ftype(int n);
1061
1062 /** Get parent protocol of registered header_field number n.
1063  @param n item # n (0-indexed)
1064  @return -1 if item _is_ a protocol */
1065 extern int proto_registrar_get_parent(int n);
1066
1067 /** Is item # n a protocol?
1068  @param n item # n (0-indexed)
1069  @return TRUE if it's a protocol, FALSE if it's not */
1070 extern gboolean proto_registrar_is_protocol(int n);
1071
1072 /* Get length of registered field according to field type.
1073  @param n item # n (0-indexed)
1074  @return 0 means undeterminable at registration time, * -1 means unknown field */
1075 extern gint proto_registrar_get_length(int n);
1076
1077
1078 /* Routines to use to iterate over the protocols and their fields;
1079  * they return the item number of the protocol in question or the
1080  * appropriate hfinfo pointer, and keep state in "*cookie". */
1081 extern int proto_get_first_protocol(void **cookie);
1082 extern int proto_get_next_protocol(void **cookie);
1083 extern header_field_info *proto_get_first_protocol_field(int proto_id, void **cookle);
1084 extern header_field_info *proto_get_next_protocol_field(void **cookle);
1085
1086 /** Given a protocol's filter_name.
1087  @param filter_name the filter name to search for
1088  @return proto_id */
1089 extern int proto_get_id_by_filter_name(const gchar* filter_name);
1090
1091 /** Can item # n decoding be disabled?
1092  @param proto_id protocol id (0-indexed)
1093  @return TRUE if it's a protocol, FALSE if it's not */
1094 extern gboolean proto_can_toggle_protocol(int proto_id);
1095
1096 /** Get the "protocol_t" structure for the given protocol's item number.
1097  @param proto_id protocol id (0-indexed) */
1098 extern protocol_t *find_protocol_by_id(int proto_id);
1099
1100 /** Get the protocol's name for the given protocol's item number.
1101  @param proto_id protocol id (0-indexed)
1102  @return its name */
1103 extern const char *proto_get_protocol_name(int proto_id);
1104
1105 /** Get the protocol's item number, for the given protocol's "protocol_t".
1106  @return its proto_id */
1107 extern int proto_get_id(protocol_t *protocol);
1108
1109 /** Get the protocol's short name, for the given protocol's "protocol_t".
1110  @return its short name. */
1111 extern const char *proto_get_protocol_short_name(protocol_t *protocol);
1112
1113 /** Is protocol's decoding enabled ?
1114  @param protocol
1115  @return TRUE if decoding is enabled, FALSE if not */
1116 extern gboolean proto_is_protocol_enabled(protocol_t *protocol);
1117
1118 /** Get a protocol's filter name by it's item number.
1119  @param proto_id protocol id (0-indexed)
1120  @return its filter name. */
1121 extern const char *proto_get_protocol_filter_name(int proto_id);
1122
1123 /** Enable / Disable protocol of the given item number.
1124  @param proto_id protocol id (0-indexed)
1125  @param enabled enable / disable the protocol */
1126 extern void proto_set_decoding(int proto_id, gboolean enabled);
1127
1128 /** Disable disabling/enabling of protocol of the given item number.
1129  @param proto_id protocol id (0-indexed) */
1130 extern void proto_set_cant_toggle(int proto_id);
1131
1132 /** Checks for existence any protocol or field within a tree.
1133  @param tree "Protocols" are assumed to be a child of the [empty] root node.
1134  @param id ???
1135  @return TRUE = found, FALSE = not found
1136  @todo add explanation of id parameter */
1137 extern gboolean proto_check_for_protocol_or_field(proto_tree* tree, int id);
1138
1139 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
1140  * tree. Only works with primed trees, and is fast. */
1141 extern GPtrArray* proto_get_finfo_ptr_array(proto_tree *tree, int hfindex);
1142
1143 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
1144  * tree. Works with any tree, primed or unprimed, and is slower than
1145  * proto_get_finfo_ptr_array because it has to search through the tree. */
1146 extern GPtrArray* proto_find_finfo(proto_tree *tree, int hfindex);
1147
1148 /** Dumps a glossary of the protocol registrations to STDOUT */
1149 extern void proto_registrar_dump_protocols(void);
1150
1151 /** Dumps a glossary of the field value strings or true/false strings to STDOUT */
1152 extern void proto_registrar_dump_values(void);
1153
1154 /** Dumps a glossary of the protocol and field registrations to STDOUT.
1155  * Format 1 is the original format. Format 2 includes the base (for integers)
1156  * and the blurb. */
1157 extern void proto_registrar_dump_fields(int format);
1158
1159
1160
1161 /** Points to the first element of an array of Booleans, indexed by
1162    a subtree item type. That array element is TRUE if subtrees of
1163    an item of that type are to be expanded. With MSVC and a
1164    libethereal.dll, we need a special declaration. */
1165 ETH_VAR_IMPORT gboolean      *tree_is_expanded;
1166
1167 /** Number of elements in the tree_is_expanded array. With MSVC and a
1168  * libethereal.dll, we need a special declaration. */
1169 ETH_VAR_IMPORT int           num_tree_types;
1170
1171 /** glib doesn't have g_ptr_array_len of all things!*/
1172 #ifndef g_ptr_array_len
1173 #define g_ptr_array_len(a)      ((a)->len)
1174 #endif
1175
1176 /** Get number of bits of a header_field.
1177  @param hfinfo header_field
1178  @return the bitwidth */
1179 extern int
1180 hfinfo_bitwidth(header_field_info *hfinfo);
1181
1182
1183
1184
1185 #include "epan.h"
1186
1187 /** Can we do a "match selected" on this field.
1188  @param finfo field_info
1189  @param edt epan dissecting
1190  @return TRUE if we can do a "match selected" on the field, FALSE otherwise. */
1191 extern gboolean
1192 proto_can_match_selected(field_info *finfo, epan_dissect_t *edt);
1193
1194 /** Construct a display filter string.
1195  @param finfo field_info
1196  @param edt epan dissecting
1197  @return the display filter string */
1198 extern char*
1199 proto_construct_dfilter_string(field_info *finfo, epan_dissect_t *edt);
1200
1201 /** Find field from offset in tvb.
1202  @param tree
1203  @param offset offset in the tvb
1204  @param tvb the tv buffer
1205  @return the corresponding field_info */
1206 extern field_info*
1207 proto_find_field_from_offset(proto_tree *tree, guint offset, tvbuff_t *tvb);
1208
1209 #endif /* proto.h */