2004-07-18 00:24:25 +00:00
|
|
|
$Id$
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
1. Plugins
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
Writing a "plugin" dissector is not very different from writing a
|
|
|
|
standard one. In fact all of the functions described in
|
2007-11-16 22:53:18 +00:00
|
|
|
README.developer can be used in the plugins exactly as they are used in
|
2006-04-20 02:39:04 +00:00
|
|
|
standard dissectors.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-05-31 19:12:15 +00:00
|
|
|
(Note, however, that not all OSes on which Wireshark runs can support
|
2003-11-06 09:52:28 +00:00
|
|
|
plugins.)
|
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
If you've chosen "xxx" as the name of your plugin (typically, that would
|
|
|
|
be a short name for your protocol, in all lower case), the following
|
|
|
|
instructions tell you how to implement it as a plugin. All occurrences
|
|
|
|
of "xxx" below should be replaced by the name of your plugin.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2. The directory for the plugin, and its files
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
The plugin should be placed in a new plugins/xxx directory which should
|
|
|
|
contain minimally the following files:
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
AUTHORS
|
|
|
|
COPYING
|
|
|
|
ChangeLog
|
|
|
|
Makefile.am
|
2006-04-20 02:39:04 +00:00
|
|
|
Makefile.common
|
2001-07-10 01:22:58 +00:00
|
|
|
Makefile.nmake
|
|
|
|
moduleinfo.h
|
2006-12-20 16:24:19 +00:00
|
|
|
moduleinfo.nmake
|
|
|
|
plugin.rc.in
|
2006-04-20 02:39:04 +00:00
|
|
|
The source files and header files for your dissector
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
Examples of these files can be found in plugins/gryphon.
|
2006-12-20 16:24:19 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.1 AUTHORS, COPYING, and ChangeLog
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
|
2006-12-20 16:24:19 +00:00
|
|
|
files.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
2.2 Makefile.am
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
For your plugins/xxx/Makefile.am file, see the corresponding file in
|
2009-02-21 16:33:48 +00:00
|
|
|
plugins/gryphon. Replace all occurrences of "gryphon" in those files
|
|
|
|
with "xxx".
|
2005-03-05 06:28:10 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
2.3 Makefile.common
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
Your plugins/xxx/Makefile.common should only list the main source file(s),
|
|
|
|
which exports register_*() and handoff_*(), for your dissector in the
|
|
|
|
DISSECTOR_SRC variable, and all other supporting source files in the
|
|
|
|
DISSECTOR_SUPPORT_SRC variable.
|
2007-08-24 16:08:31 +00:00
|
|
|
The header files for your dissector, if any, must be listed in the
|
|
|
|
DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
|
|
|
|
include moduleinfo.h.
|
2006-12-20 16:24:19 +00:00
|
|
|
|
|
|
|
2.4 Makefile.nmake
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
For your plugins/xxx/Makefile.nmake file, see the corresponding file in
|
2009-02-21 16:33:48 +00:00
|
|
|
plugins/gryphon. No modifications are needed here.
|
2005-03-05 06:28:10 +00:00
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
2.5 moduleinfo.h
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
Your plugins/xxx/moduleinfo.h file is used to set the version information
|
|
|
|
for the plugin.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
2.6 moduleinfo.nmake
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
Your plugins/xxx/moduleinfo.nmake is used to set the version information
|
|
|
|
for building the plugin. Its contents should match that in moduleinfo.h
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
2.7 plugin.rc.in
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
Your plugins/xxx/plugin.rc.in is the Windows resource template file
|
|
|
|
used to add the plugin specific information as resources to the DLL.
|
|
|
|
No modifications are needed here.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-05-31 19:12:15 +00:00
|
|
|
3. Changes to existing Wireshark files
|
2006-04-20 02:39:04 +00:00
|
|
|
|
2008-03-14 22:06:05 +00:00
|
|
|
You will also need to change the following files:
|
|
|
|
configure.in
|
|
|
|
epan/Makefile.am
|
|
|
|
Makefile.am
|
|
|
|
Makefile.nmake
|
|
|
|
packaging/nsis/Makefile.nmake
|
|
|
|
packaging/nsis/wireshark.nsi
|
|
|
|
plugins/Makefile.am
|
|
|
|
plugins/Makefile.nmake
|
|
|
|
|
|
|
|
You might also want to search your Wireshark development directory for
|
|
|
|
occurrences of an existing plugin name, in case this document is out of
|
|
|
|
date with the current directory structure. For example,
|
|
|
|
|
|
|
|
grep -rl gryphon .
|
|
|
|
|
|
|
|
could be used from a shell prompt.
|
2006-04-20 02:39:04 +00:00
|
|
|
|
|
|
|
3.1 Changes to plugins/Makefile.am
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
The plugins directory contains a Makefile.am. You need to change the
|
2007-01-18 12:22:21 +00:00
|
|
|
SUBDIRS directive to reflect the addition of your plugin:
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
SUBDIRS = $(_CUSTOM_SUBDIRS_) \
|
|
|
|
...
|
2005-07-25 18:27:35 +00:00
|
|
|
gryphon \
|
2008-01-18 07:35:01 +00:00
|
|
|
irda \
|
2009-02-21 16:33:48 +00:00
|
|
|
xxx \
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
3.2 Changes to plugins/Makefile.nmake
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2008-02-05 19:23:48 +00:00
|
|
|
To the Makefile.nmake you need to add the following (in
|
|
|
|
alphabetical order) for your plugin to the process-plugins: rule
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2004-07-03 21:50:05 +00:00
|
|
|
cd xxx
|
2008-02-05 19:23:48 +00:00
|
|
|
$(MAKE) /$(MAKEFLAGS) -f Makefile.nmake $(PLUGIN_TARGET)
|
2004-07-03 21:50:05 +00:00
|
|
|
cd ..
|
|
|
|
|
2008-02-05 19:23:48 +00:00
|
|
|
Then add a copy command to the install-plugins rule:
|
2004-07-03 21:50:05 +00:00
|
|
|
|
2008-02-05 19:23:48 +00:00
|
|
|
...
|
2009-02-21 16:33:48 +00:00
|
|
|
xcopy plugins\xxx\*.dll $(INSTALL_DIR)\plugins\$(VERSION) /d
|
|
|
|
cd plugins
|
2008-02-05 19:23:48 +00:00
|
|
|
if exist Custom.nmake $(MAKE) /$(MAKEFLAGS) -f Custom.nmake install-plugins
|
2005-03-05 06:28:10 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
3.3 Changes to the top level Makefile.am
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2008-02-05 19:23:48 +00:00
|
|
|
Add your plugin (in alphabetical order) to the plugin_ldadd:
|
2004-07-03 21:50:05 +00:00
|
|
|
|
2008-02-05 19:23:48 +00:00
|
|
|
if HAVE_PLUGINS
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2001-07-20 02:40:42 +00:00
|
|
|
plugin_ldadd = \
|
2008-02-05 19:23:48 +00:00
|
|
|
...
|
2009-02-21 16:33:48 +00:00
|
|
|
-dlopen plugins/gryphon/gryphon.la \
|
|
|
|
-dlopen plugins/irda/irda.la \
|
2008-02-05 19:23:48 +00:00
|
|
|
-dlopen plugins/xxx/xxx.la \
|
2009-02-21 16:33:48 +00:00
|
|
|
...
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
3.4 Changes to the top level configure.in
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
You need to add your plugins Makefile (in alphbetical order) to the AC_OUTPUT
|
|
|
|
rule in the configure.in
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
AC_OUTPUT(
|
2009-02-21 16:33:48 +00:00
|
|
|
...
|
2001-07-10 01:22:58 +00:00
|
|
|
plugins/gryphon/Makefile
|
2008-01-18 07:35:01 +00:00
|
|
|
plugins/irda/Makefile
|
2001-07-10 01:22:58 +00:00
|
|
|
plugins/xxx/Makefile
|
2009-02-21 16:33:48 +00:00
|
|
|
...
|
2001-07-10 01:22:58 +00:00
|
|
|
,)
|
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
3.5 Changes to epan/Makefile.am
|
2008-03-14 22:06:05 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
Add the relative path of your plugin (in alphbetical order) to plugin_src:
|
2008-03-14 22:06:05 +00:00
|
|
|
|
|
|
|
plugin_src = \
|
2009-02-21 16:33:48 +00:00
|
|
|
...
|
|
|
|
../plugins/gryphon/packet-gryphon.c \
|
|
|
|
../plugins/irda/packet-irda.c \
|
|
|
|
../plugins/xxx/packet-xxx.c \
|
|
|
|
...
|
2008-03-14 22:06:05 +00:00
|
|
|
|
2009-02-21 16:33:48 +00:00
|
|
|
3.6 Changes to the installers
|
2006-12-20 16:24:19 +00:00
|
|
|
|
2007-08-21 17:59:08 +00:00
|
|
|
If you want to include your plugin in an installer you have to add lines
|
2009-02-21 16:33:48 +00:00
|
|
|
in the NSIS installer Makefile.nmake and wireshark.nsi files.
|
2007-08-21 17:59:08 +00:00
|
|
|
|
|
|
|
For the NSIS installer:
|
|
|
|
|
|
|
|
Add ../../plugins/xxx/xxx.dll to the list of plugins for the
|
|
|
|
PLUGINS variable in packaging/nsis/Makefile.nmake.
|
|
|
|
|
|
|
|
Add
|
|
|
|
|
|
|
|
File "..\..\plugins\xxx\xxx.dll"
|
|
|
|
|
|
|
|
to the list of "File" statements in the "Dissector Plugins"
|
2007-08-21 18:09:33 +00:00
|
|
|
section in packaging/nsis/wireshark.nsi.
|
|
|
|
|
2008-03-14 22:06:05 +00:00
|
|
|
The U3 and PortableApps installers build their manifests, including plugins,
|
2009-02-21 16:33:48 +00:00
|
|
|
from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-01-18 12:22:21 +00:00
|
|
|
4. Development and plugins on Unix
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
Plugins make some aspects of development easier and some harder.
|
|
|
|
|
2007-01-18 12:22:21 +00:00
|
|
|
The first thing is that you'll have to run autogen.sh and configure
|
|
|
|
once more to setup your build environment.
|
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
The good news is that if you are working on a single plugin
|
|
|
|
then you will find recompiling the plugin MUCH faster than
|
2007-01-18 12:22:21 +00:00
|
|
|
recompiling a dissector and then linking it back into Wireshark.
|
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
The bad news is that Wireshark will not use the plugins unless the
|
2007-01-18 12:22:21 +00:00
|
|
|
plugins are installed in one of the places it expects them to find.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-01-18 12:22:21 +00:00
|
|
|
One way of dealing with this problem is to set an environment variable
|
|
|
|
when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
|
2001-07-10 01:22:58 +00:00
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
Another way to deal with this problem is to set up a working root for
|
2006-05-31 19:12:15 +00:00
|
|
|
wireshark, say in $HOME/build/root and build wireshark to install
|
2001-07-10 01:22:58 +00:00
|
|
|
there
|
|
|
|
|
|
|
|
./configure --prefix=${HOME}/build/root;make install
|
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
then subsequent rebuilds/installs of your plugin can be accomplished
|
|
|
|
by going to the plugins/xxx directory and running
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
make install
|
|
|
|
|
2006-12-20 16:24:19 +00:00
|
|
|
5. Update "old style" plugins
|
|
|
|
|
2007-08-24 16:08:31 +00:00
|
|
|
5.1 How to update an "old style" plugin (using plugin_register and
|
2006-12-20 16:24:19 +00:00
|
|
|
plugin_reg_handoff functions).
|
|
|
|
|
|
|
|
The plugin registration has changed with the extension of the build
|
2007-08-24 16:08:31 +00:00
|
|
|
scripts. These now generate the additional code needed for plugin
|
2006-12-20 16:24:19 +00:00
|
|
|
encapsulation in plugin.c. When using the new style build scripts,
|
|
|
|
stips the parts outlined below:
|
|
|
|
|
2007-10-12 19:13:31 +00:00
|
|
|
o Remove the following include statements:
|
2006-12-20 16:24:19 +00:00
|
|
|
|
|
|
|
#include <gmodule.h>
|
|
|
|
#include "moduleinfo.h"
|
|
|
|
|
|
|
|
o Removed the definition:
|
|
|
|
|
|
|
|
#ifndef ENABLE_STATIC
|
|
|
|
G_MODULE_EXPORT gchar version[] = VERSION;
|
|
|
|
#endif
|
|
|
|
|
|
|
|
o Move relevant code from the blocks and delete these functions:
|
|
|
|
|
|
|
|
#ifndef ENABLE_STATIC
|
|
|
|
plugin_reg_handoff()
|
|
|
|
....
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#ifndef ENABLE_STATIC
|
|
|
|
plugin_register()
|
|
|
|
....
|
|
|
|
#endif
|
|
|
|
|
|
|
|
This will leave a clean dissector source file without plugin specifics.
|
|
|
|
|
|
|
|
5.2 How to update an "old style" plugin (using plugin_init function)
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2005-03-08 19:31:01 +00:00
|
|
|
The plugin registering has changed between 0.10.9 and 0.10.10; everyone
|
|
|
|
is encouraged to update their plugins as outlined below:
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Remove following include statements from all plugin sources:
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
#include "plugins/plugin_api.h"
|
|
|
|
#include "plugins/plugin_api_defs.h"
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Remove the init function.
|
2005-03-08 19:03:09 +00:00
|
|
|
|
2006-04-20 02:39:04 +00:00
|
|
|
o Add a new Makefile.common file with the lists of source files and
|
|
|
|
headers.
|
|
|
|
|
|
|
|
o Change the Makefile.am and Makefile.nmake files to match those of
|
|
|
|
the DOCSIS plugin.
|
2005-03-08 19:03:09 +00:00
|
|
|
|
|
|
|
----------------
|
|
|
|
|
2001-07-10 01:22:58 +00:00
|
|
|
Ed Warnicke <hagbard@physics.rutgers.edu>
|
2006-04-20 02:39:04 +00:00
|
|
|
Guy Harris <guy@alum.mit.edu>
|
2001-07-10 01:22:58 +00:00
|
|
|
|
|
|
|
Derived and expanded from the plugin section of README.developers
|
|
|
|
which was originally written by
|
|
|
|
|
|
|
|
James Coe <jammer@cin.net>
|
2001-11-13 23:55:44 +00:00
|
|
|
Gilbert Ramirez <gram@alumni.rice.edu>
|
2001-07-10 01:22:58 +00:00
|
|
|
Jeff Foster <jfoste@woodward.com>
|
|
|
|
Olivier Abad <oabad@cybercable.fr>
|
2003-01-26 19:35:31 +00:00
|
|
|
Laurent Deniel <laurent.deniel@free.fr>
|
2006-12-20 16:24:19 +00:00
|
|
|
Jaap Keuter <jaap.keuter@xs4all.nl>
|