doc/README.plugins

   1 $Id$
   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 "moduleinfo.h"
  19
  20 This header is optional and is described in greater detail further on.
  21
  22 #include <gmodule.h>
  23 This header is required to define G_MODULE_EXPORT, which must be used
  24 when defining constants and functions exported by the plugin.
  25
  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
  29 "gmodule.h".
  30
  31 2 New exported constants in packet-xxx.c
  32
  33 Plugins need to provide the following exported constants:
  34
  35 #ifndef ENABLE_STATIC
  36 G_MODULE_EXPORT const gchar version[] = VERSION;
  37 #endif
  38
  39 version       : a version number associated with the plugin.
  40
  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.
  43
  44 3 New exported functions in packet-xxx.c
  45
  46 The following two functions need to be exported by the plugin:
  47
  48 #ifndef ENABLE_STATIC
  49 G_MODULE_EXPORT void
  50 plugin_register(void)
  51 #endif
  52
  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.
  56
  57 Here is a sample code for the function:
  58
  59         /* register the new protocol, protocol fields, and subtrees */
  60         if (proto_xxx == -1) { /* execute protocol initialization only once */
  61                 proto_register_xxx();
  62         }
  63
  64 #ifndef ENABLE_STATIC
  65 G_MODULE_EXPORT void
  66 plugin_reg_handoff(void)
  67 #endif
  68
  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.
  72
  73 Here is a sample code for the function:
  74
  75   proto_reg_handoff_xxx();
  76
  77 As you can see, the plugin_reg_handoff and plugin_register functions are
  78 just wrappers for the proto_reg_handoff_xxx and proto_register_xxx
  79 functions.
  80
  81 4 Directory structure and other file changes
  82
  83 Plugins should be places in plugins/xxx/ which should contain minimally
  84 the following files:
  85
  86 AUTHORS
  87 COPYING
  88 ChangeLog
  89 Makefile.am
  90 Makefile.nmake
  91 moduleinfo.h
  92 packet-xxx.c
  93
  94 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
  95 files, see plugins/mgcp for examples.  You will also need to change
  96 the plugins/Makefile.am toplevel Makefile.am, the plugins/Makefile.nmake
  97 toplevel Makefile.nmake, and toplevel configure.in files.
  98
  99 3.4.1 plugins/xxx/Makefile.am
 100
 101 An example of the Makefile.am follows (note that the @foo@ constructs will be
 102 replaced with their actual values when running configure):
 103
 104 INCLUDES = -I$(top_srcdir)
 105
 106 plugindir = @plugindir@
 107
 108 plugin_LTLIBRARIES = xxx.la
 109 xxx_la_SOURCES = packet-xxx.c moduleinfo.h
 110 xxx_la_LDFLAGS = -module -avoid-version
 111 xxx_la_LIBADD = @PLUGIN_LIBS@
 112
 113 # Libs must be cleared, or else libtool won't create a shared module.
 114 # If your module needs to be linked against any particular libraries,
 115 # add them here.
 116 LIBS =
 117
 118 CLEANFILES = \
 119         xxx
 120
 121 EXTRA_DIST = \
 122         Makefile.nmake
 123
 124
 125 4.2 plugins/xxx/Makefile.nmake
 126
 127 Makefile.nmake is used for building the plugin for for Windows.
 128
 129 include ..\..\config.nmake
 130
 131 ############### no need to modify below this line #########
 132
 133 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
 134         /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
 135
 136 LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS)
 137
 138 !IFDEF ENABLE_LIBETHEREAL
 139 LINK_PLUGIN_WITH=..\..\epan\libethereal.lib
 140 CFLAGS=/DHAVE_WIN32_LIBETHEREAL_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS)
 141
 142 OBJECTS=packet-xxx.obj
 143
 144 xxx.dll xxx.exp xxx.lib : $(OBJECTS) $(LINK_PLUGIN_WITH)
 145         link -dll /out:xxx.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) \
 146         $(GLIB_LIBS)
 147
 148 !ENDIF
 149
 150 clean:
 151         rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib *.pdb
 152
 153 distclean: clean
 154
 155 maintainer-clean: distclean
 156
 157 4.3 plugins/xxx/moduleinfo.h
 158
 159 moduleinfo.h is used to set the version information for the plugin.
 160 An example follows:
 161
 162 /* Included *after* config.h, in order to re-define these macros */
 163
 164 #ifdef PACKAGE
 165 #undef PACKAGE
 166 #endif
 167
 168 /* Name of package */
 169 #define PACKAGE "xxx"
 170
 171
 172 #ifdef VERSION
 173 #undef VERSION
 174 #endif
 175
 176 /* Version number of package */
 177 #define VERSION "0.0.8"
 178
 179 4.4  Changes to plugins/Makefile.am
 180
 181 The plugins directory contains a Makefile.am.
 182 You need to change the SUBDIRS directive to reflect the addition of
 183 your plugin:
 184
 185 SUBDIRS = gryphon mgcp xxx
 186
 187
 188 4.5 Changes to plugins/Makefile.nmake
 189
 190 To the Makefile.nmake you need to add your plugin to the all: rule
 191
 192 all: plugin_api.obj gryphon mgcp xxx
 193
 194 then add a rule for your plugin:
 195
 196 xxx::
 197         cd xxx
 198         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
 199         cd ..
 200
 201 and finally add to the clean rule support for cleaning up after your
 202 plugin:
 203
 204 clean:
 205         rm -f plugin_api.obj
 206         cd gryphon
 207         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 208         cd ../mgcp
 209         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 210         cd ..
 211         cd xxx
 212         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 213         cd ..
 214
 215
 216 distclean: clean
 217         cd gryphon
 218         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 219         cd ../mgcp
 220         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 221         cd ..
 222         cd xxx
 223         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 224         cd ..
 225
 226
 227 maintainer-clean: clean
 228         cd gryphon
 229         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 230         cd ../mgcp
 231         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 232         cd ..
 233         cd xxx
 234         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 235         cd ..
 236
 237
 238 4.6 Changes to the top level Makefile.am
 239
 240 Unfortunately there are quite some several places in the top level
 241 Makefile.am that need to be altered for adding a plugin.
 242
 243 Add your plugin to the plugin_libs and plugin_ldadd (two times):
 244
 245 plugin_libs = \
 246         plugins/gryphon/gryphon.la \
 247         plugins/mgcp/mgcp.la    \
 248         plugins/xxx/xxx.la
 249
 250 if ENABLE_STATIC
 251 plugin_ldadd = \
 252         plugins/gryphon/gryphon.o \
 253         plugins/mgcp/mgcp.o \
 254         plugins/xxx/xxx.o
 255
 256 else          # ENABLE_STATIC
 257 plugin_ldadd = \
 258         "-dlopen" self  \
 259         "-dlopen" plugins/gryphon/gryphon.la \
 260         "-dlopen" plugins/mgcp/mgcp.la \
 261         "-dlopen" plugins/xxx/xxx.la
 262
 263 4.7  Changes to top level configure.in
 264
 265 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 266 configure.in
 267
 268 AC_OUTPUT(
 269   Makefile
 270   doc/Makefile
 271   gtk/Makefile
 272   packaging/Makefile
 273   packaging/nsis/Makefile
 274   packaging/rpm/Makefile
 275   packaging/rpm/ethereal.spec
 276   packaging/svr4/Makefile
 277   packaging/svr4/checkinstall
 278   packaging/svr4/pkginfo
 279   plugins/Makefile
 280   plugins/gryphon/Makefile
 281   plugins/mgcp/Makefile
 282   plugins/xxx/Makefile
 283   tools/Makefile
 284   tools/lemon/Makefile
 285   ,)
 286
 287
 288 5       Development and plugins
 289
 290 Plugins make some aspects of development easier and some harder.
 291
 292 The good news is that if you are working on a single plugin
 293 then you will find recompiling the plugin MUCH faster than
 294 recompiling a dissector and then linking it back into ethereal.
 295
 296 The bad news is that ethereal will not use the plugin unless the
 297 plugin is installed in one of the places it expects to look.
 298
 299 One way to deal with this problem is to set up a working root for
 300 ethereal, say in $HOME/build/root and build ethereal to install
 301 there
 302
 303 ./configure --prefix=${HOME}/build/root;make install
 304
 305 then subsequent rebuilds/installs of your plugin can be accomplished
 306 by going to the plugins/xxx directory and running
 307
 308 make install
 309
 310
 311 6       How to update an "old style" plugin (using plugin_init function)
 312
 313 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
 314 is encouraged to update their plugins as outlined below:
 315
 316 --- Remove following include statements from all plugin sources ---
 317
 318 #include "plugins/plugin_api.h"
 319 #include "plugins/plugin_api_defs.h"
 320
 321 --- Change init function from this ---
 322
 323 G_MODULE_EXPORT void
 324 plugin_init(plugin_address_table_t *pat
 325 #ifndef PLUGINS_NEED_ADDRESS_TABLE
 326 _U_
 327 #endif
 328 ){
 329    /* initialise the table of pointers needed in Win32 DLLs */
 330    plugin_address_table_init(pat);
 331    /* register the new protocol, protocol fields, and subtrees */
 332    if (proto_xxx == -1) { /* execute protocol initialization only once */
 333      proto_register_xxx();
 334    }
 335 }
 336
 337 ------ to this ------
 338
 339 G_MODULE_EXPORT void
 340 plugin_register(void)
 341 {
 342    /* register the new protocol, protocol fields, and subtrees */
 343    if (proto_xxx == -1) { /* execute protocol initialization only once */
 344      proto_register_xxx();
 345    }
 346 }
 347
 348 --- Changes to plugin's Makefile.nmake ---
 349 change
 350 !IFDEF LINK_PLUGINS_WITH_LIBETHEREAL
 351 to
 352 !IFDEF ENABLE_LIBETHEREAL
 353
 354 remove
 355 !ELSE
 356 LINK_PLUGIN_WITH=..\plugin_api.obj
 357
 358 move
 359 !ENDIF
 360 to the line just before the clean target
 361
 362 ----------------
 363
 364 Ed Warnicke <hagbard@physics.rutgers.edu>
 365
 366 Derived and expanded from the plugin section of README.developers
 367 which was originally written by
 368
 369 James Coe <jammer@cin.net>
 370 Gilbert Ramirez <gram@alumni.rice.edu>
 371 Jeff Foster <jfoste@woodward.com>
 372 Olivier Abad <oabad@cybercable.fr>
 373 Laurent Deniel <laurent.deniel@free.fr>