$Id$ 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. (Note, however, that not all OSes on which Ethereal runs can support plugins.) 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 "moduleinfo.h" This header is optional and is described in greater detail further on. #include 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 ENABLE_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 ENABLE_STATIC G_MODULE_EXPORT void plugin_register(void) #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. Here is a sample code for the function: /* register the new protocol, protocol fields, and subtrees */ if (proto_xxx == -1) { /* execute protocol initialization only once */ proto_register_xxx(); } #ifndef ENABLE_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_register 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 plugins/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 plugins/Makefile.am toplevel Makefile.am, the plugins/Makefile.nmake toplevel Makefile.nmake, and toplevel configure.in files. 3.4.1 plugins/xxx/Makefile.am An example of the Makefile.am follows (note that the @foo@ constructs will be replaced with their actual values when running configure): INCLUDES = -I$(top_srcdir) plugindir = @plugindir@ plugin_LTLIBRARIES = xxx.la xxx_la_SOURCES = packet-xxx.c moduleinfo.h xxx_la_LDFLAGS = -module -avoid-version xxx_la_LIBADD = @PLUGIN_LIBS@ # 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 = CLEANFILES = \ xxx EXTRA_DIST = \ Makefile.nmake 4.2 plugins/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 $(GLIB_CFLAGS) \ /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS) LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS) !IFDEF ENABLE_LIBETHEREAL LINK_PLUGIN_WITH=..\..\epan\libethereal.lib CFLAGS=/DHAVE_WIN32_LIBETHEREAL_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS) OBJECTS=packet-xxx.obj xxx.dll xxx.exp xxx.lib : $(OBJECTS) $(LINK_PLUGIN_WITH) link -dll /out:xxx.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) \ $(GLIB_LIBS) !ENDIF clean: rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib *.pdb distclean: clean maintainer-clean: distclean 4.3 plugins/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 .. distclean: clean cd gryphon $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean cd ../mgcp $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean cd .. cd xxx $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean cd .. maintainer-clean: clean cd gryphon $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean cd ../mgcp $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean cd .. cd xxx $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-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_libs and plugin_ldadd (two times): plugin_libs = \ plugins/gryphon/gryphon.la \ plugins/mgcp/mgcp.la \ plugins/xxx/xxx.la if ENABLE_STATIC plugin_ldadd = \ plugins/gryphon/gryphon.o \ plugins/mgcp/mgcp.o \ plugins/xxx/xxx.o else # ENABLE_STATIC 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 plugins/xxx directory and running make install 6 How to update an "old style" plugin (using plugin_init function) The plugin registering has changed between 0.10.9 and 0.10.10, everyone is encouraged to update it's plugins as outlined below: --- Remove following include statements from all plugin sources --- #include "plugins/plugin_api.h" #include "plugins/plugin_api_defs.h" --- Change init function from this --- G_MODULE_EXPORT void plugin_init(plugin_address_table_t *pat #ifndef PLUGINS_NEED_ADDRESS_TABLE _U_ #endif ){ /* 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(); } } ------ to this ------ G_MODULE_EXPORT void plugin_register(void) { /* register the new protocol, protocol fields, and subtrees */ if (proto_xxx == -1) { /* execute protocol initialization only once */ proto_register_xxx(); } } --- Changes to plugin's Makefile.nmake --- change !IFDEF LINK_PLUGINS_WITH_LIBETHEREAL to !IFDEF ENABLE_LIBETHEREAL remove !ELSE LINK_PLUGIN_WITH=..\plugin_api.obj move !ENDIF to the line just before the clean target ---------------- 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