$darkmode
Elektra 0.11.0
|
The goal of the high-level API is to increase the usability of libelektra for developers who want to integrate Elektra into their applications. Applications usually do not want to use low-level APIs. KDB
and KeySet
are useful for plugins and to implement APIs, but not to be directly used in applications. The high-level API should be extremely easy to get started with and at the same time it should be hard to use it in a wrong way. This tutorial gives an introduction for developers who want to elektrify their application using the high-level API.
The API supports all CORBA Basic Data Types, except for wchar
, as well as the string
type (see also Data Types below).
First you have to add elektra-highlevel
, elektra-kdb
and elektra-ease
to the linked libraries of your application. To be able to use it in your source file, just include the main header with #include <elektra.h>
at the top of your file.
The quickest way to get started is to adapt the following piece of code to your needs:
To run the application, the configuration should be specified:
The getter and setter functions follow the simple naming scheme elektra
(Get
/Set
)[Type]. Additionally for each one there is a variant to access array elements with the suffix ArrayElement
. For more information see below.
You can find a complete example at the end of this document and here.
In Elektra keys may have attached metadata describing additional properties of the key. By using Elektra'snamespaces" and @ref doc_tutorials_cascading_md "cascading keys" it is also possible to have a full specification of your applications configuration.
This specification should be placed into the spec
namespace. From there the high-level API and Elektra's plugins will access it. A specification for use with the high-level API has to define at least the default
and the type
metadata for each key the application is going to use. The default
metakey simply defines which value will be returned, if the user didn't set a value. type
defines the data type of key. For more information on data types see below.
The API also supports passing a KeySet
to elektraOpen
that contains the specification. This is, however, not recommended for general use and is mainly useful for debugging and testing purposes.
Elektra
is the handle you use to access the underlying KDB (hierarchical key database) that stores the configuration key-value pairs. All key-value read and write operations expect this handle to be passed as in as a parameter. To create the handle, you simply write:
Please replace "/sw/org/myapp/#0/current"
with an appropriate value for your application (see here for more information). You can use the parameter defaults
to pass a KeySet
containing Key
s with default values to the Elektra
instance.
The ElektraError
can be used to check for initialization errors. You can detect initialization errors by comparing the result of elektraOpen
to NULL:
If an error occurred, you must call elektraErrorReset
before using the same error pointer in any other function calls (e.g. elektraSet*
calls). It is also safe to call elektraErrorReset
, if no error occurred.
In order to give Elektra the chance to clean up all its allocated resources, you have to close your instance, when you are done using it, by calling:
NOTE: Elektra is only thread-safe when you use one handle per thread or protect your handle. If you have multiple threads accessing key-values, create a separate handle for each thread to avoid concurrency issues.
The library is designed to shield developers from the many errors one can encounter when using KDB directly. However it is not possible to hide all those issues. As with every library, things can go wrong and there needs to be a way to react to errors once they have occurred at runtime. Therefore the high-level API introduces a struct called ElektraError
, which encapsulates all information necessary for the developer to handle runtime-errors appropriately in the application.
Functions that can produce errors, despite correct use of the API, accept an ElektraError
pointer as parameter, for example:
In most cases you'll want to set the error variable to NULL
before passing it to the function. You can do this either by declaring and initializing a new variable with ElektraError * error = NULL
or by reusing an already existing error variable by resetting it with elektraErrorReset (&error)
.
Notice, that you should always check if an error occurred by comparing it to NULL
after the function call.
If an error happened, it is often useful to show an error message to the user. A description of what went wrong is provided in the ElektraError
struct and can be accessed using elektraErrorDescription (error)
. Additionally the error code can be accessed through elektraErrorCode (error)
. NOTE: The error API is still a work in progress, so more functions will likely be added in the future.
To avoid leakage of memory, you have to call elektraErrorReset (&error)
(ideally as soon as you are finished resolving the error):
Currently there is only one way to configure an Elektra
instance:
This allows you to set the callback called by Elektra, when a fatal error occurs. Technically a fatal error could occur at any time, but the most common use case for this callback is inside of functions that do not take a separate ElektraError
argument. For example, this function will be called, when any of the getter-functions is called on a non-existent key which is not part of any specification, and therefore has no specified default value.
If you provide your own callback, it must interrupt the thread of execution in some way (e.g. by calling exit()
or throwing an exception in C++). It must not return to the calling function.
The handler will also be called whenever you pass NULL
where a function expects an ElektraError **
. In this case the error code will be ELEKTRA_ERROR_CODE_NULL_ERROR
.
The default callback simply logs the error with ELEKTRA_LOG_DEBUG
and then calls exit()
with exit code EXIT_FAILURE
It is expected that you implement your own callback, so that you get proper error message logged in your applications preferred format. Using the default callback is only viable for very simple applications, because you won't get any indication as to which key caused the error (unless you compiled Elektra with debug logging enabled).
The API determines the data type of a given key, by reading its type
metadata. The API supports the following types, which are taken from the CORBA specification:
string
in metadatatrue
or false
, represented by boolean
in metadata, in the KDB the raw value "1"
is regarded as true, "0"
regarded as false and any other value is an errorchar
in metadataoctet
in metadatashort
(unsigned_short
) in metadatalong
(unsigned_long
) in metadatalong_long
(unsigned_long_long
) in metadatafloat
, probably IEEE-754 single-precision, represented by float
in metadatadouble
, probably IEEE-754 double-precision, represented by double
in metadatalong double
, not always available, represented by long_double
in metadataThe API contains one header that is not automatically included from elektra.h
. You can use it with #include <elektra/conversion.h>
. The header provides the functions Elektra uses to convert your configuration values to and from strings. In most cases, you won't need to use these functions directly, but they might still be useful sometimes (e.g. in combination with elektraGetType
and elektraGetRawString
). We also provide a KDB_TPYE_*
constant for each of the types listed above. Again, most users won't use these but, if you ever do need to use the raw type metadata using constants enables code completion and protects against typos.
There is also the type enum
with constant KDB_TYPE_ENUM
. It is only supported via the code-generation API.
We enforce a few minimum properties for floating point types. They are taken from the IEE-754 specification and are:
float
: 32 bits, binary, 24 mantissa digits and exponent range of at least -125 to 128double
: 64 bits, binary, 53 mantissa digits and exponent range of at least -1021 to 1024long double
: at least 80 bits, binary, at least 64 mantissa digits and exponent range of at least -2^14 + 3 to 2^14Additionally for C++ compilers we use a static_assert
that will fail if std::numeric_limits<T>::is_iec559
is false
when T
is any of float
, double
or long double
.
While these checks won't ensure actual IEEE-754 arithmetic, they will at least ensure all values can be represented correctly.
When calling elektraOpen
you pass the parent key for your application. Afterwards getters and setters get passed in only the part below that key in the KDB. For example, if you call elektraOpen
with "/sw/org/myapp/#0/current"
, you can access your applications configuration value for the key "/sw/org/myapp/#0/current/message"
with the provided getters and setters by passing them only "message"
as the name for the configuration value.
A typical application wants to read some configuration values at start. This should be made as easy as possible for the developer. Reading configuration data in most cases is not part of the business logic of the application and therefore should not "pollute" the applications source code with cumbersome setup and file-parsing code. This is exactly where Elektra comes in handy, because you can leave all the configuration file handling and parsing to the underlying layers of Elektra and just use the high-level API to access the desired data. Reading values from KDB can be done with elektra-getter functions that follow a simple naming scheme:
elektraGet
+ the type of the value you want to read.
For example, you can get the value for the key named "message" like this:
Sometimes you'll want to access arrays as well. You can access single elements of an array using the provided array-getters following again a simple naming scheme:
elektraGet
+ the type of the value you want to read + ArrayElement
.
For example, you can get the value at index 3 for the array "message" like this:
To get the size of the array you would like to access you can use the function elektraArraySize
:
For some background information on arrays in Elektra see the Array tutorial, as well as our decision document on this topic. Please note that the high level API does not support arrays with missing elements. If an element is missing (and the specification provides no default value), getters will fail.
Notice that both the getters for primitive types and the getters for array types do not accept error parameters. The library expects you to run a correct Elektra setup. If the configuration is well specified, no runtime errors can occur when reading a value. Therefore the getters do not accept an error variable as argument. If there is however a severe internal error, or you try to access a key which you have not specified correctly, then the library will call the error callback set with elektraFatalErrorHandler
to prevent data inconsistencies or exceptions further down in your application.
You can find the complete list of the available functions for all supported value types in elektra.h
Sometimes, after having read a value from the KDB, you will want to write back a modified value. As described in Read values from the KDB we follow a naming scheme for getters. The high-level API provides setters follow an analogous naming scheme as well. For example, to write back a modified "message", you can call elektraSetString
:
The counterpart for array-getters again follows the same naming scheme:
Because even the best specification and perfect usage as intended can not prevent any error from occurring, when saving the configuration, all setter-functions take an additional ElektraError
argument, which will be set if an error occurs.
You can use const char * elektraGetRawString (Elektra * elektra, const char * name)
to read the raw (string) value of a key. No type checking or type conversion will be attempted. Additionally this function does not call the fatal error handler. It will simply return NULL
, if the key was not found.
If you want to set a raw value, use void elektraSetRawString (Elektra * elektra, const char * name, const char * value, KDBType type, ElektraError ** error)
. Obviously you have to provide a type for the value you set, so that the API can perform type checking, when reading the value next time.
Similar functions are provided for array elements:
The type information is stored in the "type"
metakey. KDBType elektraGetType (Elektra * elektra, const char * keyname)
(or KDBType elektraGetArrayElementType (Elektra * elektra, const char * name, kdb_long_long_t index)
for array elements) lets you access this information. A setter is not provided, because Elektra assumes keys to always have the same type (as specified).
elektraGetType
, elektraGetRawString
and elektraSetRawString
can be used together to create custom data types. If your application for example uses arbitrary-precision integers, you could something similar to these functions:
To get the type
plugin to validate your custom types you should make sure the check/type
metadata is set to string
(or any
) on all keys that use custom types. This works, because the type
plugin prefers the value of check/type
over that of type
.
The high-level API does not support binary key values at this time.