Elektra 0.11.0
|
The JNA dynamic proxy interface to libelektra. More...
Public Member Functions | |
Pointer | kdbOpen (@Nullable Pointer contractKeySet, Pointer errorKey) |
Opens the session with the Key database. | |
int | kdbClose (Pointer handle, Pointer errorKey) |
Closes the session with the Key database. | |
int | kdbGet (Pointer handle, Pointer returnKeySet, Pointer parentKey) |
Retrieve keys in an atomic and universal way. | |
int | kdbSet (Pointer handle, Pointer keySet, Pointer parentKey) |
Set keys in an atomic and universal way. | |
int | elektraGOptsContractFromStrings (Pointer contractKeySet, long argsSize, String args, long envSize, String env, Pointer parentKey, @Nullable Pointer goptsConfigKeySet) |
Sets up a contract for use with kdbOpen() that configures the gopts plugin. | |
Pointer | keyNew (@Nullable String name, @Nullable Object... args) |
A practical way to fully create a Key object in one step. | |
Public Attributes | |
Elektra | INSTANCE = Native.load("elektra-kdb", Elektra.class) |
Singleton instance of the native library proxy. | |
Static Public Attributes | |
static final Pointer | KS_END = null |
Use to terminate var args array ksNew(int, Object...) . | |
static final int | KDB_O_NONE = 0 |
Flag for use with ksLookup(Pointer, Pointer, int) and ksLookupByName(Pointer,
String, int) . | |
static final int | KDB_O_DEL = 1 |
Flag for use with ksLookup(Pointer, Pointer, int) . | |
static final int | KDB_O_POP = 1 << 1 |
Flag for use with ksLookup(Pointer, Pointer, int) and ksLookupByName(Pointer,
String, int) . | |
The JNA dynamic proxy interface to libelektra.
This proxy is not intended to be used directly by libelektra API consumers. Please see KDB
and its accompanying classes.
int org.libelektra.Elektra.elektraGOptsContractFromStrings | ( | Pointer | contractKeySet, |
long | argsSize, | ||
String | args, | ||
long | envSize, | ||
String | env, | ||
Pointer | parentKey, | ||
@Nullable Pointer | goptsConfigKeySet ) |
Sets up a contract for use with kdbOpen()
that configures the gopts
plugin.
contractKeySet | Pointer to a valid KeySet into which the contract will be written. |
argsSize | Size of the args data. |
args | Continuous buffer containing all argv arguments separated (and terminated) by zero bytes. The whole buffer is copied, so the pointer only has to be valid for this function call. |
envSize | Size of the env data. |
env | Continuous buffer containing all environment variables separated (and terminated) by zero bytes The whole buffer is copied, so the pointer only has to be valid for this function call. |
parentKey | The parent key that should be used by gopts . Only the key name is copied. The key can be deleted immediately after calling this function. |
goptsConfigKeySet | Configuration that is used to mount the gopts plugin. Only keys in the user:/ namespace will be used. |
0
on success -1
on null
pointer passed int org.libelektra.Elektra.kdbClose | ( | Pointer | handle, |
Pointer | errorKey ) |
Closes the session with the Key database.
You must call this method when you finished your affairs with the key database. You can still manipulate Key
and KeySet
objects after calling #kdbClose(Pointer,
, but you must not use any
Pointer)kdb*()
call afterwards.
handle | Pointer to a valid KDB handle as returned by kdbOpen() . |
errorKey | Pointer to a valid Key , where issued errors and warnings will be made available. |
0
on success -1
on null
pointer passed int org.libelektra.Elektra.kdbGet | ( | Pointer | handle, |
Pointer | returnKeySet, | ||
Pointer | parentKey ) |
Retrieve keys in an atomic and universal way.
The returnKeySet
may already contain some keys, e.g. from previous kdbGet()
calls. The new retrieved keys will be appended using the native function underlying ksAppendKey()
.
@apiNote kdbGet()
might retrieve more keys than requested (that are not below parentKey). These keys must be passed to when saving modifications via kdbSet()
, otherwise they will be lost. This stems from the fact that the user has the only copy of the whole configuration and backends only write configuration that was passed to them. For example, if you get system:/mountpoint/interest
you will not only get all keys below
, but also all keys below
system:/mountpoint/interestsystem:/mountpoint
(if
is a mountpoint as the name suggests, but
system:/mountpoint
is not a mountpoint). Make sure to not touch or remove keys outside the keys of interest, because others may need them! @implNote Optimization: In the first run of
system:/mountpoint/interestkdbGet()
all requested (or more) keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay in the
returned as passed.
KeySet
KeySet
was retrieved handle | Pointer to a valid KDB handle as returned by kdbOpen() . |
returnKeySet | Pointer to a valid KeySet to be populated with all keys found. It will not be changed on error or if no update is required. |
parentKey | Pointer to a valid Key . It is used to add warnings and set an error information. Additionally, its name is a hint which keys should be retrieved (it is possible that more are retrieved, see API Note).
|
1
if the keys were retrieved successfully 0
if there was no update -1
on failure or null
pointer passed kdbGet()
will return -1
with all error and warning information in the parentKey
and
returnKeySet
left unchanged. Pointer org.libelektra.Elektra.kdbOpen | ( | @Nullable Pointer | contractKeySet, |
Pointer | errorKey ) |
Opens the session with the Key database.
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()
.
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.
contractKeySet | TODO #3754 - documentation unclear - 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 | Pointer to a valid Key , where issued errors and warnings will be made available. |
Pointer
to KDB handle
on success null
on failure int org.libelektra.Elektra.kdbSet | ( | Pointer | handle, |
Pointer | keySet, | ||
Pointer | parentKey ) |
Set keys in an atomic and universal way.
For the particularities of error handling, please see the documentation of the native library: TODO #3754 link to C API documentation
@apiNote kdbGet()
must be called before kdbSet()
: initially (after kdbOpen()
) and also after conflict errors in kdbSet()
.
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 | Pointer to a valid KDB handle as returned by kdbOpen() . |
keySet | Pointer to a valid KeySet containing modified keys, otherwise no update is done. |
parentKey | Pointer to a valid Key . It 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).With parentKey you can give an hint which part of the given KeySet is of interest to 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() .
|
Pointer org.libelektra.Elektra.keyNew | ( | @Nullable String | name, |
@Nullable Object... | args ) |
A practical way to fully create a Key object in one step.
For examples and further particularities, please see the documentation of the native library: TODO #3754 link to C API documentation
name | A valid key name. Use CASCADING_ROOT_KEY_NAME to get a simple initialized, but really empty, object. |
args | Argument flags, each followed by a corresponding value, if appropriate. |
Pointer
to a newly allocated and initialized Key
object on success null
on allocation error or if an invalid name
was passed (see keySetName()
|
static |
Flag for use with ksLookup(Pointer, Pointer, int)
.
Will cause the release of parameter key
using keyDel(Pointer)
.
|
static |
Flag for use with ksLookup(Pointer, Pointer, int)
and ksLookupByName(Pointer,
String, int)
.
Represents no option set.
|
static |
Flag for use with ksLookup(Pointer, Pointer, int)
and ksLookupByName(Pointer,
String, int)
.
Will cause the found key to be removed from the key set.