epan/plugin_if.h

   1 /* plugin_if.h
   2  * An API for Wireshark plugins
   3  *
   4  * This enables wireshark dissectors, especially those implemented by plugins
   5  * to register menubar entries, which then will call a pre-defined callback
   6  * function for the dissector or plugin.
   7  *
   8  * Also it implements additional methods, which allow plugins to interoperate
   9  * with the main GUI.
  10  *
  11  * Wireshark - Network traffic analyzer
  12  * By Gerald Combs <gerald@wireshark.org>
  13  * Copyright 1998 Gerald Combs
  14  *
  15  * This program is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU General Public License
  17  * as published by the Free Software Foundation; either version 2
  18  * of the License, or (at your option) any later version.
  19  *
  20  * This program is distributed in the hope that it will be useful,
  21  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23  * GNU General Public License for more details.
  24  *
  25  * You should have received a copy of the GNU General Public License
  26  * along with this program; if not, write to the Free Software
  27  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  28  */
  29 #ifndef EPAN_PLUGIN_IF_H
  30 #define EPAN_PLUGIN_IF_H
  31
  32 #include <config.h>
  33
  34 #include "ws_symbol_export.h"
  35
  36 #include <glib.h>
  37 #include <epan/epan.h>
  38 #include <epan/packet_info.h>
  39 #include <cfile.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif /* __cplusplus */
  44
  45 #define EXT_MENUBAR_MAX_DEPTH 5
  46
  47 typedef enum
  48 {
  49     EXT_MENUBAR_GTK_GUI,
  50     EXT_MENUBAR_QT_GUI
  51 } ext_menubar_gui_type;
  52
  53 /* menubar callback */
  54 typedef void (*ext_menubar_action_cb)(ext_menubar_gui_type gui_type, gpointer gui_object, gpointer user_data);
  55
  56 typedef enum
  57 {
  58     EXT_MENUBAR_MENU,
  59     EXT_MENUBAR_ITEM,
  60     EXT_MENUBAR_SEPARATOR,
  61     EXT_MENUBAR_URL
  62 } ext_menubar_entry_t;
  63
  64 typedef struct _ext_menubar_t ext_menubar_t;
  65 typedef ext_menubar_t ext_menu_t;
  66
  67 struct _ext_menubar_t
  68 {
  69     ext_menubar_entry_t type;
  70     ext_menu_t * parent;
  71     int proto;
  72     GList * children;
  73     guint submenu_cnt;
  74     guint item_cnt;
  75
  76     gchar * name;
  77     gchar * label;
  78
  79     gchar * tooltip;
  80     gboolean is_plugin;
  81     gpointer user_data;
  82
  83     ext_menubar_action_cb callback;
  84
  85     gchar * parent_menu;
  86 };
  87
  88 /* Registers a new main menu.
  89  *
  90  * This will register a new main menu entry, underneath all other menu entries will
  91  * be sorted
  92  *
  93  * @param proto_id the proto item for the protocol this menu entry belongs too
  94  * @param name the entry name (the internal used one) for the menu item
  95  * @param menulabel the entry label (the displayed name) for the menu item
  96  * @param is_plugin must be set to TRUE for plugin registration
  97  */
  98 WS_DLL_PUBLIC ext_menu_t * ext_menubar_register_menu(
  99         int proto_id, const gchar * menulabel, gboolean is_plugin);
 100
 101 /* Sets a parent menu for the user menu.
 102  *
 103  * This will set a parent menu, which allows this menu to be filtered underneath
 104  * the given menu as a submenu. If the parent menu does not exist, the main menu
 105  * will be used
 106  *
 107  * @param menu the menu for which to add the entry
 108  * @param parentmenu a valid menu name for the parent menu
 109  */
 110 WS_DLL_PUBLIC ext_menu_t * ext_menubar_set_parentmenu(
 111         ext_menu_t * menu, const gchar * parentmenu);
 112
 113 /* Registers a new main menu.
 114  *
 115  * This will register a new sub menu entry, underneath the parent menu
 116  *
 117  * @param parent the parent menu for this submenu
 118  * @param name the entry name (the internal used one) for the menu item
 119  * @param menulabel the entry label (the displayed name) for the menu item
 120  */
 121 WS_DLL_PUBLIC ext_menu_t * ext_menubar_add_submenu(
 122         ext_menu_t * parent, const gchar *menulabel);
 123
 124 /* Registers a new menubar entry.
 125  *
 126  * This registers a new menubar entry, which will have the given name, and
 127  * call the provided callback on activation
 128  *
 129  * @param parent_menu the parent menu for this entry
 130  * @param name the entry name (the internal used one) for the menu item
 131  * @param label the entry label (the displayed name) for the menu item
 132  * @param tooltip a tooltip to be displayed on mouse-over
 133  * @param callback the action which will be invoked after click on the menu item
 134  */
 135 WS_DLL_PUBLIC void ext_menubar_add_entry(
 136         ext_menu_t * parent_menu,
 137         const gchar *label,
 138         const gchar *tooltip,
 139         ext_menubar_action_cb callback,
 140         gpointer user_data);
 141
 142 /* Registers a new separator entry.
 143  *
 144  * @note This will not work using the legacy GTK interface, due to
 145  * restrictions on how separators are handled in the menu
 146  *
 147  * @param parent_menu the parent menu for this entry
 148  */
 149 WS_DLL_PUBLIC void ext_menubar_add_separator(ext_menu_t *parent_menu);
 150
 151 /* Registers a entry for a website call
 152  *
 153  * This registers a new menubar entry, which will call the given website, using
 154  * the predefined webbrowser
 155  *
 156  * @param parent_menu the parent menu for this entry
 157  * @param name the entry name (the internal used one) for the menu item
 158  * @param label the entry label (the displayed name) for the menu item
 159  * @param tooltip a tooltip to be displayed on mouse-over
 160  * @param url the url for the website
 161  */
 162 WS_DLL_PUBLIC void ext_menubar_add_website(ext_menu_t * parent, const gchar *label,
 163         const gchar *tooltip, const gchar *url);
 164
 165
 166 /*
 167  * Structure definition for the plugin_if_get_ws_info function
 168  */
 169
 170 typedef struct _ws_info_t
 171 {
 172     gboolean ws_info_supported;                 /* false if no libpcap */
 173     file_state cf_state;                        /* Current state of capture file */
 174     gchar *cf_filename;                         /* Name of capture file */
 175     guint32 cf_count;                           /* Total number of frames */
 176     guint32 cf_framenr;                         /**< Currently displayed frame number */
 177     gboolean frame_passed_dfilter;              /**< true = display, false = no display */
 178 } ws_info_t;
 179
 180
 181 /*
 182  * Enumeration of possible actions, which are registered in GUI interfaces
 183  */
 184 typedef enum
 185 {
 186     /* Applies a given string as filter */
 187     PLUGIN_IF_FILTER_ACTION_APPLY,
 188
 189     /* Prepares the given string as filter */
 190     PLUGIN_IF_FILTER_ACTION_PREPARE,
 191
 192     /* Saves a preference entry */
 193     PLUGIN_IF_PREFERENCE_SAVE,
 194
 195     /* Jumps to the provided frame number */
 196     PLUGIN_IF_GOTO_FRAME,
 197
 198     /* Gets status information about the currently loaded capture file */
 199     PLUGIN_IF_GET_WS_INFO
 200 } plugin_if_callback_t;
 201
 202
 203 typedef void (*plugin_if_gui_cb)(gconstpointer user_data);
 204
 205 WS_DLL_PUBLIC void plugin_if_register_gui_cb(plugin_if_callback_t actionType, plugin_if_gui_cb callback);
 206
 207 /* Applies the given filter string as display filter */
 208 WS_DLL_PUBLIC void plugin_if_apply_filter(const char * filter_string, gboolean force);
 209
 210 /* Saves the given preference to the main preference storage */
 211 WS_DLL_PUBLIC void plugin_if_save_preference(const char * pref_module, const char * pref_key, const char * pref_value);
 212
 213 /* Jumps to the given frame number */
 214 WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr);
 215
 216 /* Takes a snapshot of status information from Wireshark */
 217 WS_DLL_PUBLIC void plugin_if_get_ws_info(ws_info_t ** ws_info);
 218
 219 /* Private Method for retrieving the menubar entries
 220  *
 221  * Is only to be used by the UI interfaces to retrieve the menu entries
 222  */
 223 WS_DLL_PUBLIC GList * ext_menubar_get_entries(void);
 224
 225 #ifdef __cplusplus
 226 }
 227 #endif /* __cplusplus */
 228
 229 #endif /* EPAN_PLUGIN_IF_H */
 230
 231 /*
 232  * Editor modelines
 233  *
 234  * Local Variables:
 235  * c-basic-offset: 4
 236  * tab-width: 8
 237  * indent-tabs-mode: nil
 238  * End:
 239  *
 240  * ex: set shiftwidth=4 tabstop=8 expandtab:
 241  * :indentSize=4:tabSize=8:noTabs=true:
 242  */