WebSVN – nexmon – Blame – Rev 1 – /utilities/wireshark/doc/README.plugins

1

office

1

1. Plugins

2

3

Writing a "plugin" dissector is not very different from writing a standard

4

one. In fact all of the functions described in README.dissector can be

5

used in the plugins exactly as they are used in standard dissectors.

6

7

(Note, however, that not all OSes on which Wireshark runs can support

8

plugins.)

9

10

If you've chosen "foo" as the name of your plugin (typically, that would

11

be a short name for your protocol, in all lower case), the following

12

instructions tell you how to implement it as a plugin. All occurrences

13

of "foo" below should be replaced by the name of your plugin.

14

15

2. The directory for the plugin, and its files

16

17

The plugin should be placed in a new plugins/foo directory which should

18

contain at least the following files:

AUTHORS

COPYING

ChangeLog

CMakeLists.txt

Makefile.am

moduleinfo.h

plugin.rc.in

And of course the source and header files for your dissector.

29

30

Examples of these files can be found in plugins/gryphon.

31

32

2.1 AUTHORS, COPYING, and ChangeLog

33

34

The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project

files.

2.2 CMakeLists.txt

For your plugins/foo/CMakeLists.txt file, see the corresponding file in

40

plugins/gryphon. Replace all occurrences of "gryphon" in those files

41

with "foo" and add your source files to the DISSECTOR_SRC variable.

2.3 Makefile.am

For your plugins/foo/Makefile.am file, see the corresponding file in

46

plugins/gryphon. Replace all occurrences of "gryphon" in those files

47

with "foo".

48

49

Your plugins/foo/Makefile.am also needs to list the main source file(s),

50

which exports register_*() and handoff_*(), for your dissector in the

51

DISSECTOR_SRC variable. All other supporting source files should be

52

listed in the DISSECTOR_SUPPORT_SRC variable.

53

The header files for your dissector, if any, must be listed in the

54

DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not

55

include moduleinfo.h.

2.4 moduleinfo.h

Your plugins/foo/moduleinfo.h file is used to set the version information

for the plugin.

2.5 plugin.rc.in

Your plugins/foo/plugin.rc.in is the Windows resource template file used

65

to add the plugin specific information as resources to the DLL.

66

No modifications are needed here.

67

68

3. Changes to existing Wireshark files

69

70

There are two ways to add your plugin dissector to the build, as a custom

71

extension or as a permanent addition. The custom extension is easy to

72

configure, but won't be used for inclusion in the distribution if that's

73

your goal. Setting up the permanent addition is somewhat more involved.

74

75

3.1 Custom extension

76

77

Go to the plugins directory and copy the Custom.m4.example and

78

Custom.make.example files to files of the same name but without the ".example"

79

suffix. Now you have two Custom files ready for building a plugin with the

80

name "foo". Replace the name if you so require.

81

82

If you want to add the plugin to your own Windows installer add a text

83

file named custom_plugins.txt to the packaging/nsis directory, with a

84

"File" statement for NSIS:

85

86

File "..\..\plugins\foo\foo.dll"

87

88

For CMake builds, either pass the custom plugin dir on the CMake generation

89

step command line:

90

91

CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/foo"

92

93

or copy the top-level file CMakeListsCustom.txt.example to CMakeListsCustom.txt

94

(also in the top-level source dir) and edit so that CUSTOM_PLUGIN_SRC_DIR is

95

set() to the relative path of your plugin, e.g.

96

97

set(CUSTOM_PLUGIN_SRC_DIR plugins/foo)

98

99

and re-run the CMake generation step.

100

101

To build the plugin, run your normal Wireshark build step.

102

103

3.2 Permanent addition

104

105

In order to be able to permanently add a plugin take the following steps.

106

You will need to change the following files:

configure.ac

CMakeLists.txt

epan/Makefile.am

Makefile.am

packaging/nsis/wireshark.nsi

112

plugins/Makefile.am

113

114

You might also want to search your Wireshark development directory for

115

occurrences of an existing plugin name, in case this document is out of

116

date with the current directory structure. For example,

grep -rl gryphon .

could be used from a shell prompt.

121

122

3.2.1 Changes to plugins/Makefile.am

123

124

The plugins directory contains a Makefile.am. You need to add to SUBDIRS

125

(in alphabetical order) the name of your plugin:

126

127

SUBDIRS = $(_CUSTOM_SUBDIRS_) \

...

ethercat \

foo \

gryphon \

irda \

3.2.2 Changes to the top level Makefile.am

136

137

Add your plugin (in alphabetical order) to plugin_ldadd:

if HAVE_PLUGINS

plugin_ldadd = $(_CUSTOM_plugin_ldadd_) \

142

...

143

-dlopen plugins/ethercat/ethercat.la \

144

-dlopen plugins/foo/foo.la \

145

-dlopen plugins/gryphon/gryphon.la \

146

-dlopen plugins/irda/irda.la \

147

...

148

149

3.2.3 Changes to the top level configure.ac

150

151

You need to add your plugins Makefile (in alphabetical order) to the

152

AC_OUTPUT rule in the configure.ac

AC_OUTPUT(

...

plugins/ethercat/Makefile

157

plugins/foo/Makefile

158

plugins/gryphon/Makefile

159

plugins/irda/Makefile

...

,)

3.2.4 Changes to epan/Makefile.am

164

165

Add the relative path of all your plugin source files (in alphbetical

166

order) to plugin_src:

plugin_src = \

...

../plugins/ethercat/packet-ioraw.c \

171

../plugins/ethercat/packet-nv.c \

172

../plugins/foo/packet-foo.c \

173

../plugins/gryphon/packet-gryphon.c \

174

../plugins/irda/packet-ircomm.c \

175

../plugins/irda/packet-irda.c \

176

...

177

178

3.2.5 Changes to CMakeLists.txt

179

180

Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:

if(ENABLE_PLUGINS)

...

set(PLUGIN_SRC_DIRS

...

plugins/ethercat

plugins/foo

plugins/gryphon

plugins/irda

...

3.2.6 Changes to the installers

193

194

If you want to include your plugin in an installer you have to add lines

195

in the NSIS installer wireshark.nsi file.

196

197

3.2.6.1 Changes to packaging/nsis/wireshark.nsi

198

199

Add the relative path of your plugin DLL (in alphbetical order) to the

200

list of "File" statements in the "Dissector Plugins" section:

201

202

File "${STAGING_DIR}\plugins\${VERSION}\ethercat.dll"

203

File "${STAGING_DIR}\plugins\${VERSION}\foo.dll"

204

File "${STAGING_DIR}\plugins\${VERSION}\gryphon.dll"

205

File "${STAGING_DIR}\plugins\${VERSION}\irda.dll"

206

207

3.2.6.2 Other installers

208

209

The PortableApps installer copies plugins from the build directory

210

and should not require configuration.

211

212

4. Development and plugins on Unix

213

214

Plugins make some aspects of development easier and some harder.

215

216

The first thing is that you'll have to run autogen.sh and configure once

217

more to setup your build environment.

218

219

The good news is that if you are working on a single plugin then you will

220

find recompiling the plugin MUCH faster than recompiling a dissector and

221

then linking it back into Wireshark. Use "make -C plugins" to compile just

222

your plugins.

223

224

The bad news is that Wireshark will not use the plugins unless the plugins

225

are installed in one of the places it expects them to find.

226

227

One way of dealing with this problem is to set an environment variable

228

when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.

229

230

Another way to deal with this problem is to set up a working root for

231

wireshark, say in $HOME/build/root and build wireshark to install

232

there

233

234

./configure --prefix=${HOME}/build/root && make install

235

236

then subsequent rebuilds/installs of your plugin can be accomplished

237

by going to the plugins/foo directory and running

make install

5. Update "old style" plugins

242

243

5.1 How to update an "old style" plugin (using plugin_register and

244

plugin_reg_handoff functions).

245

246

The plugin registration has changed with the extension of the build

247

scripts. These now generate the additional code needed for plugin

248

encapsulation in plugin.c. When using the new style build scripts,

249

stips the parts outlined below:

250

251

o Remove the following include statements:

252

253

#include <gmodule.h>

254

#include "moduleinfo.h"

255

256

o Removed the definition:

257

258

#ifndef ENABLE_STATIC

259

WS_DLL_PUBLIC_DEF gchar version[] = VERSION;

260

#endif

261

262

o Move relevant code from the blocks and delete these functions:

263

264

#ifndef ENABLE_STATIC

265

plugin_reg_handoff()

....

#endif

#ifndef ENABLE_STATIC

plugin_register()

....

#endif

This will leave a clean dissector source file without plugin specifics.

275

276

5.2 How to update an "old style" plugin (using plugin_init function)

277

278

The plugin registering has changed between 0.10.9 and 0.10.10; everyone

279

is encouraged to update their plugins as outlined below:

280

281

o Remove following include statements from all plugin sources:

282

283

#include "plugins/plugin_api.h"

284

#include "plugins/plugin_api_defs.h"

285

286

o Remove the init function.

287

288

o Change the Makefile.am file to match the one of the DOCSIS plugin.

289

290

291

6 How to plugin related interface options

292

293

6.1 Implement a plugin GUI menu

294

295

A plugin (as well as built-in dissectors) may implement a menu within

296

Wireshark to be used to trigger options, start tools, open Websites, ...

297

298

This menu structure is built using the plugin_if.h interface and its

299

corresponding functions.

300

301

The menu items all call a callback provided by the plugin, which takes

302

a pointer to the menuitem entry ad data. This pointer may be used to

303

provide userdata to each entry. The pointer must utilize WS_DLL_PUBLIC_DEF

304

and has the following structure:

305

306

WS_DLL_PUBLIC_DEF void

307

menu_cb(ext_menubar_gui_type gui_type, gpointer gui_data,

308

gpointer user_data _U_)

309

{

310

... Do something ...

311

}

312

313

The menu entries themselves are generated with the following code structure:

314

315

ext_menu_t * ext_menu, *os_menu = NULL;

316

317

ext_menu = ext_menubar_register_menu (

318

<your_proto_item>, "Some Menu Entry", TRUE );

319

ext_menubar_add_entry(ext_menu, "Test Entry 1",

320

"This is a tooltip", menu_cb, <user_data>);

321

ext_menubar_add_entry(ext_menu, "Test Entry 2",

322

NULL, menu_cb, <user_data>);

323

324

os_menu = ext_menubar_add_submenu(ext_menu, "Sub Menu" );

325

ext_menubar_add_entry(os_menu, "Test Entry A",

326

NULL, menu_cb, <user_data>);

327

ext_menubar_add_entry(os_menu, "Test Entry B",

328

NULL, menu_cb, <user_data>);

329

330

This will not work with the GTK version on OS X; the GTK interface is

331

currently not supported on this platform. The Qt interface on OS X

332

provides the menu.

333

334

For a more detailed information, please refer to plugin_if.h

335

336

6.2 Implement interactions with the main interface

337

338

Due to memory constraints on most platforms, plugin functionality cannot be

339

called directly from a DLL context. Instead special functions will be used, which

340

will implement certain options for plugins to utilize.

341

342

The following methods exist so far:

343

344

/* Applies the given filter string as display filter */

345

WS_DLL_PUBLIC void plugin_if_apply_filter

346

(const char * filter_string, gboolean force);

347

348

/* Saves the given preference to the main preference storage */

349

WS_DLL_PUBLIC void plugin_if_save_preference

350

(const char * pref_module, const char * pref_key, const char * pref_value);

351

352

/* Jumps to the given frame number */

353

WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr);

----------------

Ed Warnicke <hagbard@physics.rutgers.edu>

360

Guy Harris <guy@alum.mit.edu>

361

362

Derived and expanded from the plugin section of README.developers

363

which was originally written by

364

365

James Coe <jammer@cin.net>

366

Gilbert Ramirez <gram@alumni.rice.edu>

367

Jeff Foster <jfoste@woodward.com>

368

Olivier Abad <oabad@cybercable.fr>

369

Laurent Deniel <laurent.deniel@free.fr>

370

Jaap Keuter <jaap.keuter@xs4all.nl>

nexmon – Blame information for rev 1