epan/plugin_if.h

   1 /** @file
   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  * SPDX-License-Identifier: GPL-2.0-or-later
  16  */
  17 #ifndef EPAN_PLUGIN_IF_H
  18 #define EPAN_PLUGIN_IF_H
  19
  20 #include "ws_symbol_export.h"
  21 #include "ws_attributes.h"
  22
  23 #include <glib.h>
  24 #include <epan/epan.h>
  25 #include <epan/packet_info.h>
  26 #include <cfile.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif /* __cplusplus */
  31
  32 #define EXT_MENUBAR_MAX_DEPTH 5
  33
  34 typedef enum
  35 {
  36     EXT_MENUBAR_GTK_GUI,
  37     EXT_MENUBAR_QT_GUI
  38 } ext_menubar_gui_type;
  39
  40 /* menubar callback */
  41 typedef void (*ext_menubar_action_cb)(ext_menubar_gui_type gui_type, void *gui_object, void *user_data);
  42
  43 typedef enum
  44 {
  45     EXT_MENUBAR_MENU,
  46     EXT_MENUBAR_ITEM,
  47     EXT_MENUBAR_SEPARATOR,
  48     EXT_MENUBAR_URL
  49 } ext_menubar_entry_t;
  50
  51 typedef struct _ext_menubar_t ext_menubar_t;
  52 typedef ext_menubar_t ext_menu_t;
  53
  54 struct _ext_menubar_t
  55 {
  56     ext_menubar_entry_t type;
  57     ext_menu_t * parent;
  58     int proto;
  59     GList * children;
  60     unsigned submenu_cnt;
  61     unsigned item_cnt;
  62
  63     char * name;
  64     char * label;
  65
  66     char * tooltip;
  67     bool is_plugin;
  68     void *user_data;
  69
  70     ext_menubar_action_cb callback;
  71
  72     char * parent_menu;
  73 };
  74
  75 typedef void (*ext_toolbar_action_cb)(void *toolbar_item, void *item_data, void *user_data);
  76
  77 typedef enum
  78 {
  79     EXT_TOOLBAR_BAR,
  80     EXT_TOOLBAR_ITEM
  81 } ext_toolbar_entry_t;
  82
  83 typedef enum
  84 {
  85     EXT_TOOLBAR_BOOLEAN,
  86     EXT_TOOLBAR_BUTTON,
  87     EXT_TOOLBAR_STRING,
  88     EXT_TOOLBAR_SELECTOR
  89 } ext_toolbar_item_t;
  90
  91 typedef struct _ext_toolbar_value_t
  92 {
  93     char * value;
  94     char * display;
  95
  96     bool is_default;
  97
  98 } ext_toolbar_value_t;
  99
 100 typedef struct _ext_toolbar_t
 101 {
 102     ext_toolbar_entry_t type;
 103
 104     GList * children;
 105     unsigned submenu_cnt;
 106     unsigned item_cnt;
 107
 108     char * name;
 109     char * defvalue;
 110     char * tooltip;
 111     void *user_data;
 112
 113     bool is_required;
 114     bool capture_only;
 115     ext_toolbar_item_t item_type;
 116
 117     GList * values;
 118     char * regex;
 119
 120     ext_toolbar_action_cb callback;
 121
 122 } ext_toolbar_t;
 123
 124 typedef enum
 125 {
 126     EXT_TOOLBAR_UPDATE_VALUE,
 127     EXT_TOOLBAR_UPDATE_DATA,
 128     EXT_TOOLBAR_UPDATE_DATABYINDEX,
 129     EXT_TOOLBAR_UPDATE_DATA_ADD,
 130     EXT_TOOLBAR_UPDATE_DATA_REMOVE,
 131     EXT_TOOLBAR_SET_ACTIVE
 132 } ext_toolbar_update_type_t;
 133
 134 typedef struct _ext_toolbar_update_t
 135 {
 136     ext_toolbar_update_type_t type;
 137     bool silent;
 138     void *user_data;
 139     void *data_index;
 140 } ext_toolbar_update_t;
 141
 142 /* Registers a new main menu.
 143  *
 144  * This will register a new main menu entry, underneath all other menu entries will
 145  * be sorted
 146  *
 147  * @param proto_id the proto item for the protocol this menu entry belongs too
 148  * @param name the entry name (the internal used one) for the menu item
 149  * @param menulabel the entry label (the displayed name) for the menu item
 150  * @param is_plugin must be set to true for plugin registration
 151  */
 152 WS_DLL_PUBLIC ext_menu_t * ext_menubar_register_menu(
 153         int proto_id, const char * menulabel, bool is_plugin);
 154
 155 /* Sets a parent menu for the user menu.
 156  *
 157  * This will set a parent menu, which allows this menu to be filtered underneath
 158  * the given menu as a submenu. If the parent menu does not exist, the main menu
 159  * will be used
 160  *
 161  * @param menu the menu for which to add the entry
 162  * @param parentmenu a valid menu name for the parent menu
 163  */
 164 WS_DLL_PUBLIC ext_menu_t * ext_menubar_set_parentmenu(
 165         ext_menu_t * menu, const char * parentmenu);
 166
 167 /* Registers a new main menu.
 168  *
 169  * This will register a new sub menu entry, underneath the parent menu
 170  *
 171  * @param parent the parent menu for this submenu
 172  * @param name the entry name (the internal used one) for the menu item
 173  * @param menulabel the entry label (the displayed name) for the menu item
 174  */
 175 WS_DLL_PUBLIC ext_menu_t * ext_menubar_add_submenu(
 176         ext_menu_t * parent, const char *menulabel);
 177
 178 /* Registers a new menubar entry.
 179  *
 180  * This registers a new menubar entry, which will have the given name, and
 181  * call the provided callback on activation
 182  *
 183  * @param parent_menu the parent menu for this entry
 184  * @param name the entry name (the internal used one) for the menu item
 185  * @param label the entry label (the displayed name) for the menu item
 186  * @param tooltip a tooltip to be displayed on mouse-over
 187  * @param callback the action which will be invoked after click on the menu item
 188  */
 189 WS_DLL_PUBLIC void ext_menubar_add_entry(
 190         ext_menu_t * parent_menu,
 191         const char *label,
 192         const char *tooltip,
 193         ext_menubar_action_cb callback,
 194         void *user_data);
 195
 196 /* Registers a new separator entry.
 197  *
 198  * @note This will not work using the legacy GTK interface, due to
 199  * restrictions on how separators are handled in the menu
 200  *
 201  * @param parent_menu the parent menu for this entry
 202  */
 203 WS_DLL_PUBLIC void ext_menubar_add_separator(ext_menu_t *parent_menu);
 204
 205 /* Registers a entry for a website call
 206  *
 207  * This registers a new menubar entry, which will call the given website, using
 208  * the predefined webbrowser
 209  *
 210  * @param parent_menu the parent menu for this entry
 211  * @param name the entry name (the internal used one) for the menu item
 212  * @param label the entry label (the displayed name) for the menu item
 213  * @param tooltip a tooltip to be displayed on mouse-over
 214  * @param url the url for the website
 215  */
 216 WS_DLL_PUBLIC void ext_menubar_add_website(ext_menu_t * parent, const char *label,
 217         const char *tooltip, const char *url);
 218
 219 /* Registers a toolbar.
 220  *
 221  * This will register a new toolbar, which can contain various gui elements
 222  *
 223  * @param toolbar_label the entry label (the displayed name) for the toolbar item
 224  */
 225 WS_DLL_PUBLIC ext_toolbar_t * ext_toolbar_register_toolbar(const char * toolbar_label);
 226
 227 /* Removes a toolbar from the system.
 228  *
 229  * This will remove the provided toolbar from the application
 230  *
 231  * @param toolbar the toolbar to be removed
 232  */
 233 WS_DLL_PUBLIC void ext_toolbar_unregister_toolbar(ext_toolbar_t * toolbar);
 234
 235 /* Removes a toolbar from the system by providing the name of the toolbar.
 236  *
 237  * This will remove the provided toolbar from the application
 238  *
 239  * @param toolbar_name the name of the toolbar to be removed
 240  */
 241 WS_DLL_PUBLIC void ext_toolbar_unregister_toolbar_by_name(const char * toolbar_name);
 242
 243 /* Registers a new toolbar entry.
 244  *
 245  * This registers a new toolbar entry, which will have the given name, and
 246  * call the provided callback on activation
 247  *
 248  * The callback will be fired on different events, depending on the item type
 249  * and the implementation of the item type in a GUI element. The following types should
 250  * behave as following
 251  *
 252  *  * EXT_TOOLBAR_STRING - Every change of the content fires the callback
 253  *  * EXT_TOOLBAR_BOOLEAN - Every change of the value fires the callback
 254  *  * EXT_TOOLBAR_BUTTON - if the button is pressed, the callback fires
 255  *  * EXT_TOOLBAR_SELECTION - every time the selection changes the callback fires
 256  *
 257  * @param parent_bar the parent toolbar for this entry
 258  * @param name the entry name (the internal used one) for the item
 259  * @param label the entry label (the displayed name) for the item
 260  * @param defvalue the default value for the toolbar element
 261  * @param tooltip a tooltip to be displayed on mouse-over
 262  * @param capture_only entry is only active, if capture is active
 263  * @param callback the action which will be invoked after click on the item
 264  * @param value_list a non-null list of values, if the item type is EXT_TOOLBAR_SELECTOR
 265  * @param valid_regex a validation regular expression for EXT_TOOLBAR_STRING
 266  *
 267  * @return a reference to the newly created toolbar entry
 268  */
 269 WS_DLL_PUBLIC ext_toolbar_t * ext_toolbar_add_entry(
 270         ext_toolbar_t * parent_bar,
 271         ext_toolbar_item_t type,
 272         const char *label,
 273         const char *defvalue,
 274         const char *tooltip,
 275         bool capture_only,
 276         GList * value_list,
 277         bool is_required,
 278         const char * valid_regex,
 279         ext_toolbar_action_cb callback,
 280         void *user_data);
 281
 282 WS_DLL_PUBLIC GList * ext_toolbar_add_val(GList * entries, char * value, char * display, bool is_default);
 283
 284 WS_DLL_PUBLIC void ext_toolbar_register_update_cb(ext_toolbar_t * entry, ext_toolbar_action_cb callback, void *item_data);
 285
 286 /* Updates the entry values
 287  *
 288  * Update the values for the entry, it is up to the implemented widget, to interpret the
 289  * given character values
 290  *
 291  * @param entry the entry to be updated
 292  * @param data the data for the entry
 293  * @param silent the update for the entry should not trigger additional actions
 294  */
 295 WS_DLL_PUBLIC void ext_toolbar_update_value(ext_toolbar_t * entry, void *data, bool silent);
 296
 297 /* Updates the entry data
 298  *
 299  * Update the data for the entry, it is up to the implemented widget, to interpret the given character data
 300  *
 301  * @param entry the entry to be updated
 302  * @param data the data for the entry
 303  * @param silent the update for the entry should not trigger additional actions
 304  */
 305 WS_DLL_PUBLIC void ext_toolbar_update_data(ext_toolbar_t * entry, void *data, bool silent);
 306
 307 /* Updates the entry data by index
 308  *
 309  * This is used to update a single entry of a selector list, by giving it's value and a new display
 310  * entry
 311  *
 312  * @param entry the toolbar item to be updated
 313  * @param data the display data for the entry
 314  * @param idx the value for the entry to be updated
 315  * @param silent the update for the entry should not trigger additional actions
 316  */
 317 WS_DLL_PUBLIC void ext_toolbar_update_data_by_index(ext_toolbar_t * entry, void *data, void *idx, bool silent);
 318
 319 /* Adds the entry data by index
 320  *
 321  * This is used to add a single entry to a selector list, by giving it's new value and a new display
 322  * entry. If the value already exists, the selector may choose to ignore the command
 323  *
 324  * @param entry the toolbar item to be updated
 325  * @param data the display data for the entry to be added
 326  * @param idx the value for the entry to be added
 327  * @param silent the adding of the entry should not trigger additional actions
 328  */
 329 WS_DLL_PUBLIC void ext_toolbar_update_data_add_entry(ext_toolbar_t * entry, void *data, void *idx, bool silent);
 330
 331 /* Removes an entry data by index
 332  *
 333  * This is used to remove a single entry to a selector list, by giving it's value and a display
 334  * entry. If the value already exists, the selector may choose to ignore the command. Both value
 335  * and display must be given, as it is not established, how the entry is found in the selector list
 336  *
 337  * @param entry the toolbar item to be updated
 338  * @param data the display data for the entry to be removed
 339  * @param idx the value for the entry to be removed
 340  * @param silent the removal of the entry should not trigger additional actions
 341  */
 342 WS_DLL_PUBLIC void ext_toolbar_update_data_remove_entry(ext_toolbar_t * entry, void *data, void *idx, bool silent);
 343
 344 /* Search for and return if found an entry from the toolbar with the given label */
 345 WS_DLL_PUBLIC ext_toolbar_t * ext_toolbar_entry_by_label(const ext_toolbar_t * toolbar, const char * label);
 346
 347 /* Set the ui element for the given enry to the status */
 348 WS_DLL_PUBLIC void ext_toolbar_update_data_set_active(ext_toolbar_t * entry, bool status);
 349
 350 /*
 351  * Structure definition for the plugin_if_get_ws_info function
 352  */
 353
 354 typedef struct _ws_info_t
 355 {
 356     bool ws_info_supported;                 /* false if no libpcap */
 357     file_state cf_state;                        /* Current state of capture file */
 358     char *cf_filename;                         /* Name of capture file */
 359     uint32_t cf_count;                           /* Total number of frames */
 360     uint32_t cf_framenr;                         /**< Currently displayed frame number */
 361     bool frame_passed_dfilter;              /**< true = display, false = no display */
 362 } ws_info_t;
 363
 364
 365 /*
 366  * Enumeration of possible actions, which are registered in GUI interfaces
 367  */
 368 typedef enum
 369 {
 370     /* Applies a given string as filter */
 371     PLUGIN_IF_FILTER_ACTION_APPLY,
 372
 373     /* Prepares the given string as filter */
 374     PLUGIN_IF_FILTER_ACTION_PREPARE,
 375
 376     /* Saves a preference entry */
 377     PLUGIN_IF_PREFERENCE_SAVE,
 378
 379     /* Jumps to the provided frame number */
 380     PLUGIN_IF_GOTO_FRAME,
 381
 382     /* Gets status information about the currently loaded capture file */
 383     PLUGIN_IF_GET_WS_INFO,
 384
 385     /* Gets information from frame_data for current packet */
 386     PLUGIN_IF_GET_FRAME_DATA,
 387
 388     /* Gets information from capture_file */
 389     PLUGIN_IF_GET_CAPTURE_FILE,
 390
 391     /* Remove toolbar */
 392     PLUGIN_IF_REMOVE_TOOLBAR
 393
 394 } plugin_if_callback_t;
 395
 396
 397 typedef void (*plugin_if_gui_cb)(GHashTable * data_set);
 398
 399 WS_DLL_PUBLIC void plugin_if_register_gui_cb(plugin_if_callback_t actionType, plugin_if_gui_cb callback);
 400
 401 /* Applies the given filter string as display filter */
 402 WS_DLL_PUBLIC void plugin_if_apply_filter(const char * filter_string, bool force);
 403
 404 /* Saves the given preference to the main preference storage */
 405 WS_DLL_PUBLIC void plugin_if_save_preference(const char * pref_module, const char * pref_key, const char * pref_value);
 406
 407 /* Jumps to the given frame number */
 408 WS_DLL_PUBLIC void plugin_if_goto_frame(uint32_t framenr);
 409
 410 /* Takes a snapshot of status information from Wireshark */
 411 WS_DLL_PUBLIC void plugin_if_get_ws_info(ws_info_t ** ws_info);
 412
 413 typedef void* (*plugin_if_frame_data_cb)(frame_data*, void*);
 414 /* Gets frame_data for current packet, data are extracted by extract_cb */
 415 WS_DLL_PUBLIC void* plugin_if_get_frame_data(plugin_if_frame_data_cb extract_cb, void *user_data);
 416
 417 typedef void* (*plugin_if_capture_file_cb)(capture_file*, void*);
 418 /* Gets capture_file, data are extracted by extract_cb */
 419 WS_DLL_PUBLIC void* plugin_if_get_capture_file(plugin_if_capture_file_cb extract_cb, void* user_data);
 420
 421 /* Private Method for retrieving the menubar entries
 422  *
 423  * Is only to be used by the UI interfaces to retrieve the menu entries
 424  */
 425 WS_DLL_PUBLIC GList * ext_menubar_get_entries(void);
 426
 427 /* Private Method for retrieving the toolbar entries
 428  *
 429  * Is only to be used by the UI interfaces to retrieve the toolbar entries
 430  */
 431 WS_DLL_PUBLIC GList * ext_toolbar_get_entries(void);
 432
 433 #ifdef __cplusplus
 434 }
 435 #endif /* __cplusplus */
 436
 437 #endif /* EPAN_PLUGIN_IF_H */
 438
 439 /*
 440  * Editor modelines
 441  *
 442  * Local Variables:
 443  * c-basic-offset: 4
 444  * tab-width: 8
 445  * indent-tabs-mode: nil
 446  * End:
 447  *
 448  * ex: set shiftwidth=4 tabstop=8 expandtab:
 449  * :indentSize=4:tabSize=8:noTabs=true:
 450  */