Elektra 0.11.0
Files | Typedefs | Functions
Notification

Notification feature. More...

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.
 

Detailed Description

Notification feature.

For an introduction to notifications please see the Notification Tutorial.

Examples:

Hook Setup

elektraNotificationContract() returns a contract for use with kdbOpen(). The contract ensures that the internalnotification plugin is registered into the correct hook and configured correctly.

Transport Plugins

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:

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 Documentation

◆ ElektraNotificationChangeCallback

typedef void(* ElektraNotificationChangeCallback) (Key *key, void *context)

Callback function for key changes.

Parameters
keychanged key
contextuser supplied callback context

◆ ElektraNotificationConversionErrorCallback

typedef void(* ElektraNotificationConversionErrorCallback) (Key *key, void *context)

Callback function called when string to number conversion failed.

Parameters
keykey with invalid value
contextuser supplied callback context

Function Documentation

◆ ELEKTRA_NOTIFICATION_REGISTER_SIGNATURE()

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.

Parameters
handleplugin handle
keykey to watch for changes
variablevariable
Return values
1on success
0on failure

◆ elektraNotificationRegisterCallback()

int elektraNotificationRegisterCallback ( KDB *  kdb,
Key *  key,
ElektraNotificationChangeCallback  callback,
void *  context 
)

Subscribe for updates via callback when a given key value is changed.

Parameters
handleplugin handle
keykey to watch for changes
callbackcallback function
contextuser supplied context passed to callback function
Return values
1on success
0on failure

◆ elektraNotificationRegisterCallbackSameOrBelow()

int elektraNotificationRegisterCallbackSameOrBelow ( KDB *  kdb,
Key *  key,
ElektraNotificationChangeCallback  callback,
void *  context 
)

Subscribe for updates via callback when a given key or a key below changed.

Parameters
handleplugin handle
keykey to watch for changes
callbackcallback function
contextuser supplied context passed to callback function
Return values
1on success
0on failure