$darkmode
Elektra 0.11.0
|
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 (KeySet &contract) | |
Constructs a class KDB. More... | |
KDB (KeySet &contract, Key &errorKey) | |
Constructs a class KDB. More... | |
virtual void | open (Key &errorKey) |
Open the database. More... | |
virtual void | open (KeySet &contract, Key &errorKey) |
Open the database. More... | |
virtual void | close () throw () |
Close the database. More... | |
virtual void | close (Key &errorKey) throw () |
Close the database. More... | |
virtual int | get (KeySet &returned, std::string const &keyname) |
Get all keys below keyname inside returned. More... | |
virtual int | get (KeySet &returned, Key &parentKey) |
Get all keys below parentKey inside returned. More... | |
virtual int | set (KeySet &returned, std::string const &keyname) |
Set all keys below keyname. More... | |
virtual int | set (KeySet &returned, Key &parentKey) |
Set all keys below parentKey. More... | |
virtual ElektraDiff | calculateChanges (KeySet &changedKeySet, std::string const &parentKeyName) |
Calculates the changes between the provided KeySet and the current state of the KDB. More... | |
virtual ElektraDiff | calculateChanges (KeySet &changedKeySet, Key &parentKey) |
Calculates the changes between the provided KeySet and the current state of the KDB. More... | |
ckdb::KDB * | getKdb () const |
Passes out the raw kdb pointer. More... | |
ckdb::KDB * | operator* () const |
Is an abbreviation for getKdb. More... | |
Constructs a class KDB.
KDBException | if database could not be opened |
Opens the session with the Key database.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
|
inlineexplicit |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
|
inlineexplicit |
Constructs a class KDB.
contract | the contract that should be ensured |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
Constructs a class KDB.
contract | the contract that should be ensured |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
|
inlinevirtual |
|
inlinevirtual |
|
inlinevirtual |
Close the database.
The return value does not matter because its only a null pointer check.
Closes the session with the Key database.
This is the counterpart of kdbOpen().
You must call this method when you are finished working 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 |
|
inlinevirtual |
Close 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 are finished working 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 |
Get all keys below parentKey inside returned.
Retrieve Keys from the Key database in an atomic and universal way.
handle
must be a valid KDB handle as returned from kdbOpen(). returned
must be a valid KeySet, i.e., constructed with ksNew(). returned
must contain keys only from the spec:/
, dir:/
, user:/
, system:/
, default:/
or proc:/
namespaces. parentKey
must be a valid Key, i.e., constructed with keyNew(). parentKey
must not have read-only name, value or metadata. parentKey
must use the spec:/
, dir:/
, user:/
, system:/
, default:/
, proc:/
or cascading namespace.If you pass NULL
or a key with read-only metadata as parentKey
, kdbGet() will fail immediately without doing anything. If you pass another invalid parentKey
, or NULL
as ks
or handle
, kdbGet() will set an error on parentKey
and then return immediately.
parentKey
with writable metadata, kdbGet() will always remove any existing errors and warnings from parentKey
.handle
you must make sure to pass all keys from ks
, which you do not want to remove.Not all namespace can be loaded.
spec:/
, dir:/
, user:/
and system:/
can be loaded via kdbGet().proc:/
keys can be loaded via kdbGet(), but are not persisted or cached.default:/
keys can be inserted by kdbGet() but they will always stem from a specification in spec:/
keys.ks
contains a key with any other namespace, an error will be returned.The parentKey
defines which parts of ks
will be loaded. Everything that is at or below parentKey
wil be loaded together with any key that shares a backend with such a key. Backends are always loaded as an atomic unit.
parentKey
is in the cascading namespace, keys of all loadable namespaces (see above) will be loaded. This is generally the recommended approach.Upon sucessfully returning kdbGet() also sets the value of parentKey
to the storage identifier used by the backend that contains (or would contain) parentKey
. For file-based backends this is the absolute path of the underlying file. Other backends may use different identifiers, but it always uniquely identifies the underlying storage unit.
parentKey
is in the cascading, default:/
or `proc:/ namespace, the value of parentKey
will be set to an empty string. This is done, because those namespaces are not persistable (see kdbSet()) and therfore have no storage identifier.Below or at parentKey
, the KeySet ks
will mostly contain keys loaded from backends. The only exception are proc:/
and spec:/
keys that were already present, before kdbGet() was called and do not overlap with an existing backend (for those namespaces). This can be used to provide a hard-coded fallback specifications and/or process-specific data.
Keys not below (or at) parentKey
that were present when kdbGet() was called, may still be removed. For example, this could be because they overlap with a backend that also has keys below parentKey
(backends are atomic units).
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 be sure to get a fresh KeySet again, you need to open a second handle to the Key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | Keys below parentKey will be retrieved from handle . It is also used to add warnings and set error information. |
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
2 | if only proc:/ backends were executed. This means no data was loaded from storage. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as errors! |
1 | if the Keys were retrieved successfully. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as errors! |
0 | if there was no update at all - no changes are made to the KeySet then. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as erorrs! |
-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 |
Reimplemented in kdb::tools::merging::MergingKDB.
|
inlinevirtual |
Get all keys below keyname inside returned.
Retrieve Keys from the Key database in an atomic and universal way.
handle
must be a valid KDB handle as returned from kdbOpen(). returned
must be a valid KeySet, i.e., constructed with ksNew(). returned
must contain keys only from the spec:/
, dir:/
, user:/
, system:/
, default:/
or proc:/
namespaces. parentKey
must be a valid Key, i.e., constructed with keyNew(). parentKey
must not have read-only name, value or metadata. parentKey
must use the spec:/
, dir:/
, user:/
, system:/
, default:/
, proc:/
or cascading namespace.If you pass NULL
or a key with read-only metadata as parentKey
, kdbGet() will fail immediately without doing anything. If you pass another invalid parentKey
, or NULL
as ks
or handle
, kdbGet() will set an error on parentKey
and then return immediately.
parentKey
with writable metadata, kdbGet() will always remove any existing errors and warnings from parentKey
.handle
you must make sure to pass all keys from ks
, which you do not want to remove.Not all namespace can be loaded.
spec:/
, dir:/
, user:/
and system:/
can be loaded via kdbGet().proc:/
keys can be loaded via kdbGet(), but are not persisted or cached.default:/
keys can be inserted by kdbGet() but they will always stem from a specification in spec:/
keys.ks
contains a key with any other namespace, an error will be returned.The parentKey
defines which parts of ks
will be loaded. Everything that is at or below parentKey
wil be loaded together with any key that shares a backend with such a key. Backends are always loaded as an atomic unit.
parentKey
is in the cascading namespace, keys of all loadable namespaces (see above) will be loaded. This is generally the recommended approach.Upon sucessfully returning kdbGet() also sets the value of parentKey
to the storage identifier used by the backend that contains (or would contain) parentKey
. For file-based backends this is the absolute path of the underlying file. Other backends may use different identifiers, but it always uniquely identifies the underlying storage unit.
parentKey
is in the cascading, default:/
or `proc:/ namespace, the value of parentKey
will be set to an empty string. This is done, because those namespaces are not persistable (see kdbSet()) and therfore have no storage identifier.Below or at parentKey
, the KeySet ks
will mostly contain keys loaded from backends. The only exception are proc:/
and spec:/
keys that were already present, before kdbGet() was called and do not overlap with an existing backend (for those namespaces). This can be used to provide a hard-coded fallback specifications and/or process-specific data.
Keys not below (or at) parentKey
that were present when kdbGet() was called, may still be removed. For example, this could be because they overlap with a backend that also has keys below parentKey
(backends are atomic units).
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 be sure to get a fresh KeySet again, you need to open a second handle to the Key database using kdbOpen().
handle | contains internal information of opened key database |
parentKey | Keys below parentKey will be retrieved from handle . It is also used to add warnings and set error information. |
ks | the (pre-initialized) KeySet returned with all keys found will not be changed on error or if no update is required |
2 | if only proc:/ backends were executed. This means no data was loaded from storage. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as errors! |
1 | if the Keys were retrieved successfully. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as errors! |
0 | if there was no update at all - no changes are made to the KeySet then. There might be warnings attached to the parentKey! Depending on your use case, you might need to treat them as erorrs! |
-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 |
Reimplemented in kdb::tools::merging::MergingKDB.
|
inline |
Passes out the raw kdb pointer.
This pointer can be used to directly interact with the underlying kdb instance
|
inlinevirtual |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
Open the database.
contract | the contract that should be ensured |
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.
You must always call this method before retrieving or committing any keys to the database. At the end of a program, after using the Key database (KDB), you must not forget to call kdbClose() to free resources.
The method will bootstrap itself in 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. Then the global plugins and global keyset data from the contract
is processed. Finally, the libraries for backends will be loaded and with it the KDB
data structure will be initialized.
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.
contract | the contract that should be ensured before opening the KDB all data is copied and the KeySet can safely be used for e.g. kdbGet() later |
errorKey | the key which holds errors and warnings which were issued |
NULL | on failure |
|
inline |
Is an abbreviation for getKdb.
Passes out the raw kdb pointer. This pointer can be used to directly interact with the underlying kdb instance
Set all keys below parentKey.
If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
Set Keys to the Key database in an atomic and universal way.
ks
must be a valid KeySet, i.e., constructed with ksNew(). ks
must only contain only keys in the spec:/
, dir:/
, user:/
, system:/
, default:/
or proc:/
namespaces. parentKey
must be a valid Key, e.g. constructed with keyNew(). parentKey
must not have read-only name, value or metadata. parentKey
must use the spec:/
, dir:/
, user:/
, system:/
, default:/
, proc:/
or cascading namespace.If you pass NULL
or a key with read-only metadata as parentKey
, kdbSet() will fail immediately without doing anything. If you pass another invalid parentKey
, or NULL
as ks
or handle
, kdbSet() will set an error on parentKey
and then return immediately.
parentKey
with writable metadata, kdbSet() will always remove any existing errors and warnings from parentKey
.Not all namespace can be persisted.
spec:/
, dir:/
, user:/
and system:/
will be persisted by kdbSet().default:/
and proc:/
keys are ignored by kdbSet().ks
contains a key with any other namespace, an error will be returned.In general it is recommended to use a parentKey
in the cascading namespace to cover all namespaces at once.
The parentKey
defines which parts of ks
will be stored. Everything that is at or below parentKey
will be persisted together with any key that shares a backend with such a key. Backends are always stored as an atomic unit.
parentKey
is in the cascading namespace, keys of all persistable namespaces (see above) will be stored. This is generally the recommended approach.The contents of ks
will mostly not be modified by kdbSet(). The only modifications made are those caused by applying the specification in spec:/
to dir:/
, user:/
and system:/
.
parentKey == NULL
or parentKey
has read-only metadata, kdbSet() will immediately return the error code -1. In all other error cases the following happens:In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:
If none of the backends needs an update, kdbSet() returns 0 and does nothing.
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 | Keys below parentKey will be set to handle . It is also used to add warnings and set error information. |
1 | on success |
0 | if nothing had to be done, no changes in KDB |
-1 | on failure, no changes in KDB, an error will be set on parentKey if possible (see "Errors" above) |
handle
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 |
|
inlinevirtual |
Set all keys below keyname.
If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
Set Keys to the Key database in an atomic and universal way.
ks
must be a valid KeySet, i.e., constructed with ksNew(). ks
must only contain only keys in the spec:/
, dir:/
, user:/
, system:/
, default:/
or proc:/
namespaces. parentKey
must be a valid Key, e.g. constructed with keyNew(). parentKey
must not have read-only name, value or metadata. parentKey
must use the spec:/
, dir:/
, user:/
, system:/
, default:/
, proc:/
or cascading namespace.If you pass NULL
or a key with read-only metadata as parentKey
, kdbSet() will fail immediately without doing anything. If you pass another invalid parentKey
, or NULL
as ks
or handle
, kdbSet() will set an error on parentKey
and then return immediately.
parentKey
with writable metadata, kdbSet() will always remove any existing errors and warnings from parentKey
.Not all namespace can be persisted.
spec:/
, dir:/
, user:/
and system:/
will be persisted by kdbSet().default:/
and proc:/
keys are ignored by kdbSet().ks
contains a key with any other namespace, an error will be returned.In general it is recommended to use a parentKey
in the cascading namespace to cover all namespaces at once.
The parentKey
defines which parts of ks
will be stored. Everything that is at or below parentKey
will be persisted together with any key that shares a backend with such a key. Backends are always stored as an atomic unit.
parentKey
is in the cascading namespace, keys of all persistable namespaces (see above) will be stored. This is generally the recommended approach.The contents of ks
will mostly not be modified by kdbSet(). The only modifications made are those caused by applying the specification in spec:/
to dir:/
, user:/
and system:/
.
parentKey == NULL
or parentKey
has read-only metadata, kdbSet() will immediately return the error code -1. In all other error cases the following happens:In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are:
If none of the backends needs an update, kdbSet() returns 0 and does nothing.
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 | Keys below parentKey will be set to handle . It is also used to add warnings and set error information. |
1 | on success |
0 | if nothing had to be done, no changes in KDB |
-1 | on failure, no changes in KDB, an error will be set on parentKey if possible (see "Errors" above) |
handle
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 |