Elektra
0.8.23
|
Projects usually do not want to use low-level APIs. KDB
and KeySet
is useful for plugins and to implement APIs but not to be directly used in applications.
KeySet
or exit after elektraOpen)KDB
, applications need to implement their own APIs:string
if not givendefault
to be part of parametersWe provide 3 high-level C APIs:
Furthermore, we will:
elektraGetType
before getting a value, no error can occur when getting it laterelektraError
as extra parameter (for prototyping and examples you can pass 0)(needed for lcdproc)
```c Elektra * elektraOpen (const char * application, const KeySet * defaultSpec, ElektraError ** error); void elektraReload (Elektra * handle, ElektraError ** error); void elektraParse (Elektra * handle, int argc, char ** argv, char ** environ); // pass environ? void elektraDefault (Elektra * handle); void elektraClose (Elektra * handle); ```
If NULL
is passed as error, the API will try to continue if possible. On fatal errors, i.e. on API misuse or when it is not safe to use the handle afterwards, the API aborts with exit
.
If you want to avoid elektraOpen
or later elektraReload
to fail, make sure to use pass a KeySet
, that has your whole specification included (and defaults everywhere needed).
```c const char * elektraErrorMessage (const ElektraError * error); kdb_boolean_t elektraErrorAbort (const ElektraError * error); void elektraErrorFree (ElektraError * error) ```
elektraErrorAbort
tells you if you need to quit your application because of severe issues that are permanent. Otherwise, developers can just print the message and continue. (Default settings might be used then.)
(most of them needed for lcdproc)
```c // getters const char * elektraGetString (Elektra * elektra, const char * name); kdb_boolean_t elektraGetBoolean (Elektra * elektra, const char * name); kdb_char_t elektraGetChar (Elektra * elektra, const char * name); kdb_octet_t elektraGetOctet (Elektra * elektra, const char * name); kdb_short_t elektraGetShort (Elektra * elektra, const char * name); kdb_unsigned_short_t elektraGetUnsignedShort (Elektra * elektra, const char * name); kdb_long_t elektraGetLong (Elektra * elektra, const char * name); kdb_unsigned_long_t elektraGetUnsignedLong (Elektra * elektra, const char * name); kdb_long_long_t elektraGetLongLong (Elektra * elektra, const char * name); kdb_unsigned_long_long_t elektraGetUnsignedLongLong (Elektra * elektra, const char * name); kdb_float_t elektraGetFloat (Elektra * elektra, const char * name); kdb_double_t elektraGetDouble (Elektra * elektra, const char * name); kdb_long_double_t elektraGetLongDouble (Elektra * elektra, const char * name); ```
(needed for lcdproc)
```c size_t elektraArraySize (Elektra * handle, const char * name); kdb_long_t elektraArrayLong (Elektra * handle, const char * name, size_t elem); // same types as above
```
(needed for lcdproc)
For every entry in the specification, such as:
``` [key] default=10 type=long ```
The code generator yields:
kdb_long_t elektraGetKey(Elektra * handle);
KeySet
to be used as defaultSpecelektraOpenOrgApplication()
All spec keys together are part of the KeySet that is automatically applied on failures in lower-level calls when using: elektraOpenOrgApplication()
where OrgApplication
is the org and application name.
In the specification:
``` [server/serverScreen] check/enum/#0=off check/enum/#1=on check/enum/#2=blank ```
The code generator emits:
``` typedef enum { ELEKTRA_ENUM_SERVER_SERVERSCREEN_OFF = 0, ELEKTRA_ENUM_SERVER_SERVERSCREEN_ON = 1, ELEKTRA_ENUM_SERVER_SERVERSCREEN_BLANK = 2, } ElektraEnumScreen; ```
Which can be used as:
``` ElektraEnumScreen elektraGetEnum(...); ```
``` [server] define/type/serverscreenstatus define/type/serverscreenstatus/check/enum/#0=off define/type/serverscreenstatus/check/enum/#1=on define/type/serverscreenstatus/check/enum/#2=blank ```
Then we can define:
``` [server/serverScreen] type = serverscreenstatus ```
``` typedef enum { ELEKTRA_ENUM_SERVER_SERVERSCREEN_OFF = 0, ELEKTRA_ENUM_SERVER_SERVERSCREEN_ON = 1, ELEKTRA_ENUM_SERVER_SERVERSCREEN_BLANK = 2, } ElektraEnumScreenStatus; ```
(not needed for lcdproc)
```c // gives you a duplicate for other threads (same application+version), automatically calls elektraErrorClear Elektra * elektraDup (Elektra * handle);
enum ElektraType { ELEKTRA_TYPE_BOOLEAN, ELEKTRA_TYPE_NONE, ... };
ElektraType elektraGetType (Elektra * handle);
KDB * elektraGetKDB (Elektra * handle); KeySet * elektraGetKeySet (Elektra * handle, const char * cutkey); KeySet * elektraGetKeyHierarchy (Elektra * handle, const char * cutkey);
// enum, int, tristate void elektraSetInt (Elektra * handle, const char * name, int value); ```
(not needed for lcdproc)
```c // will be used internally in elektraGetInt, are for other APIs useful, too int keyGetInt (Key * key);
// and so on ```
(needed for lcdproc in a client)
A tree of KeyHierarchy
elements, each element has a Key
embedded. Can be transformed from/to keysets. With iterators to iterate over sub KeyHierarchy
elements.
```c keyhHasChildren (KeyHierarchy * kh);
// TODO, add rest of API ```
Very easy to get started with, to get a key needs 3 lines of codes:
```c Elektra *handle = elektraOpen ("/sw/elektra/kdb/#0/current", 0); printf ("number /mykey is " ELEKTRA_LONG_F "\n", elektraGetLong (handle, "/mykey")); elektraClose (handle); ```