Elektra: Notification

Elektra 0.8.24

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...
int | elektraNotificationRegisterKdbLongDouble (KDB *kdb, Key *key, kdb_long_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:

- Basic notifications using polling
- Using asynchronous I/O bindings
- Reload KDB when Elektra's configuration has changed

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).

- If there is no plugin mounted at a required position the internalnotification plugin is mounted at this position.
- In the default configuration or when mounting a plugin globally using `kdb global-mount` the list plugin is mounted at all positions. This plugin allows to mount multiple plugins at a position. If this plugin is present at a position the internalnotification plugin is added to the list plugin's configuration at run-time.
- If another plugin is mounted at a desired position the configuration is considered broken and mounting is aborted. The list plugin requires to be mounted at all positions in order to keep track of the current position and call plugins accordingly.

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

  key | changed key
  context | user supplied callback context

## ◆ ElektraNotificationConversionErrorCallback

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

Callback function called when string to number conversion failed.

Parameters

  key | key with invalid value
  context | user 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

  kdb | KDB instance

Return values

  1 | on success
  0 | on 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

  kdb | KDB instance

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  callback | callback function
  context | user supplied context passed to callback function

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  callback | callback function
  context | user supplied context passed to callback function

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on failure

## ◆ elektraNotificationRegisterKdbLongDouble()

int elektraNotificationRegisterKdbLongDouble | ( | KDB * | kdb,
|  | Key * | key,
|  | kdb_long_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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on 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

  handle | plugin handle
  key | key to watch for changes
  variable | variable

Return values

  1 | on success
  0 | on failure