5 Writing a "plugin" dissector is not very different from writing a standard one.
6 In fact all of the functions described in the README.developer can be
7 used in the plugins exactly as the are used in standard dissectors.
9 (Note, however, that not all OSes on which Ethereal runs can support
12 Once you have written a packet-xxx.c to create your plugin
13 ( where xxx is the name of the protocol you are dissecting ) there are
14 only a few changes you need to make to "pluginize" your dissector.
16 1 New headers needed in packet-xxx.c
18 #include "moduleinfo.h"
20 This header is optional and is described in greater detail further on.
23 This header is required to define G_MODULE_EXPORT, which must be used
24 when defining constants and functions exported by the plugin.
26 "gmodule.h" includes "glib.h", so you don't need to include "glib.h" if
27 you include "gmodule.h"; however, "glib.h" is protected from multiple
28 inclusion by #ifdefs, so it's safe to include it after including
31 2 New exported constants in packet-xxx.c
33 Plugins need to provide the following exported constants:
36 G_MODULE_EXPORT const gchar version[] = VERSION;
39 version : a version number associated with the plugin.
41 the #ifndef is to allow for the building of a non-plugin version of
42 the object for linking into a static ethereal binary.
44 3 New exported functions in packet-xxx.c
46 The following two functions need to be exported by the plugin:
53 This function is called by Ethereal when the plugin is initialized; it's
54 similar to the "proto_register_XXX()" routine for a non-plugin
55 dissector, except for the name.
57 Here is a sample code for the function:
59 /* register the new protocol, protocol fields, and subtrees */
60 if (proto_xxx == -1) { /* execute protocol initialization only once */
66 plugin_reg_handoff(void)
69 This function is called by Ethereal after all dissectors, including all
70 plugins, are initialized; it's similar to the "proto_reg_handoff_XXX()"
71 routine for a non-plugin dissector, except for the name.
73 Here is a sample code for the function:
75 proto_reg_handoff_xxx();
77 As you can see the plugin_reg_handoff and plugin_init are just
78 wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
80 4 Directory structure and other file changes
82 Plugins should be places in plugins/xxx/ which should contain minimally
93 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
94 files, see plugins/mgcp for examples. You will also need to change
95 the plugins/Makefile.am toplevel Makefile.am, the plugins/Makefile.nmake
96 toplevel Makefile.nmake, and toplevel configure.in files.
98 3.4.1 plugins/xxx/Makefile.am
100 An example of the Makefile.am follows (note that the @foo@ constructs will be
101 replaced with their actual values when running configure):
103 INCLUDES = -I$(top_srcdir)
105 plugindir = @plugindir@
107 plugin_LTLIBRARIES = xxx.la
108 xxx_la_SOURCES = packet-xxx.c moduleinfo.h
109 xxx_la_LDFLAGS = -module -avoid-version
110 xxx_la_LIBADD = @PLUGIN_LIBS@
112 # Libs must be cleared, or else libtool won't create a shared module.
113 # If your module needs to be linked against any particular libraries,
124 4.2 plugins/xxx/Makefile.nmake
126 Makefile.nmake is used for building the plugin for for Windows.
128 include ..\..\config.nmake
130 ############### no need to modify below this line #########
132 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
133 /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
135 LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS)
137 !IFDEF ENABLE_LIBETHEREAL
138 LINK_PLUGIN_WITH=..\..\epan\libethereal.lib
139 CFLAGS=/DHAVE_WIN32_LIBETHEREAL_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS)
141 OBJECTS=packet-xxx.obj
143 xxx.dll xxx.exp xxx.lib : $(OBJECTS) $(LINK_PLUGIN_WITH)
144 link -dll /out:xxx.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) \
150 rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib *.pdb
154 maintainer-clean: distclean
156 4.3 plugins/xxx/moduleinfo.h
158 moduleinfo.h is used to set the version information for the plugin.
161 /* Included *after* config.h, in order to re-define these macros */
167 /* Name of package */
168 #define PACKAGE "xxx"
175 /* Version number of package */
176 #define VERSION "0.0.8"
178 4.4 Changes to plugins/Makefile.am
180 The plugins directory contains a Makefile.am.
181 You need to change the SUBDIRS directive to reflect the addition of
184 SUBDIRS = gryphon mgcp xxx
187 4.5 Changes to plugins/Makefile.nmake
189 To the Makefile.nmake you need to add your plugin to the all: rule
191 all: plugin_api.obj gryphon mgcp xxx
193 then add a rule for your plugin:
197 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
200 and finally add to the clean rule support for cleaning up after your
206 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
208 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
211 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
217 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
219 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
222 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
226 maintainer-clean: clean
228 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
230 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
233 $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
237 4.6 Changes to the top level Makefile.am
239 Unfortunately there are quite some several places in the top level
240 Makefile.am that need to be altered for adding a plugin.
242 Add your plugin to the plugin_libs and plugin_ldadd (two times):
245 plugins/gryphon/gryphon.la \
246 plugins/mgcp/mgcp.la \
251 plugins/gryphon/gryphon.o \
252 plugins/mgcp/mgcp.o \
258 "-dlopen" plugins/gryphon/gryphon.la \
259 "-dlopen" plugins/mgcp/mgcp.la \
260 "-dlopen" plugins/xxx/xxx.la
262 4.7 Changes to top level configure.in
264 You need to add your plugins Makefile to the AC_OUTPUT rule in the
272 packaging/nsis/Makefile
273 packaging/rpm/Makefile
274 packaging/rpm/ethereal.spec
275 packaging/svr4/Makefile
276 packaging/svr4/checkinstall
277 packaging/svr4/pkginfo
279 plugins/gryphon/Makefile
280 plugins/mgcp/Makefile
287 5 Development and plugins
289 Plugins make some aspects of development easier and some harder.
291 The good news is that if you are working on a single plugin
292 then you will find recompiling the plugin MUCH faster than
293 recompiling a dissector and then linking it back into ethereal.
295 The bad news is that ethereal will not use the plugin unless the
296 plugin is installed in one of the places it expects to look.
298 One way to deal with this problem is to set up a working root for
299 ethereal, say in $HOME/build/root and build ethereal to install
302 ./configure --prefix=${HOME}/build/root;make install
304 then subsequent rebuilds/installs of your plugin can be accomplished
305 by going to the plugins/xxx directory and running
310 Ed Warnicke <hagbard@physics.rutgers.edu>
312 Derived and expanded from the plugin section of README.developers
313 which was originally written by
315 James Coe <jammer@cin.net>
316 Gilbert Ramirez <gram@alumni.rice.edu>
317 Jeff Foster <jfoste@woodward.com>
318 Olivier Abad <oabad@cybercable.fr>
319 Laurent Deniel <laurent.deniel@free.fr>