path: root/doc/README.plugins

$Id: README.plugins,v 1.13 2004/07/03 21:50:05 tuexen 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.

(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 "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 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_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 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_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 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)

OBJECTS=packet-xxx.obj 

xxx.dll xxx.exp xxx.lib : $(OBJECTS) ..\plugin_api.obj
	link -dll /out:xxx.dll $(OBJECTS) ..\plugin_api.obj \
	$(GLIB_LIBS)

clean:
	rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib $(PDB_FILE)

distclean: clean

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 ..


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


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>