Elektra  0.9.7
Public Member Functions | Public Attributes | List of all members
org.libelektra.Elektra Interface Reference

The JNA dynamic proxy interface to libelektra. More...

Inherits Library.

Public Member Functions

Pointer kdbOpen (@Nullable Pointer contractKeySet, Pointer errorKey)
 Opens the session with the Key database. More...
 
int kdbClose (Pointer handle, Pointer errorKey)
 Closes the session with the Key database. More...
 
int kdbGet (Pointer handle, Pointer returnKeySet, Pointer parentKey)
 Retrieve keys in an atomic and universal way. More...
 
int kdbSet (Pointer handle, Pointer keySet, Pointer parentKey)
 Set keys in an atomic and universal way. More...
 
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. More...
 
Pointer keyNew (@Nullable String name, @Nullable Object... args)
 A practical way to fully create a Key object in one step. More...
 

Public Attributes

Elektra INSTANCE = Native.load ("elektra-kdb", Elektra.class)
 Singleton instance of the native library proxy.
 

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*()
This is the main namespace for the C++ binding and libraries.
Definition: backend.hpp:31

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

@implNote Optimization: Each key is checked using the native function underlying keyNeedSync() before being actually committed. If no key of a backend needs to be synced any affairs to backends are omitted and

0

is returned.
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
#keyNeedSync(Pointer) keyNeedSync()
#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 name to the key, or KEY_NAME_SIMPLE_INITALIZED_BUT_EMPTY_OBJECT 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()

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