LCOV - code coverage report
Current view: top level - src/libs/plugin - plugin.c (source / functions) Hit Total Coverage
Test: coverage-filtered.info Lines: 29 32 90.6 %
Date: 2019-09-12 12:28:41 Functions: 5 5 100.0 %

          Line data    Source code
       1             : /**
       2             :  * @file
       3             :  *
       4             :  * @brief Access plugin handle.
       5             :  *
       6             :  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
       7             :  */
       8             : 
       9             : #ifdef HAVE_KDBCONFIG_H
      10             : #include "kdbconfig.h"
      11             : #endif
      12             : 
      13             : #include <kdbassert.h>
      14             : #include <kdbinternal.h>
      15             : 
      16             : 
      17             : /**
      18             :  * @brief Allows one to Export Methods for a Plugin.
      19             :  *
      20             :  * This function must be called within ELEKTRA_PLUGIN_EXPORT.
      21             :  * It define the plugin's methods that will be exported.
      22             :  *
      23             :  * All KDB methods implemented by the plugin basically could
      24             :  * have random names (convention is elektraName*), except
      25             :  * ELEKTRA_PLUGIN_EXPORT.
      26             :  *
      27             :  * This is the single symbol that will be looked up
      28             :  * when loading the plugin, and the first method of the backend
      29             :  * implementation that will be called.
      30             :  *
      31             :  * You need to use a macro so that both dynamic and static loading
      32             :  * of the plugin works. For example for the doc plugin:
      33             :  * @snippet doc.c export
      34             :  *
      35             :  * The first parameter is the name of the plugin.
      36             :  * Then every plugin should have:
      37             :  * @c ELEKTRA_PLUGIN_OPEN,
      38             :  * @c ELEKTRA_PLUGIN_CLOSE,
      39             :  * @c ELEKTRA_PLUGIN_GET,
      40             :  * @c ELEKTRA_PLUGIN_SET and optionally
      41             :  * @c ELEKTRA_PLUGIN_ERROR and
      42             :  * @c ELEKTRA_PLUGIN_COMMIT.
      43             :  *
      44             :  * The list is terminated with
      45             :  * @c ELEKTRA_PLUGIN_END.
      46             :  *
      47             :  * You must use static "char arrays" in a read only segment.
      48             :  * Don't allocate storage, it won't be freed.
      49             :  *
      50             :  * @param pluginName the name of this plugin
      51             :  * @return an object that contains all plugin information needed by
      52             :  *      libelektra.so
      53             :  * @ingroup plugin
      54             :  */
      55      169593 : Plugin * elektraPluginExport (const char * pluginName, ...)
      56             : {
      57             :         va_list va;
      58             :         Plugin * returned;
      59      169593 :         plugin_t method = 0;
      60             : 
      61      169593 :         if (pluginName == 0) return 0;
      62             : 
      63      169593 :         returned = elektraCalloc (sizeof (struct _Plugin));
      64             : 
      65             :         /* Start processing parameters */
      66      169593 :         va_start (va, pluginName);
      67      169593 :         returned->name = pluginName;
      68             : 
      69     1081191 :         while ((method = va_arg (va, plugin_t)))
      70             :         {
      71      742005 :                 switch (method)
      72             :                 {
      73             :                 case ELEKTRA_PLUGIN_OPEN:
      74      134257 :                         returned->kdbOpen = va_arg (va, kdbOpenPtr);
      75      134257 :                         break;
      76             :                 case ELEKTRA_PLUGIN_CLOSE:
      77      131055 :                         returned->kdbClose = va_arg (va, kdbClosePtr);
      78      131055 :                         break;
      79             :                 case ELEKTRA_PLUGIN_GET:
      80      169593 :                         returned->kdbGet = va_arg (va, kdbGetPtr);
      81      169593 :                         break;
      82             :                 case ELEKTRA_PLUGIN_SET:
      83      169053 :                         returned->kdbSet = va_arg (va, kdbSetPtr);
      84      169053 :                         break;
      85             :                 case ELEKTRA_PLUGIN_ERROR:
      86       80020 :                         returned->kdbError = va_arg (va, kdbErrorPtr);
      87       80020 :                         break;
      88             :                 case ELEKTRA_PLUGIN_COMMIT:
      89       58027 :                         returned->kdbCommit = va_arg (va, kdbCommitPtr);
      90       58027 :                         break;
      91             :                 default:
      92           0 :                         ELEKTRA_ASSERT (0, "plugin passed something unexpected");
      93             :                 // fallthrough, will end here
      94             :                 case ELEKTRA_PLUGIN_END:
      95           0 :                         va_end (va);
      96           0 :                         return returned;
      97             :                 }
      98             :         }
      99             :         return returned;
     100             : }
     101             : 
     102             : 
     103             : /**
     104             :  * @brief Returns the configuration of that plugin.
     105             :  *
     106             :  * - The user/ config holds plugin specific configuration
     107             :  * - The system/ config holds backend specific configuration
     108             :  *
     109             :  * So prefer cascading lookups to honor both.
     110             :  *
     111             :  * @param handle a pointer to the plugin
     112             :  * @ingroup plugin
     113             :  * @return keyset to the configuration for that plugin
     114             :  */
     115      166676 : KeySet * elektraPluginGetConfig (Plugin * handle)
     116             : {
     117      166676 :         return handle->config;
     118             : }
     119             : 
     120             : /**
     121             :  * @brief Store a pointer to any plugin related data.
     122             :  *
     123             :  * @see elektraPluginGetData
     124             :  * @param plugin a pointer to the plugin
     125             :  * @param data the pointer to the data
     126             :  * @ingroup plugin
     127             :  */
     128      267471 : void elektraPluginSetData (Plugin * plugin, void * data)
     129             : {
     130      267471 :         plugin->data = data;
     131      267471 : }
     132             : 
     133             : /**
     134             :  * @brief Get a pointer to any plugin related data stored before.
     135             :  *
     136             :  * If elektraPluginSetData() was not called earlier, NULL will be returned.
     137             :  *
     138             :  * @see elektraPluginSetData
     139             :  * @param plugin a pointer to the plugin
     140             :  * @return a pointer to the data
     141             :  * @ingroup plugin
     142             :  */
     143      263447 : void * elektraPluginGetData (Plugin * plugin)
     144             : {
     145      263447 :         return plugin->data;
     146             : }
     147             : 
     148             : /**
     149             :  * @brief Get a pointer to the global keyset.
     150             :  *
     151             :  * Initialized for all plugins by the KDB, except for manually
     152             :  * created plugins with `elektraPluginOpen()`.
     153             :  * The global keyset is tied to a KDB handle, initialized on
     154             :  * `kdbOpen()` and deleted on `kdbClose()`.
     155             :  *
     156             :  * Plugins using this keyset are responsible for cleaning up
     157             :  * their parts of the keyset which they do not need any more.
     158             :  *
     159             :  * @param plugin a pointer to the plugin
     160             :  * @return a pointer to the global keyset
     161             :  * @ingroup plugin
     162             :  */
     163       42169 : KeySet * elektraPluginGetGlobalKeySet (Plugin * plugin)
     164             : {
     165       42169 :         return plugin->global;
     166             : }

Generated by: LCOV version 1.13