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 are just
  78 wrappers for the proto_reg_handoff_xxx and proto_register_xxx functions.
  79
  80 4 Directory structure and other file changes
  81
  82 Plugins should be places in plugins/xxx/ which should contain minimally
  83 the following files:
  84
  85 AUTHORS
  86 COPYING
  87 ChangeLog
  88 Makefile.am
  89 Makefile.nmake
  90 moduleinfo.h
  91 packet-xxx.c
  92
  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.
  97
  98 3.4.1 plugins/xxx/Makefile.am
  99
 100 An example of the Makefile.am follows (note that the @foo@ constructs will be
 101 replaced with their actual values when running configure):
 102
 103 INCLUDES = -I$(top_srcdir)
 104
 105 plugindir = @plugindir@
 106
 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@
 111
 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,
 114 # add them here.
 115 LIBS =
 116
 117 CLEANFILES = \
 118         xxx
 119
 120 EXTRA_DIST = \
 121         Makefile.nmake
 122
 123
 124 4.2 plugins/xxx/Makefile.nmake
 125
 126 Makefile.nmake is used for building the plugin for for Windows.
 127
 128 include ..\..\config.nmake
 129
 130 ############### no need to modify below this line #########
 131
 132 CFLAGS=/DHAVE_CONFIG_H /I../.. /I../../wiretap $(GLIB_CFLAGS) \
 133         /I$(PCAP_DIR)\include -D_U_="" $(LOCAL_CFLAGS)
 134
 135 LDFLAGS = /NOLOGO /INCREMENTAL:no /MACHINE:I386 $(LOCAL_LDFLAGS)
 136
 137 !IFDEF ENABLE_LIBETHEREAL
 138 LINK_PLUGIN_WITH=..\..\epan\libethereal.lib
 139 CFLAGS=/DHAVE_WIN32_LIBETHEREAL_LIB /D_NEED_VAR_IMPORT_ $(CFLAGS)
 140
 141 OBJECTS=packet-xxx.obj
 142
 143 xxx.dll xxx.exp xxx.lib : $(OBJECTS) $(LINK_PLUGIN_WITH)
 144         link -dll /out:xxx.dll $(LDFLAGS) $(OBJECTS) $(LINK_PLUGIN_WITH) \
 145         $(GLIB_LIBS)
 146
 147 !ENDIF
 148
 149 clean:
 150         rm -f $(OBJECTS) xxx.dll xxx.exp xxx.lib *.pdb
 151
 152 distclean: clean
 153
 154 maintainer-clean: distclean
 155
 156 4.3 plugins/xxx/moduleinfo.h
 157
 158 moduleinfo.h is used to set the version information for the plugin.
 159 An example follows:
 160
 161 /* Included *after* config.h, in order to re-define these macros */
 162
 163 #ifdef PACKAGE
 164 #undef PACKAGE
 165 #endif
 166
 167 /* Name of package */
 168 #define PACKAGE "xxx"
 169
 170
 171 #ifdef VERSION
 172 #undef VERSION
 173 #endif
 174
 175 /* Version number of package */
 176 #define VERSION "0.0.8"
 177
 178 4.4  Changes to plugins/Makefile.am
 179
 180 The plugins directory contains a Makefile.am.
 181 You need to change the SUBDIRS directive to reflect the addition of
 182 your plugin:
 183
 184 SUBDIRS = gryphon mgcp xxx
 185
 186
 187 4.5 Changes to plugins/Makefile.nmake
 188
 189 To the Makefile.nmake you need to add your plugin to the all: rule
 190
 191 all: plugin_api.obj gryphon mgcp xxx
 192
 193 then add a rule for your plugin:
 194
 195 xxx::
 196         cd xxx
 197         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake
 198         cd ..
 199
 200 and finally add to the clean rule support for cleaning up after your
 201 plugin:
 202
 203 clean:
 204         rm -f plugin_api.obj
 205         cd gryphon
 206         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 207         cd ../mgcp
 208         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 209         cd ..
 210         cd xxx
 211         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake clean
 212         cd ..
 213
 214
 215 distclean: clean
 216         cd gryphon
 217         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 218         cd ../mgcp
 219         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 220         cd ..
 221         cd xxx
 222         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake distclean
 223         cd ..
 224
 225
 226 maintainer-clean: clean
 227         cd gryphon
 228         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 229         cd ../mgcp
 230         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 231         cd ..
 232         cd xxx
 233         $(MAKE) /$(MAKEFLAGS) -f Makefile.nmake maintainer-clean
 234         cd ..
 235
 236
 237 4.6 Changes to the top level Makefile.am
 238
 239 Unfortunately there are quite some several places in the top level
 240 Makefile.am that need to be altered for adding a plugin.
 241
 242 Add your plugin to the plugin_libs and plugin_ldadd (two times):
 243
 244 plugin_libs = \
 245         plugins/gryphon/gryphon.la \
 246         plugins/mgcp/mgcp.la    \
 247         plugins/xxx/xxx.la
 248
 249 if ENABLE_STATIC
 250 plugin_ldadd = \
 251         plugins/gryphon/gryphon.o \
 252         plugins/mgcp/mgcp.o \
 253         plugins/xxx/xxx.o
 254
 255 else          # ENABLE_STATIC
 256 plugin_ldadd = \
 257         "-dlopen" self  \
 258         "-dlopen" plugins/gryphon/gryphon.la \
 259         "-dlopen" plugins/mgcp/mgcp.la \
 260         "-dlopen" plugins/xxx/xxx.la
 261
 262 4.7  Changes to top level configure.in
 263
 264 You need to add your plugins Makefile to the AC_OUTPUT rule in the
 265 configure.in
 266
 267 AC_OUTPUT(
 268   Makefile
 269   doc/Makefile
 270   gtk/Makefile
 271   packaging/Makefile
 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
 278   plugins/Makefile
 279   plugins/gryphon/Makefile
 280   plugins/mgcp/Makefile
 281   plugins/xxx/Makefile
 282   tools/Makefile
 283   tools/lemon/Makefile
 284   ,)
 285
 286
 287 5       Development and plugins
 288
 289 Plugins make some aspects of development easier and some harder.
 290
 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.
 294
 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.
 297
 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
 300 there
 301
 302 ./configure --prefix=${HOME}/build/root;make install
 303
 304 then subsequent rebuilds/installs of your plugin can be accomplished
 305 by going to the plugins/xxx directory and running
 306
 307 make install
 308
 309
 310 6       How to update an "old style" plugin (using plugin_init function)
 311
 312 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
 313 is encouraged to update their plugins as outlined below:
 314
 315 --- Remove following include statements from all plugin sources ---
 316
 317 #include "plugins/plugin_api.h"
 318 #include "plugins/plugin_api_defs.h"
 319
 320 --- Change init function from this ---
 321
 322 G_MODULE_EXPORT void
 323 plugin_init(plugin_address_table_t *pat
 324 #ifndef PLUGINS_NEED_ADDRESS_TABLE
 325 _U_
 326 #endif
 327 ){
 328    /* initialise the table of pointers needed in Win32 DLLs */
 329    plugin_address_table_init(pat);
 330    /* register the new protocol, protocol fields, and subtrees */
 331    if (proto_xxx == -1) { /* execute protocol initialization only once */
 332      proto_register_xxx();
 333    }
 334 }
 335
 336 ------ to this ------
 337
 338 G_MODULE_EXPORT void
 339 plugin_register(void)
 340 {
 341    /* register the new protocol, protocol fields, and subtrees */
 342    if (proto_xxx == -1) { /* execute protocol initialization only once */
 343      proto_register_xxx();
 344    }
 345 }
 346
 347 --- Changes to plugin's Makefile.nmake ---
 348 change
 349 !IFDEF LINK_PLUGINS_WITH_LIBETHEREAL
 350 to
 351 !IFDEF ENABLE_LIBETHEREAL
 352
 353 remove
 354 !ELSE
 355 LINK_PLUGIN_WITH=..\plugin_api.obj
 356
 357 move
 358 !ENDIF
 359 to the line just before the clean target
 360
 361 ----------------
 362
 363 Ed Warnicke <hagbard@physics.rutgers.edu>
 364
 365 Derived and expanded from the plugin section of README.developers
 366 which was originally written by
 367
 368 James Coe <jammer@cin.net>
 369 Gilbert Ramirez <gram@alumni.rice.edu>
 370 Jeff Foster <jfoste@woodward.com>
 371 Olivier Abad <oabad@cybercable.fr>
 372 Laurent Deniel <laurent.deniel@free.fr>