Invoke

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

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

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.

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

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