| Wireshark 4.7.3 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
tap.h File Reference
`#include <epan/epan.h>`
`#include <epan/packet_info.h>`
`#include "ws_symbol_export.h"`

Go to the source code of this file.

## Classes
struct | tap_plugin
| Describes a tap plugin, providing a callback to register its tap listener with the tap framework. More...
struct | _tap_reg
| Describes a single built-in tap registration entry, pairing a tap name with its registration callback. More...

## Macros
#define | TL_REQUIRES_NOTHING 0x00000000
#define | TL_REQUIRES_PROTO_TREE 0x00000001
#define | TL_REQUIRES_COLUMNS 0x00000002
#define | TL_REQUIRES_ERROR_PACKETS 0x00000004
#define | TL_REQUIRES_PROTOCOLS 0x00000020
#define | TL_IS_DISSECTOR_HELPER 0x00000008
#define | TL_IGNORE_DISPLAY_FILTER 0x00000010
#define | TL_DISPLAY_FILTER_IGNORED 0x00100000
#define | TL_LIMIT_TO_DISPLAY_FILTER 0x00000040
#define | TL_IP_AGGREGATION_NULL 0x00000100
#define | TL_IP_AGGREGATION_ORI 0x00000200
#define | TL_IP_AGGREGATION_RESERVED 0x00000400

## Typedefs
typedef unsigned | tap_flags_t
typedef void(* | tap_reset_cb) (void *tapdata)
typedef tap_packet_status(* | tap_packet_cb) (void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data, tap_flags_t flags)
typedef void(* | tap_draw_cb) (void *tapdata)
typedef void(* | tap_finish_cb) (void *tapdata)
typedef struct _tap_reg | tap_reg_t
| Describes a single built-in tap registration entry, pairing a tap name with its registration callback.

## Enumerations
enum | tap_packet_status { TAP_PACKET_DONT_REDRAW , TAP_PACKET_REDRAW , TAP_PACKET_FAILED }

## Functions
WS_DLL_PUBLIC void | tap_register_plugin (const tap_plugin *plug)
| Registers a packet tap plugin.
void | register_all_tap_listeners (tap_reg_t const *tap_reg_listeners)
| For all taps, call their register routines. Must be called after plugins_init(), if plugins are supported, and must be called only once in a program.
void | tap_init (void)
| Initializes the tap system.
WS_DLL_PUBLIC int | register_tap (const char *name)
| Registers a tap with the given name.
WS_DLL_PUBLIC GList * | get_tap_names (void)
| Returns a list of tap names.
WS_DLL_PUBLIC int | find_tap_id (const char *name)
| Finds the ID of a tap by its name.
WS_DLL_PUBLIC void | tap_queue_packet (int tap_id, packet_info *pinfo, const void *tap_specific_data)
WS_DLL_PUBLIC void | tap_build_interesting (epan_dissect_t *edt)
| Build a list of all interesting hf_fields for tap listeners.
void | tap_queue_init (epan_dissect_t *edt)
void | tap_push_tapped_queue (epan_dissect_t *edt)
WS_DLL_PUBLIC void | reset_tap_listeners (void)
| Resets all tap listeners.
WS_DLL_PUBLIC void | draw_tap_listeners (bool draw_all)
| Draws all tap listeners.
WS_DLL_PUBLIC GString * | register_tap_listener (const char *tapname, void *tapdata, const char *fstring, unsigned flags, tap_reset_cb tap_reset, tap_packet_cb tap_packet, tap_draw_cb tap_draw, tap_finish_cb tap_finish) G_GNUC_WARN_UNUSED_RESULT
WS_DLL_PUBLIC GString * | set_tap_dfilter (void *tapdata, const char *fstring)
| Set a display filter for a tap listener.
WS_DLL_PUBLIC void | tap_listeners_dfilter_recompile (void)
| Recompiles dfilter for all registered tap listeners.
WS_DLL_PUBLIC void | remove_tap_listener (void *tapdata)
| Removes a tap listener from the queue.
WS_DLL_PUBLIC GString * | set_tap_flags (void *tapdata, unsigned flags)
| Set flags for a tap listener.
WS_DLL_PUBLIC bool | tap_listeners_require_dissection (void)
| Check if any tap listeners require dissection.
WS_DLL_PUBLIC bool | tap_listeners_require_columns (void)
| Check if any tap listeners require column information.
WS_DLL_PUBLIC bool | have_tap_listener (int tap_id)
| Check if there is a tap listener with the given ID.
WS_DLL_PUBLIC bool | have_filtering_tap_listeners (void)
| Check if there are any tap listeners that require filtering.
WS_DLL_PUBLIC void | tap_listeners_load_field_references (epan_dissect_t *edt)
| If any tap listeners have a filter with references to the currently selected frame in the GUI (edt->tree), update them.
WS_DLL_PUBLIC unsigned | union_of_tap_listener_flags (void)
| Get the union of all the flags for all the tap listeners; that gives an indication of whether the protocol tree, or the columns, are required by any taps.
WS_DLL_PUBLIC const void * | fetch_tapped_data (int tap_id, int idx)
| Fetch tapped data before returning.
void | tap_cleanup (void)
| Clean internal structures.
WS_DLL_PUBLIC void | tap_load_main_filter (struct epan_dfilter *dfcode)
| Loads the main filter in the tapping system for taps that limit their results to the main display filter. Does not take ownership of the filter, which must still be freed in the main program.

## Detailed Description

packet tap interface 2002 Ronnie Sahlberg

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

## Macro Definition Documentation

## ◆ TL_DISPLAY_FILTER_IGNORED

#define TL_DISPLAY_FILTER_IGNORED 0x00100000

flag for the conversation handler

## ◆ TL_IGNORE_DISPLAY_FILTER

#define TL_IGNORE_DISPLAY_FILTER 0x00000010

Flags to indicate what the packet cb should do use packet, even if it would be filtered out

## ◆ TL_IP_AGGREGATION_NULL

#define TL_IP_AGGREGATION_NULL 0x00000100

Flags to indicate how the IP aggregation should behave during the statistics cb default analysis, no aggregation at all

## ◆ TL_IP_AGGREGATION_ORI

#define TL_IP_AGGREGATION_ORI 0x00000200

replace with subnets when possible, and keep original data

## ◆ TL_IP_AGGREGATION_RESERVED

#define TL_IP_AGGREGATION_RESERVED 0x00000400

reserved

## ◆ TL_IS_DISSECTOR_HELPER

#define TL_IS_DISSECTOR_HELPER 0x00000008

TL_REQUIRES_PROTO_TREE does not generate the full protocol tree; any fields not referenced (e.g., in a filter) will still be "faked." Note that if the tap does have a filter, it doesn't need TL_REQUIRES_PROTO_TREE because filtering implies needing a tree. It is for ensuring anything normally skipped with a NULL tree won't be, which may include constructing data to pass to the tap. To make all fields visible (which impacts performance), epan_set_always_visible() can be used at the same time as registering the tap. XXX - There should probably be a flag to set the tree visible. Flags to indicate what the tap listener does tap helps a dissector do work but does not, itself, require dissection

## ◆ TL_LIMIT_TO_DISPLAY_FILTER

#define TL_LIMIT_TO_DISPLAY_FILTER 0x00000040

limit to the main display filter, and retap if it changes.

## ◆ TL_REQUIRES_COLUMNS

#define TL_REQUIRES_COLUMNS 0x00000002

columns

## ◆ TL_REQUIRES_ERROR_PACKETS

#define TL_REQUIRES_ERROR_PACKETS 0x00000004

include packet even if pinfo->flags.in_error_pkt is set

## ◆ TL_REQUIRES_NOTHING

#define TL_REQUIRES_NOTHING 0x00000000

Flags to indicate what a tap listener's packet routine requires. nothing

## ◆ TL_REQUIRES_PROTO_TREE

#define TL_REQUIRES_PROTO_TREE 0x00000001

non-NULL protocol tree

## ◆ TL_REQUIRES_PROTOCOLS

#define TL_REQUIRES_PROTOCOLS 0x00000020

don't fake protocols

## Enumeration Type Documentation

## ◆ tap_packet_status

enum tap_packet_status

Status returned by the per-packet callback.

Enumerator
TAP_PACKET_DONT_REDRAW | Packet processing succeeded, no need to redraw
TAP_PACKET_REDRAW | Packet processing succeeded, must redraw
TAP_PACKET_FAILED | Packet processing failed, stop calling this tap

## Function Documentation

## ◆ draw_tap_listeners()

WS_DLL_PUBLIC void draw_tap_listeners | ( | bool | draw_all | ) |

Draws all tap listeners.

This function is called when we need to redraw all tap listeners, for example when we open/start a new capture or if we need to rescan the packet list. It should be called from a low priority thread say once every 3 seconds

If draw_all is true, redraw all applications regardless if they have changed or not.

Parameters

  draw_all | If true, redraw all tap listeners regardless of their state; if false, only redraw those that need it.

## ◆ fetch_tapped_data()

WS_DLL_PUBLIC const void * fetch_tapped_data | ( | int | tap_id,
|  | int | idx )

Fetch tapped data before returning.

This function can be used by a dissector to fetch any tapped data before returning. This can be useful if one wants to extract the data inside dissector BEFORE it exists as an alternative to the callbacks that are all called AFTER the dissection has completed.

Example: SMB2 uses this mechanism to extract the data tapped from NTLMSSP containing the account and domain names before exiting. Note that the SMB2 tap listener specifies all three callbacks as NULL.

Beware: when using this mechanism to extract the tapped data you can not use "filters" and should specify the "filter" as NULL when registering the tap listener.

Parameters

  tap_id | The ID of the tap to fetch data from.
  idx | The index of the tapped data to fetch.

Returns
  A pointer to the tapped data, or NULL if not found or if tapping is not active.

## ◆ find_tap_id()

WS_DLL_PUBLIC int find_tap_id | ( | const char * | name | ) |

Finds the ID of a tap by its name.

This function will return the tap_id for the specific protocol tap or 0 if no such tap was found.

Parameters

  name | The name of the tap to find.

Returns
  The tap_id of the tap with the given name, or 0 if not found.

## ◆ get_tap_names()

WS_DLL_PUBLIC GList * get_tap_names | ( | void |  | ) |

Returns a list of tap names.

This function returns a GList containing the names of all available taps.

Returns
  A GList of tap names, or NULL if no taps are available.

## ◆ have_filtering_tap_listeners()

WS_DLL_PUBLIC bool have_filtering_tap_listeners | ( | void |  | ) |

Check if there are any tap listeners that require filtering.

Returns
  true if there is at least one tap listener with a filter, false otherwise.

## ◆ have_tap_listener()

WS_DLL_PUBLIC bool have_tap_listener | ( | int | tap_id | ) |

Check if there is a tap listener with the given ID.

Parameters

  tap_id | The ID of the tap listener to check for.

Returns
  true if a tap listener with the given ID exists, false otherwise.

## ◆ register_all_tap_listeners()

void register_all_tap_listeners | ( | tap_reg_t const * | tap_reg_listeners | ) |
| extern

For all taps, call their register routines. Must be called after plugins_init(), if plugins are supported, and must be called only once in a program.

Parameters

  tap_reg_listeners | Array of tap_reg_t structures for built-in taps, terminated by an entry with cb_func == NULL.

## ◆ register_tap()

WS_DLL_PUBLIC int register_tap | ( | const char * | name | ) |

Registers a tap with the given name.

This function registers that a dissector has the packet tap ability available. The name parameter is the name of this tap and extensions can use open_tap(char *name,... to specify that it wants to receive packets/ events from this tap.

This function is only to be called once, when the dissector initializes.

The return value from this call is later used as a parameter to the tap_packet(unsigned int *tap_id,... call so that the tap subsystem knows to which tap point this tapped packet is associated.

Parameters

  name | The name of the tap to register.

Returns
  The ID of the registered tap, or 0 on failure.

## ◆ register_tap_listener()

WS_DLL_PUBLIC GString * register_tap_listener | ( | const char * | tapname,
|  | void * | tapdata,
|  | const char * | fstring,
|  | unsigned | flags,
|  | tap_reset_cb | tap_reset,
|  | tap_packet_cb | tap_packet,
|  | tap_draw_cb | tap_draw,
|  | tap_finish_cb | tap_finish )

this function attaches the tap_listener to the named tap. function returns : NULL: ok. non-NULL: error, return value points to GString containing error message.

Parameters

  tapname | The name of the tap we want to listen to.
  tapdata | is the instance identifier. The tap system uses the value of this pointer to distinguish between different instances of a tap. Just make sure that it is unique by letting it be the pointer to a struct holding all state variables. If you want to allow multiple concurrent instances, just put ALL state variables inside a struct allocated by g_malloc() and use that pointer.
  fstring | is a pointer to a filter string. If this is NULL, then the tap system will provide ALL packets passing the tapped protocol to your listener. If you specify a filter string here the tap system will first try to apply this string to the packet and then only pass those packets that matched the filter to your listener. The syntax for the filter string is identical to normal display filters.

NOTE: Specifying filter strings will have a significant performance impact on your application and Wireshark. If possible it is MUCH better to take unfiltered data and just filter it yourself in the packet-callback than to specify a filter string. ONLY use a filter string if no other option exist.

Parameters

  flags | is a set of flags for the tap listener. The flags that can be set are:
                       TL_REQUIRES_PROTO_TREE

                      set if your tap listener "packet" routine requires a protocol
                      tree to be built.  It will require a protocol tree to be
                      built if either

                          1) it looks at the protocol tree in edt->tree

                      or

                          2) the tap-specific data passed to it is constructed only if
                             the protocol tree is being built.

                       TL_REQUIRES_COLUMNS

                      set if your tap listener "packet" routine requires the column
                      strings to be constructed.

                        If no flags are needed, use TL_REQUIRES_NOTHING.
  tap_reset | void (*reset)(void *tapdata) This callback is called whenever Wireshark wants to inform your listener that it is about to start [re]reading a capture file or a new capture from an interface and that your application should reset any state it has in the *tapdata instance.
  tap_packet | tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data) This callback is used whenever a new packet has arrived at the tap and that it has passed the filter (if there were a filter). The *data structure type is specific to each tap. This function returns an bool and it should return true, if the data in the packet caused state to be updated (and thus a redraw of the window would later be required) false, if we don't need to redraw the window. NOTE: that (*packet) should be as fast and efficient as possible. Use this function ONLY to store data for later and do the CPU-intensive processing or GUI updates down in (*draw) instead.
  tap_draw | void (*draw)(void *tapdata) This callback is used when Wireshark wants your application to redraw its output. It will usually not be called unless your application has received new data through the (*packet) callback. On some ports of Wireshark (gtk2) (*draw) will be called asynchronously from a separate thread up to once every 2-3 seconds. On other ports it might only be called once when the capture is finished or the file has been [re]read completely.
  tap_finish | void (*finish)(void *tapdata) This callback is called when your listener is removed.

## ◆ remove_tap_listener()

WS_DLL_PUBLIC void remove_tap_listener | ( | void * | tapdata | ) |

Removes a tap listener from the queue.

Parameters

  tapdata | Pointer to the tap data associated with the listener to be removed.

## ◆ reset_tap_listeners()

WS_DLL_PUBLIC void reset_tap_listeners | ( | void |  | ) |

Resets all tap listeners.

This function is called after a packet has been fully dissected to push the tapped data to all extensions that has callbacks registered.

## ◆ set_tap_dfilter()

WS_DLL_PUBLIC GString * set_tap_dfilter | ( | void * | tapdata,
|  | const char * | fstring )

Set a display filter for a tap listener.

This function sets a display filter for a tap listener using the provided filter string.

Parameters

  tapdata | Pointer to the tap data structure.
  fstring | The display filter string.

Returns
  A GString containing an error message if the filter is invalid, or NULL on success.

## ◆ set_tap_flags()

WS_DLL_PUBLIC GString * set_tap_flags | ( | void * | tapdata,
|  | unsigned | flags )

Set flags for a tap listener.

This function sets the flags for a tap listener identified by the provided tapdata pointer. It returns NULL if the operation is successful, or an error message if it fails.

Parameters

  tapdata | Pointer to the tap data structure.
  flags | Flags to be set for the tap listener.

Returns
  NULL on success, error message on failure.

## ◆ tap_build_interesting()

WS_DLL_PUBLIC void tap_build_interesting | ( | epan_dissect_t * | edt | ) |

Build a list of all interesting hf_fields for tap listeners.

Functions used by file.c to drive the tap subsystem

Loop over all tap listeners and build the list of all interesting hf_fields.

Parameters

  edt | The epan_dissect_t structure containing the dissection data.

## ◆ tap_init()

void tap_init | ( | void |  | ) |
| extern

Initializes the tap system.

This function initializes the tap system and should be called once when the dissector is initialized.

## ◆ tap_listeners_dfilter_recompile()

WS_DLL_PUBLIC void tap_listeners_dfilter_recompile | ( | void |  | ) |

Recompiles dfilter for all registered tap listeners.

This function iterates through all registered tap listeners and recompiles their dfilters. If a listener's filter string is invalid, it sets up a dfilter that matches no packets.

## ◆ tap_listeners_load_field_references()

WS_DLL_PUBLIC void tap_listeners_load_field_references | ( | epan_dissect_t * | edt | ) |

If any tap listeners have a filter with references to the currently selected frame in the GUI (edt->tree), update them.

Parameters

  edt | The epan_dissect_t structure containing the dissection data for the current packet.

## ◆ tap_listeners_require_columns()

WS_DLL_PUBLIC bool tap_listeners_require_columns | ( | void |  | ) |

Check if any tap listeners require column information.

Returns
  true if any tap listeners require column information, false otherwise.

## ◆ tap_listeners_require_dissection()

WS_DLL_PUBLIC bool tap_listeners_require_dissection | ( | void |  | ) |

Check if any tap listeners require dissection.

Returns
  true if any tap listeners require dissection, false otherwise.

## ◆ tap_load_main_filter()

WS_DLL_PUBLIC void tap_load_main_filter | ( | struct epan_dfilter * | dfcode | ) |

Loads the main filter in the tapping system for taps that limit their results to the main display filter. Does not take ownership of the filter, which must still be freed in the main program.

Parameters

  dfcode | The main display filter to load into the tapping system.

## ◆ tap_push_tapped_queue()

void tap_push_tapped_queue | ( | epan_dissect_t * | edt | ) |
| extern

this function is called after a packet has been fully dissected to push the tapped data to all extensions that has callbacks registered.

Parameters

  edt | The epan_dissect_t structure containing the dissection data for the current packet.

## ◆ tap_queue_init()

void tap_queue_init | ( | epan_dissect_t * | edt | ) |
| extern

This function is used to delete/initialize the tap queue and prime an epan_dissect_t with all the filters for tap listeners. To free the tap queue, we just prepend the used queue to the free queue.

Parameters

  edt | The epan_dissect_t structure to prime with tap listener filters.

## ◆ tap_queue_packet()

WS_DLL_PUBLIC void tap_queue_packet | ( | int | tap_id,
|  | packet_info * | pinfo,
|  | const void * | tap_specific_data )

Every time the dissector has finished dissecting a packet (and all subdissectors have returned) and if the dissector has been made "tappable" it will push some data to everyone tapping this layer by a call to tap_queue_packet(). The first parameter is the tap_id returned by the register_tap() call for this dissector (so the tap system can keep track of who it came from and who is listening to it) The second is the packet_info structure which many tap readers will find interesting. The third argument is specific to each tap point or NULL if no additional data is available to this tap. A tap point in say IP will probably want to push the IP header structure here. Same thing for TCP and ONCRPC.

The pinfo and the specific pointer are what is supplied to every listener in the read_callback() call made to every one currently listening to this tap.

The tap reader is responsible to know how to parse any structure pointed to by the tap specific data pointer.

Parameters

  tap_id | The ID of the tap to which this packet belongs.
  pinfo | Pointer to the packet information structure for the current packet.
  tap_specific_data | Pointer to tap-specific data, or NULL if not applicable.

## ◆ tap_register_plugin()

WS_DLL_PUBLIC void tap_register_plugin | ( | const tap_plugin * | plug | ) |

Registers a packet tap plugin.

Register tap plugin with the plugin system.

Registers a new packet tap plugin with Wireshark.

Parameters

  plug | Pointer to the tap_plugin structure containing plugin information.

## ◆ union_of_tap_listener_flags()

WS_DLL_PUBLIC unsigned union_of_tap_listener_flags | ( | void |  | ) |

Get the union of all the flags for all the tap listeners; that gives an indication of whether the protocol tree, or the columns, are required by any taps.

Returns
  The union of all the flags for all the tap listeners.