diff --git a/doc/README.plugins b/doc/README.plugins index de18dcb5c8..14b1896870 100644 --- a/doc/README.plugins +++ b/doc/README.plugins @@ -1,4 +1,15 @@ -1. Plugins +0. Plugins + +There are a multitude of plugin options available in Wireshark that allow to +extend its functionality without changing the source code itself. Using the +available APIs gives you the means to do this. + +Currently plugin APIs are available for dissectors (epan), capture file types +(wiretap) and media decoders (codecs). This README focuses primarily on +dissector plugins; most of the descriptions are applicable to the other plugin +types as well. + +1. Dissector plugins Writing a "plugin" dissector is not very different from writing a standard one. In fact all of the functions described in README.dissector can be @@ -14,7 +25,7 @@ of "foo" below should be replaced by the name of your plugin. 2. The directory for the plugin, and its files -The plugin should be placed in a new plugins/foo directory which should +The plugin should be placed in a new plugins/epan/foo directory which should contain at least the following files: CMakeLists.txt @@ -27,21 +38,21 @@ Optionally you can add your own plugin.rc.in. And of course the source and header files for your dissector. -Examples of these files can be found in plugins/gryphon. +Examples of these files can be found in plugins/epan/gryphon. 2.1 CMakeLists.txt -For your plugins/foo/CMakeLists.txt file, see the corresponding file in -plugins/gryphon. Replace all occurrences of "gryphon" in those files +For your plugins/epan/foo/CMakeLists.txt file, see the corresponding file in +plugins/epan/gryphon. Replace all occurrences of "gryphon" in those files with "foo" and add your source files to the DISSECTOR_SRC variable. 2.2 Makefile.am -For your plugins/foo/Makefile.am file, see the corresponding file in -plugins/gryphon. Replace all occurrences of "gryphon" in those files +For your plugins/epan/foo/Makefile.am file, see the corresponding file in +plugins/epan/gryphon. Replace all occurrences of "gryphon" in those files with "foo". -Your plugins/foo/Makefile.am also needs to list the main source file +Your plugins/epan/foo/Makefile.am also needs to list the main source file which exports plugin_register() for your dissector in the DISSECTOR_SRC variable. All other supporting source files should be listed in the DISSECTOR_SUPPORT_SRC variable. @@ -50,7 +61,7 @@ DISSECTOR_INCLUDES variable. 2.4 plugin.rc.in -Your plugins/foo/plugin.rc.in is the Windows resource template file used +Your plugins/epan/foo/plugin.rc.in is the Windows resource template file used to add the plugin specific information as resources to the DLL. If not provided the plugins/plugin.rc.in file will be used. @@ -72,18 +83,18 @@ If you want to add the plugin to your own Windows installer add a text file named custom_plugins.txt to the packaging/nsis directory, with a "File" statement for NSIS: -File "..\..\plugins\foo\foo.dll" +File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll" For CMake builds, either pass the custom plugin dir on the CMake generation step command line: -CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/foo" +CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/epan/foo" or copy the top-level file CMakeListsCustom.txt.example to CMakeListsCustom.txt (also in the top-level source dir) and edit so that CUSTOM_PLUGIN_SRC_DIR is set() to the relative path of your plugin, e.g. -set(CUSTOM_PLUGIN_SRC_DIR plugins/foo) +set(CUSTOM_PLUGIN_SRC_DIR plugins/epan/foo) and re-run the CMake generation step. @@ -115,10 +126,10 @@ The plugins directory contains a Makefile.am. You need to add to SUBDIRS SUBDIRS = $(_CUSTOM_SUBDIRS_) \ ... - ethercat \ - foo \ - gryphon \ - irda \ + epan/ethercat \ + epan/foo \ + epan/gryphon \ + epan/irda \ 3.2.2 Changes to the top level configure.ac @@ -128,10 +139,10 @@ AC_OUTPUT rule in the configure.ac AC_OUTPUT( ... - plugins/ethercat/Makefile - plugins/foo/Makefile - plugins/gryphon/Makefile - plugins/irda/Makefile + plugins/epan/ethercat/Makefile + plugins/epan/foo/Makefile + plugins/epan/gryphon/Makefile + plugins/epan/irda/Makefile ... ,) @@ -142,12 +153,12 @@ order) to plugin_src: plugin_src = \ ... - ../plugins/ethercat/packet-ioraw.c \ - ../plugins/ethercat/packet-nv.c \ - ../plugins/foo/packet-foo.c \ - ../plugins/gryphon/packet-gryphon.c \ - ../plugins/irda/packet-ircomm.c \ - ../plugins/irda/packet-irda.c \ + ../plugins/epan/ethercat/packet-ioraw.c \ + ../plugins/epan/ethercat/packet-nv.c \ + ../plugins/epan/foo/packet-foo.c \ + ../plugins/epan/gryphon/packet-gryphon.c \ + ../plugins/epan/irda/packet-ircomm.c \ + ../plugins/epan/irda/packet-irda.c \ ... 3.2.4 Changes to CMakeLists.txt @@ -158,10 +169,10 @@ if(ENABLE_PLUGINS) ... set(PLUGIN_SRC_DIRS ... - plugins/ethercat - plugins/foo - plugins/gryphon - plugins/irda + plugins/epan/ethercat + plugins/epan/foo + plugins/epan/gryphon + plugins/epan/irda ... 3.2.5 Changes to the installers @@ -174,10 +185,10 @@ in the NSIS installer wireshark.nsi file. Add the relative path of your plugin DLL (in alphbetical order) to the list of "File" statements in the "Dissector Plugins" section: -File "${STAGING_DIR}\plugins\${VERSION}\ethercat.dll" -File "${STAGING_DIR}\plugins\${VERSION}\foo.dll" -File "${STAGING_DIR}\plugins\${VERSION}\gryphon.dll" -File "${STAGING_DIR}\plugins\${VERSION}\irda.dll" +File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\ethercat.dll" +File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll" +File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\gryphon.dll" +File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\irda.dll" 3.2.5.2 Other installers @@ -296,9 +307,9 @@ is encouraged to update their plugins as outlined below: 6 How to plugin related interface options -To demonstrate the functionality of the plugin interface options, a demonstration -plugin exists (pluginifdemo). To build it using cmake, the build option ENABLE_PLUGINIFDEMO -has to be enabled. +To demonstrate the functionality of the plugin interface options, a +demonstration plugin exists (pluginifdemo). To build it using cmake, the +build option ENABLE_PLUGINIFDEMO has to be enabled. 6.1 Implement a plugin GUI menu @@ -346,8 +357,8 @@ For a more detailed information, please refer to plugin_if.h 6.2 Implement interactions with the main interface Due to memory constraints on most platforms, plugin functionality cannot be -called directly from a DLL context. Instead special functions will be used, which -will implement certain options for plugins to utilize. +called directly from a DLL context. Instead special functions will be used, +which will implement certain options for plugins to utilize. The following methods exist so far: diff --git a/plugins/Makefile.am.inc b/plugins/Makefile.am.inc index 5a0326223a..3a560ee2c6 100644 --- a/plugins/Makefile.am.inc +++ b/plugins/Makefile.am.inc @@ -152,39 +152,6 @@ CPP_FILES = \ $(LEMON_GENERATED_CPP_FILES) \ $(NONGENERATED_CPP_FILES) -# -# Build plugin.c, which contains the plugin_version[] string, a -# function plugin_register() that calls the register routines for all -# protocols, and a function plugin_reg_handoff() that calls the handoff -# registration routines for all protocols. -# -# We do this by scanning sources. If that turns out to be too slow, -# maybe we could just require every .o file to have an register routine -# of a given name (packet-aarp.o -> proto_register_aarp, etc.). -# -# Formatting conventions: The name of the proto_register_* routines an -# proto_reg_handoff_* routines must start in column zero, or must be -# preceded only by "void " starting in column zero, and must not be -# inside #if. -# -# REGISTER_SRC_FILES is assumed to have all the files that need to be scanned. -# -# For some unknown reason, having a big "for" loop in the Makefile -# to scan all the files doesn't work with some "make"s; they seem to -# pass only the first few names in the list to the shell, for some -# reason. -# -# Therefore, we use a script to generate the register.c file. -# The first argument is the directory in which the source files live. -# The second argument is "plugin", to indicate that we should build -# a plugin.c file for a plugin. -# All subsequent arguments are the files to scan. -# -plugin.c: $(REGISTER_SRC_FILES) $(top_srcdir)/tools/make-plugin-reg.py - @echo Making plugin.c - @$(PYTHON) $(top_srcdir)/tools/make-plugin-reg.py $(srcdir) \ - plugin $(REGISTER_SRC_FILES) - checkapi: $(PERL) $(top_srcdir)/tools/checkAPIs.pl -g abort -g termoutput -build \ -sourcedir=$(srcdir) \ diff --git a/plugins/codecs/Makefile.am.inc b/plugins/codecs/Makefile.am.inc new file mode 100644 index 0000000000..14ac941b08 --- /dev/null +++ b/plugins/codecs/Makefile.am.inc @@ -0,0 +1,42 @@ +# Makefile.am.inc +# Include file with common automake definitions for codec plugins +# +# Wireshark - Network traffic analyzer +# By Gerald Combs +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0+ +# + +include $(top_srcdir)/plugins/Makefile.am.inc + +# +# Build plugin.c, which contains the plugin_version[] and plugin_release[] +# string, and a function plugin_register() that calls the register routines +# for all codecs. +# +# We do this by scanning sources. If that turns out to be too slow, +# maybe we could just require every .o file to have an register routine +# of a given name (packet-aarp.o -> proto_register_aarp, etc.). +# +# Formatting conventions: The name of the codec_register_* routines must +# start in column zero, or must be preceded only by "void " starting in +# column zero, and must not be inside #if. +# +# REGISTER_SRC_FILES is assumed to have all the files that need to be scanned. +# +# For some unknown reason, having a big "for" loop in the Makefile +# to scan all the files doesn't work with some "make"s; they seem to +# pass only the first few names in the list to the shell, for some +# reason. +# +# Therefore, we use a script to generate the register.c file. +# The first argument is the directory in which the source files live. +# The second argument is "plugin_codec", to indicate that we should build +# a plugin.c file for a codec plugin. +# All subsequent arguments are the files to scan. +# +plugin.c: $(REGISTER_SRC_FILES) $(top_srcdir)/tools/make-plugin-reg.py + @echo Making plugin.c + @$(PYTHON) $(top_srcdir)/tools/make-plugin-reg.py $(srcdir) \ + plugin_codec $(REGISTER_SRC_FILES) diff --git a/plugins/epan/Makefile.am.inc b/plugins/epan/Makefile.am.inc new file mode 100644 index 0000000000..5c7f5256ec --- /dev/null +++ b/plugins/epan/Makefile.am.inc @@ -0,0 +1,43 @@ +# Makefile.am.inc +# Include file with common automake definitions for dissector plugins +# +# Wireshark - Network traffic analyzer +# By Gerald Combs +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0+ +# + +include $(top_srcdir)/plugins/Makefile.am.inc + +# +# Build plugin.c, which contains the plugin_version[] and plugin_release[] +# string, and a function plugin_register() that calls the register routines +# for all protocols. +# +# We do this by scanning sources. If that turns out to be too slow, +# maybe we could just require every .o file to have an register routine +# of a given name (packet-aarp.o -> proto_register_aarp, etc.). +# +# Formatting conventions: The name of the proto_register_* routines and +# proto_reg_handoff_* routines must start in column zero, or must be +# preceded only by "void " starting in column zero, and must not be +# inside #if. +# +# REGISTER_SRC_FILES is assumed to have all the files that need to be scanned. +# +# For some unknown reason, having a big "for" loop in the Makefile +# to scan all the files doesn't work with some "make"s; they seem to +# pass only the first few names in the list to the shell, for some +# reason. +# +# Therefore, we use a script to generate the register.c file. +# The first argument is the directory in which the source files live. +# The second argument is "plugin", to indicate that we should build +# a plugin.c file for a dissector plugin. +# All subsequent arguments are the files to scan. +# +plugin.c: $(REGISTER_SRC_FILES) $(top_srcdir)/tools/make-plugin-reg.py + @echo Making plugin.c + @$(PYTHON) $(top_srcdir)/tools/make-plugin-reg.py $(srcdir) \ + plugin $(REGISTER_SRC_FILES) diff --git a/plugins/epan/docsis/Makefile.am b/plugins/epan/docsis/Makefile.am index 3137cbab87..33200bf47c 100644 --- a/plugins/epan/docsis/Makefile.am +++ b/plugins/epan/docsis/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = docsis diff --git a/plugins/epan/ethercat/Makefile.am b/plugins/epan/ethercat/Makefile.am index e9cde19249..5a06af9ef9 100644 --- a/plugins/epan/ethercat/Makefile.am +++ b/plugins/epan/ethercat/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = ethercat diff --git a/plugins/epan/gryphon/Makefile.am b/plugins/epan/gryphon/Makefile.am index 81495fdd7c..46fa7c1562 100644 --- a/plugins/epan/gryphon/Makefile.am +++ b/plugins/epan/gryphon/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = gryphon diff --git a/plugins/epan/irda/Makefile.am b/plugins/epan/irda/Makefile.am index 1678d88874..77f891645f 100644 --- a/plugins/epan/irda/Makefile.am +++ b/plugins/epan/irda/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = irda diff --git a/plugins/epan/mate/Makefile.am b/plugins/epan/mate/Makefile.am index bb1f576f74..786d4a5d65 100644 --- a/plugins/epan/mate/Makefile.am +++ b/plugins/epan/mate/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = mate diff --git a/plugins/epan/opcua/Makefile.am b/plugins/epan/opcua/Makefile.am index 1023747325..d119418166 100644 --- a/plugins/epan/opcua/Makefile.am +++ b/plugins/epan/opcua/Makefile.am @@ -20,7 +20,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = opcua diff --git a/plugins/epan/pluginifdemo/Makefile.am b/plugins/epan/pluginifdemo/Makefile.am index aca6a56b94..bad9605bc9 100644 --- a/plugins/epan/pluginifdemo/Makefile.am +++ b/plugins/epan/pluginifdemo/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = pluginifdemo diff --git a/plugins/epan/profinet/Makefile.am b/plugins/epan/profinet/Makefile.am index ce0888690c..0bb8b2fc9e 100644 --- a/plugins/epan/profinet/Makefile.am +++ b/plugins/epan/profinet/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = profinet diff --git a/plugins/epan/stats_tree/Makefile.am b/plugins/epan/stats_tree/Makefile.am index 1b4c9326cf..ec4feb51f2 100644 --- a/plugins/epan/stats_tree/Makefile.am +++ b/plugins/epan/stats_tree/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = stats_tree diff --git a/plugins/epan/transum/Makefile.am b/plugins/epan/transum/Makefile.am index 615255c66b..19bce627c9 100644 --- a/plugins/epan/transum/Makefile.am +++ b/plugins/epan/transum/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = transum diff --git a/plugins/epan/unistim/Makefile.am b/plugins/epan/unistim/Makefile.am index 8c1ea042f1..c6051aa980 100644 --- a/plugins/epan/unistim/Makefile.am +++ b/plugins/epan/unistim/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = unistim diff --git a/plugins/epan/wimax/Makefile.am b/plugins/epan/wimax/Makefile.am index 3074a525a5..0e37798377 100644 --- a/plugins/epan/wimax/Makefile.am +++ b/plugins/epan/wimax/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = wimax diff --git a/plugins/epan/wimaxasncp/Makefile.am b/plugins/epan/wimaxasncp/Makefile.am index c2f122c3b0..4443b15883 100644 --- a/plugins/epan/wimaxasncp/Makefile.am +++ b/plugins/epan/wimaxasncp/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = wimaxasncp diff --git a/plugins/epan/wimaxmacphy/Makefile.am b/plugins/epan/wimaxmacphy/Makefile.am index 3edb07567a..d69df68bac 100644 --- a/plugins/epan/wimaxmacphy/Makefile.am +++ b/plugins/epan/wimaxmacphy/Makefile.am @@ -19,7 +19,7 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. include $(top_srcdir)/Makefile.am.inc -include $(top_srcdir)/plugins/Makefile.am.inc +include $(top_srcdir)/plugins/epan/Makefile.am.inc # the name of the plugin PLUGIN_NAME = wimaxmacphy diff --git a/plugins/wiretap/Makefile.am.inc b/plugins/wiretap/Makefile.am.inc new file mode 100644 index 0000000000..eab1328465 --- /dev/null +++ b/plugins/wiretap/Makefile.am.inc @@ -0,0 +1,42 @@ +# Makefile.am.inc +# Include file with common automake definitions for wiretap plugins +# +# Wireshark - Network traffic analyzer +# By Gerald Combs +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0+ +# + +include $(top_srcdir)/plugins/Makefile.am.inc + +# +# Build plugin.c, which contains the plugin_version[] and plugin_release[] +# string, and a function plugin_register() that calls the register routines +# for all wiretap modules. +# +# We do this by scanning sources. If that turns out to be too slow, +# maybe we could just require every .o file to have an register routine +# of a given name (packet-aarp.o -> proto_register_aarp, etc.). +# +# Formatting conventions: The name of the wtap_register_* routines must +# start in column zero, or must be preceded only by "void " starting in +# column zero, and must not be inside #if. +# +# REGISTER_SRC_FILES is assumed to have all the files that need to be scanned. +# +# For some unknown reason, having a big "for" loop in the Makefile +# to scan all the files doesn't work with some "make"s; they seem to +# pass only the first few names in the list to the shell, for some +# reason. +# +# Therefore, we use a script to generate the register.c file. +# The first argument is the directory in which the source files live. +# The second argument is "plugin_wtap", to indicate that we should build +# a plugin.c file for a wiretap plugin. +# All subsequent arguments are the files to scan. +# +plugin.c: $(REGISTER_SRC_FILES) $(top_srcdir)/tools/make-plugin-reg.py + @echo Making plugin.c + @$(PYTHON) $(top_srcdir)/tools/make-plugin-reg.py $(srcdir) \ + plugin_wtap $(REGISTER_SRC_FILES)