Remove autotools build system.
[metze/wireshark/wip.git] / doc / README.plugins
1 0. Plugins
2
3 There are a multitude of plugin options available in Wireshark that allow to
4 extend its functionality without changing the source code itself.  Using the
5 available APIs gives you the means to do this.
6
7 Currently plugin APIs are available for dissectors (epan), capture file types
8 (wiretap) and media decoders (codecs).  This README focuses primarily on
9 dissector plugins; most of the descriptions are applicable to the other plugin
10 types as well.
11
12 1. Dissector plugins
13
14 Writing a "plugin" dissector is not very different from writing a standard
15 one.  In fact all of the functions described in README.dissector can be
16 used in the plugins exactly as they are used in standard dissectors.
17
18 (Note, however, that not all OSes on which Wireshark runs can support
19 plugins.)
20
21 If you've chosen "foo" as the name of your plugin (typically, that would
22 be a short name for your protocol, in all lower case), the following
23 instructions tell you how to implement it as a plugin.  All occurrences
24 of "foo" below should be replaced by the name of your plugin.
25
26 2. The directory for the plugin, and its files
27
28 The plugin should be placed in a new plugins/epan/foo directory which should
29 contain at least the following files:
30
31 CMakeLists.txt
32 README
33
34 The README can be brief but it should provide essential information relevant
35 to developers and users. Optionally AUTHORS and ChangeLog files can be added.
36 Optionally you can add your own plugin.rc.in.
37
38 And of course the source and header files for your dissector.
39
40 Examples of these files can be found in plugins/epan/gryphon.
41
42 2.1 CMakeLists.txt
43
44 For your plugins/epan/foo/CMakeLists.txt file, see the corresponding file in
45 plugins/epan/gryphon.  Replace all occurrences of "gryphon" in those files
46 with "foo" and add your source files to the DISSECTOR_SRC variable.
47
48 2.2 plugin.rc.in
49
50 Your plugins/epan/foo/plugin.rc.in is the Windows resource template file used
51 to add the plugin specific information as resources to the DLL.
52 If not provided the plugins/plugin.rc.in file will be used.
53
54 3. Changes to existing Wireshark files
55
56 There are two ways to add your plugin dissector to the build, as a custom
57 extension or as a permanent addition.  The custom extension is easy to
58 configure, but won't be used for inclusion in the distribution if that's
59 your goal.  Setting up the permanent addition is somewhat more involved.
60
61 3.1 Custom extension
62
63 Go to the plugins directory and copy the Custom.m4.example and
64 Custom.make.example files to files of the same name but without the ".example"
65 suffix.  Now you have two Custom files ready for building a plugin with the
66 name "foo".  Replace the name if you so require.
67
68 If you want to add the plugin to your own Windows installer add a text
69 file named custom_plugins.txt to the packaging/nsis directory, with a
70 "File" statement for NSIS:
71
72 File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll"
73
74 For CMake builds, either pass the custom plugin dir on the CMake generation
75 step command line:
76
77 CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/epan/foo"
78
79 or copy the top-level file CMakeListsCustom.txt.example to CMakeListsCustom.txt
80 (also in the top-level source dir) and edit so that CUSTOM_PLUGIN_SRC_DIR is
81 set() to the relative path of your plugin, e.g.
82
83 set(CUSTOM_PLUGIN_SRC_DIR plugins/epan/foo)
84
85 and re-run the CMake generation step.
86
87 To build the plugin, run your normal Wireshark build step.
88
89 3.2 Permanent addition
90
91 In order to be able to permanently add a plugin take the following steps.
92 You will need to change the following files:
93         configure.ac
94         CMakeLists.txt
95         packaging/nsis/wireshark.nsi
96
97 You might also want to search your Wireshark development directory for
98 occurrences of an existing plugin name, in case this document is out of
99 date with the current directory structure.  For example,
100
101         grep -rl gryphon .
102
103 could be used from a shell prompt.
104
105 3.2.1  Changes to CMakeLists.txt
106
107 Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
108
109 if(ENABLE_PLUGINS)
110         ...
111         set(PLUGIN_SRC_DIRS
112                 ...
113                 plugins/epan/ethercat
114                 plugins/epan/foo
115                 plugins/epan/gryphon
116                 plugins/epan/irda
117                 ...
118
119 3.2.2  Changes to the installers
120
121 If you want to include your plugin in an installer you have to add lines
122 in the NSIS installer wireshark.nsi file.
123
124 3.2.2.1  Changes to packaging/nsis/wireshark.nsi
125
126 Add the relative path of your plugin DLL (in alphbetical order) to the
127 list of "File" statements in the "Dissector Plugins" section:
128
129 File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\ethercat.dll"
130 File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll"
131 File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\gryphon.dll"
132 File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\irda.dll"
133
134 3.2.2.2  Other installers
135
136 The PortableApps installer copies plugins from the build directory
137 and should not require configuration.
138
139 4. Development and plugins on Unix
140
141 Plugins make some aspects of development easier and some harder.
142
143 The first thing is that you'll have to run autogen.sh and configure once
144 more to setup your build environment.
145
146 The good news is that if you are working on a single plugin then you will
147 find recompiling the plugin MUCH faster than recompiling a dissector and
148 then linking it back into Wireshark. Use "make -C plugins" to compile just
149 your plugins.
150
151 The bad news is that Wireshark will not use the plugins unless the plugins
152 are installed in one of the places it expects them to find.
153
154 One way of dealing with this problem is to set an environment variable
155 when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
156
157 Another way to deal with this problem is to set up a working root for
158 wireshark, say in $HOME/build/root and build wireshark to install
159 there
160
161 ./configure --prefix=${HOME}/build/root && make install
162
163 then subsequent rebuilds/installs of your plugin can be accomplished
164 by going to the plugins/foo directory and running
165
166 make install
167
168 5. Update "old style" plugins
169
170 5.1 How to update an "old style" plugin (since Wireshark 2.5)
171
172 Plugins need exactly three visible symbols: plugin_version, plugin_release and
173 plugin_register. Each plugin is either a libwscodecs plugin, libwiretap plugin or
174 libwireshark plugin and the library will call "plugin_register" after
175 loading the plugin. "plugin_register" in turn calls all the hooks necessary
176 to enable the plugin. So if you had two function like so:
177
178     WS_DLL_PUBLIC void plugin_register(void);
179     WS_DLL_PUBLIC void plugin_reg_handoff(void);
180
181     void plugin_register(void) {...};
182     void plugin_reg_handoff(void) {...};
183
184 You'll have to rewrite it as:
185
186     WS_DLL_PUBLIC void plugin_register(void);
187
188     static void proto_register_foo(void) {...};
189     static void proto_reg_handoff_foo(void) {...};
190
191     void plugin_register(void)
192     {
193         static proto_plugin plugin_foo;
194
195         plugin_foo.register_protoinfo = proto_register_foo;
196         plugin_foo.register_handoff = proto_reg_handoff_foo;
197         proto_register_plugin(&plugin_foo);
198     }
199
200 See doc/plugins.example for an example.
201
202 5.2 How to update an "old style" plugin (using plugin_register and
203     plugin_reg_handoff functions).
204
205 The plugin registration has changed with the extension of the build
206 scripts. These now generate the additional code needed for plugin
207 encapsulation in plugin.c. When using the new style build scripts,
208 stips the parts outlined below:
209
210     o Remove the following include statements:
211
212         #include <gmodule.h>
213         #include "moduleinfo.h"
214
215     o Removed the definition:
216
217         #ifndef ENABLE_STATIC
218         WS_DLL_PUBLIC_DEF gchar version[] = VERSION;
219         #endif
220
221     o Move relevant code from the blocks and delete these functions:
222
223         #ifndef ENABLE_STATIC
224         plugin_reg_handoff()
225         ....
226         #endif
227
228         #ifndef ENABLE_STATIC
229         plugin_register()
230         ....
231         #endif
232
233 This will leave a clean dissector source file without plugin specifics.
234
235 5.3 How to update an "old style" plugin (using plugin_init function)
236
237 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
238 is encouraged to update their plugins as outlined below:
239
240     o Remove following include statements from all plugin sources:
241
242         #include "plugins/plugin_api.h"
243         #include "plugins/plugin_api_defs.h"
244
245     o Remove the init function.
246
247 6 How to plugin related interface options
248
249 To demonstrate the functionality of the plugin interface options, a
250 demonstration plugin exists (pluginifdemo). To build it using cmake, the
251 build option ENABLE_PLUGINIFDEMO has to be enabled.
252
253 6.1 Implement a plugin GUI menu
254
255 A plugin (as well as built-in dissectors) may implement a menu within
256 Wireshark to be used to trigger options, start tools, open Websites, ...
257
258 This menu structure is built using the plugin_if.h interface and its
259 corresponding functions.
260
261 The menu items all call a callback provided by the plugin, which takes
262 a pointer to the menuitem entry ad data. This pointer may be used to
263 provide userdata to each entry. The pointer must utilize WS_DLL_PUBLIC_DEF
264 and has the following structure:
265
266     WS_DLL_PUBLIC_DEF void
267     menu_cb(ext_menubar_gui_type gui_type, gpointer gui_data,
268             gpointer user_data _U_)
269     {
270         ... Do something ...
271     }
272
273 The menu entries themselves are generated with the following code structure:
274
275     ext_menu_t * ext_menu, *os_menu = NULL;
276
277     ext_menu = ext_menubar_register_menu (
278             <your_proto_item>, "Some Menu Entry", TRUE );
279     ext_menubar_add_entry(ext_menu, "Test Entry 1",
280             "This is a tooltip", menu_cb, <user_data>);
281     ext_menubar_add_entry(ext_menu, "Test Entry 2",
282             NULL, menu_cb, <user_data>);
283
284     os_menu = ext_menubar_add_submenu(ext_menu, "Sub Menu" );
285     ext_menubar_add_entry(os_menu, "Test Entry A",
286             NULL, menu_cb, <user_data>);
287     ext_menubar_add_entry(os_menu, "Test Entry B",
288             NULL, menu_cb, <user_data>);
289
290 For a more detailed information, please refer to plugin_if.h
291
292 6.2 Implement interactions with the main interface
293
294 Due to memory constraints on most platforms, plugin functionality cannot be
295 called directly from a DLL context. Instead special functions will be used,
296 which will implement certain options for plugins to utilize.
297
298 The following methods exist so far:
299
300         /* Applies the given filter string as display filter */
301         WS_DLL_PUBLIC void plugin_if_apply_filter
302                 (const char * filter_string, gboolean force);
303
304         /* Saves the given preference to the main preference storage */
305         WS_DLL_PUBLIC void plugin_if_save_preference
306                 (const char * pref_module, const char * pref_key, const char * pref_value);
307
308         /* Jumps to the given frame number */
309         WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr);
310
311 6.3 Implement a plugin specific toolbar
312
313 A toolbar may be registered which allows implementing an interactive user
314 interaction with the main application. The toolbar is generated using the following
315 code:
316
317     ext_toolbar_t * tb = ext_toolbar_register_toolbar("Plugin Interface Demo Toolbar");
318
319 This registers a toolbar, which will be shown underneath "View->Additional Toolbars" in
320 the main menu, as well as the popup action window when right-clicking on any other tool-
321 or menubar.
322
323 It behaves identically to the existing toolbars and can be hidden as well as defined to
324 appear specific to selected profiles. The name with which it is being shown is the given
325 name in this function call.
326
327 6.3.1 Register elements for the toolbar
328
329 To add items to the toolbar, 4 different types of elements do exist.
330
331   * BOOLEAN - a checkbox to select / unselect
332   * BUTTON - a button to click
333   * STRING - a text field with validation options
334   * SELECTOR - a dropdown selection field
335
336 To add an element to the toolbar, the following function is being used:
337
338     ext_toolbar_add_entry( ext_toolbar_t * parent, ext_toolbar_item_t type, const gchar *label,
339         const gchar *defvalue, const gchar *tooltip, gboolean capture_only, GList * value_list,
340         gboolean is_required, const gchar * regex, ext_toolbar_action_cb callback, gpointer user_data)
341
342     parent_bar - the parent toolbar for this entry, to be registered by ext_toolbar_register_toolbar
343     name - the entry name (the internal used one) for the item, used to send updates to the element
344     label - the entry label (the displayed name) for the item, visible to the user
345     defvalue - the default value for the toolbar element
346         - EXT_TOOLBAR_BOOLEAN - 1 is for a checked element, 0 is unchecked
347         - EXT_TOOLBAR_STRING - Text already entered upon initial display
348     tooltip - a tooltip to be displayed on mouse-over
349     capture_only - entry is only active, if a capture is active
350     callback - the action which will be invoked after the item is activated
351     value_list - a non-null list of values created by ext_toolbar_add_val(), if the item type
352         is EXT_TOOLBAR_SELECTOR
353     valid_regex - a validation regular expression for EXT_TOOLBAR_STRING
354     is_required - a zero entry for EXT_TOOLBAR_STRING is not allowed
355     user_data - a user defined pointer, which will be added to the toolbar callback
356
357 In case of the toolbar type EXT_TOOLBAR_SELECTOR a value list has to be provided. This list
358 is generated using ext_toolbar_add_val():
359
360     GList * entries = 0;
361     entries = ext_toolbar_add_val(entries, "1", "ABCD", FALSE );
362     entries = ext_toolbar_add_val(entries, "2", "EFG", FALSE );
363     entries = ext_toolbar_add_val(entries, "3", "HIJ", TRUE );
364     entries = ext_toolbar_add_val(entries, "4", "KLM", FALSE );
365
366 6.3.2 Callback for activation of an item
367
368 If an item has been activated, the provided callback is being triggered.
369
370     void toolbar_cb(gpointer toolbar_item, gpointer item_data, gpointer user_data)
371
372 For EXT_TOOLBAR_BUTTON the callback is triggered upon a click on the button, for
373 EXT_TOOLBAR_BOOLEAN and EXT_TOOLBAR_SELECTOR the callback is triggered with every change
374 of the selection.
375
376 For EXT_TOOLBAR_STRING either the return key has to be hit or the apply button pressed.
377
378 The parameters of the callback are defined as follows:
379
380     toolbar_item - an element of the type ext_toolbar_t * representing the item that has been
381                    activated
382     item_data - the data of the item during activation. The content depends on the item type:
383          - EXT_TOOLBAR_BUTTON - the entry is null
384          - EXT_TOOLBAR_BOOLEAN - the entry is 0 if the checkbox is unchecked and 1 if it is checked
385          - EXT_TOOLBAR_STRING - a string representing the context of the textbox. Only valid strings
386                    are being passed, it can be safely assumed, that an applied regular expression has
387                    been checked.
388          - EXT_TOOLBAR_SELECTOR - the value of the selected entry
389     user_data - the data provided during element registration
390
391 6.3.3 Sending updates to the toolbar items
392
393 A plugin may send updates to the toolbar entry, using one of the following methods. The parameter
394 silent defines, if the registered toolbar callback is triggered by the update or not.
395
396     void ext_toolbar_update_value(ext_toolbar_t * entry, gpointer data, gboolean silent)
397
398     - EXT_TOOLBAR_BUTTON, EXT_TOOLBAR_STRING - the displayed text (on the button or in the textbox)
399         are being changed, in that case data is expected to be a string
400     - EXT_TOOLBAR_BOOLEAN - the checkbox value is being changed, to either 0 or 1, in both cases
401         data is expected to be an integer sent by GINT_TO_POINTER(n)
402     - EXT_TOOLBAR_SELECTOR - the display text to be changed. If no element exists with this text,
403         nothing will happen
404
405     void ext_toolbar_update_data(ext_toolbar_t * entry, gpointer data, gboolean silent)
406
407     - EXT_TOOLBAR_SELECTOR - change the value list to the one provided with data. Attention! this
408         does not change the list stored within the item just the one in the displayed combobox
409
410     void ext_toolbar_update_data_by_index(ext_toolbar_t * entry, gpointer data, gpointer value,
411         gboolean silent)
412
413     - EXT_TOOLBAR_SELECTOR - change the display text for the entry with the provided value. Both
414         data and value must be gchar * pointer.
415
416
417 ----------------
418
419 Ed Warnicke <hagbard@physics.rutgers.edu>
420 Guy Harris <guy@alum.mit.edu>
421
422 Derived and expanded from the plugin section of README.developers
423 which was originally written by
424
425 James Coe <jammer@cin.net>
426 Gilbert Ramirez <gram@alumni.rice.edu>
427 Jeff Foster <jfoste@woodward.com>
428 Olivier Abad <oabad@cybercable.fr>
429 Laurent Deniel <laurent.deniel@free.fr>
430 Jaap Keuter <jaap.keuter@xs4all.nl>