LCOV - code coverage report
Current view: top level - src/libs/tools/include - plugin.hpp (source / functions) Hit Total Coverage
Test: coverage-filtered.info Lines: 4 4 100.0 %
Date: 2019-09-12 12:28:41 Functions: 1 1 100.0 %

          Line data    Source code
       1             : /**
       2             :  * @file
       3             :  *
       4             :  * @brief Header file of plugin
       5             :  *
       6             :  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
       7             :  *
       8             :  */
       9             : 
      10             : #ifndef TOOLS_PLUGIN_HPP
      11             : #define TOOLS_PLUGIN_HPP
      12             : 
      13             : #include <kdb.hpp>
      14             : #include <pluginspec.hpp>
      15             : #include <toolexcept.hpp>
      16             : 
      17             : #include <map>
      18             : #include <string>
      19             : #include <vector>
      20             : 
      21             : namespace ckdb
      22             : {
      23             : typedef struct _Plugin Plugin;
      24             : }
      25             : 
      26             : namespace kdb
      27             : {
      28             : 
      29             : namespace tools
      30             : {
      31             : 
      32             : /**
      33             :  * This is a C++ representation of a plugin.
      34             :  *
      35             :  * It will load an Elektra plugin using the module loader
      36             :  * from Elektra.
      37             :  *
      38             :  * Then you can either check the plugins configuration
      39             :  * using loadInfo(), parse() and check.
      40             :  * Symbols can then be retrieved with getSymbol().
      41             :  *
      42             :  * Or you can use the normal open(), close(), get(),
      43             :  * set() and error() API which every plugin exports.
      44             :  */
      45             : class Plugin
      46             : {
      47             : private:
      48             :         typedef void (*func_t) ();
      49             : 
      50             : private:
      51             :         ckdb::Plugin * plugin;
      52             :         PluginSpec spec;
      53             :         kdb::KeySet info;
      54             : 
      55             :         std::map<std::string, func_t> symbols;
      56             :         std::map<std::string, std::string> infos;
      57             : 
      58             :         void uninit ();
      59             : 
      60             : public:
      61             :         /**
      62             :          * @brief Do not construct a plugin yourself, use Modules.load
      63             :          */
      64             :         Plugin (PluginSpec const & spec, kdb::KeySet & modules);
      65             : 
      66             :         Plugin (Plugin const & other);
      67             :         Plugin & operator= (Plugin const & other);
      68             : 
      69             :         Plugin (Plugin && other) = delete;
      70             :         Plugin & operator= (Plugin && other) = delete;
      71             : 
      72             :         ~Plugin ();
      73             : 
      74             :         /**
      75             :          * @brief Is toggled during serialization.
      76             :          *
      77             :          * (is a hack, only allows a single serialization!)
      78             :          */
      79             :         bool firstRef;
      80             : 
      81             :         /**
      82             :          * Gets the configuration for the plugin.
      83             :          * (will be done in Modules.load)
      84             :          */
      85             :         void loadInfo ();
      86             : 
      87             :         /**
      88             :          * Creates symbol and info table.
      89             :          * (will be done in Modules.load)
      90             :          */
      91             :         void parse ();
      92             : 
      93             :         /**
      94             :          * Does various checks on the Plugin and throws exceptions
      95             :          * if something is not ok.
      96             :          *
      97             :          * - Check if Plugin is compatible to current Version of Backend-API.
      98             :          *
      99             :          * @throw PluginCheckException if there are errors
     100             :          * @param warnings for warnings
     101             :          *
     102             :          * @pre parse()
     103             :          */
     104             :         void check (std::vector<std::string> & warnings);
     105             : 
     106             :         ckdb::Plugin * operator-> ();
     107             : 
     108             :         /**
     109             :          * Gets the whole string of an information item.
     110             :          * @pre loadInfo()
     111             :          */
     112             :         std::string lookupInfo (std::string item, std::string section = "infos");
     113             : 
     114             :         /**
     115             :          * Searches within a string of an information item.
     116             :          * @pre loadInfo()
     117             :          */
     118             :         bool findInfo (std::string check, std::string item, std::string section = "infos");
     119             : 
     120             :         /**
     121             :          * Returns the whole keyset of information.
     122             :          * @pre loadInfo()
     123             :          */
     124             :         kdb::KeySet getInfo ()
     125             :         {
     126         826 :                 return info;
     127             :         }
     128             : 
     129             :         /**
     130             :          * In the plugin's contract there is a description of which
     131             :          * config is needed in order to work together with a backend
     132             :          * properly.
     133             :          *
     134             :          * @return the keyset with the config needed for the backend.
     135             :          * @see getConfig()
     136             :          * @pre loadInfo()
     137             :          */
     138             :         kdb::KeySet getNeededConfig ();
     139             : 
     140             :         /**
     141             :          * @brief return the plugin config
     142             :          *
     143             :          * @return the config supplied with constructor
     144             :          * @see getNeededConfig()
     145             :          */
     146             :         kdb::KeySet getConfig ();
     147             : 
     148             :         /**
     149             :          * Returns symbol to a function.
     150             :          * @pre parse()
     151             :          */
     152        6713 :         func_t getSymbol (std::string which)
     153             :         {
     154       22215 :                 if (symbols.find (which) == symbols.end ()) throw MissingSymbol (which);
     155        5675 :                 return symbols[which];
     156             :         }
     157             : 
     158             :         /**
     159             :          * Calls the open function of the plugin
     160             :          * @pre parse()
     161             :          */
     162             :         int open (kdb::Key & errorKey);
     163             : 
     164             :         /**
     165             :          * Calls the close function of the plugin
     166             :          * @pre parse()
     167             :          */
     168             :         int close (kdb::Key & errorKey);
     169             : 
     170             :         /**
     171             :          * Calls the get function of the plugin
     172             :          * @pre parse()
     173             :          */
     174             :         int get (kdb::KeySet & ks, kdb::Key & parentKey);
     175             : 
     176             :         /**
     177             :          * Calls the set function of the plugin
     178             :          * @pre parse()
     179             :          */
     180             :         int set (kdb::KeySet & ks, kdb::Key & parentKey);
     181             : 
     182             :         /**
     183             :          * Calls the commit function of the plugin
     184             :          * @pre parse()
     185             :          */
     186             :         int commit (kdb::KeySet & ks, kdb::Key & parentKey);
     187             : 
     188             :         /**
     189             :          * Calls the error function of the plugin
     190             :          * @pre parse()
     191             :          */
     192             :         int error (kdb::KeySet & ks, kdb::Key & parentKey);
     193             : 
     194             :         /**
     195             :          * @return the name of the plugin (module)
     196             :          */
     197             :         std::string name ();
     198             : 
     199             :         /**
     200             :          * @return the fullname of the plugin
     201             :          */
     202             :         std::string getFullName ();
     203             : 
     204             : private:
     205             :         friend class ErrorPlugins;
     206             :         friend class GetPlugins;
     207             :         friend class SetPlugins;
     208             :         /**
     209             :          * @return the name how it would be referred to in mountpoint
     210             :          *
     211             :          * # name # label # (when called the first time)
     212             :          * or
     213             :          * # ref
     214             :          *
     215             :          * @note Its not the same as getRefName(), and is only suitable for serialization!
     216             :          * @warning Its stateful in a really weird way!
     217             :          */
     218             :         std::string refname ();
     219             : };
     220             : 
     221             : typedef std::unique_ptr<Plugin> PluginPtr;
     222             : } // namespace tools
     223             : } // namespace kdb
     224             : 
     225             : #endif

Generated by: LCOV version 1.13