diff options
| author | João Valverde <j@v6e.pt> | 2023-12-01 18:45:48 +0000 |
|---|---|---|
| committer | João Valverde <j@v6e.pt> | 2023-12-14 16:18:35 +0000 |
| commit | 7f32c90ab9b7c6f19fb38011d5cb0b7ce815046c (patch) | |
| tree | 65921674336f414a68e65911425c4629cbc2929b /doc | |
| parent | b52d9173f8f0201a360bc1d5ada38297a6e13553 (diff) | |
plugins: Add a codecs API level
Add a minimum and maximum API level. Backward-compatible changes to
the API only bump the maximum API level. Backward incompatible
changes bump the maximum API level and the mininum, to the
new (maximum) level.
This may allow codec plugins to continue working without recompilation,
possibly with reduced functionality.
The API level is only defined for codecs because it is a small
and easy to define API, and very stable.
Maybe we could do the same for wiretap (file type) plugins. For the
various epan plugin types it seems pointless and futile. I cannot
see a scenario where a new Wireshark minor release does not increase
the minimum API level.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.plugins | 23 |
1 files changed, 21 insertions, 2 deletions
diff --git a/doc/README.plugins b/doc/README.plugins index 39973dc91f..190621d9ae 100644 --- a/doc/README.plugins +++ b/doc/README.plugins @@ -169,7 +169,9 @@ by going to the plugins/foo directory and running make install -5. Plugin registration API common to all plugin types +5. Plugin registration + +5.1 Registration API common to all plugin types You must include the plugin API header: @@ -218,7 +220,24 @@ WIRESHARK_PLUGIN_REGISTER_CODEC(&module, 0) As the name implies each plugin binary type has a specific registration macro (but they all have the same arguments). The macro takes a pointer to the struct ws_module as the first argument. The second argument is -currently unused and should be zero. +unused only by codec plugins and explained in the next section. For all +other plugin types it is ignored and should be zero. + +5.2 The plugin minimum API level argument + +The ABI version test for equality is the main check for compatibility for +all plugin types but additionally the codec plugin API has an extra +check called the API level. The codec API is very small and changes very +infrequently. Codecs plugins that only use the API in wsutil/codecs.h should +declare a minimum API level required. If the API needs to be changed and that +can be done in a backward-compatible manner for the ABI/API then only the +maximum API level will be increased and the minimum API level can stay the same. + +This means the same plugin can still be loaded successfully without +recompilation using the older API (possibly with reduced functionality). + +This is currently experimental and may change in the future or be removed +entirely. 6 How to plugin related interface options |