| Wireshark 4.7.0 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
struct | _tap_reg

## 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

## 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)
void | register_all_tap_listeners (tap_reg_t const *tap_reg_listeners)
void | tap_init (void)
WS_DLL_PUBLIC int | register_tap (const char *name)
WS_DLL_PUBLIC GList * | get_tap_names (void)
WS_DLL_PUBLIC int | find_tap_id (const char *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)
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)
WS_DLL_PUBLIC void | draw_tap_listeners (bool draw_all)
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)
WS_DLL_PUBLIC void | tap_listeners_dfilter_recompile (void)
WS_DLL_PUBLIC void | remove_tap_listener (void *tapdata)
WS_DLL_PUBLIC GString * | set_tap_flags (void *tapdata, unsigned flags)
WS_DLL_PUBLIC bool | tap_listeners_require_dissection (void)
WS_DLL_PUBLIC bool | tap_listeners_require_columns (void)
WS_DLL_PUBLIC bool | have_tap_listener (int tap_id)
WS_DLL_PUBLIC bool | have_filtering_tap_listeners (void)
WS_DLL_PUBLIC void | tap_listeners_load_field_references (epan_dissect_t *edt)
WS_DLL_PUBLIC unsigned | union_of_tap_listener_flags (void)
WS_DLL_PUBLIC const void * | fetch_tapped_data (int tap_id, int idx)
void | tap_cleanup (void)
WS_DLL_PUBLIC void | tap_load_main_filter (struct epan_dfilter *dfcode)

## 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 | ) |

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.

## ◆ fetch_tapped_data()

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

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.

## ◆ find_tap_id()

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

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

## ◆ have_filtering_tap_listeners()

WS_DLL_PUBLIC bool have_filtering_tap_listeners | ( | void |  | ) |

Return true if we have any tap listeners with filters, false otherwise.

## ◆ have_tap_listener()

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

Returns true there is an active tap listener for the specified tap id.

## ◆ register_tap()

WS_DLL_PUBLIC int register_tap | ( | const char * | 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.

## ◆ 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 | ) |

this function removes a tap listener

## ◆ reset_tap_listeners()

WS_DLL_PUBLIC void reset_tap_listeners | ( | void |  | ) |

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
| ) |  |

This function sets a new dfilter to a tap listener

## ◆ set_tap_flags()

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

This function sets new flags to a tap listener

## ◆ tap_build_interesting()

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

Functions used by file.c to drive the tap subsystem

## ◆ tap_cleanup()

void tap_cleanup | ( | void |  | ) |
| extern

Clean internal structures

## ◆ tap_listeners_dfilter_recompile()

WS_DLL_PUBLIC void tap_listeners_dfilter_recompile | ( | void |  | ) |

This function recompiles dfilter for all registered tap listeners

## ◆ 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.

## ◆ tap_listeners_require_columns()

WS_DLL_PUBLIC bool tap_listeners_require_columns | ( | void |  | ) |

Return true if we have one or more tap listeners that require the columns, false otherwise.

## ◆ tap_listeners_require_dissection()

WS_DLL_PUBLIC bool tap_listeners_require_dissection | ( | void |  | ) |

Return true if we have one or more tap listeners that 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.

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ tap_register_plugin()

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

Register tap plugin with the plugin system.

## ◆ 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.