Elektra  0.9.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. More...
 
typedef void(* ElektraNotificationChangeCallback) (Key *key, void *context)
 Callback function for key changes. More...
 

Functions

int elektraNotificationOpen (KDB *kdb)
 Initialize the notification system for the given KDB instance. More...
 
int elektraNotificationClose (KDB *kdb)
 Stop the notification system for the given KDB instance. More...
 
int elektraNotificationRegisterCallback (KDB *kdb, Key *key, ElektraNotificationChangeCallback callback, void *context)
 Subscribe for updates via callback when a given key value is changed. More...
 
int elektraNotificationRegisterCallbackSameOrBelow (KDB *kdb, Key *key, ElektraNotificationChangeCallback callback, void *context)
 Subscribe for updates via callback when a given key or a key below changed. More...
 
int elektraNotificationRegisterInt (KDB *kdb, Key *key, int *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterUnsignedInt (KDB *kdb, Key *key, unsigned int *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterLong (KDB *kdb, Key *key, long *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterUnsignedLong (KDB *kdb, Key *key, unsigned long *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterLongLong (KDB *kdb, Key *key, long long *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterUnsignedLongLong (KDB *kdb, Key *key, unsigned long long *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterFloat (KDB *kdb, Key *key, float *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterDouble (KDB *kdb, Key *key, double *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbBoolean (KDB *kdb, Key *key, kdb_boolean_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbChar (KDB *kdb, Key *key, kdb_char_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbOctet (KDB *kdb, Key *key, kdb_octet_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbShort (KDB *kdb, Key *key, kdb_short_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbUnsignedShort (KDB *kdb, Key *key, kdb_unsigned_short_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbLong (KDB *kdb, Key *key, kdb_long_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbUnsignedLong (KDB *kdb, Key *key, kdb_unsigned_long_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbLongLong (KDB *kdb, Key *key, kdb_long_long_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbUnsignedLongLong (KDB *kdb, Key *key, kdb_unsigned_long_long_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbFloat (KDB *kdb, Key *key, kdb_float_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 
int elektraNotificationRegisterKdbDouble (KDB *kdb, Key *key, kdb_double_t *variable)
 Subscribe for automatic updates to a given variable when the given key value is changed. More...
 

Detailed Description

Notification feature.

For an introduction to notifications please see the Notification Tutorial.

Examples:

Global Mounting

elektraNotificationOpen() loads and mounts the internalnotification plugin globally at run-time. The key database is not altered permanently. elektraNotificationClose() reverts the mounting.

The internalnotification plugin is mounted at its defined positions (see its plugin docs).

Transport Plugins

Notification transport plugins (or simply transport plugins) export "openNotification" (ElektraNotificationOpenNotification()) and optionally "closeNotification" (ElektraNotificationCloseNotification()) functions as part of their contract.

The function "openNotification" is called during elektraNotificationOpen(). At this point an I/O binding is set and it is save to use it. If no binding is set despite the plugin requires it, it should log a message and perform no additional operations. This ensures that the plugin can be used in applications that do not use I/O bindings or notification features.

ElektraNotificationOpenNotification() receives a callback and additional data. When a key change notification is received (or a change is detected by other means) this callback shall be called with the changed Key and the additional data.

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

◆ elektraNotificationClose()

int elektraNotificationClose ( KDB *  kdb)

Stop the notification system for the given KDB instance.

May only be called after elektraNotificationOpen() was called for given KDB instance.

Parameters
kdbKDB instance
Return values
1on success
0on error

◆ elektraNotificationOpen()

int elektraNotificationOpen ( KDB *  kdb)

Initialize the notification system for the given KDB instance.

Asynchronous receiving of notifications requires an I/O binding. Use elektraIoSetBinding() before calling this function.

May only be called once for a KDB instance. Subsequent calls return 0.

Parameters
kdbKDB instance
Return values
1on success
0on error

◆ 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

◆ elektraNotificationRegisterDouble()

int elektraNotificationRegisterDouble ( KDB *  kdb,
Key *  key,
double *  variable 
)

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

◆ elektraNotificationRegisterFloat()

int elektraNotificationRegisterFloat ( KDB *  kdb,
Key *  key,
float *  variable 
)

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

◆ elektraNotificationRegisterInt()

int elektraNotificationRegisterInt ( KDB *  kdb,
Key *  key,
int *  variable 
)

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 failureSubscribe 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

◆ elektraNotificationRegisterKdbBoolean()

int elektraNotificationRegisterKdbBoolean ( KDB *  kdb,
Key *  key,
kdb_boolean_t *  variable 
)

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

◆ elektraNotificationRegisterKdbChar()

int elektraNotificationRegisterKdbChar ( KDB *  kdb,
Key *  key,
kdb_char_t *  variable 
)

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

◆ elektraNotificationRegisterKdbDouble()

int elektraNotificationRegisterKdbDouble ( KDB *  kdb,
Key *  key,
kdb_double_t *  variable 
)

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

◆ elektraNotificationRegisterKdbFloat()

int elektraNotificationRegisterKdbFloat ( KDB *  kdb,
Key *  key,
kdb_float_t *  variable 
)

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

◆ elektraNotificationRegisterKdbLong()

int elektraNotificationRegisterKdbLong ( KDB *  kdb,
Key *  key,
kdb_long_t *  variable 
)

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

◆ elektraNotificationRegisterKdbLongLong()

int elektraNotificationRegisterKdbLongLong ( KDB *  kdb,
Key *  key,
kdb_long_long_t *  variable 
)

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

◆ elektraNotificationRegisterKdbOctet()

int elektraNotificationRegisterKdbOctet ( KDB *  kdb,
Key *  key,
kdb_octet_t *  variable 
)

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

◆ elektraNotificationRegisterKdbShort()

int elektraNotificationRegisterKdbShort ( KDB *  kdb,
Key *  key,
kdb_short_t *  variable 
)

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

◆ elektraNotificationRegisterKdbUnsignedLong()

int elektraNotificationRegisterKdbUnsignedLong ( KDB *  kdb,
Key *  key,
kdb_unsigned_long_t *  variable 
)

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

◆ elektraNotificationRegisterKdbUnsignedLongLong()

int elektraNotificationRegisterKdbUnsignedLongLong ( KDB *  kdb,
Key *  key,
kdb_unsigned_long_long_t *  variable 
)

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

◆ elektraNotificationRegisterKdbUnsignedShort()

int elektraNotificationRegisterKdbUnsignedShort ( KDB *  kdb,
Key *  key,
kdb_unsigned_short_t *  variable 
)

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

◆ elektraNotificationRegisterLong()

int elektraNotificationRegisterLong ( KDB *  kdb,
Key *  key,
long *  variable 
)

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

◆ elektraNotificationRegisterLongLong()

int elektraNotificationRegisterLongLong ( KDB *  kdb,
Key *  key,
long long *  variable 
)

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

◆ elektraNotificationRegisterUnsignedInt()

int elektraNotificationRegisterUnsignedInt ( KDB *  kdb,
Key *  key,
unsigned int *  variable 
)

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

◆ elektraNotificationRegisterUnsignedLong()

int elektraNotificationRegisterUnsignedLong ( KDB *  kdb,
Key *  key,
unsigned long *  variable 
)

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

◆ elektraNotificationRegisterUnsignedLongLong()

int elektraNotificationRegisterUnsignedLongLong ( KDB *  kdb,
Key *  key,
unsigned long long *  variable 
)

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