kdb::KDB(3elektra) | Elektra | kdb::KDB(3elektra) |
NAME¶
kdb::KDB - Opens the session with the Key database.SYNOPSIS¶
#include <kdb.hpp>Public Member Functions¶
KDB ()
Detailed Description¶
Opens the session with the Key database. Constructs a class KDB. Exceptions: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:
thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); }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. Parameters:
errorKey the key which holds errors and warnings
which were issued must be given
See also:
kdbClose() to end all affairs to the Key
database.
Returns:
a KDB pointer on success
NULL on failure
Access to the key database.
Invariant:
the object holds an valid connection to the key database
or is empty
Constructor & Destructor Documentation¶
kdb::KDB::KDB () [inline]¶
Opens the session with the Key database. Constructs a class KDB. Exceptions: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:
thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); }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. Parameters:
errorKey the key which holds errors and warnings
which were issued must be given
See also:
kdbClose() to end all affairs to the Key
database.
Returns:
a KDB pointer on success
NULL on failure
kdb::KDB::KDB ( Key &errorKey) [inline]¶
Opens the session with the Key database. Constructs a class KDB. Parameters:errorKey is useful if you want to get the warnings
in the successful case, when no exception is thrown.
Exceptions:
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:
thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); }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. Parameters:
errorKey the key which holds errors and warnings
which were issued must be given
See also:
kdbClose() to end all affairs to the Key
database.
Returns:
a KDB pointer on success
NULL on failure
kdb::KDB::~KDB () [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(). See also:kdbOpen()
Parameters:
handle contains internal information of opened
key database
errorKey the key which holds error information
Returns:
0 on success
-1 on NULL pointer
Member Function Documentation¶
void kdb::KDB::close ( Key &errorKey) [inline]¶
Open the database. The return value does not matter because its only a null pointer check. Parameters: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().
See also:
kdbOpen()
Parameters:
handle contains internal information of opened
key database
errorKey the key which holds error information
Returns:
0 on success
-1 on NULL pointer
int kdb::KDB::get ( KeySet &returned, std::string const &keyname) [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.Example¶
This example demonstrates the typical usecase within an application without updating. Example:KeySet *myConfig = ksNew(0); Key *key = keyNew("system/sw/MyApp",KEY_END); KDB *handle = kdbOpen(key); kdbGet(handle, myConfig, key); keySetName(key, "user/sw/MyApp"); kdbGet(handle, myConfig, key); // check for errors in key keyDel(key); key = ksLookupByName(myConfig,"/sw/MyApp/key", 0); // check if key is not 0 and work with it... ksDel (myConfig); // delete the in-memory configuration // maybe you want kdbSet() myConfig here kdbClose(handle, 0); // no more affairs with the key database.
Details¶
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.Updating¶
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(). Parameters: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
See also:
ksLookupByName() for powerful lookups after the
KeySet was retrieved
Returns:
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
#include <kdb.hpp> #include <keyio.hpp> using namespace kdb; int main() { KeySet config; KDB kdb; kdb.get(config, "/sw/MyApp"); Key k = config.lookup("/sw/MyApp/mykey"); if (k) { std::cout << k << " is " << k.get<int>() << std::endl; } else { std::cerr << "No key found" << std::endl; return 1; } }Parameters:
returned the keyset where the keys will be in
keyname the root keyname which should be used to get keys below it
Return values:
0 if no key was updated
1 if user or system keys were updated
2 if user and system keys were updated
Exceptions:
KDBException if there were problems with the
database
See also:
KDB::get (KeySet & returned, Key
& parentKey)
int kdb::KDB::get ( KeySet &returned, Key &parentKey) [inline]¶
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.Example¶
This example demonstrates the typical usecase within an application without updating. Example:KeySet *myConfig = ksNew(0); Key *key = keyNew("system/sw/MyApp",KEY_END); KDB *handle = kdbOpen(key); kdbGet(handle, myConfig, key); keySetName(key, "user/sw/MyApp"); kdbGet(handle, myConfig, key); // check for errors in key keyDel(key); key = ksLookupByName(myConfig,"/sw/MyApp/key", 0); // check if key is not 0 and work with it... ksDel (myConfig); // delete the in-memory configuration // maybe you want kdbSet() myConfig here kdbClose(handle, 0); // no more affairs with the key database.
Details¶
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.Updating¶
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(). Parameters: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
See also:
ksLookupByName() for powerful lookups after the
KeySet was retrieved
Returns:
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
Parameters:
returned the keyset where the keys will be in
parentKey the parentKey of returned
Return values:
0 if no key was updated
1 if user or system keys were updated
2 if user and system keys were updated
Exceptions:
KDBException if there were problems with the
database
void kdb::KDB::open ( Key &errorKey) [inline]¶
Opens the session with the Key database. Open the database Parameters: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:
thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); }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. Parameters:
errorKey the key which holds errors and warnings
which were issued must be given
See also:
kdbClose() to end all affairs to the Key
database.
Returns:
a KDB pointer on success
NULL on failure
int kdb::KDB::set ( KeySet &returned, std::string const &keyname) [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.parentKey¶
With parentKey you can only store a part of the given keyset.KeySet *ks = ksNew(0); Key *parentKey = keyNew("user/app/myapp/default", KEY_END); kdbGet (h, ks, parentKey)); //now only set everything below user if (kdbSet (h, ks, parentKey) == -1) { // in parentKey you can check the error cause // ksCurrent(ks) is the faulty key } ksDel (ks);If you pass a parentKey without a name the whole keyset will be set in an atomic way.
Update¶
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.Error Situations¶
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:- •
- repeat the same kdbSet (for temporary errors)
- •
- remove the key and set it again (for validation or type errors)
- •
- change the value and try it again (for validation errors)
- •
- do a kdbGet and then (for conflicts ...)
- •
- set the same keyset again (in favour of what was set by this user)
- •
- drop the old keyset (in favour of what was set elsewhere)
- •
- export the configuration into a file (for unresolvable errors)
int i; KeySet *ks; // the KeySet I want to set // fill ks with some keys for (i=0; i< NR_OF_TRIES; i++) // limit to NR_OF_TRIES tries { ret=kdbSet(handle, ks, parentKey); if (ret == -1) { // We got an error. Warn user. Key *problemKey = ksCurrent(ks); // parentKey has the errorInformation // problemKey is the faulty key (may be null) int userInput = showElektraErrorDialog (parentKey, problemKey); switch (userInput) { case INPUT_REPEAT: continue; case INPUT_REMOVE: ksLookup (ks, parentKey, KDB_O_POP); break; ... } } }
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
Returns:
1 on success
0 if nothing had to be done
-1 on failure
See also:
keyNeedSync(), ksNext(),
ksCurrent()
Return values:
0 if no key was updated
1 if user or system keys were updated
2 if user and system keys were updated
Parameters:
returned the keyset where the keys will be in
keyname the keyname below the names should be set
Exceptions:
KDBException if there were problems with the
database
int kdb::KDB::set ( KeySet &returned, Key &parentKey) [inline]¶
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.parentKey¶
With parentKey you can only store a part of the given keyset.KeySet *ks = ksNew(0); Key *parentKey = keyNew("user/app/myapp/default", KEY_END); kdbGet (h, ks, parentKey)); //now only set everything below user if (kdbSet (h, ks, parentKey) == -1) { // in parentKey you can check the error cause // ksCurrent(ks) is the faulty key } ksDel (ks);If you pass a parentKey without a name the whole keyset will be set in an atomic way.
Update¶
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.Error Situations¶
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:- •
- repeat the same kdbSet (for temporary errors)
- •
- remove the key and set it again (for validation or type errors)
- •
- change the value and try it again (for validation errors)
- •
- do a kdbGet and then (for conflicts ...)
- •
- set the same keyset again (in favour of what was set by this user)
- •
- drop the old keyset (in favour of what was set elsewhere)
- •
- export the configuration into a file (for unresolvable errors)
int i; KeySet *ks; // the KeySet I want to set // fill ks with some keys for (i=0; i< NR_OF_TRIES; i++) // limit to NR_OF_TRIES tries { ret=kdbSet(handle, ks, parentKey); if (ret == -1) { // We got an error. Warn user. Key *problemKey = ksCurrent(ks); // parentKey has the errorInformation // problemKey is the faulty key (may be null) int userInput = showElektraErrorDialog (parentKey, problemKey); switch (userInput) { case INPUT_REPEAT: continue; case INPUT_REMOVE: ksLookup (ks, parentKey, KDB_O_POP); break; ... } } }
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
Returns:
1 on success
0 if nothing had to be done
-1 on failure
See also:
keyNeedSync(), ksNext(),
ksCurrent()
Return values:
0 if no key was updated
1 if user or system keys were updated
2 if user and system keys were updated
Parameters:
returned the keyset where the keys are passed to
the user
parentKey the parentKey of returned
Exceptions:
KDBException if there were problems with the
database
Author¶
Generated automatically by Doxygen for Elektra from the source code.Tue Aug 19 2014 | Version 0.8.7 |