$darkmode
Elektra 0.11.0
Functions
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...
 
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);
ElektraInvokeHandle * elektraInvokeOpen(const char *elektraPluginName, KeySet *config, Key *errorKey)
Opens a new handle to invoke functions for a plugin.
Definition: invoke.c:94
void elektraInvokeClose(ElektraInvokeHandle *handle, Key *errorKey)
Closes all affairs with the handle.
Definition: invoke.c:318
int elektraInvoke2Args(ElektraInvokeHandle *handle, const char *elektraPluginFunctionName, KeySet *ks, Key *k)
A convenience function to call a function with two arguments.
Definition: invoke.c:293

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
handleinvoke handle
elektraPluginFunctionNamefunction name
parametersparameter key set. Can bee freed afterwards.
Return values
0on success
-1when 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
listdeferred call list
namefunction name
parametersfunction parameters
Return values
1on success
0when 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
listlist

◆ elektraDeferredCallsExecute()

void elektraDeferredCallsExecute ( Plugin *  plugin,
ElektraDeferredCallList *  list 
)

Execute deferred calls on given plugin.

Used internally by plugins.

Parameters
pluginplugin handle
listlist

◆ elektraInvoke2Args()

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

A convenience function to call a function with two arguments.

Parameters
handlethe handle to work with
elektraPluginFunctionNamethe function to call, e.g. "get"
ksthe keyset to be used as first parameter
kthe 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
-2if 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
handleinvoke handle
elektraPluginFunctionNamefunction name
parametersparameter key set
Return values
0on success
-1when 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
handlethe handle to work with
errorKeya 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
handleinvoke handle
listlist

◆ elektraInvokeGetExports()

KeySet* elektraInvokeGetExports ( ElektraInvokeHandle *  handle)

Get the exports from the plugin.

Parameters
handlethe 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
handlethe handle to use
elektraPluginFunctionNamethe 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
const void * elektraInvokeGetFunction(ElektraInvokeHandle *handle, const char *elektraPluginFunctionName)
Get a function pointer.
Definition: invoke.c:161
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
handlethe 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
handlethe 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
handlethe 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
handlethe 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
elektraPluginNamethe plugin on which we want to invoke functions.
configthe config to be passed to the plugin.
errorKeya key where error messages will be stored
Returns
the handle
Return values
0on errors