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

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

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:

- I/O binding: `system:/elektra/io/binding` Type: `ElektraIoInterface *`
- Callback: `system:/elektra/notification/callback` Type: `ElektraNotificationCallback`
- Context: `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 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

## ◆ 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

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

Return values

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

  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