\hypertarget{group__plugin}{
\section{Plugins :: Elektra framework for plugins}
\label{group__plugin}\index{Plugins :: Elektra framework for plugins@{Plugins :: Elektra framework for plugins}}
}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
\hyperlink{struct__Plugin}{Plugin} $\ast$ \hyperlink{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{elektraPluginExport} (const char $\ast$pluginName,...)
\item 
\hyperlink{struct__KeySet}{KeySet} $\ast$ \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektraPluginGetConfig} (\hyperlink{struct__Plugin}{Plugin} $\ast$handle)
\item 
void \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektraPluginSetData} (\hyperlink{struct__Plugin}{Plugin} $\ast$plugin, void $\ast$data)
\item 
void $\ast$ \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektraPluginGetData} (\hyperlink{struct__Plugin}{Plugin} $\ast$plugin)
\item 
int \hyperlink{group__plugin_ga1e2cbea1275fc0d39a00a74eb69e12d8}{elektraDocOpen} (\hyperlink{struct__Plugin}{Plugin} $\ast$handle, \hyperlink{struct__Key}{Key} $\ast$errorKey)
\item 
int \hyperlink{group__plugin_gafb66a15abe15f79c9c5b3a928b42147d}{elektraDocClose} (\hyperlink{struct__Plugin}{Plugin} $\ast$handle, \hyperlink{struct__Key}{Key} $\ast$errorKey)
\item 
int \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektraDocGet} (\hyperlink{struct__Plugin}{Plugin} $\ast$handle, \hyperlink{struct__KeySet}{KeySet} $\ast$returned, \hyperlink{struct__Key}{Key} $\ast$parentKey)
\item 
int \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektraDocSet} (\hyperlink{struct__Plugin}{Plugin} $\ast$handle, \hyperlink{struct__KeySet}{KeySet} $\ast$returned, \hyperlink{struct__Key}{Key} $\ast$parentKey)
\item 
\hyperlink{struct__Plugin}{Plugin} $\ast$ \hyperlink{group__plugin_gabe78724d2d477eef39997fd9b85bff16}{ELEKTRA\_\-PLUGIN\_\-EXPORT} (doc)
\end{DoxyCompactItemize}


\subsection{Detailed Description}
\hypertarget{group__plugin_intro}{}\subsection{Introduction}\label{group__plugin_intro}
\begin{DoxySince}{Since}
Since version 0.4.9, Elektra can dynamically load different key storage plugins.

Since version 0.7.0 Elektra can have multiple plugins, mounted at any place in the key database.

Since version 0.8.0 Elektra plugins are composed out of multiple plugins.
\end{DoxySince}
\hypertarget{index_overview}{}\subsubsection{Overview}\label{index_overview}
A plugin can implement anything related to configuration. There are 5 possible entry points, but you need not to implement all of them. See the descriptions below what each of them is supposed to do. 

\subsection{Function Documentation}
\hypertarget{group__plugin_gabe78724d2d477eef39997fd9b85bff16}{
\index{plugin@{plugin}!ELEKTRA\_\-PLUGIN\_\-EXPORT@{ELEKTRA\_\-PLUGIN\_\-EXPORT}}
\index{ELEKTRA\_\-PLUGIN\_\-EXPORT@{ELEKTRA\_\-PLUGIN\_\-EXPORT}!plugin@{plugin}}
\subsubsection[{ELEKTRA\_\-PLUGIN\_\-EXPORT}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Plugin}$\ast$ ELEKTRA\_\-PLUGIN\_\-EXPORT (
\begin{DoxyParamCaption}
\item[{doc}]{}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gabe78724d2d477eef39997fd9b85bff16}
All KDB methods implemented by the plugin can have random names, except kdbBackendFactory(). This is the single symbol that will be looked up when loading the plugin, and the first method of the backend implementation that will be called.

Its purpose is to publish the exported methods for libelektra.so. The implementation inside the provided skeleton is usually enough: simply call kdbBackendExport() with all methods that must be exported.

The first paramter is the name of the plugin. Then every plugin must have: {\ttfamily KDB\_\-BE\_\-OPEN}, {\ttfamily KDB\_\-BE\_\-CLOSE}, {\ttfamily KDB\_\-BE\_\-GET} and {\ttfamily KDB\_\-BE\_\-SET} 

You might also give following information by char $\ast$: {\ttfamily KDB\_\-BE\_\-VERSION}, {\ttfamily KDB\_\-BE\_\-AUTHOR}, {\ttfamily KDB\_\-BE\_\-LICENCE}, {\ttfamily KDB\_\-BE\_\-DESCRIPTION}, {\ttfamily ELEKTRA\_\-PLUGIN\_\-NEEDS} and {\ttfamily ELEKTRA\_\-PLUGIN\_\-PROVIDES} 

You must use static \char`\"{}char arrays\char`\"{} in a read only segment. Don't allocate storage, it won't be freed.

With capability you can get that information on runtime from any plugin with kdbGetCapability().

The last parameter must be {\ttfamily KDB\_\-BE\_\-END}.

\begin{DoxyReturn}{Returns}
kdbBackendExport() with the above described parameters. 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
kdbBackendExport() for an example 

kdbOpenBackend() 
\end{DoxySeeAlso}
\hypertarget{group__plugin_gafb66a15abe15f79c9c5b3a928b42147d}{
\index{plugin@{plugin}!elektraDocClose@{elektraDocClose}}
\index{elektraDocClose@{elektraDocClose}!plugin@{plugin}}
\subsubsection[{elektraDocClose}]{\setlength{\rightskip}{0pt plus 5cm}int elektraDocClose (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ handle, }
\item[{{\bf Key} $\ast$}]{ errorKey}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gafb66a15abe15f79c9c5b3a928b42147d}
Finalize the plugin. Called prior to unloading the plugin dynamic module. Should ensure that no functions or static/global variables from the module will ever be accessed again.

Make sure to free all memory that your plugin requested at runtime.

Specifically make sure to capDel() all capabilites and free your pluginData in kdbhGetBackendData().

After this call, libelektra.so will unload the plugin library, so this is the point to shutdown any affairs with the storage.


\begin{DoxyParams}{Parameters}
\item[{\em handle}]contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \end{DoxyParams}
\begin{DoxyReturn}{Returns}
0 on success, anything else otherwise. 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose()} 
\end{DoxySeeAlso}
\hypertarget{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{
\index{plugin@{plugin}!elektraDocGet@{elektraDocGet}}
\index{elektraDocGet@{elektraDocGet}!plugin@{plugin}}
\subsubsection[{elektraDocGet}]{\setlength{\rightskip}{0pt plus 5cm}int elektraDocGet (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ handle, }
\item[{{\bf KeySet} $\ast$}]{ returned, }
\item[{{\bf Key} $\ast$}]{ parentKey}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gacb69f3441c6d84241b4362f958fbe313}
Retrieve information from a permanent storage to construct a keyset.\hypertarget{group__plugin_intro}{}\subsection{Introduction}\label{group__plugin_intro}
This function does everything related to get keys out from a plugin. There is only one function for that purpose to make implementation and locking much easier.

The keyset {\ttfamily returned} needs to be filled with information so that the application using elektra can access it. See the live cycle of a comment to understand: 
\begin{DoxyCode}
elektraDocGet(KDB *handle, KeySet *returned, Key *parentKey)
{
        // the task of elektraPluginGet is to retrieve the comment out of the per
      manent storage
        Key *key = keyDup (parentKey); // generate a new key to hold the informat
      ion
        char *comment;
        loadfromdisc (comment);
        keySetComment (key, comment, size); // set the information
        ksAppendKey(returned, key);
}

// Now return to kdbGet
int elektraDocGet(Plugin *handle, KeySet *keyset, Key *parentKey)
{
        elektraPluginGet (handle, keyset, 0);
        // postprocess the keyset and return it
}

// Now return to usercode, waiting for the comment
void usercode (Key *key)
{
        kdbGet (handle, keyset, parentKey, 0);
        key = ksCurrent (keyset, key); // lookup the key from the keyset
        keyGetComment (key); // now the usercode retrieves the comment
}
\end{DoxyCode}
 Of course not only the comment, but all information of every key in the keyset {\ttfamily returned} need to be fetched from permanent storage and stored in the key. So this specification needs to give an exhaustive list of information present in a key.\hypertarget{group__plugin_conditions}{}\subsection{Conditions}\label{group__plugin_conditions}
\begin{DoxyPrecond}{Precondition}
The caller \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} will make sure before you are called that the parentKey:
\begin{DoxyItemize}
\item is a valid key (means that it is a system or user key).
\item is below (see \hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{keyIsBelow()}) your mountpoint and that your plugin is responsible for it. and that the returned:
\item is a valid keyset.
\item has {\ttfamily all} keys with the flag KEY\_\-FLAG\_\-SYNC set.
\item contains only valid keys direct below (see \hyperlink{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{keyIsDirectBelow()}) your parentKey. That also means, that the parentKey will not be in that keyset.
\item is in a sorted order, see ksSort(). and that the handle:
\begin{DoxyItemize}
\item is a valid KDB for your plugin.
\item that elektraPluginhGetBackendHandle() contains the same handle for lifetime \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen()} until elektraPluginClose() was called.
\end{DoxyItemize}
\end{DoxyItemize}

The caller \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} will make sure that afterwards you were called, whenever the user requested it with the options, that:
\begin{DoxyItemize}
\item hidden keys they will be thrown away.
\item dirs or only dirs \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} will remove the other.
\item you will be called again recursively with all subdirectories.
\item the keyset will be sorted when needed.
\item the keys in returned having KEY\_\-FLAG\_\-SYNC will be sorted out.
\end{DoxyItemize}
\end{DoxyPrecond}
\begin{DoxyInvariant}{Invariant}
There are no global variables and kdbhGetBackendData() only stores information which can be regenerated any time. The handle is the same when it is the same plugin.
\end{DoxyInvariant}
\begin{DoxyPostcond}{Postcondition}
The keyset {\ttfamily returned} has the {\ttfamily parentKey} and all keys direct below (\hyperlink{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{keyIsDirectBelow()}) with all information from the storage. Make sure to return all keys, all directories and also all hidden keys. If some of them are not wished, the caller \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} will drop these keys, see above.
\end{DoxyPostcond}
\hypertarget{group__plugin_detail}{}\subsection{Details}\label{group__plugin_detail}
Now lets look at an example how the typical elektraPluginGet() might be implemented. To explain we introduce some pseudo functions which do all the work with the storage (which is of course 90\% of the work for a real plugin):
\begin{DoxyItemize}
\item find\_\-key() gets an key out from the storage and memorize the position.
\item next\_\-key() will find the next key and return it (with the name).
\item fetch\_\-key() gets out all information of a key from storage (details see below example).
\item stat\_\-key() gets all meta information (everything but value and comment). It removes the key \hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{keyNeedSync()} flag afterwards. returns the next key out from the storage. The typical loop now will be like: 
\begin{DoxyCode}
ssize_t elektraDocGet(KDB *handle, KeySet *update, const Key *parentKey) {
        Key * current;
        KeySet *returned = ksNew(ksGetSize(update)*2, KS_END);

        find_key (parentKey);
        current = keyDup (parentKey);
        current = fetch_key(current);

        keyClearSync (current);
        ksAppendKey(returned, current);

        while ((current = next_key()) != 0)
        {
                // search if key was passed in update by caller
                Key * tmp = ksLookup (update, current, KDB_O_WITHOWNER|KDB_O_POP)
      ;
                if (tmp) current = tmp; // key was passed, so use it
                current = fetch_key(current);
                keyClearSync (current);
                ksAppendKey(returned, current);
                // TODO: delete lookup key
        }

        if (error_happened())
        {
                errno = restore_errno();
                return -1;
        }

        ksClear (update); // the rest of update keys is not in storage anymore
        ksAppend(update, returned); // append the keys
        ksDel (returned);

        return nr_keys();
}
\end{DoxyCode}

\end{DoxyItemize}

\begin{DoxyNote}{Note}
-\/ returned and update are separated, for details why see \hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ksLookup()}
\begin{DoxyItemize}
\item the bit KEY\_\-FLAG\_\-SYNC is always cleared, see postconditions
\end{DoxyItemize}
\end{DoxyNote}
So your mission is simple: Search the {\ttfamily parentKey} and add it and then search all keys below and add them too, of course with all the values.\hypertarget{group__plugin_updating}{}\subsection{Updating}\label{group__plugin_updating}
To get all keys out of the storage over and over again can be very inefficient. You might know a more efficient method to know if the key needs update or not, e.g. by stating it or by an external time stamp info. In that case you can make use of {\ttfamily returned} KeySet. There are following possibilities:
\begin{DoxyItemize}
\item The key is in returned and up to date. You just need to remove the KEY\_\-FLAG\_\-SYNC flag.
\item The key is not in returned. You need to fully retrieve the key out of storage, clear KEY\_\-FLAG\_\-SYNC using \hyperlink{group__keytest_ga6a994eebd4b1c253d4912fa80df16506}{keyClearSync()} and \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey()} it to the {\ttfamily returned} keyset.
\end{DoxyItemize}

\begin{DoxyNote}{Note}
You must clear the flag KEY\_\-FLAG\_\-SYNC at the very last point where no more modification on the key will take place, because any modification on the key will set the KEY\_\-FLAG\_\-SYNC flag again. With that \hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{keyNeedSync()} will return true and the caller will sort this key out.
\end{DoxyNote}
\hypertarget{group__plugin_fullget}{}\subsection{only Full Get}\label{group__plugin_fullget}
In some plugins it is not useful to get only a part of the configuration, because getting all keys would take as long as getting some. For this situation, you can declare onlyFullGet, see kdbcGetonlyFullGet().

The only valid call for your plugin is then that {\ttfamily parentKey} equals the {\ttfamily mountpoint}. For all other {\ttfamily parentKey} you must, add nothing and just return 0.


\begin{DoxyCode}
if (strcmp (keyName(kdbhGetMountpoint(handle)), keyName(parentKey))) return 0;
\end{DoxyCode}


If the {\ttfamily parentKey} is your mountpoint you will of course fetch all keys, and not only the keys direct below the {\ttfamily parentKey}. So {\ttfamily returned} is valid iff:
\begin{DoxyItemize}
\item every key is below ( \hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{keyIsBelow()}) the parentKey
\item every key has a direct parent (\hyperlink{group__keytest_ga4f175aafd98948ce6c774f3bd92b72ca}{keyIsDirectBelow()}) in the keyset
\end{DoxyItemize}

\begin{DoxyNote}{Note}
This statement is only valid for plugins with kdbcGetonlyFullGet() set.

If any calls you use change errno, make sure to restore the old errno.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} for caller.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
\item[{\em handle}]contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \item[{\em returned}]contains a keyset where the function need to append the keys got from the storage. There might be also some keys inside it, see conditions. You may use them to support efficient updating of keys, see \hyperlink{group__plugin_updating}{Updating}. \item[{\em parentKey}]contains the information below which key the keys should be gotten.\end{DoxyParams}
\begin{DoxyReturn}{Returns}
1 on success 

0 when nothing was to do 

-\/1 on failure, the current key in returned shows the position. use ELEKTRA\_\-SET\_\-ERROR in $<$kdberrors$>$ to define the error code 
\end{DoxyReturn}
\hypertarget{group__plugin_ga1e2cbea1275fc0d39a00a74eb69e12d8}{
\index{plugin@{plugin}!elektraDocOpen@{elektraDocOpen}}
\index{elektraDocOpen@{elektraDocOpen}!plugin@{plugin}}
\subsubsection[{elektraDocOpen}]{\setlength{\rightskip}{0pt plus 5cm}int elektraDocOpen (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ handle, }
\item[{{\bf Key} $\ast$}]{ errorKey}
\end{DoxyParamCaption}
)}}
\label{group__plugin_ga1e2cbea1275fc0d39a00a74eb69e12d8}
Initialize the plugin. This is the first method called after dynamically loading this plugin.

This method is responsible for:
\begin{DoxyItemize}
\item plugin's specific configuration gathering
\item all plugin's internal structs initialization
\item if unavoidable initial setup of all I/O details such as opening a file, connecting to a database, setup connection to a server, etc.
\end{DoxyItemize}

You may also read the configuration you can get with \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektraPluginGetConfig()} and transform it into other structures used by your plugin.

\begin{DoxyNote}{Note}
The plugin must not have any global variables. If you do elektra will not be threadsafe.
\end{DoxyNote}
Instead you can use \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektraPluginGetData()} and \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektraPluginSetData()} to store and get any information related to your plugin.

The correct substitute for global variables will be: 
\begin{DoxyCode}
struct _GlobalData{ int global; };
typedef struct _GlobalData GlobalData;
int elektraPluginOpen(KDB *handle) {
        PasswdData *data;
        data=malloc(sizeof(PasswdData));
        data.global = 20;
        kdbhSetBackendData(handle,data);
}
\end{DoxyCode}


\begin{DoxyNote}{Note}
Make sure to free everything within \hyperlink{group__plugin_gafb66a15abe15f79c9c5b3a928b42147d}{elektraDocClose()}.
\end{DoxyNote}
\begin{DoxyReturn}{Returns}
0 on success 
\end{DoxyReturn}

\begin{DoxyParams}{Parameters}
\item[{\em handle}]contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \item[{\em errorKey}]defines an errorKey \end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen()} 
\end{DoxySeeAlso}
\hypertarget{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{
\index{plugin@{plugin}!elektraDocSet@{elektraDocSet}}
\index{elektraDocSet@{elektraDocSet}!plugin@{plugin}}
\subsubsection[{elektraDocSet}]{\setlength{\rightskip}{0pt plus 5cm}int elektraDocSet (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ handle, }
\item[{{\bf KeySet} $\ast$}]{ returned, }
\item[{{\bf Key} $\ast$}]{ parentKey}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}
Store a keyset permanently.

This function does everything related to set and remove keys in a plugin. There is only one function for that purpose to make implementation and locking much easier.

The keyset {\ttfamily returned} was filled in with information from the application using elektra and the task of this function is to store it in a permanent way so that a subsequent call of elektraPluginGet() can rebuild the keyset as it was before. See the live cycle of a comment to understand: 
\begin{DoxyCode}
void usercode (Key *key)
{
        keySetComment (key, "mycomment"); // the usercode stores a comment for th
      e key
        ksAppendKey(keyset, key); // append the key to the keyset
        kdbSet (handle, keyset, 0, 0);
}

// so now kdbSet is called
int kdbSet(KDB *handle, KeySet *keyset, Key *parentKey, options)
{
        // find appropriate plugin
        elektraPluginSet (handle, keyset, 0); // the keyset with the key will be 
      passed to this function
}

// so now elektraPluginSet(), which is the function described here, is called
elektraPluginSet(KDB *handle, KeySet *keyset, Key *parentKey)
{
        // the task of elektraPluginSet is now to store the comment
        Key *key = ksCurrent (keyset); // get out the key where the user set the 
      comment before
        char *comment = allocate(size);
        keyGetComment (key, comment, size);
        savetodisc (comment);
}
\end{DoxyCode}
 Of course not only the comment, but all information of every key in the keyset {\ttfamily returned} need to be stored permanetly. So this specification needs to give an exhaustive list of information present in a key.

\begin{DoxyPrecond}{Precondition}
The keyset {\ttfamily returned} holds all keys which must be saved permanently for this keyset. The keyset is sorted and rewinded. All keys having children must be true for \hyperlink{group__keytest_gac0a10c602d52a35f81347e8a32312017}{keyIsDir()}.

The {\ttfamily parentKey} is the key which is the ancestor for all other keys in the keyset. The first key of the keyset {\ttfamily returned} has the same keyname. The parentKey is below the mountpoint, see kdbhGetMountpoint().

The caller kdbSet will fulfill following parts:
\begin{DoxyItemize}
\item If the user does not want hidden keys they will be thrown away. All keys in {\ttfamily returned} need to be stored permanently.
\item If the user does not want dirs or only dirs \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} will remove the other.
\item Sorting of the keyset. It is not important in which order the keys are appended. So make sure to set all keys, all directories and also all hidden keys. If some of them are not wished, the caller \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet()} will sort them out.
\end{DoxyItemize}
\end{DoxyPrecond}
\begin{DoxyInvariant}{Invariant}
There are no global variables and kdbhGetBackendData() only stores information which can be regenerated any time. The handle is the same when it is the same plugin.
\end{DoxyInvariant}
\begin{DoxyPostcond}{Postcondition}
The information of the keyset {\ttfamily returned} is stored permanently.
\end{DoxyPostcond}
Lock your permanent storage in an exclusive way, no access of a concurrent elektraPluginSet\_\-plugin() or \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet()} is possible and these methods block until the function has finished. Otherwise declare kdbcGetnoLock().

\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet()} for caller.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
\item[{\em handle}]contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \item[{\em returned}]contains a keyset with relevant keys \item[{\em parentKey}]contains the information where to set the keys\end{DoxyParams}
\begin{DoxyReturn}{Returns}
When everything works gracefully return the number of keys you set. The cursor position and the keys remaining in the keyset are not important.

Return 0 on success with no changed key in database

Return -\/1 on failure.
\end{DoxyReturn}
\begin{DoxyNote}{Note}
If any calls you use change errno, make sure to restore the old errno.
\end{DoxyNote}
\begin{Desc}
\item[\hyperlink{err__err000001}{Error}]In normal execution cases a positive value will be returned. But in some cases you are not able to set keys and have to return -\/1. If you declare kdbcGetnoError() you are done, but otherwise you have to set the cause of the error. (Will be added with 0.7.1)\end{Desc}


You also have to make sure that \hyperlink{group__keyset_gaffe507ab9281c322eb16c3e992075d29}{ksGetCursor()} shows to the position where the error appeared. \hypertarget{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{
\index{plugin@{plugin}!elektraPluginExport@{elektraPluginExport}}
\index{elektraPluginExport@{elektraPluginExport}!plugin@{plugin}}
\subsubsection[{elektraPluginExport}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Plugin}$\ast$ elektraPluginExport (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{ pluginName, }
\item[{}]{ ...}
\end{DoxyParamCaption}
)}}
\label{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}
This function must be called by a plugin's elektraPluginSymbol() to define the plugin's methods that will be exported.

See \hyperlink{group__plugin_gabe78724d2d477eef39997fd9b85bff16}{ELEKTRA\_\-PLUGIN\_\-EXPORT()} how to use it for plugins.

The order and number of arguments are flexible (as in \hyperlink{group__key_gaf6893c038b3ebee90c73a9ea8356bebf}{keyNew()} and \hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew()}) to let libelektra.so evolve without breaking its ABI compatibility with plugins. So for each method a plugin must export, there is a flag defined by plugin\_\-t. Each flag tells kdbPluginExport() which method comes next. A plugin can have no implementation for a few methods that have default inefficient high-\/level implementations and to use these defaults, simply don't pass anything to kdbPluginExport() about them.


\begin{DoxyParams}{Parameters}
\item[{\em pluginName}]a simple name for this plugin \end{DoxyParams}
\begin{DoxyReturn}{Returns}
an object that contains all plugin informations needed by libelektra.so 
\end{DoxyReturn}
\hypertarget{group__plugin_ga644bead796506c172817724051c977c9}{
\index{plugin@{plugin}!elektraPluginGetConfig@{elektraPluginGetConfig}}
\index{elektraPluginGetConfig@{elektraPluginGetConfig}!plugin@{plugin}}
\subsubsection[{elektraPluginGetConfig}]{\setlength{\rightskip}{0pt plus 5cm}{\bf KeySet}$\ast$ elektraPluginGetConfig (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ handle}
\end{DoxyParamCaption}
)}}
\label{group__plugin_ga644bead796506c172817724051c977c9}
Returns the configuration of that plugin.


\begin{DoxyParams}{Parameters}
\item[{\em handle}]a pointer to the plugin \end{DoxyParams}
\hypertarget{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{
\index{plugin@{plugin}!elektraPluginGetData@{elektraPluginGetData}}
\index{elektraPluginGetData@{elektraPluginGetData}!plugin@{plugin}}
\subsubsection[{elektraPluginGetData}]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ elektraPluginGetData (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ plugin}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}
Get a pointer to any plugin related data stored before.


\begin{DoxyParams}{Parameters}
\item[{\em plugin}]a pointer to the plugin \end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the data 
\end{DoxyReturn}
\hypertarget{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{
\index{plugin@{plugin}!elektraPluginSetData@{elektraPluginSetData}}
\index{elektraPluginSetData@{elektraPluginSetData}!plugin@{plugin}}
\subsubsection[{elektraPluginSetData}]{\setlength{\rightskip}{0pt plus 5cm}void elektraPluginSetData (
\begin{DoxyParamCaption}
\item[{{\bf Plugin} $\ast$}]{ plugin, }
\item[{void $\ast$}]{ data}
\end{DoxyParamCaption}
)}}
\label{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}
Store a pointer to any plugin related data.


\begin{DoxyParams}{Parameters}
\item[{\em plugin}]a pointer to the plugin \item[{\em data}]the pointer to the data \end{DoxyParams}
