1a66f9aec9
svn path=/trunk/; revision=7003
310 lines
8.2 KiB
Text
310 lines
8.2 KiB
Text
$Id: README.plugins,v 1.8 2003/01/26 19:35:27 deniel Exp $
|
|
|
|
Plugins
|
|
|
|
Writing a "plugin" dissector is not very different from writing a standard one.
|
|
In fact all of the functions described in the README.developer can be
|
|
used in the plugins exactly as the are used in standard dissectors.
|
|
|
|
Once you have written a packet-xxx.c to create your plugin
|
|
( where xxx is the name of the protocol you are dissecting ) there are
|
|
only a few changes you need to make to "pluginize" your dissector.
|
|
|
|
1 New headers needed in packet-xxx.c
|
|
|
|
#include "plugins/plugin_api.h"
|
|
|
|
Some OSes (Win32) have DLLs that cannot reference symbols in the parent
|
|
executable. So, the executable needs to provide a table of pointers for the DLL
|
|
plugin to use. The plugin_api.h header provides definitions for this (or empty
|
|
definitions on OSes which don't need this).
|
|
|
|
#include "moduleinfo.h"
|
|
|
|
This header is optional and is described in greater detail further on.
|
|
|
|
#include <gmodule.h>
|
|
This header is required to define G_MODULE_EXPORT, which must be used
|
|
when defining constants and functions exported by the plugin.
|
|
|
|
"gmodule.h" includes "glib.h", so you don't need to include "glib.h" if
|
|
you include "gmodule.h"; however, "glib.h" is protected from multiple
|
|
inclusion by #ifdefs, so it's safe to include it after including
|
|
"gmodule.h".
|
|
|
|
#include "plugins/plugin_api_defs.h"
|
|
Only include this in one source file if you have more than one. It defines,
|
|
(as opposed to declares,) the function pointer variables that the plugin uses
|
|
to reference the address table.
|
|
|
|
2 New exported constants in packet-xxx.c
|
|
|
|
Plugins need to provide the following exported constants:
|
|
|
|
#ifndef __ETHEREAL_STATIC__
|
|
G_MODULE_EXPORT const gchar version[] = VERSION;
|
|
#endif
|
|
|
|
version : a version number associated with the plugin.
|
|
|
|
the #ifndef is to allow for the building of a non-plugin version of
|
|
the object for linking into a static ethereal binary.
|
|
|
|
3 New exported functions in packet-xxx.c
|
|
|
|
The following two functions need to be exported by the plugin:
|
|
|
|
#ifndef __ETHEREAL_STATIC__
|
|
G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat)
|
|
#endif
|
|
|
|
This function is called by Ethereal when the plugin is initialized; it's
|
|
similar to the "proto_register_XXX()" routine for a non-plugin
|
|
dissector, except for the name and the call to
|
|
"plugin_address_table_init()".
|
|
|
|
Here is a sample code for the function:
|
|
|
|
/* initialise the table of pointers needed in Win32 DLLs */
|
|
plugin_address_table_init(pat);
|
|
|
|
/* register the new protocol, protocol fields, and subtrees */
|
|
if (proto_xxx == -1) { /* execute protocol initialization only once */
|
|
proto_register_xxx();
|
|
}
|
|
|
|
#ifndef __ETHEREAL_STATIC__
|
|
G_MODULE_EXPORT void plugin_reg_handoff(void)
|
|
#endif
|
|
|
|
This function is called by Ethereal after all dissectors, including all
|
|
plugins, are initialized; it's similar to the "proto_reg_handoff_XXX()"
|
|
routine for a non-plugin dissector, except for the name.
|
|
|
|
Here is a sample code for the function:
|
|
|
|
proto_reg_handoff_xxx();
|
|
|
|
As you can see the plugin_reg_handoff and plugin_init are just
|
|
wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
|
|
|
|
4 Directory structure and other file changes
|
|
|
|
Plugins should be places in plugin/xxx/ which should contain minimally
|
|
the following files:
|
|
|
|
AUTHORS
|
|
COPYING
|
|
ChangeLog
|
|
Makefile.am
|
|
Makefile.nmake
|
|
moduleinfo.h
|
|
packet-xxx.c
|
|
|
|
The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
|
|
files, see plugins/mgcp for examples. You will also need to change
|
|
the plugin/Makefile.am toplevel Makefile.am and toplevel configure.in
|
|
files.
|
|
|
|
3.4.1 plugin/xxx/Makefile.am
|
|
|
|
An example of the Makefile.am follows:
|
|
|
|
INCLUDES = -I$(top_srcdir)
|
|
|
|
plugindir = @plugindir@
|
|
|
|
plugin_LTLIBRARIES = xxx.la
|
|
xxx_la_SOURCES = packet-xxx.c moduleinfo.h
|
|
xxx_la_LDFLAGS = -module -avoid-version
|
|
|
|
# Libs must be cleared, or else libtool won't create a shared module.
|
|
# If your module needs to be linked against any particular libraries,
|
|
# add them here.
|
|
LIBS =
|
|
|
|
|
|
# The following allows a non-plugin version of the module to be built to
|
|
# be linked with a static ethereal binary.
|
|
#
|
|
xxx_la_DEPENDENCIES = packet-xxx-static.o
|
|
|
|
packet-xxx-static.o: packet-xxx.c moduleinfo.h
|
|
$(LTCOMPILE) -c -o packet-xxx-static.o -D__ETHEREAL_STATIC__ $(srcdir)/packet-xxx.c
|
|
|
|
CLEANFILES = \
|
|
xxx \
|
|
EXTRA_DIST = \
|
|
Makefile.nmake
|
|
|
|
|
|
4.2 plugin/xxx/Makefile.nmake
|
|
|
|
Makefile.nmake is used for building the plugin for for Windows.
|
|
|
|
include ..\..\config.nmake
|
|
|
|
############### no need to modify below this line #########
|
|
|
|
CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap \
|
|
/I$(GLIB_DIR) /I$(GTK_DIR) /I$(GLIB_DIR)/gmodule \
|
|
/I$(GTK_DIR)\gdk /I$(GTK_DIR)\gdk\win32 \
|
|
/I$(PCAP_DIR)\include $(LOCAL_CFLAGS)
|
|
|
|
OBJECTS=packet-xxx.obj
|
|
|
|
xxx.dll xxx.exp xxx.lib : packet-xxx.obj ..\plugin_api.obj
|
|
link -dll /out:xxx.dll packet-xxx.obj ..\plugin_api.obj \
|
|
$(GLIB_DIR)\glib-$(GLIB_VERSION).lib
|
|
|
|
clean:
|
|
rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib
|
|
|
|
|
|
4.3 plugin/xxx/moduleinfo.h
|
|
|
|
moduleinfo.h is used to set the version information for the plugin.
|
|
An example follows:
|
|
|
|
/* Included *after* config.h, in order to re-define these macros */
|
|
|
|
#ifdef PACKAGE
|
|
#undef PACKAGE
|
|
#endif
|
|
|
|
/* Name of package */
|
|
#define PACKAGE "xxx"
|
|
|
|
|
|
#ifdef VERSION
|
|
#undef VERSION
|
|
#endif
|
|
|
|
/* Version number of package */
|
|
#define VERSION "0.0.8"
|
|
|
|
4.4 Changes to plugins/Makefile.am
|
|
|
|
The plugins directory contains a Makefile.am.
|
|
You need to change the SUBDIRS directive to reflect the addition of
|
|
your plugin:
|
|
|
|
SUBDIRS = gryphon mgcp xxx
|
|
|
|
|
|
4.5 Changes to plugins/Makefile.nmake
|
|
|
|
To the Makefile.nmake you need to add your plugin to the all: rule
|
|
|
|
all: plugin_api.obj gryphon mgcp xxx
|
|
|
|
then add a rule for your plugin:
|
|
|
|
xxx::
|
|
cd xxx
|
|
$(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
|
|
cd ..
|
|
|
|
and finally add to the clean rule support for cleaning up after your
|
|
plugin:
|
|
|
|
clean:
|
|
rm -f plugin_api.obj
|
|
cd gryphon
|
|
$(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
|
|
cd ../mgcp
|
|
$(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
|
|
cd ..
|
|
cd xxx
|
|
$(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
|
|
cd ..
|
|
|
|
|
|
4.6 Changes to the top level Makefile.am
|
|
|
|
Unfortunately there are quite some several places in the top level
|
|
Makefile.am that need to be altered for adding a plugin.
|
|
|
|
Add your plugin to the plugin_src, plugin_static_ldadd, plugin_libs,
|
|
and plugin_ldadd:
|
|
|
|
plugin_src = \
|
|
plugins/mgcp/packet-mgcp.c \
|
|
plugins/gryphon/packet-gryphon.c \
|
|
plugins/xxx/packet-xxx.c
|
|
|
|
plugin_static_ldadd = \
|
|
plugins/mgcp/packet-mgcp-static.o \
|
|
plugins/gryphon/packet-gryphon-static.o \
|
|
plugins/xxx/packet-xxx-static.o
|
|
|
|
plugin_libs = \
|
|
plugins/gryphon/gryphon.la \
|
|
plugins/mgcp/mgcp.la \
|
|
plugins/xxx/xxx.la
|
|
|
|
plugin_ldadd = \
|
|
"-dlopen" self \
|
|
"-dlopen" plugins/gryphon/gryphon.la \
|
|
"-dlopen" plugins/mgcp/mgcp.la \
|
|
"-dlopen" plugins/xxx/xxx.la
|
|
|
|
4.7 Changes to top level configure.in
|
|
|
|
You need to add your plugins Makefile to the AC_OUTPUT rule in the
|
|
configure.in
|
|
|
|
AC_OUTPUT(
|
|
Makefile
|
|
doc/Makefile
|
|
gtk/Makefile
|
|
packaging/Makefile
|
|
packaging/nsis/Makefile
|
|
packaging/rpm/Makefile
|
|
packaging/rpm/ethereal.spec
|
|
packaging/svr4/Makefile
|
|
packaging/svr4/checkinstall
|
|
packaging/svr4/pkginfo
|
|
plugins/Makefile
|
|
plugins/gryphon/Makefile
|
|
plugins/mgcp/Makefile
|
|
plugins/xxx/Makefile
|
|
tools/Makefile
|
|
tools/lemon/Makefile
|
|
,)
|
|
|
|
|
|
5 Development and plugins
|
|
|
|
Plugins make some aspects of development easier and some harder.
|
|
|
|
The good news is that if you are working on a single plugin
|
|
then you will find recompiling the plugin MUCH faster than
|
|
recompiling a dissector and then linking it back into ethereal.
|
|
|
|
The bad news is that ethereal will not use the plugin unless the
|
|
plugin is installed in one of the places it expects to look.
|
|
|
|
One way to deal with this problem is to set up a working root for
|
|
ethereal, say in $HOME/build/root and build ethereal to install
|
|
there
|
|
|
|
./configure --prefix=${HOME}/build/root;make install
|
|
|
|
then subsequent rebuilds/installs of your plugin can be accomplished
|
|
by going to the plugin/xxx directory and running
|
|
|
|
make install
|
|
|
|
|
|
Ed Warnicke <hagbard@physics.rutgers.edu>
|
|
|
|
Derived and expanded from the plugin section of README.developers
|
|
which was originally written by
|
|
|
|
James Coe <jammer@cin.net>
|
|
Gilbert Ramirez <gram@alumni.rice.edu>
|
|
Jeff Foster <jfoste@woodward.com>
|
|
Olivier Abad <oabad@cybercable.fr>
|
|
Laurent Deniel <laurent.deniel@free.fr>
|