Wireshark  4.3.0
The Wireshark network protocol analyzer
plugin_if.h
Go to the documentation of this file.
1 
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, gpointer gui_object, gpointer 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;
53 
55 {
56  ext_menubar_entry_t type;
57  ext_menu_t * parent;
58  int proto;
59  GList * children;
60  guint submenu_cnt;
61  guint item_cnt;
62 
63  gchar * name;
64  gchar * label;
65 
66  gchar * tooltip;
67  gboolean is_plugin;
68  gpointer user_data;
69 
70  ext_menubar_action_cb callback;
71 
72  gchar * parent_menu;
73 };
74 
75 typedef void (*ext_toolbar_action_cb)(gpointer toolbar_item, gpointer item_data, gpointer 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  gchar * value;
94  gchar * display;
95 
96  gboolean is_default;
97 
99 
100 typedef struct _ext_toolbar_t
101 {
102  ext_toolbar_entry_t type;
103 
104  GList * children;
105  guint submenu_cnt;
106  guint item_cnt;
107 
108  gchar * name;
109  gchar * defvalue;
110  gchar * tooltip;
111  gpointer user_data;
112 
113  gboolean is_required;
114  gboolean capture_only;
115  ext_toolbar_item_t item_type;
116 
117  GList * values;
118  gchar * 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  gboolean silent;
138  gpointer user_data;
139  gpointer data_index;
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 gchar * menulabel, gboolean 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 gchar * 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 gchar *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 gchar *label,
192  const gchar *tooltip,
193  ext_menubar_action_cb callback,
194  gpointer 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 gchar *label,
217  const gchar *tooltip, const gchar *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 gchar * 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 gchar * 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 gchar *label,
273  const gchar *defvalue,
274  const gchar *tooltip,
275  gboolean capture_only,
276  GList * value_list,
277  gboolean is_required,
278  const gchar * valid_regex,
279  ext_toolbar_action_cb callback,
280  gpointer user_data);
281 
282 WS_DLL_PUBLIC GList * ext_toolbar_add_val(GList * entries, gchar * value, gchar * display, gboolean is_default);
283 
284 WS_DLL_PUBLIC void ext_toolbar_register_update_cb(ext_toolbar_t * entry, ext_toolbar_action_cb callback, gpointer 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, gpointer data, gboolean 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, gpointer data, gboolean 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, gpointer data, gpointer idx, gboolean 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, gpointer data, gpointer idx, gboolean 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, gpointer data, gpointer idx, gboolean 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 gchar * 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, gboolean status);
349 
350 /*
351  * Structure definition for the plugin_if_get_ws_info function
352  */
353 
354 typedef struct _ws_info_t
355 {
356  gboolean ws_info_supported; /* false if no libpcap */
357  file_state cf_state; /* Current state of capture file */
358  gchar *cf_filename; /* Name of capture file */
359  guint32 cf_count; /* Total number of frames */
360  guint32 cf_framenr;
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, gboolean 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(guint32 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  */
Definition: cfile.h:67
Definition: plugin_if.h:55
Definition: plugin_if.h:101
Definition: plugin_if.h:135
Definition: plugin_if.h:92
Definition: plugin_if.h:355
guint32 cf_framenr
Definition: plugin_if.h:360
gboolean frame_passed_dfilter
Definition: plugin_if.h:361
Definition: prefs-int.h:27
#define ws_info(...)
Definition: wslog.h:371