Public Member Functions¶

KDB ()
Constructs a class KDB. KDB (Key &errorKey)
Constructs a class KDB. virtual void open (Key &errorKey)
Open the database. virtual void close () throw ()
Close the database. virtual void close (Key &errorKey) throw ()
Close the database. virtual int get (KeySet &returned, std::string const &keyname)
Get all keys below keyname inside returned. virtual int get (KeySet &returned, Key &parentKey)
Get all keys below parentKey inside returned. virtual int set (KeySet &returned, std::string const &keyname)
Set all keys below keyname. virtual int set (KeySet &returned, Key &parentKey)
Set all keys below parentKey.

kdb::KDB::KDB () [inline]¶

Constructs a class KDB.

Exceptions:

Opens the session with the Key database.

Precondition:

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 data structure 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:

void thread1 (void)
{


        Key * parent = keyNew ("/app/part1", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}
void thread2 (void)
{


        Key * parent = keyNew ("/app/part2", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}

You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.

Precondition:

Parameters:

See also:

Return values:

kdb::KDB::KDB (Key & errorKey) [inline], [explicit]¶

Constructs a class KDB.

Parameters:

Exceptions:

Opens the session with the Key database.

Precondition:

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 data structure 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:

void thread1 (void)
{


        Key * parent = keyNew ("/app/part1", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}
void thread2 (void)
{


        Key * parent = keyNew ("/app/part2", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}

You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.

Precondition:

Parameters:

See also:

Return values:

void kdb::KDB::close () [inline], [virtual]¶

Close the database. The return value does not matter because its only a null pointer check.

Closes the session with the Key database.

Precondition:

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.

Parameters:

Return values:

void kdb::KDB::close (Key & errorKey) [inline], [virtual]¶

Close the database. The return value does not matter because its only a null pointer check.

Parameters:

Closes the session with the Key database.

Precondition:

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.

Parameters:

Return values:

int kdb::KDB::get (KeySet & returned, std::string const & keyname) [inline], [virtual]¶

Get all keys below keyname inside returned. Retrieve keys in an atomic and universal way.

Precondition:

If you pass NULL 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().

If not done earlier kdbGet() will fully retrieve all keys under the parentKey folder recursively (See Optimization below when it will not be done).

Note:

Example:

#include <kdb.h>
#include <stdio.h>
int main (void)
{


        KeySet * myConfig = ksNew (0, KS_END);


        // for error handling see kdbget_error.c


        // clang-format off
Key * key = keyNew ("/sw/tests/myapp/#0/current/",  KEY_END);
KDB * handle = kdbOpen (key);
kdbGet (handle, myConfig, key);
Key * result = ksLookupByName (myConfig, "/sw/tests/myapp/#0/current/testkey1", 0);


        // clang-format on


        keyDel (key);


        const char * key_name = keyName (result);


        const char * key_value = keyString (result);


        const char * key_comment = keyString (keyGetMeta (result, "comment"));


        printf ("key: %s value: %s comment: %s0, key_name, key_value, key_comment);


        ksDel (myConfig); // delete the in-memory configuration


        // maybe you want kdbSet() myConfig here


        kdbClose (handle, 0); // no more affairs with the key database.
}

When a backend fails kdbGet() will return -1 with all error and warning information in the parentKey. The parameter returned will not be changed.

Optimization:

It is your responsibility to save the original keyset if you need it afterwards.

If you want to be sure to get a fresh keyset again, you need to open a second handle to the key database using kdbOpen().

Parameters:

See also:

Return values:

#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:

Return values:

Exceptions:

See also:

Reimplemented in kdb::tools::merging::MergingKDB.

int kdb::KDB::get (KeySet & returned, Key & parentKey) [inline], [virtual]¶

Get all keys below parentKey inside returned. Retrieve keys in an atomic and universal way.

Precondition:

If you pass NULL 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().

If not done earlier kdbGet() will fully retrieve all keys under the parentKey folder recursively (See Optimization below when it will not be done).

Note:

Example:

#include <kdb.h>
#include <stdio.h>
int main (void)
{


        KeySet * myConfig = ksNew (0, KS_END);


        // for error handling see kdbget_error.c


        // clang-format off
Key * key = keyNew ("/sw/tests/myapp/#0/current/",  KEY_END);
KDB * handle = kdbOpen (key);
kdbGet (handle, myConfig, key);
Key * result = ksLookupByName (myConfig, "/sw/tests/myapp/#0/current/testkey1", 0);


        // clang-format on


        keyDel (key);


        const char * key_name = keyName (result);


        const char * key_value = keyString (result);


        const char * key_comment = keyString (keyGetMeta (result, "comment"));


        printf ("key: %s value: %s comment: %s0, key_name, key_value, key_comment);


        ksDel (myConfig); // delete the in-memory configuration


        // maybe you want kdbSet() myConfig here


        kdbClose (handle, 0); // no more affairs with the key database.
}

When a backend fails kdbGet() will return -1 with all error and warning information in the parentKey. The parameter returned will not be changed.

Optimization:

It is your responsibility to save the original keyset if you need it afterwards.

If you want to be sure to get a fresh keyset again, you need to open a second handle to the key database using kdbOpen().

Parameters:

See also:

Return values:

Parameters:

Return values:

Exceptions:

Reimplemented in kdb::tools::merging::MergingKDB.

void kdb::KDB::open (Key & errorKey) [inline], [virtual]¶

Open the database.

Parameters:

Opens the session with the Key database.

Precondition:

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 data structure 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:

void thread1 (void)
{


        Key * parent = keyNew ("/app/part1", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}
void thread2 (void)
{


        Key * parent = keyNew ("/app/part2", KEY_CASCADING_NAME, KEY_END);


        KDB * h = kdbOpen (parent);


        // fetch keys and work with them


        kdbClose (h, parent);
}

You don't need kdbOpen() if you only want to manipulate plain in-memory Key or KeySet objects.

Precondition:

Parameters:

See also:

Return values:

int kdb::KDB::set (KeySet & returned, std::string const & keyname) [inline], [virtual]¶

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.

Precondition:

If you pass NULL on any parameter kdbSet() will fail immediately without doing anything.

With parentKey you can give an hint which part of the given keyset is of interest for you. Then you promise to only modify or remove keys below this key. All others would be passed back as they were retrieved by kdbGet().

Errors

In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:

• remove the problematic key and use kdbSet() again (for validation or type errors)
• change the value of the problematic key and use kdbSet() again (for validation errors)
• do a kdbGet() (for conflicts, i.e. error 30) and then

•

set the same keyset again (in favour of what was set by this user)

•

drop the old keyset (in favour of what was set from another application)

•

merge the original, your own and the other keyset

• export the configuration into a file (for unresolvable errors)
• repeat the same kdbSet might be of limited use if the user does not explicitly request it, because temporary errors are rare and its unlikely that they fix themselves (e.g. disc full, permission problems)

Optimization

KeySet * myConfig = ksNew (0, KS_END);
Key * parentKey = keyNew ("system/sw/MyApp", KEY_END);
KDB * handle = kdbOpen (parentKey);
kdbGet (handle, myConfig, parentKey); // kdbGet needs to be called first!
KeySet * base = ksDup (myConfig);     // save a copy of original keyset
// change the keys within myConfig
KeySet * ours = ksDup (myConfig); // save a copy of our keyset
KeySet * theirs;                  // needed for 3-way merging
int ret = kdbSet (handle, myConfig, parentKey);
while (ret == -1) // as long as we have an error
{


        // We got an error. Warn user.


        Key * problemKey = ksCurrent (myConfig);


        // parentKey has the errorInformation


        // problemKey is the faulty key (may be null)


        int userInput = showElektraErrorDialog (parentKey, problemKey);


        switch (userInput)


        {


        case INPUT_USE_OURS:


                kdbGet (handle, myConfig, parentKey); // refresh key database


                ksDel (myConfig);


                myConfig = ours;


                break;


        case INPUT_DO_MERGE:


                theirs = ksDup (ours);


                kdbGet (handle, theirs, parentKey); // refresh key database


                KeySet * res = doElektraMerge (ours, theirs, base);


                ksDel (theirs);


                myConfig = res;


                break;


        case INPUT_USE_THEIRS:


                // should always work, we just write what we got


                // but to be sure always give the user another way


                // to exit the loop


                kdbGet (handle, myConfig, parentKey); // refresh key database


                break;


                // other cases ...


        }


        ret = kdbSet (handle, myConfig, parentKey);
}
ksDel (ours);
ksDel (base);
ksDel (myConfig); // delete the in-memory configuration
kdbClose (handle, parentKey); // no more affairs with the key database.
keyDel (parentKey);

showElektraErrorDialog() and doElektraMerge() need to be implemented by the user of Elektra. For doElektraMerge a 3-way merge algorithm exists in libelektra-tools.

Parameters:

Return values:

See also:

Return values:

Parameters:

Exceptions:

int kdb::KDB::set (KeySet & returned, Key & parentKey) [inline], [virtual]¶

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.

Precondition:

If you pass NULL on any parameter kdbSet() will fail immediately without doing anything.

With parentKey you can give an hint which part of the given keyset is of interest for you. Then you promise to only modify or remove keys below this key. All others would be passed back as they were retrieved by kdbGet().

Errors

In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:

• remove the problematic key and use kdbSet() again (for validation or type errors)
• change the value of the problematic key and use kdbSet() again (for validation errors)
• do a kdbGet() (for conflicts, i.e. error 30) and then

•

set the same keyset again (in favour of what was set by this user)

•

drop the old keyset (in favour of what was set from another application)

•

merge the original, your own and the other keyset

• export the configuration into a file (for unresolvable errors)
• repeat the same kdbSet might be of limited use if the user does not explicitly request it, because temporary errors are rare and its unlikely that they fix themselves (e.g. disc full, permission problems)

Optimization

KeySet * myConfig = ksNew (0, KS_END);
Key * parentKey = keyNew ("system/sw/MyApp", KEY_END);
KDB * handle = kdbOpen (parentKey);
kdbGet (handle, myConfig, parentKey); // kdbGet needs to be called first!
KeySet * base = ksDup (myConfig);     // save a copy of original keyset
// change the keys within myConfig
KeySet * ours = ksDup (myConfig); // save a copy of our keyset
KeySet * theirs;                  // needed for 3-way merging
int ret = kdbSet (handle, myConfig, parentKey);
while (ret == -1) // as long as we have an error
{


        // We got an error. Warn user.


        Key * problemKey = ksCurrent (myConfig);


        // parentKey has the errorInformation


        // problemKey is the faulty key (may be null)


        int userInput = showElektraErrorDialog (parentKey, problemKey);


        switch (userInput)


        {


        case INPUT_USE_OURS:


                kdbGet (handle, myConfig, parentKey); // refresh key database


                ksDel (myConfig);


                myConfig = ours;


                break;


        case INPUT_DO_MERGE:


                theirs = ksDup (ours);


                kdbGet (handle, theirs, parentKey); // refresh key database


                KeySet * res = doElektraMerge (ours, theirs, base);


                ksDel (theirs);


                myConfig = res;


                break;


        case INPUT_USE_THEIRS:


                // should always work, we just write what we got


                // but to be sure always give the user another way


                // to exit the loop


                kdbGet (handle, myConfig, parentKey); // refresh key database


                break;


                // other cases ...


        }


        ret = kdbSet (handle, myConfig, parentKey);
}
ksDel (ours);
ksDel (base);
ksDel (myConfig); // delete the in-memory configuration
kdbClose (handle, parentKey); // no more affairs with the key database.
keyDel (parentKey);

showElektraErrorDialog() and doElektraMerge() need to be implemented by the user of Elektra. For doElektraMerge a 3-way merge algorithm exists in libelektra-tools.

Parameters:

Return values:

See also:

Return values:

Parameters:

Exceptions: