Elektra
0.8.7
|
Opens the session with the Key database. More...
#include <kdb.hpp>
Public Member Functions | |
KDB () | |
Opens the session with the Key database. More... | |
KDB (Key &errorKey) | |
Opens the session with the Key database. More... | |
~KDB () throw () | |
void | open (Key &errorKey) |
Opens the session with the Key database. More... | |
void | close (Key &errorKey) throw () |
int | get (KeySet &returned, std::string const &keyname) |
Retrieve keys in an atomic and universal way, all other kdbGet() Functions rely on that one. More... | |
int | get (KeySet &returned, Key &parentKey) |
Retrieve keys in an atomic and universal way, all other kdbGet() Functions rely on that one. More... | |
int | set (KeySet &returned, std::string const &keyname) |
int | set (KeySet &returned, Key &parentKey) |
Opens the session with the Key database.
Constructs a class KDB.
KDBException | if database could not be opened |
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(). You can use the atexit () handler for it.
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 to use the kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects without any affairs with the backend key database or when your application loads plugins directly.
errorKey | the key which holds errors and warnings which were issued must be given |
Access to the key database.
|
inline |
Opens the session with the Key database.
Constructs a class KDB.
KDBException | if database could not be opened |
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(). You can use the atexit () handler for it.
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 to use the kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects without any affairs with the backend key database or when your application loads plugins directly.
errorKey | the key which holds errors and warnings which were issued must be given |
|
inline |
Opens the session with the Key database.
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 |
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(). You can use the atexit () handler for it.
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 to use the kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects without any affairs with the backend key database or when your application loads plugins directly.
errorKey | the key which holds errors and warnings which were issued must be given |
|
inline |
The destructor closes the database.
Closes the session with the Key database.
You should call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects also after kdbClose(). You must not use any kdb* call afterwards. You can implement kdbClose() in the atexit() handler.
This is the counterpart of kdbOpen().
The handle
parameter will be finalized and all resources associated to it will be freed. After a kdbClose(), this handle
can't be used anymore, unless it gets initialized again with another call to kdbOpen().
handle | contains internal information of opened key database |
errorKey | the key which holds error information |
|
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.
You should call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects also after kdbClose(). You must not use any kdb* call afterwards. You can implement kdbClose() in the atexit() handler.
This is the counterpart of kdbOpen().
The handle
parameter will be finalized and all resources associated to it will be freed. After a kdbClose(), this handle
can't be used anymore, unless it gets initialized again with another call to kdbOpen().
handle | contains internal information of opened key database |
errorKey | the key which holds error information |
|
inline |
Retrieve keys in an atomic and universal way, all other kdbGet() Functions rely on that one.
Get all keys below keyname inside returned.
The returned
KeySet must be initialized. The returned
KeySet may already contain some keys. The new retrieved keys will be appended using ksAppendKey().
It will fully retrieve all keys under the parentKey
folder, with all subfolders and their children.
This example demonstrates the typical usecase within an application without updating.
When no backend could be found (e.g. no backend mounted) the default backend will be used.
If you pass NULL on any parameter kdbGet() will fail immediately without doing anything.
When a backend fails kdbGet() will return -1 without any changes to one of the parameter.
In the first run of kdbGet all keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay unchanged in the keyset, even when they were manipulated.
It is your responsibility to save the original keyset if you need it afterwards.
If you must get the same keyset again, e.g. in another thread you need to open a second handle to the key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | parent key holds the information which keys should be get - invalid name gets all keys |
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
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 |
Retrieve keys in an atomic and universal way, all other kdbGet() Functions rely on that one.
Get all keys below parentKey inside returned.
The returned
KeySet must be initialized. The returned
KeySet may already contain some keys. The new retrieved keys will be appended using ksAppendKey().
It will fully retrieve all keys under the parentKey
folder, with all subfolders and their children.
This example demonstrates the typical usecase within an application without updating.
When no backend could be found (e.g. no backend mounted) the default backend will be used.
If you pass NULL on any parameter kdbGet() will fail immediately without doing anything.
When a backend fails kdbGet() will return -1 without any changes to one of the parameter.
In the first run of kdbGet all keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay unchanged in the keyset, even when they were manipulated.
It is your responsibility to save the original keyset if you need it afterwards.
If you must get the same keyset again, e.g. in another thread you need to open a second handle to the key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | parent key holds the information which keys should be get - invalid name gets all keys |
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
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 |
Opens the session with the Key database.
Open the database
errorKey | is useful if you want to get the warnings in the successful case, when no exception is thrown. |
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(). You can use the atexit () handler for it.
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 to use the kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects without any affairs with the backend key database or when your application loads plugins directly.
errorKey | the key which holds errors and warnings which were issued must be given |
|
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.
All other kdbSet Functions rely on that one.
With parentKey you can only store a part of the given keyset.
If you pass a parentKey without a name the whole keyset will be set in an atomic way.
Each key is checked with keyNeedSync() before being actually committed. So only changed keys are updated. If no key of a backend needs to be synced any affairs to backends omitted and 0 is returned.
If some error occurs, kdbSet() will stop. In this situation the KeySet internal cursor will be set on the key that generated the error.
None of the keys are actually commited.
You should present the error message to the user and let the user decide what to do. Possible solutions are:
handle | contains internal information of opened key database |
ks | a KeySet which should contain changed keys, otherwise nothing is done |
parentKey | holds the information below which key keys should be set, see above |
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.
All other kdbSet Functions rely on that one.
With parentKey you can only store a part of the given keyset.
If you pass a parentKey without a name the whole keyset will be set in an atomic way.
Each key is checked with keyNeedSync() before being actually committed. So only changed keys are updated. If no key of a backend needs to be synced any affairs to backends omitted and 0 is returned.
If some error occurs, kdbSet() will stop. In this situation the KeySet internal cursor will be set on the key that generated the error.
None of the keys are actually commited.
You should present the error message to the user and let the user decide what to do. Possible solutions are:
handle | contains internal information of opened key database |
ks | a KeySet which should contain changed keys, otherwise nothing is done |
parentKey | holds the information below which key keys should be set, see above |
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 |