Elektra 0.11.0
org.libelektra.Elektra Interface Reference

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).
 

Detailed Description

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.

Member Function Documentation

◆ elektraGOptsContractFromStrings()

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.

Parameters
contractKeySetPointer to a valid KeySet into which the contract will be written.
argsSizeSize of the args data.
argsContinuous 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.
envSizeSize of the env data.
envContinuous 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.
parentKeyThe parent key that should be used by gopts. Only the key name is copied. The key can be deleted immediately after calling this function.
goptsConfigKeySetConfiguration that is used to mount the gopts plugin. Only keys in the user:/ namespace will be used.
Returns
  • 0 on success
  • -1 on null pointer passed

◆ kdbClose()

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,
Pointer)
, but you must not use any kdb*() call afterwards.

See also
#kdbOpen(Pointer, Pointer) kdbOpen()
#keyNew(String, Object...) keyNew()
Parameters
handlePointer to a valid KDB handle as returned by kdbOpen().
errorKeyPointer to a valid Key, where issued errors and warnings will be made available.
Returns
  • 0 on success
  • -1 on null pointer passed

◆ kdbGet()

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
system:/mountpoint/interest
, but also all keys below system:/mountpoint (if
system:/mountpoint
is a mountpoint as the name suggests, but
system:/mountpoint/interest
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 kdbGet() 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
KeySet
returned as passed.

See also
#kdbOpen(Pointer, Pointer) kdbOpen() which needs to be called before
ksLookup(Pointer, Pointer, int) ksLookup() and
ksLookupByName(Pointer, String, int) ksLookupByName() for powerful lookups after the KeySet was retrieved
kdbSet(Pointer, Pointer, Pointer) kdbSet() to save the configuration afterwards
kdbClose(Pointer, Pointer) kdbClose() to finish affairs with the Key database
Parameters
handlePointer to a valid KDB handle as returned by kdbOpen().
returnKeySetPointer to a valid KeySet to be populated with all keys found. It will not be changed on error or if no update is required.
parentKeyPointer 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).
  • cascading keys (starting with "/") will retrieve the same path in all namespaces
  • "/" will retrieve all keys.
Returns
  • 1 if the keys were retrieved successfully
  • 0 if there was no update
  • -1 on failure or null pointer passed
When a backend fails, kdbGet() will return -1 with all error and warning information in the parentKey and
returnKeySet
left unchanged.

◆ kdbOpen()

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.

See also
kdbGet(Pointer, Pointer, Pointer) kdbGet()
kdbClose(Pointer, Pointer) kdbClose()
#keyNew(String, Object...) keyNew()
Parameters
contractKeySetTODO #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
errorKeyPointer to a valid Key, where issued errors and warnings will be made available.
Returns
  • Pointer to KDB handle on success
  • null on failure

◆ kdbSet()

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().

See also
#kdbOpen(Pointer, Pointer) kdbopen() and
kdbGet(Pointer, Pointer, Pointer) kdbGet() must be called first
kdbClose(Pointer, Pointer) kdbClose() must be called afterwards
Parameters
handlePointer to a valid KDB handle as returned by kdbOpen().
keySetPointer to a valid KeySet containing modified keys, otherwise no update is done.
parentKeyPointer 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().
  • cascading keys (starting with "/") will set the path in all namespaces
  • "/" will commit all keys
  • metanames will be rejected (error C01320)
  • empty/invalid (error C01320)
Returns
  • 1 on success
  • 0 if nothing had to be done, no changes in KDB
  • -1 on failure or null pointer passed. No changes in KDB, an error will be set on parentKey if possible

◆ keyNew()

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

See also
keyDel(Pointer) keyDel()
Parameters
nameA valid key name. Use CASCADING_ROOT_KEY_NAME to get a simple initialized, but really empty, object.
argsArgument flags, each followed by a corresponding value, if appropriate.
Returns
  • A Pointer to a newly allocated and initialized Key object on success
  • null on allocation error or if an invalid name was passed (see keySetName()

Member Data Documentation

◆ KDB_O_DEL

final int org.libelektra.Elektra.KDB_O_DEL = 1
static

Flag for use with ksLookup(Pointer, Pointer, int).

Will cause the release of parameter key using keyDel(Pointer).

◆ KDB_O_NONE

final int org.libelektra.Elektra.KDB_O_NONE = 0
static

Flag for use with ksLookup(Pointer, Pointer, int) and ksLookupByName(Pointer, String, int).

Represents no option set.

◆ KDB_O_POP

final int org.libelektra.Elektra.KDB_O_POP = 1 << 1
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.


The documentation for this interface was generated from the following file: