epan/tap.h

   1 /* tap.h
   2  * packet tap interface   2002 Ronnie Sahlberg
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation; either version 2
  11  * of the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21  */
  22
  23 #ifndef __TAP_H__
  24 #define __TAP_H__
  25
  26 #include <epan/epan.h>
  27 #include <epan/packet_info.h>
  28 #include "ws_symbol_export.h"
  29 #ifdef HAVE_PLUGINS
  30 #include "wsutil/plugins.h"
  31 #endif
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif /* __cplusplus */
  36
  37 typedef void (*tap_reset_cb)(void *tapdata);
  38 typedef gboolean (*tap_packet_cb)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data);
  39 typedef void (*tap_draw_cb)(void *tapdata);
  40
  41 /**
  42  * Flags to indicate what a tap listener's packet routine requires.
  43  */
  44 #define TL_REQUIRES_NOTHING     0x00000000              /**< nothing */
  45 #define TL_REQUIRES_PROTO_TREE  0x00000001          /**< full protocol tree */
  46 #define TL_REQUIRES_COLUMNS     0x00000002              /**< columns */
  47 #define TL_REQUIRES_ERROR_PACKETS       0x00000004      /**< include packet even if pinfo->flags.in_error_pkt is set */
  48 /** Flags to indicate what the tap listener does */
  49 #define TL_IS_DISSECTOR_HELPER  0x00000008          /**< tap helps a dissector do work
  50                                                                          ** but does not, itself, require dissection */
  51
  52 #ifdef HAVE_PLUGINS
  53 typedef struct {
  54         void (*register_tap_listener)(void);   /* routine to call to register tap listener */
  55 } tap_plugin;
  56
  57 /** Register tap plugin with the plugin system. */
  58 WS_DLL_PUBLIC void tap_register_plugin(const tap_plugin *plug);
  59 #endif
  60
  61 /*
  62  * For all tap plugins, call their register routines.
  63  * Must be called after plugins_init(), and must be called only once in
  64  * a program.
  65  *
  66  * XXX - should probably be handled by epan_init(), as the tap mechanism
  67  * is part of libwireshark.
  68  */
  69 WS_DLL_PUBLIC void register_all_plugin_tap_listeners(void);
  70
  71 extern void tap_init(void);
  72
  73 /** This function registers that a dissector has the packet tap ability
  74  *  available.  The name parameter is the name of this tap and extensions can
  75  *  use open_tap(char *name,... to specify that it wants to receive packets/
  76  *  events from this tap.
  77  *
  78  *  This function is only to be called once, when the dissector initializes.
  79  *
  80  *  The return value from this call is later used as a parameter to the
  81  *  tap_packet(unsigned int *tap_id,...
  82  *  call so that the tap subsystem knows to which tap point this tapped
  83  *  packet is associated.
  84  */
  85 WS_DLL_PUBLIC int register_tap(const char *name);
  86
  87 /* Gets a GList of the tap names */
  88 WS_DLL_PUBLIC GList* get_tap_names(void);
  89
  90 /** This function will return the tap_id for the specific protocol tap
  91  *  or 0 if no such tap was found.
  92  */
  93 WS_DLL_PUBLIC int find_tap_id(const char *name);
  94
  95 /** Everytime the dissector has finished dissecting a packet (and all
  96  *  subdissectors have returned) and if the dissector has been made "tappable"
  97  *  it will push some data to everyone tapping this layer by a call
  98  *  to tap_queue_packet().
  99  *  The first parameter is the tap_id returned by the register_tap()
 100  *  call for this dissector (so the tap system can keep track of who it came
 101  *  from and who is listening to it)
 102  *  The second is the packet_info structure which many tap readers will find
 103  *  interesting.
 104  *  The third argument is specific to each tap point or NULL if no additional
 105  *  data is available to this tap.  A tap point in say IP will probably want to
 106  *  push the IP header structure here. Same thing for TCP and ONCRPC.
 107  *
 108  *  The pinfo and the specific pointer are what is supplied to every listener
 109  *  in the read_callback() call made to every one currently listening to this
 110  *  tap.
 111  *
 112  *  The tap reader is responsible to know how to parse any structure pointed
 113  *  to by the tap specific data pointer.
 114  */
 115 WS_DLL_PUBLIC void tap_queue_packet(int tap_id, packet_info *pinfo, const void *tap_specific_data);
 116
 117 /** Functions used by file.c to drive the tap subsystem */
 118 WS_DLL_PUBLIC void tap_build_interesting(epan_dissect_t *edt);
 119
 120 /** This function is used to delete/initialize the tap queue and prime an
 121  *  epan_dissect_t with all the filters for tap listeners.
 122  *  To free the tap queue, we just prepend the used queue to the free queue.
 123  */
 124 extern void tap_queue_init(epan_dissect_t *edt);
 125
 126 /** this function is called after a packet has been fully dissected to push the tapped
 127  *  data to all extensions that has callbacks registered.
 128  */
 129
 130 extern void tap_push_tapped_queue(epan_dissect_t *edt);
 131
 132 /** This function is called after a packet has been fully dissected to push the tapped
 133  *  data to all extensions that has callbacks registered.
 134  */
 135
 136 WS_DLL_PUBLIC void reset_tap_listeners(void);
 137
 138 /** This function is called when we need to redraw all tap listeners, for example
 139  * when we open/start a new capture or if we need to rescan the packet list.
 140  * It should be called from a low priority thread say once every 3 seconds
 141  *
 142  * If draw_all is true, redraw all aplications regardless if they have
 143  * changed or not.
 144  */
 145 WS_DLL_PUBLIC void draw_tap_listeners(gboolean draw_all);
 146
 147 /** this function attaches the tap_listener to the named tap.
 148  * function returns :
 149  *     NULL: ok.
 150  * non-NULL: error, return value points to GString containing error
 151  *           message.
 152  * @param tapname    The name of the tap we want to listen to.
 153  * @param tapdata    is the instance identifier. The tap system uses the value of this
 154  *                   pointer to distinguish between different instances of a tap.
 155  *                   Just make sure that it is unique by letting it be the pointer to a struct
 156  *                   holding all state variables. If you want to allow multiple concurrent
 157  *                   instances, just put ALL state variables inside a struct allocated by
 158  *                   g_malloc() and use that pointer.
 159  * @param fstring    is a pointer to a filter string.
 160  *                   If this is NULL, then the tap system will provide ALL packets passing the
 161  *                   tapped protocol to your listener.
 162  *                   If you specify a filter string here the tap system will first try
 163  *                   to apply this string to the packet and then only pass those packets that
 164  *                   matched the filter to your listener.
 165  *                   The syntax for the filter string is identical to normal display filters.
 166  *
 167  *                   NOTE: Specifying filter strings will have a significant performance impact
 168  *                   on your application and Wireshark. If possible it is MUCH better to take
 169  *                   unfiltered data and just filter it yourself in the packet-callback than
 170  *                   to specify a filter string.
 171  *                   ONLY use a filter string if no other option exist.
 172  *
 173  * @param flags      is a set of flags for the tap listener.  The flags that can be set are:
 174  *
 175  *                      TL_REQUIRES_PROTO_TREE
 176  *
 177  *                      set if your tap listener "packet" routine requires a protocol
 178  *                      tree to be built.  It will require a protocol tree to be
 179  *                      built if either
 180  *
 181  *                              1) it looks at the protocol tree in edt->tree
 182  *
 183  *                      or
 184  *
 185  *                              2) the tap-specific data passed to it is constructed only if
 186  *                                 the protocol tree is being built.
 187  *
 188  *                      TL_REQUIRES_COLUMNS
 189  *
 190  *                      set if your tap listener "packet" routine requires the column
 191  *                      strings to be constructed.
 192  *
 193  *                       If no flags are needed, use TL_REQUIRES_NOTHING.
 194  *
 195  * @param tap_reset  void (*reset)(void *tapdata)
 196  *                   This callback is called whenever Wireshark wants to inform your
 197  *                   listener that it is about to start [re]reading a capture file or a new capture
 198  *                   from an interface and that your application should reset any state it has
 199  *                   in the *tapdata instance.
 200  * @param tap_packet gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data)
 201  *                   This callback is used whenever a new packet has arrived at the tap and that
 202  *                   it has passed the filter (if there were a filter).
 203  *                   The *data structure type is specific to each tap.
 204  *                   This function returns an gboolean and it should return
 205  *                    TRUE, if the data in the packet caused state to be updated
 206  *                          (and thus a redraw of the window would later be required)
 207  *                    FALSE, if we don't need to redraw the window.
 208  *                   NOTE: that (*packet) should be as fast and efficient as possible. Use this
 209  *                   function ONLY to store data for later and do the CPU-intensive processing
 210  *                   or GUI updates down in (*draw) instead.
 211  * @param tap_draw   void (*draw)(void *tapdata)
 212  *                   This callback is used when Wireshark wants your application to redraw its
 213  *                   output. It will usually not be called unless your application has received
 214  *                   new data through the (*packet) callback.
 215  *                   On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
 216  *                   from a separate thread up to once every 2-3 seconds.
 217  *                   On other ports it might only be called once when the capture is finished
 218  *                   or the file has been [re]read completely.
 219  */
 220
 221 WS_DLL_PUBLIC GString *register_tap_listener(const char *tapname, void *tapdata,
 222     const char *fstring, guint flags, tap_reset_cb tap_reset,
 223     tap_packet_cb tap_packet, tap_draw_cb tap_draw);
 224
 225 /** This function sets a new dfilter to a tap listener */
 226 WS_DLL_PUBLIC GString *set_tap_dfilter(void *tapdata, const char *fstring);
 227
 228 /** This function recompiles dfilter for all registered tap listeners */
 229 WS_DLL_PUBLIC void tap_listeners_dfilter_recompile(void);
 230
 231 /** this function removes a tap listener */
 232 WS_DLL_PUBLIC void remove_tap_listener(void *tapdata);
 233
 234 /**
 235  * Return TRUE if we have one or more tap listeners that require dissection,
 236  * FALSE otherwise.
 237  */
 238 WS_DLL_PUBLIC gboolean tap_listeners_require_dissection(void);
 239
 240 /** Returns TRUE there is an active tap listener for the specified tap id. */
 241 WS_DLL_PUBLIC gboolean have_tap_listener(int tap_id);
 242
 243 /** Return TRUE if we have any tap listeners with filters, FALSE otherwise. */
 244 WS_DLL_PUBLIC gboolean have_filtering_tap_listeners(void);
 245
 246 /**
 247  * Get the union of all the flags for all the tap listeners; that gives
 248  * an indication of whether the protocol tree, or the columns, are
 249  * required by any taps.
 250  */
 251 WS_DLL_PUBLIC guint union_of_tap_listener_flags(void);
 252
 253 /** This function can be used by a dissector to fetch any tapped data before
 254  * returning.
 255  * This can be useful if one wants to extract the data inside dissector  BEFORE
 256  * it exists as an alternative to the callbacks that are all called AFTER the
 257  * dissection has completed.
 258  *
 259  * Example: SMB2 uses this mechanism to extract the data tapped from NTLMSSP
 260  * containing the account and domain names before exiting.
 261  * Note that the SMB2 tap listener specifies all three callbacks as NULL.
 262  *
 263  * Beware: when using this mechanism to extract the tapped data you can not
 264  * use "filters" and should specify the "filter" as NULL when registering
 265  * the tap listener.
 266  */
 267 WS_DLL_PUBLIC const void *fetch_tapped_data(int tap_id, int idx);
 268
 269 /** Clean internal structures
 270  */
 271 extern void tap_cleanup(void);
 272
 273 #ifdef __cplusplus
 274 }
 275 #endif /* __cplusplus */
 276
 277 #endif /* __TAP_H__ */