diff options
author | Ed Warnicke <hagbard@physics.rutgers.edu> | 2001-07-10 01:22:58 +0000 |
---|---|---|
committer | Ed Warnicke <hagbard@physics.rutgers.edu> | 2001-07-10 01:22:58 +0000 |
commit | 9e6250e3368a19717012b014d82df1d6ecccfdb2 (patch) | |
tree | 46d01c959120628290a88a1415b963ac0be0d872 /doc/README.plugins | |
parent | 1d4c6365c06a951b7043b54cb047005de2476995 (diff) |
Moved documentation for plugins to README.plugins and expanded
it. Removed most of the Plugins section from README.developers
svn path=/trunk/; revision=3675
Diffstat (limited to 'doc/README.plugins')
-rw-r--r-- | doc/README.plugins | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/doc/README.plugins b/doc/README.plugins new file mode 100644 index 0000000000..ebb336a7b0 --- /dev/null +++ b/doc/README.plugins @@ -0,0 +1,354 @@ +$Id: README.plugins,v 1.1 2001/07/10 01:22:58 hagbard 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. +# +noinst_PROGRAMS = 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../../epan /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_SRC = \ + plugins/mgcp/packet-mgcp.c \ + plugins/gryphon/packet-gryphon.c \ + plugins/xxx/packet-xxx.c + + +Add your plugin library to the ethereal_DEPENDENCIES + +ethereal_DEPENDENCIES = \ + $(ethereal_optional_objects) \ + $(ethereal_additional_libs) \ + plugins/gryphon/gryphon.la \ + plugins/mgcp/mgcp.la \ + plugins/xxx/xxx.la + +Add your plugin library to the ethereal_LDADD and ethereal_static_LDADD + +ethereal_LDADD = \ + $(ethereal_optional_objects) \ + $(ethereal_additional_libs) \ + @SNMP_LIBS@ @SSL_LIBS@ \ + "-dlopen" self \ + "-dlopen" plugins/gryphon/gryphon.la \ + "-dlopen" plugins/mgcp/mgcp.la \ + "-dlopen" plugins/xxx/xxx.la \ + @PCAP_LIBS@ @GTK_LIBS@ + +ethereal_static_LDADD = \ + "-all-static" \ + plugins/mgcp/packet-mgcp-static.o \ + plugins/gryphon/packet-gryphon-static.o \ + plugins/xxx/packet-xxx-static.o \ + $(ethereal_optional_objects) \ + $(ethereal_additional_libs) \ + @SNMP_LIBS@ @SSL_LIBS@ \ + @PCAP_LIBS@ @GTK_LIBS@ + +Add your plugin library to the tethereal_DEPENDENCIES + +tethereal_DEPENDENCIES = \ + $(ethereal_optional_objects) \ + $(tethereal_additional_libs) \ + plugins/gryphon/gryphon.la \ + plugins/mgcp/mgcp.la \ + plugins/xxx/xxx.la + +And to tethereal_LDADD and tethereal_static_LDADD + +tethereal_LDADD = wiretap/libwiretap.a \ + $(ethereal_optional_objects) \ + $(tethereal_additional_libs) \ + @SNMP_LIBS@ @SSL_LIBS@ \ + "-dlopen" self \ + "-dlopen" plugins/gryphon/gryphon.la \ + "-dlopen" plugins/mgcp/mgcp.la \ + "-dlopen" plugins/xxx/xxx.la \ + @GLIB_LIBS@ -lm \ + @PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@ + +tethereal_static_LDADD = \ + "-all-static" \ + plugins/mgcp/packet-mgcp-static.o \ + plugins/gryphon/packet-gryphon-static.o \ + plugins/xxx/packet-xxx-static.o \ + wiretap/libwiretap.a \ + $(ethereal_optional_objects) \ + $(tethereal_additional_libs) \ + @SNMP_LIBS@ @SSL_LIBS@ \ + @GLIB_LIBS@ -lm \ + @PCAP_LIBS@ @SOCKET_LIBS@ @NSL_LIBS@ + + + +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@xiexie.org> +Jeff Foster <jfoste@woodward.com> +Olivier Abad <oabad@cybercable.fr> +Laurent Deniel <deniel@worldnet.fr> |