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

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

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

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

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

◆ 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

◆ 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

Files

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ElektraNotificationChangeCallback

◆ ElektraNotificationConversionErrorCallback

Function Documentation

◆ elektraNotificationRegisterCallback()

◆ elektraNotificationRegisterCallbackSameOrBelow()

◆ elektraNotificationRegisterDouble()

◆ elektraNotificationRegisterFloat()

◆ elektraNotificationRegisterInt()

◆ elektraNotificationRegisterKdbBoolean()

◆ elektraNotificationRegisterKdbChar()

◆ elektraNotificationRegisterKdbDouble()

◆ elektraNotificationRegisterKdbFloat()

◆ elektraNotificationRegisterKdbLong()

◆ elektraNotificationRegisterKdbLongLong()

◆ elektraNotificationRegisterKdbOctet()

◆ elektraNotificationRegisterKdbShort()

◆ elektraNotificationRegisterKdbUnsignedLong()

◆ elektraNotificationRegisterKdbUnsignedLongLong()

◆ elektraNotificationRegisterKdbUnsignedShort()

◆ elektraNotificationRegisterLong()

◆ elektraNotificationRegisterLongLong()

◆ elektraNotificationRegisterUnsignedInt()

◆ elektraNotificationRegisterUnsignedLong()

◆ elektraNotificationRegisterUnsignedLongLong()