Elektra
0.8.15
|
Constructs a class KDB. More...
#include <kdb.hpp>
Public Member Functions | |
KDB () | |
Constructs a class KDB. More... | |
KDB (Key &errorKey) | |
Constructs a class KDB. More... | |
~KDB () throw () | |
The destructor closes the database. More... | |
void | open (Key &errorKey) |
Open the database. More... | |
void | close (Key &errorKey) throw () |
Open the database. More... | |
int | get (KeySet &returned, std::string const &keyname) |
Get all keys below keyname inside returned. More... | |
int | get (KeySet &returned, Key &parentKey) |
Get all keys below parentKey inside returned. More... | |
int | set (KeySet &returned, std::string const &keyname) |
Set all keys below keyname. More... | |
int | set (KeySet &returned, Key &parentKey) |
Set all keys below parentKey. More... | |
Constructs a class KDB.
KDBException | if database could not be opened |
Opens the session with the Key database.
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the KDB
datastructure will be initialized.
You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to kdbClose().
The pointer to the KDB
structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls.
Get a KDB
handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it:
You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.
errorKey | the key which holds errors and warnings which were issued |
handle | on success |
NULL | on failure |
Access to the key database.
|
inline |
Constructs a class KDB.
KDBException | if database could not be opened |
Opens the session with the Key database.
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the KDB
datastructure will be initialized.
You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to kdbClose().
The pointer to the KDB
structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls.
Get a KDB
handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it:
You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.
errorKey | the key which holds errors and warnings which were issued |
handle | on success |
NULL | on failure |
|
inline |
Constructs a class KDB.
errorKey | is useful if you want to get the warnings in the successful case, when no exception is thrown. |
KDBException | if database could not be opened |
Opens the session with the Key database.
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the KDB
datastructure will be initialized.
You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to kdbClose().
The pointer to the KDB
structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls.
Get a KDB
handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it:
You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.
errorKey | the key which holds errors and warnings which were issued |
handle | on success |
NULL | on failure |
|
inline |
The destructor closes the database.
Closes the session with the Key database.
This is the counterpart of kdbOpen().
You must call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects also after kdbClose(), but you must not use any kdb*() call afterwards.
The handle
parameter will be finalized and all resources associated to it will be freed. After a kdbClose(), the handle
cannot be used anymore.
handle | contains internal information of opened key database |
errorKey | the key which holds error/warning information |
0 | on success |
-1 | on NULL pointer |
|
inline |
Open the database.
The return value does not matter because its only a null pointer check.
errorKey | is useful if you want to get the warnings |
Closes the session with the Key database.
This is the counterpart of kdbOpen().
You must call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects also after kdbClose(), but you must not use any kdb*() call afterwards.
The handle
parameter will be finalized and all resources associated to it will be freed. After a kdbClose(), the handle
cannot be used anymore.
handle | contains internal information of opened key database |
errorKey | the key which holds error/warning information |
0 | on success |
-1 | on NULL pointer |
|
inline |
Get all keys below keyname inside returned.
Retrieve keys in an atomic and universal way.
handle
must be passed as returned from kdbOpen()returned
KeySet must be a valid KeySet, e.g. constructed with ksNew().parentKey
Key must be a valid Key, e.g. constructed with keyNew().If you pass NULL, which violates the preconditions, on any parameter kdbGet() will fail immediately without doing anything.
The returned
KeySet may already contain some keys, e.g. from previous kdbGet() calls. The new retrieved keys will be appended using ksAppendKey().
It will fully retrieve, at least, all keys under the parentKey
folder, with all subfolders and their children.
When a backend fails kdbGet() will return -1 with all error and warning information in the parentKey
. The parameter returned
will not be changed.
It is your responsibility to save the original keyset if you need it afterwards.
If you want to get the same keyset again, you need to open a second handle to the key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | is used to add warnings and set an error information. Additionally, its name is an hint which keys should be retrieved (it is possible that more are retrieved).
|
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
1 | if the keys were retrieved successfully |
0 | if there was no update - no changes are made to the keyset then |
-1 | on failure - no changes are made to the keyset then |
returned | the keyset where the keys will be in |
keyname | the root keyname which should be used to get keys below it |
0 | if no key was updated |
1 | if user or system keys were updated |
2 | if user and system keys were updated |
KDBException | if there were problems with the database |
Get all keys below parentKey inside returned.
Retrieve keys in an atomic and universal way.
handle
must be passed as returned from kdbOpen()returned
KeySet must be a valid KeySet, e.g. constructed with ksNew().parentKey
Key must be a valid Key, e.g. constructed with keyNew().If you pass NULL, which violates the preconditions, on any parameter kdbGet() will fail immediately without doing anything.
The returned
KeySet may already contain some keys, e.g. from previous kdbGet() calls. The new retrieved keys will be appended using ksAppendKey().
It will fully retrieve, at least, all keys under the parentKey
folder, with all subfolders and their children.
When a backend fails kdbGet() will return -1 with all error and warning information in the parentKey
. The parameter returned
will not be changed.
It is your responsibility to save the original keyset if you need it afterwards.
If you want to get the same keyset again, you need to open a second handle to the key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | is used to add warnings and set an error information. Additionally, its name is an hint which keys should be retrieved (it is possible that more are retrieved).
|
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
1 | if the keys were retrieved successfully |
0 | if there was no update - no changes are made to the keyset then |
-1 | on failure - no changes are made to the keyset then |
returned | the keyset where the keys will be in |
parentKey | the parentKey of returned |
0 | if no key was updated |
1 | if user or system keys were updated |
2 | if user and system keys were updated |
KDBException | if there were problems with the database |
|
inline |
Open the database.
errorKey | is useful if you want to get the warnings in the successful case, when no exception is thrown. |
Opens the session with the Key database.
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the KDB
datastructure will be initialized.
You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to kdbClose().
The pointer to the KDB
structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls.
Get a KDB
handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it:
You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.
errorKey | the key which holds errors and warnings which were issued |
handle | on success |
NULL | on failure |
|
inline |
Set all keys below keyname.
If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
Set keys in an atomic and universal way.
returned
KeySet must be a valid KeySet, e.g. constructed with ksNew().parentKey
Key must be a valid Key, e.g. constructed withWith parentKey
you can give an hint which part of the given keyset is of interest for you. Then you promise, you only modified or removed keys below this key.
In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:
showElektraErrorDialog() and doElektraMerge() need to be implemented by the user of Elektra. For doElektraMerge a 3-way merge algorithm exists in libelektra-tools.
handle | contains internal information of opened key database |
ks | a KeySet which should contain changed keys, otherwise nothing is done |
parentKey | is used to add warnings and set an error information. Additionally, its name is an hint which keys should be committed (it is possible that more are changed).
|
1 | on success |
0 | if nothing had to be done, no changes in KDB |
-1 | on failure, no changes in KDB |
0 | if no key was updated |
1 | if user or system keys were updated |
2 | if user and system keys were updated |
returned | the keyset where the keys will be in |
keyname | the keyname below the names should be set |
KDBException | if there were problems with the database |
Set all keys below parentKey.
If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
Set keys in an atomic and universal way.
returned
KeySet must be a valid KeySet, e.g. constructed with ksNew().parentKey
Key must be a valid Key, e.g. constructed withWith parentKey
you can give an hint which part of the given keyset is of interest for you. Then you promise, you only modified or removed keys below this key.
In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:
showElektraErrorDialog() and doElektraMerge() need to be implemented by the user of Elektra. For doElektraMerge a 3-way merge algorithm exists in libelektra-tools.
handle | contains internal information of opened key database |
ks | a KeySet which should contain changed keys, otherwise nothing is done |
parentKey | is used to add warnings and set an error information. Additionally, its name is an hint which keys should be committed (it is possible that more are changed).
|
1 | on success |
0 | if nothing had to be done, no changes in KDB |
-1 | on failure, no changes in KDB |
0 | if no key was updated |
1 | if user or system keys were updated |
2 | if user and system keys were updated |
returned | the keyset where the keys are passed to the user |
parentKey | the parentKey of returned |
KDBException | if there were problems with the database |