Line data Source code
1 : /**
2 : * @file
3 : *
4 : * @brief
5 : *
6 : * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
7 : */
8 :
9 : #ifndef ELEKTRA_KDB_HPP
10 : #define ELEKTRA_KDB_HPP
11 :
12 : #include <string>
13 :
14 : #include <kdbexcept.hpp>
15 : #include <key.hpp>
16 : #include <keyset.hpp>
17 :
18 : #include <kdb.h>
19 :
20 :
21 : /**
22 : * @brief This is the main namespace for the C++ binding and libraries.
23 : *
24 : * Classes or Functions directly below this namespace are header-only.
25 : * Sub namespaces are intended for libraries and you need to link
26 : * the library if you want to use them.
27 : * - @see kdb::tools
28 : */
29 : namespace kdb
30 : {
31 :
32 : /**
33 : * @copydoc KDB
34 : *
35 : * @brief Access to the key database.
36 : *
37 : * @invariant the object holds a valid connection to the key database
38 : * or is empty
39 : */
40 0 : class KDB
41 : {
42 : public:
43 : KDB ();
44 : explicit KDB (Key & errorKey);
45 28 : virtual ~KDB () throw ()
46 15745 : {
47 10237 : close ();
48 28 : }
49 :
50 : virtual inline void open (Key & errorKey);
51 : virtual inline void close () throw ();
52 : virtual inline void close (Key & errorKey) throw ();
53 :
54 : virtual inline int get (KeySet & returned, std::string const & keyname);
55 : virtual inline int get (KeySet & returned, Key & parentKey);
56 : virtual inline int set (KeySet & returned, std::string const & keyname);
57 : virtual inline int set (KeySet & returned, Key & parentKey);
58 :
59 : inline int ensure (const KeySet & contract, Key & parentKey);
60 :
61 : private:
62 : ckdb::KDB * handle; ///< holds an kdb handle
63 : };
64 :
65 : /**
66 : * Constructs a class KDB.
67 : *
68 : * @throw KDBException if database could not be opened
69 : *
70 : * @copydoc kdbOpen
71 : */
72 9790 : inline KDB::KDB ()
73 : {
74 19580 : Key errorKey;
75 9790 : open (errorKey);
76 9790 : }
77 :
78 : /**
79 : * Constructs a class KDB.
80 : *
81 : * @param errorKey is useful if you want to get the warnings in
82 : * the successful case, when no exception is thrown.
83 : *
84 : * @throw KDBException if database could not be opened
85 : *
86 : * @copydoc kdbOpen
87 : */
88 447 : inline KDB::KDB (Key & errorKey)
89 : {
90 447 : open (errorKey);
91 : }
92 :
93 : /**
94 : * Open the database
95 : *
96 : * @param errorKey is useful if you want to get the warnings in
97 : * the successful case, when no exception is thrown.
98 : *
99 : * @copydoc kdbOpen
100 : */
101 10259 : inline void KDB::open (Key & errorKey)
102 : {
103 10259 : handle = ckdb::kdbOpen (errorKey.getKey ());
104 10259 : if (!handle)
105 : {
106 0 : throw kdb::KDBException (errorKey);
107 : }
108 10259 : }
109 :
110 : /**
111 : * Close the database.
112 : *
113 : * The return value does not matter because its only a null pointer check.
114 : *
115 : * @copydoc kdbClose
116 : */
117 10241 : inline void KDB::close () throw ()
118 : {
119 20482 : Key errorKey;
120 10241 : ckdb::kdbClose (handle, errorKey.getKey ());
121 10241 : handle = nullptr;
122 10241 : }
123 :
124 :
125 : /**
126 : * Close the database.
127 : *
128 : * The return value does not matter because its only a null pointer check.
129 : *
130 : * @param errorKey is useful if you want to get the warnings
131 : *
132 : * @copydoc kdbClose
133 : */
134 34 : inline void KDB::close (Key & errorKey) throw ()
135 : {
136 34 : ckdb::kdbClose (handle, errorKey.getKey ());
137 34 : handle = nullptr;
138 34 : }
139 :
140 : /**
141 : * @class doxygenKDBReturn
142 : * @brief
143 : *
144 : * @retval 0 if no key was updated
145 : * @retval 1 if user or system keys were updated
146 : * @retval 2 if user and system keys were updated
147 : */
148 :
149 : /**
150 : * Get all keys below keyname inside returned.
151 : *
152 : * @copydoc kdbGet
153 : *
154 : * @include cpp_example_get.cpp
155 : *
156 : * @param returned the keyset where the keys will be in
157 : * @param keyname the root keyname which should be used to get keys below it
158 : *
159 : * @copydetails doxygenKDBReturn
160 : *
161 : * @throw KDBException if there were problems with the database
162 : *
163 : * @see KDB::get (KeySet & returned, Key & parentKey)
164 : */
165 10871 : inline int KDB::get (KeySet & returned, std::string const & keyname)
166 : {
167 21742 : Key parentKey (keyname.c_str (), KEY_CASCADING_NAME, KEY_END);
168 21740 : return get (returned, parentKey);
169 : }
170 :
171 : /**
172 : * Get all keys below parentKey inside returned.
173 : *
174 : * @copydoc kdbGet
175 : *
176 : * @param returned the keyset where the keys will be in
177 : * @param parentKey the parentKey of returned
178 : *
179 : * @copydetails doxygenKDBReturn
180 : *
181 : * @throw KDBException if there were problems with the database
182 : */
183 15396 : inline int KDB::get (KeySet & returned, Key & parentKey)
184 : {
185 30792 : int ret = ckdb::kdbGet (handle, returned.getKeySet (), parentKey.getKey ());
186 15396 : if (ret == -1)
187 : {
188 54 : throw KDBException (parentKey);
189 : }
190 15378 : return ret;
191 : }
192 :
193 : /**
194 : * Set all keys below keyname.
195 : *
196 : * If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
197 : *
198 : * @copydoc kdbSet
199 : *
200 : * @copydetails doxygenKDBReturn
201 : *
202 : * @param returned the keyset where the keys will be in
203 : * @param keyname the keyname below the names should be set
204 : *
205 : * @throw KDBException if there were problems with the database
206 : */
207 78 : inline int KDB::set (KeySet & returned, std::string const & keyname)
208 : {
209 156 : Key parentKey (keyname.c_str (), KEY_CASCADING_NAME, KEY_END);
210 150 : return set (returned, parentKey);
211 : }
212 :
213 : /**
214 : * Set all keys below parentKey.
215 : *
216 : * If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
217 : *
218 : * @copydoc kdbSet
219 : *
220 : * @copydetails doxygenKDBReturn
221 : *
222 : * @param returned the keyset where the keys are passed to the user
223 : * @param parentKey the parentKey of returned
224 : *
225 : * @throw KDBException if there were problems with the database
226 : */
227 1928 : inline int KDB::set (KeySet & returned, Key & parentKey)
228 : {
229 3856 : int ret = ckdb::kdbSet (handle, returned.getKeySet (), parentKey.getKey ());
230 1928 : if (ret == -1)
231 : {
232 276 : throw KDBException (parentKey);
233 : }
234 1836 : return ret;
235 : }
236 :
237 : /**
238 : * Ensures that the conditions defined in @p contract are met by this KDB.
239 : *
240 : * @see ckdb::kdbEnsure()
241 : *
242 : * @param contract The contract to ensure.
243 : * @param parentKey The parentKey to use.
244 : *
245 : * @throw KDBException if there were problems with the contract or the database
246 : * @throw ContractException if the contract couldn't be ensured
247 : */
248 14 : int KDB::ensure (const KeySet & contract, Key & parentKey)
249 : {
250 : // have to ksDup because contract is consumed and ksDel()ed by kdbEnsure
251 28 : int ret = ckdb::kdbEnsure (handle, ckdb::ksDup (contract.getKeySet ()), parentKey.getKey ());
252 14 : if (ret == -1)
253 : {
254 0 : throw KDBException (parentKey);
255 : }
256 14 : if (ret == 1)
257 : {
258 0 : throw ContractException (parentKey);
259 : }
260 14 : return ret;
261 : }
262 :
263 :
264 : } // end of namespace kdb
265 :
266 : #endif
|