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
|