Elektra 0.11.0
|
Files | |
file | kdbnotification.h |
Elektra-Notification structures and declarations for application developers. | |
file | kdbnotificationinternal.h |
Elektra-Notification structures and declarations for developing notification and transport plugins. | |
Typedefs | |
typedef void(* | ElektraNotificationConversionErrorCallback) (Key *key, void *context) |
Callback function called when string to number conversion failed. | |
typedef void(* | ElektraNotificationChangeCallback) (Key *key, void *context) |
Callback function for key changes. | |
Functions | |
int | elektraNotificationRegisterCallback (KDB *kdb, Key *key, ElektraNotificationChangeCallback callback, void *context) |
Subscribe for updates via callback when a given key value is changed. | |
int | elektraNotificationRegisterCallbackSameOrBelow (KDB *kdb, Key *key, ElektraNotificationChangeCallback callback, void *context) |
Subscribe for updates via callback when a given key or a key below changed. | |
ELEKTRA_NOTIFICATION_REGISTER_SIGNATURE (int, Int) | |
Subscribe for automatic updates to a given variable when the given key value is changed. | |
Notification feature
For an introduction to notifications please see the Notification Tutorial.
Examples:
elektraNotificationContract() returns a contract for use with kdbOpen(). The contract ensures that the internalnotification plugin is registered into the correct hook and configured correctly.
Notification transport plugins (or simply transport plugins) need access to an I/O binding, as well as a notification callback and context.
All of these can be retrieved from the global keyset. The keys are as follows:
system:/elektra/io/binding
Type: ElektraIoInterface *
system:/elektra/notification/callback
Type: ElektraNotificationCallback
system:/elektra/notification/context
Type: ElektraNotificationCallbackContext *
All of these keys are binary and store a pointer that can be read via *(TYPE **) keyValue (key)
.
The I/O binding can be accessed at any time. It is recommended, plugins read the key once during their open
function and store the pointer in their plugin data struct.
The notification callback and context are provided by the internalnotification
plugin. Since it might be initialised after the transport plugin, it is not recommended to read the callback and context in the open
function. Instead the plugin should read and store the values when the first notification is processed.
Transport plugins should handle missing I/O bindings, notification callbacks and notification contexts gracefully. The plugin should not report and error and instead simply log a debug or warning message.
typedef void(* ElektraNotificationChangeCallback) (Key *key, void *context) |
Callback function for key changes.
key | changed key |
context | user supplied callback context |
typedef void(* ElektraNotificationConversionErrorCallback) (Key *key, void *context) |
Callback function called when string to number conversion failed.
key | key with invalid value |
context | user supplied callback context |
ELEKTRA_NOTIFICATION_REGISTER_SIGNATURE | ( | int | , |
Int | ) |
Subscribe for automatic updates to a given variable when the given key value is changed.
On kdbGet iff the key is present and its content is valid, the registered variable is updated.
handle | plugin handle |
key | key to watch for changes |
variable | variable |
1 | on success |
0 | on failure |
int elektraNotificationRegisterCallback | ( | KDB * | kdb, |
Key * | key, | ||
ElektraNotificationChangeCallback | callback, | ||
void * | context ) |
Subscribe for updates via callback when a given key value is changed.
handle | plugin handle |
key | key to watch for changes |
callback | callback function |
context | user supplied context passed to callback function |
1 | on success |
0 | on failure |
int elektraNotificationRegisterCallbackSameOrBelow | ( | KDB * | kdb, |
Key * | key, | ||
ElektraNotificationChangeCallback | callback, | ||
void * | context ) |
Subscribe for updates via callback when a given key or a key below changed.
handle | plugin handle |
key | key to watch for changes |
callback | callback function |
context | user supplied context passed to callback function |
1 | on success |
0 | on failure |