From 6bc475a9e3a9a408f22ebfc058398c4379a74d2b Mon Sep 17 00:00:00 2001 From: Mikael Bourhis Date: Fri, 6 Jan 2023 17:31:31 +0100 Subject: [PATCH] Documentation: fix C++ South plugin signatures involving PLUGIN_HANDLE Fix the issue #1069 In the 'plugin_developers_guide/03_south_C_plugins.html' documentation page, the signature of some plugin functions involving PLUGIN_HANDLE is erroneous. According to the definitions of the function pointers about the South plugins ($FLEDGE_ROOT/C/services/south/include/south_plugin.h), fix these signatures. And use the appropriate C++ 'cast' operator, more restrictive and accurate 'cast' operator than the C one, for the 'PLUGIN_HANDLE' object. Signed-off-by: Mikael Bourhis --- .../02_writing_plugins.rst | 10 ++++---- .../plugin_developers_guide/03_02_Control.rst | 22 +++++++++++++----- .../plugin_developers_guide/03_02_DHT11_C.rst | 12 +++++----- .../03_south_C_plugins.rst | 23 +++++++++---------- 4 files changed, 38 insertions(+), 29 deletions(-) diff --git a/docs/plugin_developers_guide/02_writing_plugins.rst b/docs/plugin_developers_guide/02_writing_plugins.rst index 2a309f8c1..6e17b3db0 100644 --- a/docs/plugin_developers_guide/02_writing_plugins.rst +++ b/docs/plugin_developers_guide/02_writing_plugins.rst @@ -228,7 +228,7 @@ A C/C++ plugin should return a value in a *void* pointer that can then be derefe */ PLUGIN_HANDLE plugin_init(ConfigCategory *config) { - MyPluginClass *plugin = new MyPluginClass(); + MyPluginClass *plugin = new MyPluginClass(); plugin->configure(config); @@ -252,9 +252,9 @@ A C/C++ plugin might use this *plugin_shutdown* call to delete the plugin class /** * Shutdown the plugin */ - void plugin_shutdown(PLUGIN_HANDLE *handle) + void plugin_shutdown(PLUGIN_HANDLE handle) { - MyPluginClass *plugin = (MyPluginClass *)handle; + MyPluginClass *plugin = static_cast(handle); delete plugin; } @@ -300,8 +300,8 @@ In C/C++ the *plugin_reconfigure* method is very similar, note however that the */ void plugin_reconfigure(PLUGIN_HANDLE *handle, string& newConfig) { - ConfigCategory config("newConfiguration", newConfig); - MyPluginClass *plugin = (MyPluginClass *)*handle; + ConfigCategory config("newConfiguration", newConfig); + MyPluginClass *plugin = static_cast(*handle); plugin->configure(&config); } diff --git a/docs/plugin_developers_guide/03_02_Control.rst b/docs/plugin_developers_guide/03_02_Control.rst index eb8f95ad8..d01460886 100644 --- a/docs/plugin_developers_guide/03_02_Control.rst +++ b/docs/plugin_developers_guide/03_02_Control.rst @@ -1,3 +1,11 @@ +.. Links in new tabs + +.. |fledge South Random| raw:: html + + https://github.com/fledge-iot/fledge-south-random +
+ + Set Point Control ----------------- @@ -57,7 +65,7 @@ The plugin write entry point is defined as follows .. code-block:: C - bool plugin_write(PLUGIN_HANDLE *handle, string name, string value) + bool plugin_write(PLUGIN_HANDLE handle, string name, string value) Where the parameters are; @@ -71,9 +79,9 @@ The return value defines if the write was successful or not. True is returned fo .. code-block:: C - bool plugin_write(PLUGIN_HANDLE *handle, string& name, string& value) + bool plugin_write(PLUGIN_HANDLE handle, string& name, string& value) { - Random *random = (Random *)handle; + Random *random = static_cast(handle); return random->write(operation, name, value); } @@ -120,7 +128,7 @@ The plugin write operation entry point is defined as follows .. code-block:: C - bool plugin_operation(PLUGIN_HANDLE *handle, string& operation, int count, PLUGIN_PARAMETER **params) + bool plugin_operation(PLUGIN_HANDLE handle, string& operation, int count, PLUGIN_PARAMETER **params) Where the parameters are; @@ -140,9 +148,9 @@ The following example shows the implementation of the plugin operation entry poi .. code-block:: C - bool plugin_operation(PLUGIN_HANDLE *handle, string& operation, int count, PLUGIN_PARAMETER **params) + bool plugin_operation(PLUGIN_HANDLE handle, string& operation, int count, PLUGIN_PARAMETER **params) { - Random *random = (Random *)handle; + Random *random = static_cast(handle); return random->operation(operation, count, params); } @@ -185,4 +193,6 @@ In this case the implementation in the plugin class is as follows: In this example, the operation method checks the name of the operation to perform, only a single operation is supported by this plugin. If this operation name differs the method will log an error and return false. If the operation is recognized it will check for any arguments passed in, retrieve and use it. In this case an optional *seed* argument may be passed. +The full source code, including the *Random* class can be found in GitHub |fledge South Random| + There is no actual machine connected here, therefore the operation occurs within the plugin. In the case of a real machine the operation would most likely cause an action on a machine, for example a request to the machine to re-calibrate itself. diff --git a/docs/plugin_developers_guide/03_02_DHT11_C.rst b/docs/plugin_developers_guide/03_02_DHT11_C.rst index da6b2ea39..dcf76ede8 100644 --- a/docs/plugin_developers_guide/03_02_DHT11_C.rst +++ b/docs/plugin_developers_guide/03_02_DHT11_C.rst @@ -151,9 +151,9 @@ This is the code for the plugin.cpp file that provides the plugin API: /** * Poll for a plugin reading */ - Reading plugin_poll(PLUGIN_HANDLE *handle) + Reading plugin_poll(PLUGIN_HANDLE handle) { - DHT11 *dht11 = (DHT11*)handle; + DHT11 *dht11 = static_cast(handle); return dht11->takeReading(); } @@ -162,8 +162,8 @@ This is the code for the plugin.cpp file that provides the plugin API: */ void plugin_reconfigure(PLUGIN_HANDLE *handle, string& newConfig) { - ConfigCategory conf("dht", newConfig); - DHT11 *dht11 = (DHT11*)*handle; + ConfigCategory conf("dht", newConfig); + DHT11 *dht11 = static_cast(*handle); if (conf.itemExists("asset")) dht11->setAssetName(conf.getValue("asset")); @@ -177,9 +177,9 @@ This is the code for the plugin.cpp file that provides the plugin API: /** * Shutdown the plugin */ - void plugin_shutdown(PLUGIN_HANDLE *handle) + void plugin_shutdown(PLUGIN_HANDLE handle) { - DHT11 *dht11 = (DHT11*)handle; + DHT11 *dht11 = static_cast(handle); delete dht11; } }; diff --git a/docs/plugin_developers_guide/03_south_C_plugins.rst b/docs/plugin_developers_guide/03_south_C_plugins.rst index abd1ffb6f..cd502047d 100644 --- a/docs/plugin_developers_guide/03_south_C_plugins.rst +++ b/docs/plugin_developers_guide/03_south_C_plugins.rst @@ -53,9 +53,9 @@ It is important that the *poll* method does not block as this will prevent the p /** * Poll for a plugin reading */ - Reading plugin_poll(PLUGIN_HANDLE *handle) + Reading plugin_poll(PLUGIN_HANDLE handle) { - DHT11 *dht11 = (DHT11*)handle; + DHT11 *dht11 = static_cast(handle); return dht11->takeReading(); } @@ -111,12 +111,12 @@ It is possible in a C/C++ plugin to have a plugin that returns multiple readings /** * Poll for a plugin reading */ - std::vector *plugin_poll(PLUGIN_HANDLE *handle) + std::vector *plugin_poll(PLUGIN_HANDLE handle) { - Modbus *modbus = (Modbus *)handle; - if (!handle) throw runtime_error("Bad plugin handle"); + + Modbus *modbus = static_cast(handle); return modbus->takeReading(); } @@ -135,12 +135,12 @@ The *plugin_register_ingest* call is used to allow the south service to pass a c /** * Register ingest callback */ - void plugin_register_ingest(PLUGIN_HANDLE *handle, INGEST_CB cb, void *data) + void plugin_register_ingest(PLUGIN_HANDLE handle, INGEST_CB cb, void *data) { - MyPluginClass *plugin = (MyPluginClass *)handle; - if (!handle) throw new exception(); + + MyPluginClass *plugin = static_cast(handle); plugin->registerIngest(data, cb); } @@ -182,13 +182,12 @@ The *plugin_start* method, as with other plugin calls, is called with the plugin /** * Start the Async handling for the plugin */ - void plugin_start(PLUGIN_HANDLE *handle) + void plugin_start(PLUGIN_HANDLE handle) { - MyPluginClass *plugin = (MyPluginClass *)handle; - - if (!handle) return; + + MyPluginClass *plugin = static_cast(handle); plugin->start(); }