forked from osmocom/wireshark
![Guy Harris](/assets/img/avatar_default.png)
"epan/..." pathnames, so as to avoid collisions with header files in any of the directories in which we look (e.g., "proto.h", as some other package has its own "proto.h" file which it installs in the top-level include directory). Don't add "-I" flags to search "epan", as that's no longer necessary (and we want includes of "epan" headers to fail if the "epan/" is left out, so that we don't re-introduce includes lacking "epan/"). svn path=/trunk/; revision=4586
304 lines
8 KiB
Text
304 lines
8 KiB
Text
$Id: README.plugins,v 1.5 2002/01/21 07:37:36 guy 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.
|
|
|
|
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".
|
|
|
|
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) -I$(includedir)
|
|
|
|
plugindir = @PLUGIN_DIR@
|
|
|
|
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-mgcp.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 <deniel@worldnet.fr>
|