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 "ipv4.h"
  49 #include "nstime.h"
  50 #include "tvbuff.h"
  51 #include "ftypes/ftypes.h"
  52
  53 /** The header-field index for the special text pseudo-field. Exported by libethereal.dll */
  54 ETH_VAR_IMPORT int hf_text_only;
  55
  56 /** the maximum length of a protocol field string representation */
  57 #define ITEM_LABEL_LENGTH       240
  58
  59 struct _value_string;
  60
  61 /** Make a const value_string[] look like a _value_string pointer, used to set header_field_info.strings */
  62 #define VALS(x) (const struct _value_string*)(x)
  63
  64 /** Make a const true_false_string[] look like a _true_false_string pointer, used to set header_field_info.strings */
  65 #define TFS(x)  (const struct true_false_string*)(x)
  66
  67 struct _protocol;
  68
  69 /** Structure for information about a protocol */
  70 typedef struct _protocol protocol_t;
  71
  72 /** check protocol activation
  73  * @todo this macro looks like a hack */
  74 #define CHECK_DISPLAY_AS_X(x_handle,index, tvb, pinfo, tree) {  \
  75         if (!proto_is_protocol_enabled(find_protocol_by_id(index))) {   \
  76                 call_dissector(x_handle,tvb, pinfo, tree);              \
  77                 return;                                                 \
  78         }                                                               \
  79   }
  80
  81
  82 /** GNUC has the ability to check format strings that follow the syntax used in printf and others.
  83  Hide the differences between different compilers in this GNUC_FORMAT_CHECK macro.
  84  @param archetype one of: printf, scanf, strftime or strfmon
  85  @param string_index specifies which argument is the format string argument (starting from 1)
  86  @param first_to_check is the number of the first argument to check against the format string
  87  @todo as this check is also done at some other places too, move this macro to a more central place? */
  88 #if __GNUC__ >= 2
  89         #define GNUC_FORMAT_CHECK(archetype, string_index, first_to_check) __attribute__((format (archetype, string_index, first_to_check)))
  90 #else
  91         #define GNUC_FORMAT_CHECK(archetype, string_index, first_to_check)
  92 #endif
  93
  94
  95 /** radix for decimal values, used in header_field_info.display */
  96 typedef enum {
  97         BASE_NONE,      /**< none */
  98         BASE_DEC,       /**< decimal */
  99         BASE_HEX,       /**< hexadecimal */
 100         BASE_OCT        /**< octal */
 101 } base_display_e;
 102
 103 /** information describing a header field */
 104 typedef struct _header_field_info header_field_info;
 105
 106 /** information describing a header field */
 107 struct _header_field_info {
 108         /* ---------- set by dissector --------- */
 109         char                            *name;      /**< full name of this field */
 110         char                            *abbrev;    /**< abbreviated name of this field */
 111         enum ftenum                     type;       /**< field type, one of FT_ (from ftypes.h) */
 112         int                                     display;        /**< one of BASE_, or number of field bits for FT_BOOLEAN */
 113         const void                      *strings;       /**< _value_string (or true_false_string for FT_BOOLEAN), typically converted by VALS() or TFS() */
 114         guint32                         bitmask;    /**< FT_BOOLEAN only: bitmask of interesting bits */
 115         char                            *blurb;         /**< Brief description of field. */
 116
 117         /* ------- set by proto routines (prefilled by HFILL macro, see below) ------ */
 118         int                             id;             /**< Field ID */
 119         int                             parent;         /**< parent protocol tree */
 120         int                             bitshift;       /**< bits to shift (FT_BOOLEAN only) */
 121         header_field_info               *same_name_next; /**< Link to next hfinfo with same abbrev*/
 122         header_field_info               *same_name_prev; /**< Link to previous hfinfo with same abbrev*/
 123 };
 124
 125 /**
 126  * HFILL initializes all the "set by proto routines" fields in a
 127  * _header_field_info. If new fields are added or removed, it should
 128  * be changed as necessary.
 129  */
 130 #define HFILL 0, 0, 0, NULL, NULL
 131
 132 /** Used when registering many fields at once, using proto_register_field_array() */
 133 typedef struct hf_register_info {
 134         int                     *p_id;  /**< written to by register() function */
 135         header_field_info       hfinfo; /**< the field info to be registered */
 136 } hf_register_info;
 137
 138
 139
 140
 141 /** string representation, if one of the proto_tree_add_..._format() functions used */
 142 typedef struct _item_label_t {
 143         char representation[ITEM_LABEL_LENGTH];
 144 } item_label_t;
 145
 146
 147 /** Contains the field information for the proto_item. */
 148 typedef struct field_info {
 149         header_field_info       *hfinfo;    /**< pointer to registered field information */
 150         gint                            start;      /**< current start of data in field_info.ds_tvb */
 151         gint                            length;     /**< current data length of item in field_info.ds_tvb */
 152         gint                            tree_type;  /**< ETT_ */
 153         item_label_t            *rep;       /**< string for GUI tree */
 154         int                                     flags;      /**< one of FI_HIDDEN, ... */
 155         tvbuff_t                        *ds_tvb;    /**< data source tvbuff */
 156         fvalue_t                        value;
 157 } field_info;
 158
 159
 160 /** The protocol field should not be shown in the tree (it's used for filtering only),
 161  * used in field_info.flags. */
 162 #define FI_HIDDEN       0x0001
 163 /** The protocol field should be displayed as "generated by Ethereal",
 164  * used in field_info.flags. */
 165 #define FI_GENERATED    0x0002
 166
 167 /** convenience macro to get field_info.flags */
 168 #define FI_GET_FLAG(fi, flag) (fi->flags & flag)
 169 /** convenience macro to set field_info.flags */
 170 #define FI_SET_FLAG(fi, flag) (fi->flags = fi->flags | flag)
 171
 172
 173
 174 /** One of these exists for the entire protocol tree. Each proto_node
 175  * in the protocol tree points to the same copy. */
 176 typedef struct {
 177     GHashTable  *interesting_hfids;
 178     gboolean    visible;
 179 } tree_data_t;
 180
 181 /** Each proto_tree, proto_item is one of these. */
 182 typedef struct _proto_node {
 183         struct _proto_node *first_child;
 184         struct _proto_node *last_child;
 185         struct _proto_node *next;
 186         struct _proto_node *parent;
 187         field_info  *finfo;
 188         tree_data_t *tree_data;
 189 } proto_node;
 190
 191 /** A protocol tree element. */
 192 typedef proto_node proto_tree;
 193 /** A protocol item element. */
 194 typedef proto_node proto_item;
 195
 196
 197 /** is this protocol field hidden from the protocol tree display (used for filtering only)? */
 198 #define PROTO_ITEM_IS_HIDDEN(proto_item)        \
 199         ((proto_item) ? FI_GET_FLAG(proto_item->finfo, FI_HIDDEN) : 0)
 200 /** mark this protocol field to be hidden from the protocol tree display (used for filtering only) */
 201 #define PROTO_ITEM_SET_HIDDEN(proto_item)       \
 202         ((proto_item) ? FI_SET_FLAG(proto_item->finfo, FI_HIDDEN) : 0)
 203 /** is this protocol field generated by Ethereal (and not read from the packet data)? */
 204 #define PROTO_ITEM_IS_GENERATED(proto_item)     \
 205         ((proto_item) ? FI_GET_FLAG(proto_item->finfo, FI_GENERATED) : 0)
 206 /** mark this protocol field as generated by Ethereal (and not read from the packet data) */
 207 #define PROTO_ITEM_SET_GENERATED(proto_item)    \
 208         ((proto_item) ? FI_SET_FLAG(proto_item->finfo, FI_GENERATED) : 0)
 209
 210
 211 typedef void (*proto_tree_foreach_func)(proto_node *, gpointer);
 212
 213 extern void proto_tree_children_foreach(proto_tree *tree,
 214     proto_tree_foreach_func func, gpointer data);
 215
 216 /** Retrieve the field_info from a proto_item */
 217 #define PITEM_FINFO(proto_item)  ((proto_item)->finfo)
 218
 219 /** Retrieve the tree_data_t from a proto_tree */
 220 #define PTREE_DATA(proto_tree)   ((proto_tree)->tree_data)
 221
 222
 223
 224 /** Sets up memory used by proto routines. Called at program startup */
 225 extern void proto_init(const char *plugin_dir,
 226     void (register_all_protocols)(void), void (register_all_handoffs)(void));
 227
 228 /** Frees memory used by proto routines. Called at program shutdown */
 229 extern void proto_cleanup(void);
 230
 231
 232
 233 /** Create a subtree under an existing item.
 234  @param ti the parent item of the new subtree
 235  @param idx one of the ett_ array elements registered with proto_register_subtree_array()
 236  @return the new subtree */
 237 extern proto_tree* proto_item_add_subtree(proto_item *ti, gint idx);
 238
 239 /** Get an existing subtree under an item.
 240  @param ti the parent item of the subtree
 241  @return the subtree or NULL */
 242 extern proto_tree* proto_item_get_subtree(proto_item *ti);
 243
 244 /** Get the parent of a subtree item.
 245  @param ti the child item in the subtree
 246  @return parent item or NULL */
 247 extern proto_item* proto_item_get_parent(proto_item *ti);
 248
 249 /** Get Nth generation parent item.
 250  @param ti the child item in the subtree
 251  @param gen the generation to get (using 1 here is the same as using proto_item_get_parent())
 252  @return parent item */
 253 extern proto_item* proto_item_get_parent_nth(proto_item *ti, int gen);
 254
 255 /** Replace text of item after it already has been created.
 256  @param ti the item to set the text
 257  @param format printf like format string
 258  @param ... printf like parameters */
 259 extern void proto_item_set_text(proto_item *ti, const char *format, ...)
 260         GNUC_FORMAT_CHECK(printf, 2,3);
 261
 262 /** Append to text of item after it has already been created.
 263  @param ti the item to append the text to
 264  @param format printf like format string
 265  @param ... printf like parameters */
 266 extern void proto_item_append_text(proto_item *ti, const char *format, ...)
 267         GNUC_FORMAT_CHECK(printf, 2,3);
 268
 269 /** Set proto_item's length inside tvb, after it has already been created.
 270  @param ti the item to set the length
 271  @param length the new length ot the item */
 272 extern void proto_item_set_len(proto_item *ti, gint length);
 273
 274 /**
 275  * Sets the length of the item based on its start and on the specified
 276  * offset, which is the offset past the end of the item; as the start
 277  * in the item is relative to the beginning of the data source tvbuff,
 278  * we need to pass in a tvbuff.
 279  @param ti the item to set the length
 280  @param tvb end is relative to this tvbuff
 281  @param end this end offset is relative to the beginning of tvb
 282  @todo make usage clearer, I don't understand it!
 283  */
 284 extern void proto_item_set_end(proto_item *ti, tvbuff_t *tvb, gint end);
 285
 286 /** Get length of a proto_item. Useful after using proto_tree_add_item()
 287  * to add a variable-length field (e.g., FT_NSTRING_UINT8).
 288  @param ti the item to get the length from
 289  @return the current length */
 290 extern int proto_item_get_len(proto_item *ti);
 291
 292
 293
 294 /** Creates a new proto_tree root.
 295  @return the new tree root */
 296 extern proto_tree* proto_tree_create_root(void);
 297
 298 /** Clear memory for entry proto_tree. Clears proto_tree struct also.
 299  @param tree the tree to free */
 300 extern void proto_tree_free(proto_tree *tree);
 301
 302 /** Set the tree visible or invisible.
 303  Is the parsing being done for a visible proto_tree or an invisible one?
 304  By setting this correctly, the proto_tree creation is sped up by not
 305  having to call vsnprintf and copy strings around.
 306  @param tree the tree to be set
 307  @param visible ... or not  */
 308 extern void
 309 proto_tree_set_visible(proto_tree *tree, gboolean visible);
 310
 311 /** Mark a field/protocol ID as "interesting".
 312  @param tree the tree to be set
 313  @param hfid the interesting field id
 314  @todo what *does* interesting mean? */
 315 extern void
 316 proto_tree_prime_hfid(proto_tree *tree, int hfid);
 317
 318 /** Get a parent item of a subtree.
 319  @param tree the tree to get the parent from
 320  @return parent item */
 321 extern proto_item* proto_tree_get_parent(proto_tree *tree);
 322
 323
 324
 325 /** Add an item to a proto_tree, using the text label registered to that item.
 326    The item is extracted from the tvbuff handed to it.
 327  @param tree the tree to append this item to
 328  @param hfindex field index
 329  @param tvb the tv buffer of the current data
 330  @param start start of data in tvb
 331  @param length length of data in tvb
 332  @param little_endian big or little endian byte representation
 333  @return the newly created item */
 334 extern proto_item *
 335 proto_tree_add_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 336     gint start, gint length, gboolean little_endian);
 337
 338 /** Add a hidden item to a proto_tree.
 339  @deprecated use proto_tree_add_item() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 340 extern proto_item *
 341 proto_tree_add_item_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 342     gint start, gint length, gboolean little_endian);
 343
 344 /** Add a text-only node to a proto_tree.
 345  @param tree the tree to append this item to
 346  @param tvb the tv buffer of the current data
 347  @param start start of data in tvb
 348  @param length length of data in tvb
 349  @param format printf like format string
 350  @param ... printf like parameters
 351  @return the newly created item */
 352 extern proto_item *
 353 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
 354         ...) GNUC_FORMAT_CHECK(printf,5,6);
 355
 356 /** Add a text-only node to a proto_tree using a variable argument list.
 357  @param tree the tree to append this item to
 358  @param tvb the tv buffer of the current data
 359  @param start start of data in tvb
 360  @param length length of data in tvb
 361  @param format printf like format string
 362  @param ap variable argument list
 363  @return the newly created item */
 364 extern proto_item *
 365 proto_tree_add_text_valist(proto_tree *tree, tvbuff_t *tvb, gint start,
 366         gint length, const char *format, va_list ap);
 367
 368
 369 /** Add a FT_NONE field to a proto_tree.
 370  @param tree the tree to append this item to
 371  @param hfindex field index
 372  @param tvb the tv buffer of the current data
 373  @param start start of data in tvb
 374  @param length length of data in tvb
 375  @param format printf like format string
 376  @param ... printf like parameters
 377  @return the newly created item */
 378 extern proto_item *
 379 proto_tree_add_none_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 380         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 381
 382 /** Add a FT_PROTOCOL to a proto_tree.
 383  @param tree the tree to append this item to
 384  @param hfindex field index
 385  @param tvb the tv buffer of the current data
 386  @param start start of data in tvb
 387  @param length length of data in tvb
 388  @param format printf like format string
 389  @param ... printf like parameters
 390  @return the newly created item */
 391 extern proto_item *
 392 proto_tree_add_protocol_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 393         gint length, const char *format, ...) GNUC_FORMAT_CHECK(printf,6,7);
 394
 395
 396
 397
 398 /** Add a FT_BYTES to a proto_tree.
 399  @param tree the tree to append this item to
 400  @param hfindex field index
 401  @param tvb the tv buffer of the current data
 402  @param start start of data in tvb
 403  @param length length of data in tvb
 404  @param start_ptr pointer to the data to display
 405  @return the newly created item */
 406 extern proto_item *
 407 proto_tree_add_bytes(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 408         gint length, const guint8* start_ptr);
 409
 410 /** Add a hidden FT_BYTES to a proto_tree.
 411  @deprecated use proto_tree_add_bytes() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 412 extern proto_item *
 413 proto_tree_add_bytes_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 414         gint length, const guint8* start_ptr);
 415
 416 /** Add a formatted FT_BYTES to a proto_tree.
 417  @param tree the tree to append this item to
 418  @param hfindex field index
 419  @param tvb the tv buffer of the current data
 420  @param start start of data in tvb
 421  @param length length of data in tvb
 422  @param start_ptr pointer to the data to display
 423  @param format printf like format string
 424  @param ... printf like parameters
 425  @return the newly created item */
 426 extern proto_item *
 427 proto_tree_add_bytes_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 428         gint length, const guint8* start_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 429
 430 /** Add a FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 431  @param tree the tree to append this item to
 432  @param hfindex field index
 433  @param tvb the tv buffer of the current data
 434  @param start start of data in tvb
 435  @param length length of data in tvb
 436  @param value_ptr pointer to the data to display
 437  @return the newly created item */
 438 extern proto_item *
 439 proto_tree_add_time(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 440         gint length, nstime_t* value_ptr);
 441
 442 /** Add a hidden FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 443  @deprecated use proto_tree_add_time() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 444 extern proto_item *
 445 proto_tree_add_time_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 446         gint length, nstime_t* value_ptr);
 447
 448 /** Add a formatted FT_ABSOLUTE_TIME or FT_RELATIVE_TIME to a proto_tree.
 449  @param tree the tree to append this item to
 450  @param hfindex field index
 451  @param tvb the tv buffer of the current data
 452  @param start start of data in tvb
 453  @param length length of data in tvb
 454  @param value_ptr pointer to the data to display
 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_time_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 460         gint length, nstime_t* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 461
 462 /** Add a FT_IPXNET to a proto_tree.
 463  @param tree the tree to append this item to
 464  @param hfindex field index
 465  @param tvb the tv buffer of the current data
 466  @param start start of data in tvb
 467  @param length length of data in tvb
 468  @param value data to display
 469  @return the newly created item */
 470 extern proto_item *
 471 proto_tree_add_ipxnet(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 472         gint length, guint32 value);
 473
 474 /** Add a hidden FT_IPXNET to a proto_tree.
 475  @deprecated use proto_tree_add_ipxnet() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 476 extern proto_item *
 477 proto_tree_add_ipxnet_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 478         gint length, guint32 value);
 479
 480 /** Add a formatted FT_IPXNET to a proto_tree.
 481  @param tree the tree to append this item to
 482  @param hfindex field index
 483  @param tvb the tv buffer of the current data
 484  @param start start of data in tvb
 485  @param length length of data in tvb
 486  @param value data to display
 487  @param format printf like format string
 488  @param ... printf like parameters
 489  @return the newly created item */
 490 extern proto_item *
 491 proto_tree_add_ipxnet_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 492         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 493
 494 /** Add a FT_IPv4 to a proto_tree.
 495  @param tree the tree to append this item to
 496  @param hfindex field index
 497  @param tvb the tv buffer of the current data
 498  @param start start of data in tvb
 499  @param length length of data in tvb
 500  @param value data to display
 501  @return the newly created item */
 502 extern proto_item *
 503 proto_tree_add_ipv4(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 504         gint length, guint32 value);
 505
 506 /** Add a hidden FT_IPv4 to a proto_tree.
 507  @deprecated use proto_tree_add_ipv4() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 508 extern proto_item *
 509 proto_tree_add_ipv4_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 510         gint length, guint32 value);
 511
 512 /** Add a formatted FT_IPv4 to a proto_tree.
 513  @param tree the tree to append this item to
 514  @param hfindex field index
 515  @param tvb the tv buffer of the current data
 516  @param start start of data in tvb
 517  @param length length of data in tvb
 518  @param value data to display
 519  @param format printf like format string
 520  @param ... printf like parameters
 521  @return the newly created item */
 522 extern proto_item *
 523 proto_tree_add_ipv4_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 524         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 525
 526 /** Add a FT_IPv6 to a proto_tree.
 527  @param tree the tree to append this item to
 528  @param hfindex field index
 529  @param tvb the tv buffer of the current data
 530  @param start start of data in tvb
 531  @param length length of data in tvb
 532  @param value_ptr data to display
 533  @return the newly created item */
 534 extern proto_item *
 535 proto_tree_add_ipv6(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 536         gint length, const guint8* value_ptr);
 537
 538 /** Add a hidden FT_IPv6 to a proto_tree.
 539  @deprecated use proto_tree_add_ipv6() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 540 extern proto_item *
 541 proto_tree_add_ipv6_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 542         gint length, const guint8* value_ptr);
 543
 544 /** Add a formatted FT_IPv6 to a proto_tree.
 545  @param tree the tree to append this item to
 546  @param hfindex field index
 547  @param tvb the tv buffer of the current data
 548  @param start start of data in tvb
 549  @param length length of data in tvb
 550  @param value_ptr data to display
 551  @param format printf like format string
 552  @param ... printf like parameters
 553  @return the newly created item */
 554 extern proto_item *
 555 proto_tree_add_ipv6_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 556         gint length, const guint8* value_ptr, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 557
 558 /** Add a FT_ETHER to a proto_tree.
 559  @param tree the tree to append this item to
 560  @param hfindex field index
 561  @param tvb the tv buffer of the current data
 562  @param start start of data in tvb
 563  @param length length of data in tvb
 564  @param value data to display
 565  @return the newly created item */
 566 extern proto_item *
 567 proto_tree_add_ether(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 568         gint length, const guint8* value);
 569
 570 /** Add a hidden FT_ETHER to a proto_tree.
 571  @deprecated use proto_tree_add_ether() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 572 extern proto_item *
 573 proto_tree_add_ether_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 574         gint length, const guint8* value);
 575
 576 /** Add a formatted FT_ETHER to a proto_tree.
 577  @param tree the tree to append this item to
 578  @param hfindex field index
 579  @param tvb the tv buffer of the current data
 580  @param start start of data in tvb
 581  @param length length of data in tvb
 582  @param value data to display
 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_ether_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 588         gint length, const guint8* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 589
 590 /** Add a FT_STRING to a proto_tree.
 591  @param tree the tree to append this item to
 592  @param hfindex field index
 593  @param tvb the tv buffer of the current data
 594  @param start start of data in tvb
 595  @param length length of data in tvb
 596  @param value data to display
 597  @return the newly created item */
 598 extern proto_item *
 599 proto_tree_add_string(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 600         gint length, const char* value);
 601
 602 /** Add a hidden FT_STRING to a proto_tree.
 603  @deprecated use proto_tree_add_string() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 604 extern proto_item *
 605 proto_tree_add_string_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 606         gint length, const char* value);
 607
 608 /** Add a formatted FT_STRING to a proto_tree.
 609  @param tree the tree to append this item to
 610  @param hfindex field index
 611  @param tvb the tv buffer of the current data
 612  @param start start of data in tvb
 613  @param length length of data in tvb
 614  @param value data to display
 615  @param format printf like format string
 616  @param ... printf like parameters
 617  @return the newly created item */
 618 extern proto_item *
 619 proto_tree_add_string_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 620         gint length, const char* value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 621
 622 /** Add a FT_BOOLEAN to a proto_tree.
 623  @param tree the tree to append this item to
 624  @param hfindex field index
 625  @param tvb the tv buffer of the current data
 626  @param start start of data in tvb
 627  @param length length of data in tvb
 628  @param value data to display
 629  @return the newly created item */
 630 extern proto_item *
 631 proto_tree_add_boolean(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 632         gint length, guint32 value);
 633
 634 /** Add a hidden FT_BOOLEAN to a proto_tree.
 635  @deprecated use proto_tree_add_boolean() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 636 extern proto_item *
 637 proto_tree_add_boolean_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 638         gint length, guint32 value);
 639
 640 /** Add a formatted FT_BOOLEAN to a proto_tree.
 641  @param tree the tree to append this item to
 642  @param hfindex field index
 643  @param tvb the tv buffer of the current data
 644  @param start start of data in tvb
 645  @param length length of data in tvb
 646  @param value data to display
 647  @param format printf like format string
 648  @param ... printf like parameters
 649  @return the newly created item */
 650 extern proto_item *
 651 proto_tree_add_boolean_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 652         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 653
 654 /** Add a FT_FLOAT to a proto_tree.
 655  @param tree the tree to append this item to
 656  @param hfindex field index
 657  @param tvb the tv buffer of the current data
 658  @param start start of data in tvb
 659  @param length length of data in tvb
 660  @param value data to display
 661  @return the newly created item */
 662 extern proto_item *
 663 proto_tree_add_float(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 664         gint length, float value);
 665
 666 /** Add a hidden FT_FLOAT to a proto_tree.
 667  @deprecated use proto_tree_add_float() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 668 extern proto_item *
 669 proto_tree_add_float_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 670         gint length, float value);
 671
 672 /** Add a formatted FT_FLOAT to a proto_tree.
 673  @param tree the tree to append this item to
 674  @param hfindex field index
 675  @param tvb the tv buffer of the current data
 676  @param start start of data in tvb
 677  @param length length of data in tvb
 678  @param value data to display
 679  @param format printf like format string
 680  @param ... printf like parameters
 681  @return the newly created item */
 682 extern proto_item *
 683 proto_tree_add_float_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 684         gint length, float value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 685
 686 /** Add a FT_DOUBLE to a proto_tree.
 687  @param tree the tree to append this item to
 688  @param hfindex field index
 689  @param tvb the tv buffer of the current data
 690  @param start start of data in tvb
 691  @param length length of data in tvb
 692  @param value data to display
 693  @return the newly created item */
 694 extern proto_item *
 695 proto_tree_add_double(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 696         gint length, double value);
 697
 698 /** Add a hidden FT_DOUBLE to a proto_tree.
 699  @deprecated use proto_tree_add_double() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 700 extern proto_item *
 701 proto_tree_add_double_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 702         gint length, double value);
 703
 704 /** Add a formatted FT_DOUBLE to a proto_tree.
 705  @param tree the tree to append this item to
 706  @param hfindex field index
 707  @param tvb the tv buffer of the current data
 708  @param start start of data in tvb
 709  @param length length of data in tvb
 710  @param value data to display
 711  @param format printf like format string
 712  @param ... printf like parameters
 713  @return the newly created item */
 714 extern proto_item *
 715 proto_tree_add_double_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 716         gint length, double value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 717
 718 /** Add one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 719  @param tree the tree to append this item to
 720  @param hfindex field index
 721  @param tvb the tv buffer of the current data
 722  @param start start of data in tvb
 723  @param length length of data in tvb
 724  @param value data to display
 725  @return the newly created item */
 726 extern proto_item *
 727 proto_tree_add_uint(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 728         gint length, guint32 value);
 729
 730 /** Add a hidden of one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 731  @deprecated use proto_tree_add_uint() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 732 extern proto_item *
 733 proto_tree_add_uint_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 734         gint length, guint32 value);
 735
 736 /** Add a formatted of one of FT_UINT8, FT_UINT16, FT_UINT24 or FT_UINT32 to a proto_tree.
 737  @param tree the tree to append this item to
 738  @param hfindex field index
 739  @param tvb the tv buffer of the current data
 740  @param start start of data in tvb
 741  @param length length of data in tvb
 742  @param value data to display
 743  @param format printf like format string
 744  @param ... printf like parameters
 745  @return the newly created item */
 746 extern proto_item *
 747 proto_tree_add_uint_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 748         gint length, guint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 749
 750 /** Add an FT_UINT64 to a proto_tree.
 751  @param tree the tree to append this item to
 752  @param hfindex field index
 753  @param tvb the tv buffer of the current data
 754  @param start start of data in tvb
 755  @param length length of data in tvb
 756  @param value data to display
 757  @return the newly created item */
 758 extern proto_item *
 759 proto_tree_add_uint64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 760         gint length, guint64 value);
 761
 762 /** Add a formatted FT_UINT64 to a proto_tree.
 763  @param tree the tree to append this item to
 764  @param hfindex field index
 765  @param tvb the tv buffer of the current data
 766  @param start start of data in tvb
 767  @param length length of data in tvb
 768  @param value data to display
 769  @param format printf like format string
 770  @param ... printf like parameters
 771  @return the newly created item */
 772 extern proto_item *
 773 proto_tree_add_uint64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 774         gint length, guint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 775
 776 /** Add one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 777  @param tree the tree to append this item to
 778  @param hfindex field index
 779  @param tvb the tv buffer of the current data
 780  @param start start of data in tvb
 781  @param length length of data in tvb
 782  @param value data to display
 783  @return the newly created item */
 784 extern proto_item *
 785 proto_tree_add_int(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 786         gint length, gint32 value);
 787
 788 /** Add a hidden of one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 789  @deprecated use proto_tree_add_int() and a subsequent call to PROTO_ITEM_SET_HIDDEN() instead */
 790 extern proto_item *
 791 proto_tree_add_int_hidden(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 792         gint length, gint32 value);
 793
 794 /** Add a formatted of one of FT_INT8, FT_INT16, FT_INT24 or FT_INT32 to a proto_tree.
 795  @param tree the tree to append this item to
 796  @param hfindex field index
 797  @param tvb the tv buffer of the current data
 798  @param start start of data in tvb
 799  @param length length of data in tvb
 800  @param value data to display
 801  @param format printf like format string
 802  @param ... printf like parameters
 803  @return the newly created item */
 804 extern proto_item *
 805 proto_tree_add_int_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 806         gint length, gint32 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 807
 808 /** Add an FT_INT64 to a proto_tree.
 809  @param tree the tree to append this item to
 810  @param hfindex field index
 811  @param tvb the tv buffer of the current data
 812  @param start start of data in tvb
 813  @param length length of data in tvb
 814  @param value data to display
 815  @return the newly created item */
 816 extern proto_item *
 817 proto_tree_add_int64(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 818         gint length, gint64 value);
 819
 820 /** Add a formatted FT_INT64 to a proto_tree.
 821  @param tree the tree to append this item to
 822  @param hfindex field index
 823  @param tvb the tv buffer of the current data
 824  @param start start of data in tvb
 825  @param length length of data in tvb
 826  @param value data to display
 827  @param format printf like format string
 828  @param ... printf like parameters
 829  @return the newly created item */
 830 extern proto_item *
 831 proto_tree_add_int64_format(proto_tree *tree, int hfindex, tvbuff_t *tvb, gint start,
 832         gint length, gint64 value, const char *format, ...) GNUC_FORMAT_CHECK(printf,7,8);
 833
 834 /** Useful for quick debugging. Also sends string to STDOUT, so don't
 835  * leave call to this function in production code.
 836  @param tree the tree to append the text to
 837  @param format printf like format string
 838  @param ... printf like parameters
 839  @return the newly created item */
 840 extern proto_item *
 841 proto_tree_add_debug_text(proto_tree *tree, const char *format,
 842         ...) GNUC_FORMAT_CHECK(printf,2,3);
 843
 844
 845
 846 /** Append a string to a protocol item.
 847  @param pi the item to append the string to
 848  @param str the string to append */
 849 extern void
 850 proto_item_append_string(proto_item *pi, const char *str);
 851
 852
 853
 854 /** Fill given label_str with string representation of field
 855  @param fi the item to get the info from
 856  @param label_str the string to fill
 857  @todo think about changing the parameter profile */
 858 extern void
 859 proto_item_fill_label(field_info *fi, gchar *label_str);
 860
 861
 862 /** Register a new protocol.
 863  @param name the name of the new protocol
 864  @param short_name abbreviated name of the new protocol
 865  @param filter_name protocol name used for a display filter string
 866  @return the new protocol handle */
 867 extern int
 868 proto_register_protocol(char *name, char *short_name, char *filter_name);
 869
 870 /** Register a header_field array.
 871  @param parent the protocol handle from proto_register_protocol()
 872  @param hf the hf_register_info array
 873  @param num_records the number of records in hf */
 874 extern void
 875 proto_register_field_array(int parent, hf_register_info *hf, int num_records);
 876
 877 /** Register a protocol subtree (ett) array.
 878  @param indices array of ett indices
 879  @param num_indices the number of records in indices */
 880 extern void
 881 proto_register_subtree_array(gint *const *indices, int num_indices);
 882
 883 /** Returns number of items (protocols or header fields) registered.
 884  @return the number of items */
 885 extern int proto_registrar_n(void);
 886
 887 /** Get name of registered header_field number n.
 888  @param n item # n (0-indexed)
 889  @return the name of this registered item */
 890 extern char* proto_registrar_get_name(int n);
 891
 892 /** Get abbreviation of registered header_field number n.
 893  @param n item # n (0-indexed)
 894  @return the abbreviation of this registered item */
 895 extern char* proto_registrar_get_abbrev(int n);
 896
 897 /** Get the header_field information based upon a field or protocol id.
 898  @param hfindex item # n (0-indexed)
 899  @return the registered item */
 900 extern header_field_info* proto_registrar_get_nth(guint hfindex);
 901
 902 /** Get the header_field information based upon a field name.
 903  @param field_name the field name to search for
 904  @return the registered item */
 905 extern header_field_info* proto_registrar_get_byname(const char *field_name);
 906
 907 /** Get enum ftenum FT_ of registered header_field number n.
 908  @param n item # n (0-indexed)
 909  @return the registered item */
 910 extern int proto_registrar_get_ftype(int n);
 911
 912 /** Get parent protocol of registered header_field number n.
 913  @param n item # n (0-indexed)
 914  @return -1 if item _is_ a protocol */
 915 extern int proto_registrar_get_parent(int n);
 916
 917 /** Is item #n a protocol?
 918  @param n item # n (0-indexed)
 919  @return TRUE if it's a protocol, FALSE if it's not */
 920 extern gboolean proto_registrar_is_protocol(int n);
 921
 922 /* Get length of registered field according to field type.
 923  @param n item # n (0-indexed)
 924  @return 0 means undeterminable at registration time, * -1 means unknown field */
 925 extern gint proto_registrar_get_length(int n);
 926
 927
 928 /* Routines to use to iterate over the protocols and their fields;
 929  * they return the item number of the protocol in question or the
 930  * appropriate hfinfo pointer, and keep state in "*cookie". */
 931 extern int proto_get_first_protocol(void **cookie);
 932 extern int proto_get_next_protocol(void **cookie);
 933 extern header_field_info *proto_get_first_protocol_field(int proto_id, void **cookle);
 934 extern header_field_info *proto_get_next_protocol_field(void **cookle);
 935
 936 /** Given a protocol's filter_name.
 937  @param filter_name the filter name to search for
 938  @return proto_id */
 939 extern int proto_get_id_by_filter_name(gchar* filter_name);
 940
 941 /** Can item #n decoding be disabled?
 942  @param proto_id protocol id (0-indexed)
 943  @return TRUE if it's a protocol, FALSE if it's not */
 944 extern gboolean proto_can_toggle_protocol(int proto_id);
 945
 946 /** Get the "protocol_t" structure for the given protocol's item number.
 947  @param proto_id protocol id (0-indexed) */
 948 extern protocol_t *find_protocol_by_id(int proto_id);
 949
 950 /** Get the protocol's name for the given protocol's item number.
 951  @param proto_id protocol id (0-indexed)
 952  @return its name */
 953 extern char *proto_get_protocol_name(int proto_id);
 954
 955 /** Get the protocol's item number, for the given protocol's "protocol_t".
 956  @return its proto_id */
 957 extern int proto_get_id(protocol_t *protocol);
 958
 959 /** Get the protocol's short name, for the given protocol's "protocol_t".
 960  @return its short name. */
 961 extern char *proto_get_protocol_short_name(protocol_t *protocol);
 962
 963 /** Is protocol's decoding enabled ?
 964  @param protocol
 965  @return TRUE if decoding is enabled, FALSE if not */
 966 extern gboolean proto_is_protocol_enabled(protocol_t *protocol);
 967
 968 /** Get a protocol's filter name by it's item number.
 969  @param proto_id protocol id (0-indexed)
 970  @return its filter name. */
 971 extern char *proto_get_protocol_filter_name(int proto_id);
 972
 973 /** Enable / Disable protocol of the given item number.
 974  @param proto_id protocol id (0-indexed)
 975  @param enabled enable / disable the protocol */
 976 extern void proto_set_decoding(int proto_id, gboolean enabled);
 977
 978 /** Disable disabling/enabling of protocol of the given item number.
 979  @param proto_id protocol id (0-indexed) */
 980 extern void proto_set_cant_toggle(int proto_id);
 981
 982 /** Checks for existence any protocol or field within a tree.
 983  @param tree "Protocols" are assumed to be a child of the [empty] root node.
 984  @param id ???
 985  @return TRUE = found, FALSE = not found
 986  @todo add explanation of id parameter */
 987 extern gboolean proto_check_for_protocol_or_field(proto_tree* tree, int id);
 988
 989 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
 990  * tree. Only works with primed trees, and is fast. */
 991 extern GPtrArray* proto_get_finfo_ptr_array(proto_tree *tree, int hfindex);
 992
 993 /* Return GPtrArray* of field_info pointers for all hfindex that appear in
 994  * tree. Works with any tree, primed or unprimed, and is slower than
 995  * proto_get_finfo_ptr_array because it has to search through the tree. */
 996 extern GPtrArray* proto_find_finfo(proto_tree *tree, int hfindex);
 997
 998 /** Dumps a glossary of the protocol registrations to STDOUT */
 999 extern void proto_registrar_dump_protocols(void);
1000
1001 /** Dumps a glossary of the field value strings or true/false strings to STDOUT */
1002 extern void proto_registrar_dump_values(void);
1003
1004 /** Dumps a glossary of the protocol and field registrations to STDOUT.
1005  * Format 1 is the original format. Format 2 includes the base (for integers)
1006  * and the blurb. */
1007 extern void proto_registrar_dump_fields(int format);
1008
1009
1010
1011 /** Points to the first element of an array of Booleans, indexed by
1012    a subtree item type. That array element is TRUE if subtrees of
1013    an item of that type are to be expanded. With MSVC and a
1014    libethereal.dll, we need a special declaration. */
1015 ETH_VAR_IMPORT gboolean      *tree_is_expanded;
1016
1017 /** Number of elements in the tree_is_expanded array. With MSVC and a
1018  * libethereal.dll, we need a special declaration. */
1019 ETH_VAR_IMPORT int           num_tree_types;
1020
1021 /** glib doesn't have g_ptr_array_len of all things!*/
1022 #ifndef g_ptr_array_len
1023 #define g_ptr_array_len(a)      ((a)->len)
1024 #endif
1025
1026 /** Get number of bits of a header_field.
1027  @param hfinfo header_field
1028  @return the bitwidth */
1029 extern int
1030 hfinfo_bitwidth(header_field_info *hfinfo);
1031
1032
1033
1034
1035 #include "epan.h"
1036
1037 /** Can we do a "match selected" on this field.
1038  @param finfo field_info
1039  @param edt epan dissecting
1040  @return TRUE if we can do a "match selected" on the field, FALSE otherwise. */
1041 extern gboolean
1042 proto_can_match_selected(field_info *finfo, epan_dissect_t *edt);
1043
1044 /** Construct a display filter string.
1045  @param finfo field_info
1046  @param edt epan dissecting
1047  @return the display filter string */
1048 extern char*
1049 proto_construct_dfilter_string(field_info *finfo, epan_dissect_t *edt);
1050
1051 /** Find field from offset in tvb.
1052  @param tree
1053  @param offset offset in the tvb
1054  @param tvb the tv buffer
1055  @return the corresponding field_info */
1056 extern field_info*
1057 proto_find_field_from_offset(proto_tree *tree, guint offset, tvbuff_t *tvb);
1058
1059 #endif /* proto.h */