Functionality to use plugins and invoke functions. More...

Functions
ElektraInvokeHandle *	elektraInvokeInitialize (const char *elektraPluginName)

ElektraInvokeHandle *	elektraInvokeOpen (const char elektraPluginName, KeySet config, Key *errorKey)
	Opens a new handle to invoke functions for a plugin. More...

const void *	elektraInvokeGetFunction (ElektraInvokeHandle handle, const char elektraPluginFunctionName)
	Get a function pointer. More...

KeySet *	elektraInvokeGetPluginConfig (ElektraInvokeHandle *handle)
	Get the configuration the plugin uses. More...

const char *	elektraInvokeGetPluginName (ElektraInvokeHandle *handle)
	Get the name of the plugin. More...

void *	elektraInvokeGetPluginData (ElektraInvokeHandle *handle)
	Get the data of the plugin. More...

KeySet *	elektraInvokeGetModules (ElektraInvokeHandle *handle)
	Get the modules used for invoking. More...

KeySet *	elektraInvokeGetExports (ElektraInvokeHandle *handle)
	Get the exports from the plugin. More...

int	elektraInvoke2Args (ElektraInvokeHandle handle, const char elektraPluginFunctionName, KeySet ks, Key k)
	A convenience function to call a function with two arguments. More...

void	elektraInvokeClose (ElektraInvokeHandle handle, Key errorKey)
	Closes all affairs with the handle. More...

int	elektraInvokeCallDeferable (ElektraInvokeHandle handle, const char elektraPluginFunctionName, KeySet *parameters)
	Invokes a deferable function on an invoke handle. More...

void	elektraInvokeExecuteDeferredCalls (ElektraInvokeHandle handle, ElektraDeferredCallList list)
	Execute deferred calls from list on given invoke handle. More...

int	elektraDeferredCall (Plugin handle, const char elektraPluginFunctionName, KeySet *parameters)
	Call a deferrable function on a plugin handle. More...

int	elektraDeferredCallAdd (ElektraDeferredCallList list, const char name, KeySet *parameters)
	Add a new deferred call to the deferred call list. More...

ElektraDeferredCallList *	elektraDeferredCallCreateList (void)
	Create new deferred call list. More...

void	elektraDeferredCallDeleteList (ElektraDeferredCallList *list)
	Delete deferred call list. More...

void	elektraDeferredCallsExecute (Plugin plugin, ElektraDeferredCallList list)
	Execute deferred calls on given plugin. More...

Detailed Description

Functionality to use plugins and invoke functions.

Allows invoking functions of plugins as needed within applications and plugins inside and outside of the KDB.

To use this library, you need to include:

#include <kdbinvoke.h>`

and link against libelektra-invoke. Then you can use it:

ElektraInvokeHandle * handle = elektraInvokeOpen ("dini", 0);
elektraInvoke2Args (handle, "get", ks, k);
elektraInvokeClose (handle);

Function Documentation

◆ elektraDeferredCall()

int elektraDeferredCall	(	Plugin *	handle,
		const char *	elektraPluginFunctionName,
		KeySet *	parameters
	)

Call a deferrable function on a plugin handle.

If the function is exported by the plugin it is directly invoked, if the plugin supports deferring calls, the call is deferred. If both is possible (function is exported and deferred calls are supported), the function is directly called and the call is deferred (i.e. for nested plugins).

Parameters

handle	invoke handle
elektraPluginFunctionName	function name
parameters	parameter key set. Can bee freed afterwards.

Return values

0	on success
-1	when the call failed (direct call and deferring not available)

◆ elektraDeferredCallAdd()

int elektraDeferredCallAdd	(	ElektraDeferredCallList *	list,
		const char *	name,
		KeySet *	parameters
	)

Add a new deferred call to the deferred call list.

Used internally by plugins.

Parameters

list	deferred call list
name	function name
parameters	function parameters

Return values

1	on success
0	when malloc failed

◆ elektraDeferredCallCreateList()

ElektraDeferredCallList* elektraDeferredCallCreateList ( void )

Create new deferred call list.

The list needs to be deleted with elektraDeferredCallDeleteList(). Used internally by plugins.

Returns: new list

◆ elektraDeferredCallDeleteList()

void elektraDeferredCallDeleteList ( ElektraDeferredCallList * list )

Delete deferred call list.

Used internally by plugins.

Parameters

list list

◆ elektraDeferredCallsExecute()

void elektraDeferredCallsExecute	(	Plugin *	plugin,
		ElektraDeferredCallList *	list
	)

Execute deferred calls on given plugin.

Used internally by plugins.

Parameters

plugin	plugin handle
list	list

◆ elektraInvoke2Args()

int elektraInvoke2Args	(	ElektraInvokeHandle *	handle,
		const char *	elektraPluginFunctionName,
		KeySet *	ks,
		Key *	k
	)

A convenience function to call a function with two arguments.

Parameters

handle	the handle to work with
elektraPluginFunctionName	the function to call, e.g. "get"
ks	the keyset to be used as first parameter
k	the key to be used as second parameter

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: the return value of the invoked function (i.e. -1, 0, or 1)

Return values

-2	if the function was not found.

◆ elektraInvokeCallDeferable()

int elektraInvokeCallDeferable	(	ElektraInvokeHandle *	handle,
		const char *	elektraPluginFunctionName,
		KeySet *	parameters
	)

Invokes a deferable function on an invoke handle.

If the function is exported by the plugin it is directly invoked, if the plugin supports deferring calls, the call is deferred.

The parameters key set can be freed afterwards.

Parameters

handle	invoke handle
elektraPluginFunctionName	function name
parameters	parameter key set

Return values

0	on success
-1	when the call failed (direct call and deferring not available)

◆ elektraInvokeClose()

void elektraInvokeClose	(	ElektraInvokeHandle *	handle,
		Key *	errorKey
	)

Closes all affairs with the handle.

The close function of the plugin will be called.

Parameters

handle	the handle to work with
errorKey	a key where error messages will be stored

Precondition: handle must be as returned from elektraInvokeOpen()

◆ elektraInvokeExecuteDeferredCalls()

void elektraInvokeExecuteDeferredCalls	(	ElektraInvokeHandle *	handle,
		ElektraDeferredCallList *	list
	)

Execute deferred calls from list on given invoke handle.

Used internally by plugins holding invoke handles.

Parameters

handle	invoke handle
list	list

◆ elektraInvokeGetExports()

KeySet* elektraInvokeGetExports ( ElektraInvokeHandle * handle )

Get the exports from the plugin.

Parameters

handle the handle to work with.

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: the exports of the plugin.

◆ elektraInvokeGetFunction()

const void* elektraInvokeGetFunction	(	ElektraInvokeHandle *	handle,
		const char *	elektraPluginFunctionName
	)

Get a function pointer.

Parameters

handle	the handle to use
elektraPluginFunctionName	the name of the function to use, e.g., get/set

Precondition: handle must be as returned from elektraInvokeOpen()

Example:

typedef int (*elektra2Args) (KeySet*, Key *);
elektra2Args func = *(elektra2Args *)elektraInvokeGetFunction (handle, elektraPluginFunctionName);
if (!func) exit(1);   // no function found, handle error
func (ks, k);         // otherwise, call function

See also: elektraInvoke2Args() a convenience function to be used for KeySet,Key arguments.

Returns: a function pointer for the specified function.

◆ elektraInvokeGetModules()

KeySet* elektraInvokeGetModules ( ElektraInvokeHandle * handle )

Get the modules used for invoking.

Warning: The modules are closed within elektraInvokeClose(). It is not enough to ksDup() the keyset, you must not call elektraInvokeClose() if you want to reuse the modules.

Parameters

handle the handle to work with.

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: the modules used for invoking.

◆ elektraInvokeGetPluginConfig()

KeySet* elektraInvokeGetPluginConfig ( ElektraInvokeHandle * handle )

Get the configuration the plugin uses.

Parameters

handle the handle to use

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: the config of the plugin.

◆ elektraInvokeGetPluginData()

void* elektraInvokeGetPluginData ( ElektraInvokeHandle * handle )

Get the data of the plugin.

Parameters

handle the handle to work with.

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: a pointer to the plugin's data.

◆ elektraInvokeGetPluginName()

const char* elektraInvokeGetPluginName ( ElektraInvokeHandle * handle )

Get the name of the plugin.

The name might differ from the name as passed with elektraInvokeOpen when symlinks are used.

Parameters

handle the handle to work with.

Precondition: handle must be as returned from elektraInvokeOpen()

Returns: the name of the plugin

◆ elektraInvokeInitialize()

ElektraInvokeHandle* elektraInvokeInitialize ( const char * elektraPluginName )

Deprecated:: Do not use.

Use elektraInvokeOpen (name, 0, 0) instead.

See also: elektraInvokeOpen()

◆ elektraInvokeOpen()

ElektraInvokeHandle* elektraInvokeOpen	(	const char *	elektraPluginName,
		KeySet *	config,
		Key *	errorKey
	)

Opens a new handle to invoke functions for a plugin.

When opening the plugin, it calls the "open" function of the plugin.

Parameters

elektraPluginName	the plugin on which we want to invoke functions.
config	the config to be passed to the plugin.
errorKey	a key where error messages will be stored

Returns: the handle

Return values

0 on errors

Functions

Detailed Description

Function Documentation

◆ elektraDeferredCall()

◆ elektraDeferredCallAdd()

◆ elektraDeferredCallCreateList()

◆ elektraDeferredCallDeleteList()

◆ elektraDeferredCallsExecute()

◆ elektraInvoke2Args()

◆ elektraInvokeCallDeferable()

◆ elektraInvokeClose()

◆ elektraInvokeExecuteDeferredCalls()

◆ elektraInvokeGetExports()

◆ elektraInvokeGetFunction()

◆ elektraInvokeGetModules()

◆ elektraInvokeGetPluginConfig()

◆ elektraInvokeGetPluginData()

◆ elektraInvokeGetPluginName()

◆ elektraInvokeInitialize()

◆ elektraInvokeOpen()