doc/README.plugins

   1 $Id: README.plugins,v 1.10 2004/03/02 23:45:33 jmayer Exp $
   2
   3 Plugins
   4
   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.
   8
   9 (Note, however, that not all OSes on which Ethereal runs can support
  10 plugins.)
  11
  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.
  15
  16 1 New headers needed in packet-xxx.c
  17
  18 #include "plugins/plugin_api.h"
  19
  20 Some OSes (Win32) have DLLs that cannot reference symbols in the parent
  21 executable. So, the executable needs to provide a table of pointers for the DLL
  22 plugin to use. The plugin_api.h header provides definitions for this (or empty
  23 definitions on OSes which don't need this).
  24
  25 #include "moduleinfo.h"
  26
  27 This header is optional and is described in greater detail further on.
  28
  29 #include <gmodule.h>
  30 This header is required to define G_MODULE_EXPORT, which must be used
  31 when defining constants and functions exported by the plugin.
  32
  33 "gmodule.h" includes "glib.h", so you don't need to include "glib.h" if
  34 you include "gmodule.h"; however, "glib.h" is protected from multiple
  35 inclusion by #ifdefs, so it's safe to include it after including
  36 "gmodule.h".
  37
  38 #include "plugins/plugin_api_defs.h"
  39 Only include this in one source file if you have more than one. It defines,
  40 (as opposed to declares,) the function pointer variables that the plugin uses
  41 to reference the address table.
  42
  43 2 New exported constants in packet-xxx.c
  44
  45 Plugins need to provide the following exported constants:
  46
  47 #ifndef ENABLE_STATIC
  48 G_MODULE_EXPORT const gchar version[] = VERSION;
  49 #endif
  50
  51 version       : a version number associated with the plugin.
  52
  53 the #ifndef is to allow for the building of a non-plugin version of
  54 the object for linking into a static ethereal binary.
  55
  56 3 New exported functions in packet-xxx.c
  57
  58 The following two functions need to be exported by the plugin:
  59
  60 #ifndef ENABLE_STATIC
  61 G_MODULE_EXPORT void
  62 plugin_init(plugin_address_table_t *pat)
  63 #endif
  64
  65 This function is called by Ethereal when the plugin is initialized; it's
  66 similar to the "proto_register_XXX()" routine for a non-plugin
  67 dissector, except for the name and the call to
  68 "plugin_address_table_init()".
  69
  70 Here is a sample code for the function:
  71
  72         /* initialise the table of pointers needed in Win32 DLLs */
  73         plugin_address_table_init(pat);
  74
  75         /* register the new protocol, protocol fields, and subtrees */
  76         if (proto_xxx == -1) { /* execute protocol initialization only once */
  77                 proto_register_xxx();
  78         }
  79
  80 #ifndef ENABLE_STATIC
  81 G_MODULE_EXPORT void
  82 plugin_reg_handoff(void)
  83 #endif
  84
  85 This function is called by Ethereal after all dissectors, including all
  86 plugins, are initialized; it's similar to the "proto_reg_handoff_XXX()"
  87 routine for a non-plugin dissector, except for the name.
  88
  89 Here is a sample code for the function:
  90
  91   proto_reg_handoff_xxx();
  92
  93 As you can see the plugin_reg_handoff and plugin_init are just
  94 wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
  95
  96 4 Directory structure and other file changes
  97
  98 Plugins should be places in plugins/xxx/ which should contain minimally
  99 the following files:
 100
 101 AUTHORS
 102 COPYING
 103 ChangeLog
 104 Makefile.am
 105 Makefile.nmake
 106 moduleinfo.h
 107 packet-xxx.c
 108
 109 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
 110 files, see plugins/mgcp for examples.  You will also need to change
 111 the plugins/Makefile.am toplevel Makefile.am, the plugins/Makefile.nmake
 112 toplevel Makefile.nmake, and toplevel configure.in files.
 113
 114 3.4.1 plugins/xxx/Makefile.am
 115
 116 An example of the Makefile.am follows:
 117
 118 INCLUDES = -I$(top_srcdir)
 119
 120 plugindir = @plugindir@
 121
 122 plugin_LTLIBRARIES = xxx.la
 123 xxx_la_SOURCES = packet-xxx.c moduleinfo.h
 124 xxx_la_LDFLAGS = -module -avoid-version
 125
 126 # Libs must be cleared, or else libtool won't create a shared module.
 127 # If your module needs to be linked against any particular libraries,
 128 # add them here.
 129 LIBS =
 130
 131 CLEANFILES = \
 132         xxx
 133
 134 EXTRA_DIST = \
 135         Makefile.nmake
 136
 137
 138 4.2 plugins/xxx/Makefile.nmake
 139
 140 Makefile.nmake is used for building the plugin for for Windows.
 141
 142 include ..\..\config.nmake
 143
 144 ############### no need to modify below this line #########
 145
 146 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
 147         /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
 148
 149 OBJECTS=packet-xxx.obj
 150
 151 xxx.dll xxx.exp xxx.lib : $(OBJECTS) ..\plugin_api.obj
 152         link -dll /out:xxx.dll $(OBJECTS) ..\plugin_api.obj \
 153         $(GLIB_LIBS)
 154
 155 clean:
 156         rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib $(PDB_FILE)
 157
 158
 159 4.3 plugins/xxx/moduleinfo.h
 160
 161 moduleinfo.h is used to set the version information for the plugin.
 162 An example follows:
 163
 164 /* Included *after* config.h, in order to re-define these macros */
 165
 166 #ifdef PACKAGE
 167 #undef PACKAGE
 168 #endif
 169
 170 /* Name of package */
 171 #define PACKAGE "xxx"
 172
 173
 174 #ifdef VERSION
 175 #undef VERSION
 176 #endif
 177
 178 /* Version number of package */
 179 #define VERSION "0.0.8"
 180
 181 4.4  Changes to plugins/Makefile.am
 182
 183 The plugins directory contains a Makefile.am.
 184 You need to change the SUBDIRS directive to reflect the addition of
 185 your plugin:
 186
 187 SUBDIRS = gryphon mgcp xxx
 188
 189
 190 4.5 Changes to plugins/Makefile.nmake
 191
 192 To the Makefile.nmake you need to add your plugin to the all: rule
 193
 194 all: plugin_api.obj gryphon mgcp xxx
 195
 196 then add a rule for your plugin:
 197
 198 xxx::
 199         cd xxx
 200         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
 201         cd ..
 202
 203 and finally add to the clean rule support for cleaning up after your
 204 plugin:
 205
 206 clean:
 207         rm -f plugin_api.obj
 208         cd gryphon
 209         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 210         cd ../mgcp
 211         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 212         cd ..
 213         cd xxx
 214         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 215         cd ..
 216
 217
 218 4.6 Changes to the top level Makefile.am
 219
 220 Unfortunately there are quite some several places in the top level
 221 Makefile.am that need to be altered for adding a plugin.
 222
 223 Add your plugin to the plugin_src, plugin_static_ldadd, plugin_libs,
 224 and plugin_ldadd:
 225
 226 plugin_src = \
 227         plugins/mgcp/packet-mgcp.c      \
 228         plugins/gryphon/packet-gryphon.c \
 229         plugins/xxx/packet-xxx.c
 230
 231 plugin_static_ldadd = \
 232         plugins/mgcp/packet-mgcp-static.o               \
 233         plugins/gryphon/packet-gryphon-static.o         \
 234         plugins/xxx/packet-xxx-static.o
 235
 236 plugin_libs = \
 237         plugins/gryphon/gryphon.la \
 238         plugins/mgcp/mgcp.la    \
 239         plugins/xxx/xxx.la
 240
 241 plugin_ldadd = \
 242         "-dlopen" self  \
 243         "-dlopen" plugins/gryphon/gryphon.la \
 244         "-dlopen" plugins/mgcp/mgcp.la \
 245         "-dlopen" plugins/xxx/xxx.la
 246
 247 4.7  Changes to top level configure.in
 248
 249 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 250 configure.in
 251
 252 AC_OUTPUT(
 253   Makefile
 254   doc/Makefile
 255   gtk/Makefile
 256   packaging/Makefile
 257   packaging/nsis/Makefile
 258   packaging/rpm/Makefile
 259   packaging/rpm/ethereal.spec
 260   packaging/svr4/Makefile
 261   packaging/svr4/checkinstall
 262   packaging/svr4/pkginfo
 263   plugins/Makefile
 264   plugins/gryphon/Makefile
 265   plugins/mgcp/Makefile
 266   plugins/xxx/Makefile
 267   tools/Makefile
 268   tools/lemon/Makefile
 269   ,)
 270
 271
 272 5       Development and plugins
 273
 274 Plugins make some aspects of development easier and some harder.
 275
 276 The good news is that if you are working on a single plugin
 277 then you will find recompiling the plugin MUCH faster than
 278 recompiling a dissector and then linking it back into ethereal.
 279
 280 The bad news is that ethereal will not use the plugin unless the
 281 plugin is installed in one of the places it expects to look.
 282
 283 One way to deal with this problem is to set up a working root for
 284 ethereal, say in $HOME/build/root and build ethereal to install
 285 there
 286
 287 ./configure --prefix=${HOME}/build/root;make install
 288
 289 then subsequent rebuilds/installs of your plugin can be accomplished
 290 by going to the plugins/xxx directory and running
 291
 292 make install
 293
 294
 295 Ed Warnicke <hagbard@physics.rutgers.edu>
 296
 297 Derived and expanded from the plugin section of README.developers
 298 which was originally written by
 299
 300 James Coe <jammer@cin.net>
 301 Gilbert Ramirez <gram@alumni.rice.edu>
 302 Jeff Foster <jfoste@woodward.com>
 303 Olivier Abad <oabad@cybercable.fr>
 304 Laurent Deniel <laurent.deniel@free.fr>