epan/packet.h

   1 /** @file
   2  * Definitions for packet disassembly structures and routines
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef __PACKET_H__
  12 #define __PACKET_H__
  13
  14 #include <wsutil/array.h>
  15 #include <wiretap/wtap_opttypes.h>
  16 #include "proto.h"
  17 #include "range.h"
  18 #include "tvbuff.h"
  19 #include "epan.h"
  20 #include "frame_data.h"
  21 #include "packet_info.h"
  22 #include "column-utils.h"
  23 #include "guid-utils.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29
  30
  31 /** @defgroup packet General Packet Dissection
  32  *
  33  * @{
  34  */
  35
  36 #define hi_nibble(b) (((b) & 0xf0) >> 4)
  37 #define lo_nibble(b) ((b) & 0x0f)
  38
  39 /* Check whether the "len" bytes of data starting at "offset" is
  40  * entirely inside the captured data for this packet. */
  41 #define BYTES_ARE_IN_FRAME(offset, captured_len, len) \
  42         ((unsigned)(offset) + (unsigned)(len) > (unsigned)(offset) && \
  43          (unsigned)(offset) + (unsigned)(len) <= (unsigned)(captured_len))
  44
  45 /* 0 is case insensitive for backwards compatibility with tables that
  46  * used false or BASE_NONE for case sensitive, which was the default.
  47  */
  48 #define STRING_CASE_SENSITIVE 0
  49 #define STRING_CASE_INSENSITIVE 1
  50
  51 extern void packet_init(void);
  52 extern void packet_cache_proto_handles(void);
  53 extern void packet_all_tables_sort_handles(void);
  54 extern void packet_cleanup(void);
  55
  56 /* Handle for dissectors you call directly or register with "dissector_add_uint()".
  57    This handle is opaque outside of "packet.c". */
  58 struct dissector_handle;
  59 typedef struct dissector_handle *dissector_handle_t;
  60
  61 /* Hash table for matching unsigned integers, or strings, and dissectors;
  62    this is opaque outside of "packet.c". */
  63 struct dissector_table;
  64 typedef struct dissector_table *dissector_table_t;
  65
  66 /*
  67  * Dissector that returns:
  68  *
  69  *      The amount of data in the protocol's PDU, if it was able to
  70  *      dissect all the data;
  71  *
  72  *      0, if the tvbuff doesn't contain a PDU for that protocol;
  73  *
  74  *      The negative of the amount of additional data needed, if
  75  *      we need more data (e.g., from subsequent TCP segments) to
  76  *      dissect the entire PDU.
  77  */
  78 typedef int (*dissector_t)(tvbuff_t *, packet_info *, proto_tree *, void *);
  79
  80 /* Same as dissector_t with an extra parameter for callback pointer */
  81 typedef int (*dissector_cb_t)(tvbuff_t *, packet_info *, proto_tree *, void *, void *);
  82
  83 /** Type of a heuristic dissector, used in heur_dissector_add().
  84  *
  85  * @param tvb the tvbuff with the (remaining) packet data
  86  * @param pinfo the packet info of this packet (additional info)
  87  * @param tree the protocol tree to be build or NULL
  88  * @return true if the packet was recognized by the sub-dissector (stop dissection here)
  89  */
  90 typedef bool (*heur_dissector_t)(tvbuff_t *tvb, packet_info *pinfo,
  91         proto_tree *tree, void *);
  92
  93 typedef enum {
  94     HEURISTIC_DISABLE,
  95     HEURISTIC_ENABLE
  96 } heuristic_enable_e;
  97
  98 typedef void (*DATFunc) (const char *table_name, ftenum_t selector_type,
  99     void *key, void *value, void *user_data);
 100 typedef void (*DATFunc_handle) (const char *table_name, void *value,
 101     void *user_data);
 102 typedef void (*DATFunc_table) (const char *table_name, const char *ui_name,
 103     void *user_data);
 104
 105 /* Opaque structure - provides type checking but no access to components */
 106 typedef struct dtbl_entry dtbl_entry_t;
 107
 108 WS_DLL_PUBLIC dissector_handle_t dtbl_entry_get_handle (dtbl_entry_t *dtbl_entry);
 109 WS_DLL_PUBLIC dissector_handle_t dtbl_entry_get_initial_handle (dtbl_entry_t * entry);
 110
 111 /** Iterate over dissectors in a table with non-default "decode as" settings.
 112  *
 113  * Walk one dissector table calling a user supplied function only on
 114  * any entry that has been changed from its original state.
 115  *
 116  * @param[in] table_name The name of the dissector table, e.g. "ip.proto".
 117  * @param[in] func The function to call for each dissector.
 118  * @param[in] user_data User data to pass to the function.
 119  */
 120 void dissector_table_foreach_changed (const char *table_name, DATFunc func,
 121     void *user_data);
 122
 123 /** Iterate over dissectors in a table.
 124  *
 125  * Walk one dissector table's hash table calling a user supplied function
 126  * on each entry.
 127  *
 128  * @param[in] table_name The name of the dissector table, e.g. "ip.proto".
 129  * @param[in] func The function to call for each dissector.
 130  * @param[in] user_data User data to pass to the function.
 131  */
 132 WS_DLL_PUBLIC void dissector_table_foreach (const char *table_name, DATFunc func,
 133     void *user_data);
 134
 135 /** Iterate over dissectors with non-default "decode as" settings.
 136  *
 137  * Walk all dissector tables calling a user supplied function only on
 138  * any "decode as" entry that has been changed from its original state.
 139  *
 140  * @param[in] func The function to call for each dissector.
 141  * @param[in] user_data User data to pass to the function.
 142  */
 143 WS_DLL_PUBLIC void dissector_all_tables_foreach_changed (DATFunc func,
 144     void *user_data);
 145
 146 /** Iterate over dissectors in a table by handle.
 147  *
 148  * Walk one dissector table's list of handles calling a user supplied
 149  * function on each entry.
 150  *
 151  * @param[in] table_name The name of the dissector table, e.g. "ip.proto".
 152  * @param[in] func The function to call for each dissector.
 153  * @param[in] user_data User data to pass to the function.
 154  */
 155 WS_DLL_PUBLIC void dissector_table_foreach_handle(const char *table_name, DATFunc_handle func,
 156     void *user_data);
 157
 158 /** Iterate over all dissector tables.
 159  *
 160  * Walk the set of dissector tables calling a user supplied function on each
 161  * table.
 162  * @param[in] func The function to call for each table.
 163  * @param[in] user_data User data to pass to the function.
 164  * @param[in] compare_key_func Function used to sort the set of tables before
 165  * calling the function.  No sorting is done if NULL. */
 166 WS_DLL_PUBLIC void dissector_all_tables_foreach_table (DATFunc_table func,
 167     void *user_data, GCompareFunc compare_key_func);
 168
 169 /* a protocol uses the function to register a sub-dissector table
 170  *
 171  * 'param' is the display base for integer tables, STRING_CASE_SENSITIVE
 172  * or STRING_CASE_INSENSITIVE for string tables, and ignored for other
 173  * table types.
 174  */
 175 WS_DLL_PUBLIC dissector_table_t register_dissector_table(const char *name,
 176     const char *ui_name, const int proto, const ftenum_t type, const int param);
 177
 178 /*
 179  * Similar to register_dissector_table, but with a "custom" hash function
 180  * to store subdissectors.
 181  */
 182 WS_DLL_PUBLIC dissector_table_t register_custom_dissector_table(const char *name,
 183     const char *ui_name, const int proto, GHashFunc hash_func, GEqualFunc key_equal_func,
 184     GDestroyNotify key_destroy_func);
 185
 186 /** Register a dissector table alias.
 187  * This is for dissectors whose original name has changed, e.g. SSL to TLS.
 188  * @param dissector_table dissector table returned by register_dissector_table.
 189  * @param alias_name alias for the dissector table name.
 190  */
 191 WS_DLL_PUBLIC void register_dissector_table_alias(dissector_table_t dissector_table,
 192     const char *alias_name);
 193
 194 /** Deregister the dissector table by table name. */
 195 void deregister_dissector_table(const char *name);
 196
 197 /* Find a dissector table by table name. */
 198 WS_DLL_PUBLIC dissector_table_t find_dissector_table(const char *name);
 199
 200 /* Get the UI name for a sub-dissector table, given its internal name */
 201 WS_DLL_PUBLIC const char *get_dissector_table_ui_name(const char *name);
 202
 203 /* Get the field type for values of the selector for a dissector table,
 204    given the table's internal name */
 205 WS_DLL_PUBLIC ftenum_t get_dissector_table_selector_type(const char *name);
 206
 207 /* Get the param set for the sub-dissector table,
 208    given the table's internal name */
 209 WS_DLL_PUBLIC int get_dissector_table_param(const char *name);
 210
 211 /* Dump all dissector tables to the standard output (not the entries,
 212    just the information about the tables) */
 213 WS_DLL_PUBLIC void dissector_dump_dissector_tables(void);
 214
 215 /* Add an entry to a uint dissector table. */
 216 WS_DLL_PUBLIC void dissector_add_uint(const char *name, const uint32_t pattern,
 217     dissector_handle_t handle);
 218
 219 /* Add an entry to a uint dissector table with "preference" automatically added. */
 220 WS_DLL_PUBLIC void dissector_add_uint_with_preference(const char *name, const uint32_t pattern,
 221     dissector_handle_t handle);
 222
 223 /** Add an range of entries to a uint dissector table. */
 224 WS_DLL_PUBLIC void dissector_add_uint_range(const char *abbrev, range_t *range,
 225     dissector_handle_t handle);
 226
 227 /** Add an range of entries to a uint dissector table with "preference" automatically added. */
 228 WS_DLL_PUBLIC void dissector_add_uint_range_with_preference(const char *abbrev, const char* range_str,
 229     dissector_handle_t handle);
 230
 231 /** Delete the entry for a dissector in a uint dissector table
 232    with a particular pattern. */
 233 WS_DLL_PUBLIC void dissector_delete_uint(const char *name, const uint32_t pattern,
 234     dissector_handle_t handle);
 235
 236 /** Delete an range of entries from a uint dissector table. */
 237 WS_DLL_PUBLIC void dissector_delete_uint_range(const char *abbrev, range_t *range,
 238     dissector_handle_t handle);
 239
 240 /** Delete all entries from a dissector table. */
 241 WS_DLL_PUBLIC void dissector_delete_all(const char *name, dissector_handle_t handle);
 242
 243 /** Change the entry for a dissector in a uint dissector table
 244    with a particular pattern to use a new dissector handle. */
 245 WS_DLL_PUBLIC void dissector_change_uint(const char *abbrev, const uint32_t pattern,
 246     dissector_handle_t handle);
 247
 248 /** Reset an entry in a uint dissector table to its initial value. */
 249 WS_DLL_PUBLIC void dissector_reset_uint(const char *name, const uint32_t pattern);
 250
 251 /** Return true if an entry in a uint dissector table is found and has been
 252  * changed (i.e. dissector_change_uint() has been called, such as from
 253  * Decode As, prefs registered via dissector_add_uint_[range_]with_preference),
 254  * etc.), otherwise return false.
 255  */
 256 WS_DLL_PUBLIC bool dissector_is_uint_changed(dissector_table_t const sub_dissectors, const uint32_t uint_val);
 257
 258 /** Look for a given value in a given uint dissector table and, if found,
 259    call the dissector with the arguments supplied, and return the number
 260    of bytes consumed, otherwise return 0. */
 261 WS_DLL_PUBLIC int dissector_try_uint(dissector_table_t sub_dissectors,
 262     const uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
 263
 264 /** Look for a given value in a given uint dissector table and, if found,
 265    call the dissector with the arguments supplied, and return the number
 266    of bytes consumed, otherwise return 0. */
 267
 268 WS_DLL_PUBLIC int dissector_try_uint_with_data(dissector_table_t sub_dissectors,
 269     const uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, const bool add_proto_name, void *data);
 270
 271 WS_DEPRECATED_X("Use dissector_try_uint_with_data instead")
 272 static inline int dissector_try_uint_new(dissector_table_t sub_dissectors,
 273         const uint32_t uint_val, tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree, const bool add_proto_name, void* data) \
 274 {       return dissector_try_uint_with_data(sub_dissectors, uint_val, tvb, pinfo, tree, add_proto_name, data); }
 275
 276 /** Look for a given value in a given uint dissector table and, if found,
 277  * return the current dissector handle for that value.
 278  *
 279  * @param[in] sub_dissectors Dissector table to search.
 280  * @param[in] uint_val Value to match, e.g. the port number for the TCP dissector.
 281  * @return The matching dissector handle on success, NULL if no match is found.
 282  */
 283 WS_DLL_PUBLIC dissector_handle_t dissector_get_uint_handle(
 284     dissector_table_t const sub_dissectors, const uint32_t uint_val);
 285
 286 /** Look for a given value in a given uint dissector table and, if found,
 287  * return the default dissector handle for that value.
 288  *
 289  * @param[in] name Dissector table name.
 290  * @param[in] uint_val Value to match, e.g. the port number for the TCP dissector.
 291  * @return The matching dissector handle on success, NULL if no match is found.
 292  */
 293 WS_DLL_PUBLIC dissector_handle_t dissector_get_default_uint_handle(
 294     const char *name, const uint32_t uint_val);
 295
 296 /* Add an entry to a string dissector table. */
 297 WS_DLL_PUBLIC void dissector_add_string(const char *name, const char *pattern,
 298     dissector_handle_t handle);
 299
 300 /* Delete the entry for a dissector in a string dissector table
 301    with a particular pattern. */
 302 WS_DLL_PUBLIC void dissector_delete_string(const char *name, const char *pattern,
 303         dissector_handle_t handle);
 304
 305 /* Change the entry for a dissector in a string dissector table
 306    with a particular pattern to use a new dissector handle. */
 307 WS_DLL_PUBLIC void dissector_change_string(const char *name, const char *pattern,
 308     dissector_handle_t handle);
 309
 310 /* Reset an entry in a string sub-dissector table to its initial value. */
 311 WS_DLL_PUBLIC void dissector_reset_string(const char *name, const char *pattern);
 312
 313 /* Return true if an entry in a string dissector table is found and has been
 314  * changed (i.e. dissector_change_string() has been called, such as from
 315  * Decode As), otherwise return false.
 316  */
 317 WS_DLL_PUBLIC bool dissector_is_string_changed(dissector_table_t const subdissectors, const char *string);
 318
 319
 320 /** Look for a given string in a given dissector table and, if found, call
 321    the dissector with the arguments supplied, and return the number of
 322    bytes consumed, otherwise return 0. */
 323 WS_DLL_PUBLIC int dissector_try_string_with_data(dissector_table_t sub_dissectors,
 324         const char* string, tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree, const bool add_proto_name, void* data);
 325
 326 /* Look for a given string in a given dissector table and, if found, call
 327    the dissector with the arguments supplied, and return the number of
 328    bytes consumed, otherwise return 0. */
 329 WS_DEPRECATED_X("Use dissector_try_string_with_data instead")
 330 static inline int
 331 dissector_try_string(dissector_table_t sub_dissectors, const char* string,\
 332         tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree, void* data) \
 333         { return dissector_try_string_with_data(sub_dissectors, string, tvb, pinfo, tree, true, data); }
 334
 335 WS_DEPRECATED_X("Use dissector_try_string_with_data instead")
 336 static inline int
 337 dissector_try_string_new(dissector_table_t sub_dissectors, const char* string, \
 338         tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree, const bool add_proto_name, void* data) \
 339 { return dissector_try_string_with_data(sub_dissectors, string, tvb, pinfo, tree, add_proto_name, data); }
 340
 341
 342 /** Look for a given value in a given string dissector table and, if found,
 343  * return the current dissector handle for that value.
 344  *
 345  * @param[in] sub_dissectors Dissector table to search.
 346  * @param[in] string Value to match, e.g. the OID for the BER dissector.
 347  * @return The matching dissector handle on success, NULL if no match is found.
 348  */
 349 WS_DLL_PUBLIC dissector_handle_t dissector_get_string_handle(
 350     dissector_table_t sub_dissectors, const char *string);
 351
 352 /** Look for a given value in a given string dissector table and, if found,
 353  * return the default dissector handle for that value.
 354  *
 355  * @param[in] name Dissector table name.
 356  * @param[in] string Value to match, e.g. the OID for the BER dissector.
 357  * @return The matching dissector handle on success, NULL if no match is found.
 358  */
 359 WS_DLL_PUBLIC dissector_handle_t dissector_get_default_string_handle(
 360     const char *name, const char *string);
 361
 362 /* Add an entry to a "custom" dissector table. */
 363 WS_DLL_PUBLIC void dissector_add_custom_table_handle(const char *name, void *pattern,
 364     dissector_handle_t handle);
 365
 366 /** Look for a given key in a given "custom" dissector table and, if found,
 367  * return the current dissector handle for that key.
 368  *
 369  * @param[in] sub_dissectors Dissector table to search.
 370  * @param[in] key Value to match, e.g. RPC key for its subdissectors
 371  * @return The matching dissector handle on success, NULL if no match is found.
 372  */
 373 WS_DLL_PUBLIC dissector_handle_t dissector_get_custom_table_handle(
 374     dissector_table_t sub_dissectors, void *key);
 375 /* Key for GUID dissector tables.  This is based off of DCE/RPC needs
 376    so some dissector tables may not need the ver portion of the hash
 377  */
 378 typedef struct _guid_key {
 379     e_guid_t guid;
 380     uint16_t ver;
 381 } guid_key;
 382
 383 /* Add an entry to a guid dissector table. */
 384 WS_DLL_PUBLIC void dissector_add_guid(const char *name, guid_key* guid_val,
 385     dissector_handle_t handle);
 386
 387 /** Look for a given value in a given guid dissector table and, if found,
 388    call the dissector with the arguments supplied, and return true,
 389    otherwise return false. */
 390 WS_DLL_PUBLIC int dissector_try_guid_with_data(dissector_table_t sub_dissectors,
 391     guid_key* guid_val, tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, const bool add_proto_name, void *data);
 392
 393 /* Delete a GUID from a dissector table. */
 394 WS_DLL_PUBLIC void dissector_delete_guid(const char *name, guid_key* guid_val,
 395     dissector_handle_t handle);
 396
 397 /** Look for a given value in a given guid dissector table and, if found,
 398  * return the current dissector handle for that value.
 399  *
 400  * @param[in] sub_dissectors Dissector table to search.
 401  * @param[in] guid_val Value to match, e.g. the GUID number for the GUID dissector.
 402  * @return The matching dissector handle on success, NULL if no match is found.
 403  */
 404 WS_DLL_PUBLIC dissector_handle_t dissector_get_guid_handle(
 405     dissector_table_t const sub_dissectors, guid_key* guid_val);
 406
 407 /* Use the currently assigned payload dissector for the dissector table and,
 408    if any, call the dissector with the arguments supplied, and return the
 409    number of bytes consumed, otherwise return 0. */
 410 WS_DLL_PUBLIC int dissector_try_payload_with_data(dissector_table_t sub_dissectors,
 411     tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, const bool add_proto_name, void *data);
 412
 413 WS_DEPRECATED_X("Use dissector_try_payload_with_data instead")
 414 static inline int dissector_try_payload_new(dissector_table_t sub_dissectors,
 415         tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree, const bool add_proto_name, void* data){ \
 416         return dissector_try_payload_with_data(sub_dissectors, tvb, pinfo, tree, add_proto_name, data); \
 417 }
 418
 419 /* Use the currently assigned payload dissector for the dissector table and,
 420    if any, call the dissector with the arguments supplied, and return the
 421    number of bytes consumed, otherwise return 0. */
 422 WS_DEPRECATED_X("Use dissector_try_payload_with_data instead")
 423 static inline int dissector_try_payload(dissector_table_t sub_dissectors,
 424         tvbuff_t* tvb, packet_info* pinfo, proto_tree* tree) {
 425         \
 426         return dissector_try_payload_with_data(sub_dissectors, tvb, pinfo, tree, true, NULL); \
 427 }
 428
 429 /* Change the entry for a dissector in a payload (FT_NONE) dissector table
 430    with a particular pattern to use a new dissector handle. */
 431 WS_DLL_PUBLIC void dissector_change_payload(const char *abbrev, dissector_handle_t handle);
 432
 433 /* Reset payload (FT_NONE) dissector table to its initial value. */
 434 WS_DLL_PUBLIC void dissector_reset_payload(const char *name);
 435
 436 /* Given a payload dissector table (type FT_NONE), return the handle of
 437    the dissector that is currently active, i.e. that was selected via
 438    Decode As. */
 439 WS_DLL_PUBLIC dissector_handle_t dissector_get_payload_handle(
 440         dissector_table_t const dissector_table);
 441
 442 /* Add a handle to the list of handles that *could* be used with this
 443    table.  That list is used by the "Decode As"/"-d" code in the UI. */
 444 WS_DLL_PUBLIC void dissector_add_for_decode_as(const char *name,
 445     dissector_handle_t handle);
 446
 447 /* Same as dissector_add_for_decode_as, but adds preference for dissector table value */
 448 WS_DLL_PUBLIC void dissector_add_for_decode_as_with_preference(const char *name,
 449     dissector_handle_t handle);
 450
 451 /** Get the list of handles for a dissector table
 452  */
 453 WS_DLL_PUBLIC GSList *dissector_table_get_dissector_handles(dissector_table_t dissector_table);
 454
 455 /** Get a handle to dissector out of a dissector table given the description
 456  * of what the dissector dissects.
 457  */
 458 WS_DLL_PUBLIC dissector_handle_t dissector_table_get_dissector_handle(dissector_table_t dissector_table, const char* description);
 459
 460 /** Get a dissector table's type
 461  */
 462 WS_DLL_PUBLIC ftenum_t dissector_table_get_type(dissector_table_t dissector_table);
 463
 464 /** Mark a dissector table as allowing "Decode As"
 465  */
 466 WS_DLL_PUBLIC void dissector_table_allow_decode_as(dissector_table_t dissector_table);
 467
 468 /** Returns true if dissector table allows "Decode As"
 469  */
 470 WS_DLL_PUBLIC bool dissector_table_supports_decode_as(dissector_table_t dissector_table);
 471
 472 /* List of "heuristic" dissectors (which get handed a packet, look at it,
 473    and either recognize it as being for their protocol, dissect it, and
 474    return true, or don't recognize it and return false) to be called
 475    by another dissector.
 476
 477    This is opaque outside of "packet.c". */
 478 struct heur_dissector_list;
 479 typedef struct heur_dissector_list *heur_dissector_list_t;
 480
 481
 482 typedef struct heur_dtbl_entry {
 483         heur_dissector_t dissector;
 484         protocol_t *protocol; /* this entry's protocol */
 485         char *list_name;     /* the list name this entry is in the list of */
 486         const char *display_name;     /* the string used to present heuristic to user */
 487         char *short_name;     /* string used for "internal" use to uniquely identify heuristic */
 488         bool enabled;
 489         bool enabled_by_default;
 490 } heur_dtbl_entry_t;
 491
 492 /** A protocol uses this function to register a heuristic sub-dissector list.
 493  *  Call this in the parent dissectors proto_register function.
 494  *
 495  * @param name a unique short name for the list
 496  * @param ui_name the name used in the user interface
 497  * @param proto the value obtained when registering the protocol
 498  */
 499 WS_DLL_PUBLIC heur_dissector_list_t register_heur_dissector_list_with_description(const char *name, const char *ui_name, const int proto);
 500
 501 /** Get description of heuristic sub-dissector list.
 502  *
 503  * @param list the dissector list
 504  */
 505 WS_DLL_PUBLIC const char *heur_dissector_list_get_description(heur_dissector_list_t list);
 506
 507 /** A protocol uses this function to register a heuristic sub-dissector list.
 508  *  Call this in the parent dissectors proto_register function.
 509  *
 510  * @param name the name of this protocol
 511  * @param proto the value obtained when registering the protocol
 512  */
 513 WS_DLL_PUBLIC heur_dissector_list_t register_heur_dissector_list(const char *name, const int proto);
 514
 515 /** Deregister a heuristic dissector list by unique short name. */
 516 void deregister_heur_dissector_list(const char *name);
 517
 518 typedef void (*DATFunc_heur) (const char *table_name,
 519     struct heur_dtbl_entry *entry, void *user_data);
 520 typedef void (*DATFunc_heur_table) (const char *table_name,
 521     struct heur_dissector_list *table, void *user_data);
 522
 523 /** Iterate over heuristic dissectors in a table.
 524  *
 525  * Walk one heuristic dissector table's list calling a user supplied function
 526  * on each entry.
 527  *
 528  * @param[in] table_name The name of the dissector table, e.g. "tcp".
 529  * @param[in] func The function to call for each dissector.
 530  * @param[in] user_data User data to pass to the function.
 531  */
 532 WS_DLL_PUBLIC void heur_dissector_table_foreach(const char *table_name,
 533     DATFunc_heur func, void *user_data);
 534
 535 /** Iterate over all heuristic dissector tables.
 536  *
 537  * Walk the set of heuristic dissector tables calling a user supplied function
 538  * on each table.
 539  * @param[in] func The function to call for each table.
 540  * @param[in] user_data User data to pass to the function.
 541  * @param[in] compare_key_func Function used to sort the set of tables before
 542  * calling the function.  No sorting is done if NULL. */
 543 WS_DLL_PUBLIC void dissector_all_heur_tables_foreach_table (DATFunc_heur_table func,
 544     void *user_data, GCompareFunc compare_key_func);
 545
 546 /* true if a heur_dissector list of that name exists to be registered into */
 547 WS_DLL_PUBLIC bool has_heur_dissector_list(const char *name);
 548
 549 /** Try all the dissectors in a given heuristic dissector list. This is done,
 550  *  until we find one that recognizes the protocol.
 551  *  Call this while the parent dissector running.
 552  *
 553  * @param sub_dissectors the sub-dissector list
 554  * @param tvb the tvbuff with the (remaining) packet data
 555  * @param pinfo the packet info of this packet (additional info)
 556  * @param tree the protocol tree to be build or NULL
 557  * @param hdtbl_entry returns the last tried dissectors hdtbl_entry.
 558  * @param data parameter to pass to subdissector
 559  * @return true if the packet was recognized by the sub-dissector (stop dissection here)
 560  */
 561 WS_DLL_PUBLIC bool dissector_try_heuristic(heur_dissector_list_t sub_dissectors,
 562     tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, heur_dtbl_entry_t **hdtbl_entry, void *data);
 563
 564 /** Find a heuristic dissector table by table name.
 565  *
 566  * @param name name of the dissector table
 567  * @return pointer to the table on success, NULL if no such table exists
 568  */
 569 WS_DLL_PUBLIC heur_dissector_list_t find_heur_dissector_list(const char *name);
 570
 571 /** Find a heuristic dissector by the unique short protocol name provided during registration.
 572  *
 573  * @param short_name short name of the protocol to look at
 574  * @return pointer to the heuristic dissector entry, NULL if not such dissector exists
 575  */
 576 WS_DLL_PUBLIC heur_dtbl_entry_t* find_heur_dissector_by_unique_short_name(const char *short_name);
 577
 578 /** Add a sub-dissector to a heuristic dissector list.
 579  *  Call this in the proto_handoff function of the sub-dissector.
 580  *
 581  * @param name the name of the heuristic dissector table into which to register the dissector, e.g. "tcp"
 582  * @param dissector the sub-dissector to be registered
 583  * @param display_name the string used to present heuristic to user, e.g. "HTTP over TCP"
 584  * @param internal_name the string used for "internal" use to identify heuristic, e.g. "http_tcp"
 585  * @param proto the protocol id of the sub-dissector
 586  * @param enable initially enabled or not
 587  */
 588 WS_DLL_PUBLIC void heur_dissector_add(const char *name, heur_dissector_t dissector,
 589     const char *display_name, const char *internal_name, const int proto, heuristic_enable_e enable);
 590
 591 /** Remove a sub-dissector from a heuristic dissector list.
 592  *  Call this in the prefs_reinit function of the sub-dissector.
 593  *
 594  * @param name the name of the "parent" protocol, e.g. "tcp"
 595  * @param dissector the sub-dissector to be unregistered
 596  * @param proto the protocol id of the sub-dissector
 597  */
 598 WS_DLL_PUBLIC void heur_dissector_delete(const char *name, heur_dissector_t dissector, const int proto);
 599
 600 /** Register a new dissector. */
 601 WS_DLL_PUBLIC dissector_handle_t register_dissector(const char *name, dissector_t dissector, const int proto);
 602
 603 /** Register a new dissector with a description. */
 604 WS_DLL_PUBLIC dissector_handle_t register_dissector_with_description(const char *name, const char *description, dissector_t dissector, const int proto);
 605
 606 /** Register a new dissector with a callback pointer. */
 607 WS_DLL_PUBLIC dissector_handle_t register_dissector_with_data(const char *name, dissector_cb_t dissector, const int proto, void *cb_data);
 608
 609 /** Deregister a dissector. */
 610 void deregister_dissector(const char *name);
 611
 612 /** Get the long name of the protocol for a dissector handle. */
 613 WS_DLL_PUBLIC const char *dissector_handle_get_protocol_long_name(const dissector_handle_t handle);
 614
 615 /** Get the short name of the protocol for a dissector handle. */
 616 WS_DLL_PUBLIC const char *dissector_handle_get_protocol_short_name(const dissector_handle_t handle);
 617
 618 /* For backwards source and binary compatibility */
 619 G_DEPRECATED_FOR(dissector_handle_get_protocol_short_name)
 620 WS_DLL_PUBLIC const char *dissector_handle_get_short_name(const dissector_handle_t handle);
 621
 622 /** Get the description for what the dissector for a dissector handle dissects. */
 623 WS_DLL_PUBLIC const char *dissector_handle_get_description(const dissector_handle_t handle);
 624
 625 /** Get the index of the protocol for a dissector handle. */
 626 WS_DLL_PUBLIC int dissector_handle_get_protocol_index(const dissector_handle_t handle);
 627
 628 /** Get a GList of all registered dissector names. */
 629 WS_DLL_PUBLIC GList* get_dissector_names(void);
 630
 631 /** Find a dissector by name. */
 632 WS_DLL_PUBLIC dissector_handle_t find_dissector(const char *name);
 633
 634 /** Find a dissector by name and add parent protocol as a dependency. */
 635 WS_DLL_PUBLIC dissector_handle_t find_dissector_add_dependency(const char *name, const int parent_proto);
 636
 637 /** Get a dissector name from handle. */
 638 WS_DLL_PUBLIC const char *dissector_handle_get_dissector_name(const dissector_handle_t handle);
 639
 640 WS_DLL_PUBLIC const char *dissector_handle_get_pref_suffix(const dissector_handle_t handle);
 641
 642 /** Create an anonymous, unregistered dissector handle. Unregistered means that
 643  * other dissectors can't find the dissector through this API. The typical use
 644  * case is dissectors added to dissector tables that shouldn't be called by other
 645  * dissectors, perhaps if some data structure must be passed to the dissector.
 646  *
 647  * @param dissector The dissector the handle will call
 648  * @param proto The value obtained when registering the protocol
 649  *
 650  * @note The protocol short name will be used as the user-visible description.
 651  */
 652 WS_DLL_PUBLIC dissector_handle_t create_dissector_handle(dissector_t dissector,
 653     const int proto);
 654
 655 /** Create an named, unregistered dissector handle.
 656  * A non-NULL name is needed for dissector_add_for_decode_add_with_preference().
 657  *
 658  * @param dissector The dissector the handle will call
 659  * @param proto The value obtained when registering the protocol
 660  * @param name a short, machine-friendly name for the dissector. Does not have
 661  * to be globally unique, but should be unique for any table the handle will be
 662  * registered to. Can be NULL, which creates an anonymous dissector.
 663  *
 664  * @note The protocol short name will be used as the user-visible description.
 665  */
 666 WS_DLL_PUBLIC dissector_handle_t create_dissector_handle_with_name(dissector_t dissector,
 667     const int proto, const char* name);
 668
 669 /** Create an named, unregistered handle dissector handle with a description.
 670  * A non-NULL name is needed for dissector_add_for_decode_add_with_preference().
 671  * The description is used to allow a user to distinguish dissectors for the
 672  * same protocol, e.g. when registered to the same table.
 673  *
 674  * @param dissector The dissector the handle will call
 675  * @param proto The value obtained when registering the protocol
 676  * @param name a short, machine-friendly name for the dissector. Does not have
 677  * to be globally unique, but should be unique for any table the handle will be
 678  * registered to. Can be NULL, which creates an anonymous dissector.
 679  * @param description Freeform text designed to be shown to a user. Must be
 680  * unique for any table the dissector is registered in. Can be NULL, in which
 681  * case the protocol short name is used as the user-visible description.
 682  */
 683 WS_DLL_PUBLIC dissector_handle_t create_dissector_handle_with_name_and_description(dissector_t dissector,
 684     const int proto, const char* name, const char* description);
 685 WS_DLL_PUBLIC dissector_handle_t create_dissector_handle_with_data(dissector_cb_t dissector,
 686     const int proto, void* cb_data);
 687
 688 /* Dump all registered dissectors to the standard output */
 689 WS_DLL_PUBLIC void dissector_dump_dissectors(void);
 690
 691 /** Call a dissector through a handle and if no dissector was found
 692  * pass it over to the "data" dissector instead.
 693  *
 694  *   @param handle The dissector to call.
 695  *   @param  tvb The buffer to dissect.
 696  *   @param  pinfo Packet Info.
 697  *   @param  tree The protocol tree.
 698  *   @param  data parameter to pass to dissector
 699  *   @return  If the protocol for that handle isn't enabled call the data
 700  *   dissector. Otherwise, if the handle refers to a new-style
 701  *   dissector, call the dissector and return its return value, otherwise call
 702  *   it and return the length of the tvbuff pointed to by the argument.
 703  */
 704 WS_DLL_PUBLIC int call_dissector_with_data(dissector_handle_t handle, tvbuff_t *tvb,
 705     packet_info *pinfo, proto_tree *tree, void *data);
 706 WS_DLL_PUBLIC int call_dissector(dissector_handle_t handle, tvbuff_t *tvb,
 707     packet_info *pinfo, proto_tree *tree);
 708
 709 WS_DLL_PUBLIC int call_data_dissector(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
 710
 711 /** Call a dissector through a handle but if no dissector was found
 712  * just return 0 and do not call the "data" dissector instead.
 713  *
 714  *   @param handle The dissector to call.
 715  *   @param  tvb The buffer to dissect.
 716  *   @param  pinfo Packet Info.
 717  *   @param  tree The protocol tree.
 718  *   @param  data parameter to pass to dissector
 719  *   @return  If the protocol for that handle isn't enabled, return 0 without
 720  *   calling the dissector. Otherwise, if the handle refers to a new-style
 721  *   dissector, call the dissector and return its return value, otherwise call
 722  *   it and return the length of the tvbuff pointed to by the argument.
 723  */
 724 WS_DLL_PUBLIC int call_dissector_only(dissector_handle_t handle, tvbuff_t *tvb,
 725     packet_info *pinfo, proto_tree *tree, void *data);
 726
 727 /**
 728  *   @param heur_dtbl_entry The heur_dtbl_entry of the dissector to call.
 729  *   @param  tvb The buffer to dissect.
 730  *   @param  pinfo Packet Info.
 731  *   @param  tree The protocol tree.
 732  *   @param  data parameter to pass to dissector
 733  */
 734
 735 WS_DLL_PUBLIC void call_heur_dissector_direct(heur_dtbl_entry_t *heur_dtbl_entry, tvbuff_t *tvb,
 736     packet_info *pinfo, proto_tree *tree, void *data);
 737
 738 /* This is opaque outside of "packet.c". */
 739 struct depend_dissector_list;
 740 typedef struct depend_dissector_list *depend_dissector_list_t;
 741
 742 /** Register a protocol dependency
 743  * This is done automatically when registering with a dissector or
 744  * heuristic table.  This is for "manual" registration when a dissector
 745  * ends up calling another through call_dissector (or similar) so
 746  * dependencies can be determined
 747  *
 748  *   @param parent "Parent" protocol short name
 749  *   @param dependent "Dependent" protocol short name
 750  *   @return  return true if dependency was successfully registered
 751  */
 752 WS_DLL_PUBLIC bool register_depend_dissector(const char* parent, const char* dependent);
 753
 754 /** Unregister a protocol dependency
 755  * This is done automatically when removing from a dissector or
 756  * heuristic table.  This is for "manual" deregistration for things
 757  * like Lua.
 758  *
 759  *   @param parent "Parent" protocol short name
 760  *   @param dependent "Dependent" protocol short name
 761  *   @return  return true if dependency was successfully unregistered
 762  */
 763 WS_DLL_PUBLIC bool deregister_depend_dissector(const char* parent, const char* dependent);
 764
 765 /** Find the list of protocol dependencies
 766  *
 767  *   @param name Protocol short name to search for
 768  *   @return  return list of dependent was successfully registered
 769  */
 770 WS_DLL_PUBLIC depend_dissector_list_t find_depend_dissector_list(const char* name);
 771
 772
 773 /* Do all one-time initialization. */
 774 extern void dissect_init(void);
 775
 776 extern void dissect_cleanup(void);
 777
 778 /*
 779  * Given a tvbuff, and a length from a packet header, adjust the length
 780  * of the tvbuff to reflect the specified length.
 781  */
 782 WS_DLL_PUBLIC void set_actual_length(tvbuff_t *tvb, const unsigned specified_len);
 783
 784 /**
 785  * Allow protocols to register "init" routines, which are called before
 786  * we make a pass through a capture file and dissect all its packets
 787  * (e.g., when we read in a new capture file, or run a "filter packets"
 788  * or "colorize packets" pass over the current capture file or when the
 789  * preferences are changed).
 790  */
 791 WS_DLL_PUBLIC void register_init_routine(void (*func)(void));
 792
 793 /**
 794  * Allows protocols to register "cleanup" routines, which are called
 795  * after closing a capture file (or when preferences are changed, in
 796  * that case these routines are called before the init routines are
 797  * executed). It can be used to release resources that are allocated in
 798  * an "init" routine.
 799  */
 800 WS_DLL_PUBLIC void register_cleanup_routine(void (*func)(void));
 801
 802 /*
 803  * Allows protocols to register "shutdown" routines, which are called
 804  * once, just before program exit
 805  */
 806 WS_DLL_PUBLIC void register_shutdown_routine(void (*func)(void));
 807
 808 /* Initialize all data structures used for dissection. */
 809 void init_dissection(void);
 810
 811 /* Free data structures allocated for dissection. */
 812 void cleanup_dissection(void);
 813
 814 /* Allow protocols to register a "cleanup" routine to be
 815  * run after the initial sequential run through the packets.
 816  * Note that the file can still be open after this; this is not
 817  * the final cleanup. */
 818 WS_DLL_PUBLIC void register_postseq_cleanup_routine(void (*func)(void));
 819
 820 /* Call all the registered "postseq_cleanup" routines. */
 821 WS_DLL_PUBLIC void postseq_cleanup_all_protocols(void);
 822
 823 /* Allow dissectors to register a "final_registration" routine
 824  * that is run like the proto_register_XXX() routine, but the end
 825  * end of the epan_init() function; that is, *after* all other
 826  * subsystems, liked dfilters, have finished initializing. This is
 827  * useful for dissector registration routines which need to compile
 828  * display filters. dfilters can't initialize itself until all protocols
 829  * have registered themselves. */
 830 WS_DLL_PUBLIC void
 831 register_final_registration_routine(void (*func)(void));
 832
 833 /* Call all the registered "final_registration" routines. */
 834 extern void
 835 final_registration_all_protocols(void);
 836
 837 /*
 838  * Add a new data source to the list of data sources for a frame, given
 839  * the tvbuff for the data source and its name.
 840  */
 841 WS_DLL_PUBLIC void add_new_data_source(packet_info *pinfo, tvbuff_t *tvb,
 842     const char *name);
 843 /* Removes the last-added data source, if it turns out it wasn't needed */
 844 WS_DLL_PUBLIC void remove_last_data_source(packet_info *pinfo);
 845
 846 /*
 847  * Return the data source name, tvb.
 848  */
 849 struct data_source;
 850 WS_DLL_PUBLIC char *get_data_source_name(const struct data_source *src);
 851 WS_DLL_PUBLIC tvbuff_t *get_data_source_tvb(const struct data_source *src);
 852 WS_DLL_PUBLIC tvbuff_t *get_data_source_tvb_by_name(packet_info *pinfo, const char *name);
 853
 854 /*
 855  * Free up a frame's list of data sources.
 856  */
 857 extern void free_data_sources(packet_info *pinfo);
 858
 859 /* Mark another frame as depended upon by the current frame.
 860  *
 861  * This information is used to ensure that the depended-upon frame is saved
 862  * if the user does a File->Save-As of only the Displayed packets and the
 863  * current frame passed the display filter.
 864  */
 865 WS_DLL_PUBLIC void mark_frame_as_depended_upon(frame_data *fd, uint32_t frame_num);
 866
 867 /* Structure passed to the frame dissector */
 868 typedef struct frame_data_s
 869 {
 870     int file_type_subtype;
 871     wtap_block_t pkt_block;         /**< NULL if not available */
 872     struct epan_dissect *color_edt; /** Used strictly for "coloring rules" */
 873
 874 } frame_data_t;
 875
 876 /* Structure passed to the file dissector */
 877 typedef struct file_data_s
 878 {
 879     wtap_block_t pkt_block;         /**< NULL if not available */
 880     struct epan_dissect *color_edt; /** Used strictly for "coloring rules" */
 881
 882 } file_data_t;
 883
 884 /*
 885  * Dissectors should never modify the record data.
 886  */
 887 extern void dissect_record(struct epan_dissect *edt, int file_type_subtype,
 888     wtap_rec *rec, const uint8_t *data, frame_data *fd, column_info *cinfo);
 889
 890 /*
 891  * Dissectors should never modify the packet data.
 892  */
 893 extern void dissect_file(struct epan_dissect *edt,
 894     wtap_rec *rec, const uint8_t *data, frame_data *fd, column_info *cinfo);
 895
 896 /* Structure passed to the ethertype dissector */
 897 typedef struct ethertype_data_s
 898 {
 899     uint16_t etype;
 900     int payload_offset;
 901     proto_tree *fh_tree;
 902     int trailer_id;
 903     int fcs_len;
 904 } ethertype_data_t;
 905
 906 /*
 907  * Dump layer/selector/dissector records in a fashion similar to the
 908  * proto_registrar_dump_* routines.
 909  */
 910 WS_DLL_PUBLIC void dissector_dump_decodes(void);
 911
 912 /*
 913  * For each heuristic dissector table, dump list of dissectors (filter_names) for that table
 914  */
 915 WS_DLL_PUBLIC void dissector_dump_heur_decodes(void);
 916
 917 /*
 918  * postdissectors are to be called by packet-frame.c after every other
 919  * dissector has been called.
 920  */
 921
 922 /*
 923  * Register a postdissector; the argument is the dissector handle for it.
 924  */
 925 WS_DLL_PUBLIC void register_postdissector(dissector_handle_t handle);
 926
 927 /*
 928  * Specify a set of hfids that the postdissector will need.
 929  * The GArray is an array of hfids (type int) and should be NULL to clear the
 930  * list. This function will take ownership of the memory.
 931  */
 932 WS_DLL_PUBLIC void set_postdissector_wanted_hfids(dissector_handle_t handle,
 933     GArray *wanted_hfids);
 934
 935 /*
 936  * Deregister a postdissector.  Not for use in (post)dissectors or
 937  * applications; only to be used by libwireshark itself.
 938  */
 939 void deregister_postdissector(dissector_handle_t handle);
 940
 941 /*
 942  * Return true if we have at least one postdissector, false if not.
 943  * Not for use in (post)dissectors or applications; only to be used
 944  * by libwireshark itself.
 945  */
 946 extern bool have_postdissector(void);
 947
 948 /*
 949  * Call all postdissectors, handing them the supplied arguments.
 950  * Not for use in (post)dissectors or applications; only to be used
 951  * by libwireshark itself.
 952  */
 953 extern void call_all_postdissectors(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
 954
 955 /*
 956  * Return true if at least one postdissector needs at least one hfid,
 957  * false otherwise.
 958  */
 959 WS_DLL_PUBLIC bool postdissectors_want_hfids(void);
 960
 961 /*
 962  * Prime an epan_dissect_t with all the hfids wanted by postdissectors.
 963  */
 964 WS_DLL_PUBLIC void
 965 prime_epan_dissect_with_postdissector_wanted_hfids(epan_dissect_t *edt);
 966
 967 /** Increment the dissection depth.
 968  * This should be used to limit recursion outside the tree depth checks in
 969  * call_dissector and dissector_try_heuristic.
 970  * @param pinfo Packet Info.
 971  */
 972
 973 WS_DLL_PUBLIC void increment_dissection_depth(packet_info *pinfo);
 974
 975 /** Decrement the dissection depth.
 976  * @param pinfo Packet Info.
 977  */
 978
 979 WS_DLL_PUBLIC void decrement_dissection_depth(packet_info *pinfo);
 980
 981 /** @} */
 982
 983 #ifdef __cplusplus
 984 }
 985 #endif /* __cplusplus */
 986
 987 #endif /* packet.h */