Documentation: fix C++ South plugin signatures involving PLUGIN_HANDLE

Fix the issue fledge-iot#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 <[email protected]>
mbourhis · Oct 13, 2023 · 6bc475a · 6bc475a
1 parent 8ecc5dd
commit 6bc475a
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 29 deletions.
diff --git 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<MyPluginClass *>(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<MyPluginClass *>(*handle);
 
           plugin->configure(&config);
   }

diff --git 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
+
+   <a href="https://github.com/fledge-iot/fledge-south-random" target="_blank">https://github.com/fledge-iot/fledge-south-random</a>
+   <br />
+
+
 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<Random *>(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<Random *>(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
@@ -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<DHT11*>(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<DHT11*>(*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<DHT11*>(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
@@ -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<DHT11 *>(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<Reading *> *plugin_poll(PLUGIN_HANDLE *handle)
+  std::vector<Reading *> *plugin_poll(PLUGIN_HANDLE handle)
   {
-  Modbus *modbus = (Modbus *)handle;
-
           if (!handle)
                   throw runtime_error("Bad plugin handle");
+
+          Modbus *modbus = static_cast<Modbus *>(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<MyPluginClass *>(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<MyPluginClass *>(handle);
           plugin->start();
   }