$Id: README.plugins,v 1.4 2001/11/13 23:55:35 gram 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../../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_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 Derived and expanded from the plugin section of README.developers which was originally written by James Coe Gilbert Ramirez Jeff Foster Olivier Abad Laurent Deniel