Wireshark 2.9.0-477-g68ec514b The Wireshark network protocol analyzer

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

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 * 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, 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;
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 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
98 } ext_toolbar_value_t;
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;
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 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;
361 gboolean frame_passed_dfilter;
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 /* Remove toolbar */
386 PLUGIN_IF_REMOVE_TOOLBAR
387
388 } plugin_if_callback_t;
389
390
391 typedef void (*plugin_if_gui_cb)(GHashTable * data_set);
392
393 WS_DLL_PUBLIC void plugin_if_register_gui_cb(plugin_if_callback_t actionType, plugin_if_gui_cb callback);
394
395 /* Applies the given filter string as display filter */
396 WS_DLL_PUBLIC void plugin_if_apply_filter(const char * filter_string, gboolean force);
397
398 /* Saves the given preference to the main preference storage */
399 WS_DLL_PUBLIC void plugin_if_save_preference(const char * pref_module, const char * pref_key, const char * pref_value);
400
401 /* Jumps to the given frame number */
402 WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr);
403
404 /* Takes a snapshot of status information from Wireshark */
405 WS_DLL_PUBLIC void plugin_if_get_ws_info(ws_info_t ** ws_info);
406
407 /* Private Method for retrieving the menubar entries
408 *
409 * Is only to be used by the UI interfaces to retrieve the menu entries
410 */
411 WS_DLL_PUBLIC GList * ext_menubar_get_entries(void);
412
413 /* Private Method for retrieving the toolbar entries
414 *
415 * Is only to be used by the UI interfaces to retrieve the toolbar entries
416 */
417 WS_DLL_PUBLIC GList * ext_toolbar_get_entries(void);
418
419 #ifdef __cplusplus
420 }
421 #endif /* __cplusplus */
422
423 #endif /* EPAN_PLUGIN_IF_H */
424
425 /*
426 * Editor modelines
427 *
428 * Local Variables:
429 * c-basic-offset: 4
430 * tab-width: 8
431 * indent-tabs-mode: nil
432 * End:
433 *
434 * ex: set shiftwidth=4 tabstop=8 expandtab:
435 * :indentSize=4:tabSize=8:noTabs=true:
436 */
_ws_info_t::cf_framenr
guint32 cf_framenr
Definition: plugin_if.h:360
pref_module
Definition: prefs-int.h:27
_ext_toolbar_t
Definition: plugin_if.h:100
_ext_toolbar_value_t
Definition: plugin_if.h:91
_ext_toolbar_update_t
Definition: plugin_if.h:134
_ws_info_t
Definition: plugin_if.h:354
_ws_info_t::frame_passed_dfilter
gboolean frame_passed_dfilter
Definition: plugin_if.h:361
_ext_menubar_t
Definition: plugin_if.h:54
packet_info.h