2002-09-04 09:40:29 +00:00
|
|
|
/* tap.h
|
|
|
|
* packet tap interface 2002 Ronnie Sahlberg
|
|
|
|
*
|
2006-05-21 05:12:17 +00:00
|
|
|
* Wireshark - Network traffic analyzer
|
|
|
|
* By Gerald Combs <gerald@wireshark.org>
|
2002-09-04 09:40:29 +00:00
|
|
|
* Copyright 1998 Gerald Combs
|
2011-05-12 03:18:34 +00:00
|
|
|
*
|
2002-09-04 09:40:29 +00:00
|
|
|
* This program is free software; you can redistribute it and/or
|
|
|
|
* modify it under the terms of the GNU General Public License
|
|
|
|
* as published by the Free Software Foundation; either version 2
|
|
|
|
* of the License, or (at your option) any later version.
|
2011-05-12 03:18:34 +00:00
|
|
|
*
|
2002-09-04 09:40:29 +00:00
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU General Public License for more details.
|
2011-05-12 03:18:34 +00:00
|
|
|
*
|
2002-09-04 09:40:29 +00:00
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
* along with this program; if not, write to the Free Software
|
2012-06-28 22:56:06 +00:00
|
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
2002-09-04 09:40:29 +00:00
|
|
|
*/
|
|
|
|
|
2012-10-18 21:14:43 +00:00
|
|
|
#ifndef __TAP_H__
|
|
|
|
#define __TAP_H__
|
2003-02-05 20:45:38 +00:00
|
|
|
|
2009-08-21 20:51:13 +00:00
|
|
|
#include <epan/epan.h>
|
2013-03-01 23:53:11 +00:00
|
|
|
#include "ws_symbol_export.h"
|
2002-10-17 02:11:20 +00:00
|
|
|
|
2012-10-18 21:14:43 +00:00
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif /* __cplusplus */
|
|
|
|
|
2002-10-31 22:16:01 +00:00
|
|
|
typedef void (*tap_reset_cb)(void *tapdata);
|
2009-06-05 22:42:47 +00:00
|
|
|
typedef gboolean (*tap_packet_cb)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data);
|
2002-10-31 22:16:01 +00:00
|
|
|
typedef void (*tap_draw_cb)(void *tapdata);
|
|
|
|
|
2013-05-03 17:33:13 +00:00
|
|
|
/**
|
2009-06-05 22:42:47 +00:00
|
|
|
* Flags to indicate what a tap listener's packet routine requires.
|
|
|
|
*/
|
2011-04-05 20:21:59 +00:00
|
|
|
#define TL_REQUIRES_NOTHING 0x00000000 /**< nothing */
|
|
|
|
#define TL_REQUIRES_PROTO_TREE 0x00000001 /**< full protocol tree */
|
|
|
|
#define TL_REQUIRES_COLUMNS 0x00000002 /**< columns */
|
2013-05-03 17:33:13 +00:00
|
|
|
/** Flags to indicate what the tap listener does */
|
|
|
|
#define TL_IS_DISSECTOR_HELPER 0x00000004 /**< tap helps a dissector do work
|
2011-05-12 03:18:34 +00:00
|
|
|
** but does not, itself, require dissection */
|
2002-10-31 22:16:01 +00:00
|
|
|
|
2013-12-10 19:13:09 +00:00
|
|
|
#ifdef HAVE_PLUGINS
|
2013-12-02 08:30:29 +00:00
|
|
|
/** Register tap plugin type with the plugin system.
|
|
|
|
Called by epan_register_plugin_types(); do not call it yourself. */
|
|
|
|
extern void register_tap_plugin_type(void);
|
2013-12-10 19:13:09 +00:00
|
|
|
#endif
|
2013-12-02 08:30:29 +00:00
|
|
|
|
|
|
|
/*
|
|
|
|
* For all tap plugins, call their register routines.
|
|
|
|
* Must be called after init_plugins(), and must be called only once in
|
|
|
|
* a program.
|
|
|
|
*
|
|
|
|
* XXX - should probably be handled by epan_init(), as the tap mechanism
|
|
|
|
* is part of libwireshark.
|
|
|
|
*/
|
|
|
|
WS_DLL_PUBLIC void register_all_plugin_tap_listeners(void);
|
|
|
|
|
2003-03-06 19:04:28 +00:00
|
|
|
extern void tap_init(void);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** 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.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC int register_tap(const char *name);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
2014-02-18 15:03:04 +00:00
|
|
|
/* Gets a GList of the tap names */
|
2014-02-25 21:44:29 +00:00
|
|
|
WS_DLL_PUBLIC GList* get_tap_names(void);
|
2014-02-18 15:03:04 +00:00
|
|
|
|
2013-05-03 17:33:13 +00:00
|
|
|
/** This function will return the tap_id for the specific protocol tap
|
|
|
|
* or 0 if no such tap was found.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC int find_tap_id(const char *name);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** Everytime 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.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC void tap_queue_packet(int tap_id, packet_info *pinfo, const void *tap_specific_data);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** Functions used by file.c to drive the tap subsystem */
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC void tap_build_interesting(epan_dissect_t *edt);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** 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.
|
|
|
|
*/
|
2003-03-06 19:04:28 +00:00
|
|
|
extern void tap_queue_init(epan_dissect_t *edt);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** this function is called after a packet has been fully dissected to push the tapped
|
|
|
|
* data to all extensions that has callbacks registered.
|
|
|
|
*/
|
|
|
|
|
2003-03-06 19:04:28 +00:00
|
|
|
extern void tap_push_tapped_queue(epan_dissect_t *edt);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** This function is called after a packet has been fully dissected to push the tapped
|
|
|
|
* data to all extensions that has callbacks registered.
|
|
|
|
*/
|
|
|
|
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC void reset_tap_listeners(void);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** 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.
|
2013-12-10 20:23:33 +00:00
|
|
|
* It should be called from a low priority thread say once every 3 seconds
|
2013-05-03 17:33:13 +00:00
|
|
|
*
|
|
|
|
* If draw_all is true, redraw all aplications regardless if they have
|
|
|
|
* changed or not.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC void draw_tap_listeners(gboolean draw_all);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** 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.
|
|
|
|
* @param tapname The name of the tap we want to listen to.
|
|
|
|
* @param 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.
|
|
|
|
* @param 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.
|
2013-12-10 20:23:33 +00:00
|
|
|
*
|
2013-05-03 17:33:13 +00:00
|
|
|
* 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.
|
|
|
|
*
|
|
|
|
* @param flags is a set of flags for the tap listener. The flags that can be set are:
|
|
|
|
*
|
|
|
|
* TL_REQUIRES_PROTO_TREE
|
2013-12-10 20:23:33 +00:00
|
|
|
*
|
2013-05-03 17:33:13 +00:00
|
|
|
* 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
|
2013-12-10 20:23:33 +00:00
|
|
|
*
|
2013-05-03 17:33:13 +00:00
|
|
|
* 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.
|
2013-12-10 20:23:33 +00:00
|
|
|
*
|
2013-05-03 17:33:13 +00:00
|
|
|
* @param 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.
|
|
|
|
* @param tap_packet gboolean (*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 gboolean 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.
|
|
|
|
* @param 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.
|
|
|
|
*/
|
|
|
|
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC GString *register_tap_listener(const char *tapname, void *tapdata,
|
2009-06-05 22:42:47 +00:00
|
|
|
const char *fstring, guint flags, tap_reset_cb tap_reset,
|
|
|
|
tap_packet_cb tap_packet, tap_draw_cb tap_draw);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** This function sets a new dfilter to a tap listener */
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC GString *set_tap_dfilter(void *tapdata, const char *fstring);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** this function removes a tap listener */
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC void remove_tap_listener(void *tapdata);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return TRUE if we have one or more tap listeners that require dissection,
|
|
|
|
* FALSE otherwise.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC gboolean tap_listeners_require_dissection(void);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** Returns TRUE there is an active tap listener for the specified tap id. */
|
2014-01-08 15:58:49 +00:00
|
|
|
WS_DLL_PUBLIC gboolean have_tap_listener(int tap_id);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** Return TRUE if we have any tap listeners with filters, FALSE otherwise. */
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC gboolean have_filtering_tap_listeners(void);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC guint union_of_tap_listener_flags(void);
|
2013-05-03 17:33:13 +00:00
|
|
|
|
|
|
|
/** 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.
|
|
|
|
*/
|
2013-03-01 23:53:11 +00:00
|
|
|
WS_DLL_PUBLIC const void *fetch_tapped_data(int tap_id, int idx);
|
2002-09-04 09:40:29 +00:00
|
|
|
|
2012-10-18 21:14:43 +00:00
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
|
|
#endif /* __TAP_H__ */
|