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

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.

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

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.

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

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

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.

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

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

name	A valid name to the key, or KEY_NAME_SIMPLE_INITALIZED_BUT_EMPTY_OBJECT to get a simple initialized, but really empty, object.
args	Argument 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:

• Elektra.java