\hypertarget{group__plugin}{}\section{Plugins}
\label{group__plugin}\index{Plugins@{Plugins}}


Elektra plugin framework.  


\subsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \hyperlink{group__plugin_gacb05c902e4014535589db4193da87460}{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON}(function)~E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+O\+N2 (E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+N\+A\+M\+E\+\_\+C, function)
\begin{DoxyCompactList}\small\item\em Declare a plugin\textquotesingle{}s function name suitable for compilation variants (see doc/tutorials). \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_gabdcb97b05a83130c32bbde75db80fc50}{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME}~E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+M\+E2 (E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+N\+A\+M\+E\+\_\+C)
\begin{DoxyCompactList}\small\item\em The filename for inclusion of the readme for compilation variants (see doc/tutorials). \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR}(number,  key,  text)
\begin{DoxyCompactList}\small\item\em Sets the error in the keys metadata. \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_ga3e4fc2c20d8e64bed7a54bb1af882e34}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF}(number,  key,  formatstring, ...)
\begin{DoxyCompactList}\small\item\em Sets the error in the keys metadata. \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_ga2bbb3bc3a3bdaf5b34b52de81886a098}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF}(number,  key,  formatstring, ...)
\begin{DoxyCompactList}\small\item\em Adds a warning in the keys metadata. \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}(number,  key,  text)
\begin{DoxyCompactList}\small\item\em Adds a warning in the keys metadata. \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_ga2f5d331ed725c6af0c511a0aa8677daa}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET}(parent\+Key)
\begin{DoxyCompactList}\small\item\em Set error in \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} when opening the file failed. \end{DoxyCompactList}\item 
\#define \hyperlink{group__plugin_gaf526686f01dbacd68671732aad4b5d76}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET}(parent\+Key)
\begin{DoxyCompactList}\small\item\em Set error in \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} when opening the file failed. \end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
Plugin $\ast$ \hyperlink{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{elektra\+Plugin\+Export} (const char $\ast$plugin\+Name,...)
\begin{DoxyCompactList}\small\item\em Allows one to Export Methods for a Plugin. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektra\+Plugin\+Get\+Config} (Plugin $\ast$handle)
\begin{DoxyCompactList}\small\item\em Returns the configuration of that plugin. \end{DoxyCompactList}\item 
void \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data} (Plugin $\ast$plugin, void $\ast$data)
\begin{DoxyCompactList}\small\item\em Store a pointer to plugin specific data. \end{DoxyCompactList}\item 
void $\ast$ \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data} (Plugin $\ast$plugin)
\begin{DoxyCompactList}\small\item\em Get a pointer to the plugin specific data stored before. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \hyperlink{group__plugin_ga436cda13ed70c0face08661a90620bf6}{elektra\+Plugin\+Get\+Global\+Key\+Set} (Plugin $\ast$plugin)
\begin{DoxyCompactList}\small\item\em Get a pointer to the global keyset. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}{elektra\+Doc\+Open} (Plugin $\ast$handle, Key $\ast$warnings\+Key)
\begin{DoxyCompactList}\small\item\em Initialize data for the plugin. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektra\+Doc\+Close} (Plugin $\ast$handle, Key $\ast$warnings\+Key)
\begin{DoxyCompactList}\small\item\em Finalize the plugin. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get} (Plugin $\ast$handle, Key\+Set $\ast$returned, Key $\ast$parent\+Key)
\begin{DoxyCompactList}\small\item\em Get data from storage to application. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set} (Plugin $\ast$handle, Key\+Set $\ast$returned, Key $\ast$parent\+Key)
\begin{DoxyCompactList}\small\item\em Set data from application to storage. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_ga52807469897b8acbada5bcc6b8c8ceab}{elektra\+Doc\+Commit} (Plugin $\ast$handle, Key\+Set $\ast$returned, Key $\ast$parent\+Key)
\begin{DoxyCompactList}\small\item\em Make changes to storage final. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}{elektra\+Doc\+Error} (Plugin $\ast$handle, Key\+Set $\ast$returned, Key $\ast$parent\+Key)
\begin{DoxyCompactList}\small\item\em Rollback in case of errors. \end{DoxyCompactList}\item 
int \hyperlink{group__plugin_ga1c8702efe0f3853c2d7ecca0889f78e8}{elektra\+Doc\+Check\+Conf} (Key $\ast$error\+Key, Key\+Set $\ast$conf)
\begin{DoxyCompactList}\small\item\em Validate plugin configuration at mount time. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Elektra plugin framework. 

\begin{DoxySince}{Since}
version 0.\+4.\+9, Elektra can dynamically load different key storage plugins.

version 0.\+7.\+0 Elektra can have multiple backends, mounted at any place in the key database.

version 0.\+8.\+0 Elektra backends are composed out of multiple plugins.
\end{DoxySince}
To get started with writing plugins, first read our \href{doc_tutorials_plugins_md.html}{\tt Plugin Tutorial}.

A plugin can implement any functionality related to configuration. There are 6 possible entry points for a plugin.
\begin{DoxyItemize}
\item \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} will be called when configuration or the plugin\textquotesingle{}s contract is retrieved from the key database
\item \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set()} will be called when configuration is written to the key database
\item \hyperlink{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}{elektra\+Doc\+Open()} will be called before any other method of the plugin is called
\item \hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektra\+Doc\+Close()} will be called as last method
\item \hyperlink{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}{elektra\+Doc\+Error()} will be called when \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} failed (to give the plugin a chance to recover/undo its actions)
\item \hyperlink{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{elektra\+Plugin\+Export()} exports all methods for the plugin.
\end{DoxyItemize}

Additionally, make sure that you write a contract in the R\+E\+A\+D\+M\+E.\+md. It is used by the build system and the mounting tools.

Plugins should not change the keyname of the key that is passed to the entry points (warnings\+Key and parent\+Key in this documentation). These keys might be members in keysets.

The names described here contain \char`\"{}\+Doc\char`\"{} within the method\textquotesingle{}s name just because the plugin described in this document is called doc (the doxygen source was generated from \hyperlink{doc_8h}{src/plugins/doc/doc.\+h}). Always replace Doc with the name of the plugin you are going to implement or use \hyperlink{group__plugin_gacb05c902e4014535589db4193da87460}{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON}.

\begin{DoxyParagraph}{Overview}
There are different types of plugins for different concerns. They all only have the entry points as defined above. The types of plugins handled in this document\+:
\begin{DoxyItemize}
\item A storage plugin gets an empty keyset in \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} and constructs the information out from a file. In \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set()} the keyset is written to a file. ~\newline
 Other persistent storage then a file is not handled within this document because it involves many other issues. For files the resolver plugin already takes care of transactions and rollback. So the storage plugin is the source and dump as known from pipes and filters.
\item A filter plugin is a plugin which operates on existing keys. It may process or change the keyset. Or it may reject specific keysets which do not meet some criteria.
\end{DoxyItemize}
\end{DoxyParagraph}
Use following include to have the functions that are not implemented by you available\+:


\begin{DoxyCodeInclude}
\textcolor{preprocessor}{#include <\hyperlink{kdbplugin_8h}{kdbplugin.h}>}
\end{DoxyCodeInclude}
 \begin{DoxyParagraph}{Error and Warnings}
In case of trouble, in some methods you can use the macro \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR} (in other methods it is not allowed). You might add warnings with the macro \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}. You can also use their pedants that accept a format string as known by printf\+: \hyperlink{group__plugin_ga3e4fc2c20d8e64bed7a54bb1af882e34}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF} and \hyperlink{group__plugin_ga2bbb3bc3a3bdaf5b34b52de81886a098}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF}. Make sure to define and use a macro in the error specification (/src/error/specification) so that you can easily renumber your error/warning codes\+:
\end{DoxyParagraph}

\begin{DoxyCodeInclude}
number:60
description:Invalid Line encountered
severity:error
macro:NOEOF
module:simpleini
\end{DoxyCodeInclude}
 Use following include to have the macros for setting the error and adding the warnings available\+:


\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}
 and then you can use\+:


\begin{DoxyCodeInclude}
ELEKTRA\_SET\_VALIDATION\_SYNTACTIC\_ERROR ( parentKey, \textcolor{stringliteral}{"Not at the end of file"});
\end{DoxyCodeInclude}
 Note that you also need to return -\/1 in the case of error. See individual description of entry points to implement below.

\begin{DoxyParagraph}{Global Key\+Set Handle}

\end{DoxyParagraph}
This keyset allows plugins to exchange information with other plugins.

The keyset is initialized by the K\+DB for all plugins, except for manually created plugins with {\ttfamily \hyperlink{elektra_2plugin_8c_a32a70a7876542c51d153164ac5108a57}{elektra\+Plugin\+Open()}}. The global keyset is tied to a K\+DB handle, initialized on {\ttfamily \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} and deleted on {\ttfamily \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

Obtain a handle to the global keyset and work with it\+:


\begin{DoxyCodeInclude}
        KeySet * globalKS = \hyperlink{group__plugin_ga436cda13ed70c0face08661a90620bf6}{elektraPluginGetGlobalKeySet} (plugin);
        \textcolor{comment}{// now we can read something from the global keyset}
        \textcolor{comment}{// or add something for us or others to read}
        Key * important = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"user/global/myDocKey"}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"global plugins can see
       me"}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
        \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey} (globalKS, important);
\end{DoxyCodeInclude}
 Clean up keys which you do not need any more, to keep the global keyset compact\+:


\begin{DoxyCodeInclude}
        \textcolor{comment}{// clean up parts of the global keyset which we do not need}
        Key * cutKey = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"user/global/myDocKey"}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
        KeySet * notNeeded = \hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut} (globalKS, cutKey);
        \hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel} (notNeeded);
\end{DoxyCodeInclude}
 \begin{DoxyParagraph}{Further help}
Do not hesitate to open an issue if anything is unclear. 
\end{DoxyParagraph}


\subsection{Macro Definition Documentation}
\mbox{\Hypertarget{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}\label{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG@{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG@{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}{ELEKTRA\_ADD\_WARNING}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG(\begin{DoxyParamCaption}\item[{}]{number,  }\item[{}]{key,  }\item[{}]{text }\end{DoxyParamCaption})}



Adds a warning in the keys metadata. 

Include \hyperlink{kdberrors_8h}{kdberrors.\+h} to make it work\+:


\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}



\begin{DoxyParams}{Parameters}
{\em number} & the warning number from src/error/specification \\
\hline
{\em key} & to write the error to \\
\hline
{\em text} & additional text for the user \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__plugin_ga2bbb3bc3a3bdaf5b34b52de81886a098}\label{group__plugin_ga2bbb3bc3a3bdaf5b34b52de81886a098}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF@{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF@{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF}{ELEKTRA\_ADD\_WARNINGF}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+N\+GF(\begin{DoxyParamCaption}\item[{}]{number,  }\item[{}]{key,  }\item[{}]{formatstring,  }\item[{}]{... }\end{DoxyParamCaption})}



Adds a warning in the keys metadata. 

Include \hyperlink{kdberrors_8h}{kdberrors.\+h} to make it work\+:


\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}



\begin{DoxyParams}{Parameters}
{\em number} & the warning number from src/error/specification \\
\hline
{\em key} & to write the error to \\
\hline
{\em formatstring} & a format string as in printf \\
\hline
{\em ...} & further arguments as in printf \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__plugin_gacb05c902e4014535589db4193da87460}\label{group__plugin_gacb05c902e4014535589db4193da87460}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON@{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON@{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON}{ELEKTRA\_PLUGIN\_FUNCTION}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+ON(\begin{DoxyParamCaption}\item[{}]{function }\end{DoxyParamCaption})~E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+F\+U\+N\+C\+T\+I\+O\+N2 (E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+N\+A\+M\+E\+\_\+C, function)}



Declare a plugin\textquotesingle{}s function name suitable for compilation variants (see doc/tutorials). 

It can be used in the same way as \hyperlink{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{elektra\+Plugin\+Export()}. \begin{DoxySeeAlso}{See also}
E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+E\+X\+P\+O\+RT
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em plugin} & the name of the plugin \\
\hline
{\em function} & which function it is (open, close, get, set, error, commit) \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__plugin_gabdcb97b05a83130c32bbde75db80fc50}\label{group__plugin_gabdcb97b05a83130c32bbde75db80fc50}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME@{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME@{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME}{ELEKTRA\_README}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME~E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+M\+E2 (E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+N\+A\+M\+E\+\_\+C)}



The filename for inclusion of the readme for compilation variants (see doc/tutorials). 


\begin{DoxyParams}{Parameters}
{\em plugin} & the name of the plugin \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}\label{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR}{ELEKTRA\_SET\_ERROR}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR(\begin{DoxyParamCaption}\item[{}]{number,  }\item[{}]{key,  }\item[{}]{text }\end{DoxyParamCaption})}



Sets the error in the keys metadata. 

Include \hyperlink{kdberrors_8h}{kdberrors.\+h} to make it work. Only a single error can be written to the key.


\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}



\begin{DoxyParams}{Parameters}
{\em number} & the error number from src/error/specification \\
\hline
{\em key} & to write the error to \\
\hline
{\em text} & additional text for the user \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{group__plugin_ga2f5d331ed725c6af0c511a0aa8677daa}\label{group__plugin_ga2f5d331ed725c6af0c511a0aa8677daa}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET}{ELEKTRA\_SET\_ERROR\_GET}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET(\begin{DoxyParamCaption}\item[{}]{parent\+Key }\end{DoxyParamCaption})}



Set error in \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} when opening the file failed. 

Assumes that error reason is in {\ttfamily errno}.


\begin{DoxyParams}{Parameters}
{\em parent\+Key} & key to append error to\\
\hline
\end{DoxyParams}
To use it include\+:


\begin{DoxyCodeInclude}
\textcolor{preprocessor}{#include <\hyperlink{kdbplugin_8h}{kdbplugin.h}>}
\end{DoxyCodeInclude}

\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}
 \begin{DoxyReturn}{Returns}

\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_gaf526686f01dbacd68671732aad4b5d76}\label{group__plugin_gaf526686f01dbacd68671732aad4b5d76}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET}{ELEKTRA\_SET\_ERROR\_SET}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET(\begin{DoxyParamCaption}\item[{}]{parent\+Key }\end{DoxyParamCaption})}



Set error in \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} when opening the file failed. 

Assumes that error reason is in {\ttfamily errno}.


\begin{DoxyParams}{Parameters}
{\em parent\+Key} & key to append error to\\
\hline
\end{DoxyParams}
To use it include\+:


\begin{DoxyCodeInclude}
\textcolor{preprocessor}{#include <\hyperlink{kdbplugin_8h}{kdbplugin.h}>}
\end{DoxyCodeInclude}

\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}
 \begin{DoxyReturn}{Returns}

\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_ga3e4fc2c20d8e64bed7a54bb1af882e34}\label{group__plugin_ga3e4fc2c20d8e64bed7a54bb1af882e34}} 
\index{Plugins@{Plugins}!E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF}}
\index{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF@{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF}{ELEKTRA\_SET\_ERRORF}}
{\footnotesize\ttfamily \#define E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+RF(\begin{DoxyParamCaption}\item[{}]{number,  }\item[{}]{key,  }\item[{}]{formatstring,  }\item[{}]{... }\end{DoxyParamCaption})}



Sets the error in the keys metadata. 

Include \hyperlink{kdberrors_8h}{kdberrors.\+h} to make it work. Only a single error can be written to the key.


\begin{DoxyCodeInclude}
\textcolor{comment}{// using namespace ckdb; // for C++}
\textcolor{preprocessor}{#include <\hyperlink{kdberrors_8h}{kdberrors.h}>}
\end{DoxyCodeInclude}



\begin{DoxyParams}{Parameters}
{\em number} & the error number from src/error/specification \\
\hline
{\em key} & to write the error to \\
\hline
{\em formatstring} & a format string as in printf \\
\hline
{\em ...} & further arguments as in printf \\
\hline
\end{DoxyParams}


\subsection{Function Documentation}
\mbox{\Hypertarget{group__plugin_ga1c8702efe0f3853c2d7ecca0889f78e8}\label{group__plugin_ga1c8702efe0f3853c2d7ecca0889f78e8}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Check\+Conf@{elektra\+Doc\+Check\+Conf}}
\index{elektra\+Doc\+Check\+Conf@{elektra\+Doc\+Check\+Conf}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Check\+Conf()}{elektraDocCheckConf()}}
{\footnotesize\ttfamily int elektra\+Doc\+Check\+Conf (\begin{DoxyParamCaption}\item[{Key $\ast$}]{error\+Key,  }\item[{Key\+Set $\ast$}]{conf }\end{DoxyParamCaption})}



Validate plugin configuration at mount time. 

During the mount phase the Backend\+Builder calls this method, if it is provided by the plugin.

In this method the plugin configuration can be checked for validity or integrity. Missing items can be added to complete the configuration.


\begin{DoxyParams}{Parameters}
{\em error\+Key} & is used to propagate error messages to the caller \\
\hline
{\em conf} & contains the plugin configuration to be validated\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success\+: the configuration was OK and has not been changed. \\
\hline
{\em 1} & on success\+: the configuration has been changed and now it is OK. \\
\hline
{\em -\/1} & on failure\+: the configuration was not OK and could not be fixed. Set an error using \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR} to inform the user what went wrong. Additionally you can add any number of warnings with \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}. \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}\label{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Close@{elektra\+Doc\+Close}}
\index{elektra\+Doc\+Close@{elektra\+Doc\+Close}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Close()}{elektraDocClose()}}
{\footnotesize\ttfamily int elektra\+Doc\+Close (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key $\ast$}]{warnings\+Key }\end{DoxyParamCaption})}



Finalize the plugin. 

Called prior to unloading the plugin dynamic module. After this function is called, it is ensured that no functions from your plugin will ever be accessed again.

Make sure to free all memory that your plugin requested at runtime. Also make sure to free what you stored by \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} before.

So for the Doc plugin we need to\+:


\begin{DoxyCodeInclude}
\textcolor{keywordtype}{int} \hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektraDocClose} (Plugin * handle, Key * warningsKey ELEKTRA\_UNUSED)
\{
        \hyperlink{internal_8c_a7f572149d2e0bfe18023a6ac969f195c}{elektraFree} (\hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektraPluginGetData} (handle));

        \textcolor{keywordflow}{return} 0; \textcolor{comment}{/* success */}
\}
\end{DoxyCodeInclude}
 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}
{\em handle} & contains internal information of the plugin \\
\hline
{\em warnings\+Key} & can be used to to add warnings using \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG} (Do not add errors!)\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success (no other return value currently allowed)\\
\hline
{\em -\/1} & on problems (only use E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG, but never set an error).\\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()} 

\hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data()}, \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} and \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektra\+Plugin\+Get\+Config()} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__plugin_ga52807469897b8acbada5bcc6b8c8ceab}\label{group__plugin_ga52807469897b8acbada5bcc6b8c8ceab}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Commit@{elektra\+Doc\+Commit}}
\index{elektra\+Doc\+Commit@{elektra\+Doc\+Commit}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Commit()}{elektraDocCommit()}}
{\footnotesize\ttfamily int elektra\+Doc\+Commit (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key\+Set $\ast$}]{returned,  }\item[{Key $\ast$}]{parent\+Key }\end{DoxyParamCaption})}



Make changes to storage final. 

Once the content of {\ttfamily returned} has been stored, the changes need to be made final and visible to other users, which is done by this function. After this function has been called, no further changes can be made by elektra\+Plugin\+Set() functions within this invocation of \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}.

The function is called by \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} if the plugin implementing it fulfills the {\ttfamily commit} role.

\begin{DoxyPrecond}{Precondition}
The keyset {\ttfamily returned} holds all stored keys which must be made final for this keyset. The keyset is sorted and rewinded.

The {\ttfamily parent\+Key} 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 name of the parent\+Key marks the mountpoint.
\end{DoxyPrecond}
\begin{DoxyPostcond}{Postcondition}
the storage changes made by the plugins previously called by \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} will be made final.
\end{DoxyPostcond}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} for caller.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of the plugin \\
\hline
{\em returned} & contains a keyset with relevant keys \\
\hline
{\em parent\+Key} & contains the location of the relevant keys within the key database.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & on success without any changes \\
\hline
{\em -\/1} & on failure. The cause of the error needs to be entered into parent\+Key, \hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor()} needs to point to the position where the error appeared. The error can be specified using \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR}. \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG} can be used to add warnings for the user. \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}\label{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Error@{elektra\+Doc\+Error}}
\index{elektra\+Doc\+Error@{elektra\+Doc\+Error}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Error()}{elektraDocError()}}
{\footnotesize\ttfamily int elektra\+Doc\+Error (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key\+Set $\ast$}]{returned,  }\item[{Key $\ast$}]{parent\+Key }\end{DoxyParamCaption})}



Rollback in case of errors. 

First for all plugins \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set()} will be called. If any plugin had problems before the commit (done by the resolver plugin), we can safely rollback our changes.

This method is rarely used by plugins, it is mainly used for resolvers (to implement rollback) or by logging plugins. It is not needed for storage plugins, because they only operate on temporary files created by the resolver.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of the plugin \\
\hline
{\em returned} & contains a keyset with relevant keys \\
\hline
{\em parent\+Key} & contains the information where to set the keys. can be used to add warnings with the macro \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}, but do not add errors!\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & on success with no action \\
\hline
{\em -\/1} & on failure (you can add warnings, but we are already in an error state, so do not set the error). \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__plugin_gacb69f3441c6d84241b4362f958fbe313}\label{group__plugin_gacb69f3441c6d84241b4362f958fbe313}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Get@{elektra\+Doc\+Get}}
\index{elektra\+Doc\+Get@{elektra\+Doc\+Get}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Get()}{elektraDocGet()}}
{\footnotesize\ttfamily int elektra\+Doc\+Get (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key\+Set $\ast$}]{returned,  }\item[{Key $\ast$}]{parent\+Key }\end{DoxyParamCaption})}



Get data from storage to application. 

Retrieve information from a permanent storage to construct a keyset.\hypertarget{group__plugin_intro}{}\subsection{Introduction}\label{group__plugin_intro}
The \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} function handle everything related to receiving keys.\hypertarget{group__plugin_contract}{}\subsubsection{Contract Handling}\label{group__plugin_contract}
The contract is a keyset that needs to be returned if the parent\+Key is system/elektra/modules/yourpluginname.

Which keys and their meaning is specified in doc/\+C\+O\+N\+T\+R\+A\+C\+T.\+ini

Here is an example for our doc plugin\+:


\begin{DoxyCodeInclude}
\textcolor{keywordtype}{int} \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektraDocGet} (Plugin * plugin ELEKTRA\_UNUSED, KeySet * returned, Key * parentKey)
\{
        \textcolor{keywordflow}{if} (!strcmp (\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName} (parentKey), \textcolor{stringliteral}{"system/elektra/modules/doc"}))
        \{
                KeySet * contract =
                        \hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew} (30, \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc"}, 
      \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, \textcolor{stringliteral}{"doc plugin waits for your orders"}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports"}, 
      \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/open"}, KEY\_FUNC, 
      \hyperlink{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}{elektraDocOpen}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/close"}, KEY\_FUNC, 
      \hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektraDocClose}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/get"}, KEY\_FUNC, 
      \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektraDocGet}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/set"}, KEY\_FUNC, 
      \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektraDocSet}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/commit"}, KEY\_FUNC, 
      \hyperlink{group__plugin_ga52807469897b8acbada5bcc6b8c8ceab}{elektraDocCommit}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/error"}, KEY\_FUNC, 
      \hyperlink{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}{elektraDocError}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/exports/checkconf"}, KEY\_FUNC, 
      \hyperlink{group__plugin_ga1c8702efe0f3853c2d7ecca0889f78e8}{elektraDocCheckConf}, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}),
#include \hyperlink{group__plugin_gabdcb97b05a83130c32bbde75db80fc50}{ELEKTRA\_README}
                               \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\textcolor{stringliteral}{"system/elektra/modules/doc/infos/version"}, 
      \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}, PLUGINVERSION, \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}), \hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END});
                \hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ksAppend} (returned, contract);
                \hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel} (contract);

                \textcolor{keywordflow}{return} 1; \textcolor{comment}{/* success */}
        \}
\end{DoxyCodeInclude}
 Some clauses of the contract, especially the description of the plugin can be done more conveniently directly in a R\+E\+A\+D\+M\+E.\+md that is included by \hyperlink{group__plugin_gabdcb97b05a83130c32bbde75db80fc50}{E\+L\+E\+K\+T\+R\+A\+\_\+\+R\+E\+A\+D\+ME}.\hypertarget{group__plugin_storage}{}\subsubsection{Storage Plugins}\label{group__plugin_storage}
For storage plugins the filename is written in the value of the parent\+Key. So the first task of the plugin is to open that file. Then it should parse its content and construct a keyset with all information of that file.

You need to be able to reconstruct the same file with the information of the keyset. So be sure to copy all comments, whitespaces and so on into some metadata of the keys. Otherwise the information is lost after writing the file the next time.

Now lets look at an example how the typical \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} 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 parse\+\_\+key will parse a key and a value from an open file handle
\end{DoxyItemize}

The typical loop for a storage plugin will be like\+:


\begin{DoxyCodeInclude}
        FILE * fp = fopen (\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString} (parentKey), \textcolor{stringliteral}{"r"});
        \textcolor{keywordtype}{char} * key = 0;
        \textcolor{keywordtype}{char} * value = 0;

        \textcolor{keywordflow}{while} (parseKey (fp, &key, &value) >= 1)
        \{
                Key * read = \hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew} (\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName} (parentKey), \hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END});
                \textcolor{keywordflow}{if} (\hyperlink{group__keyname_gaa70593a2c772c4b7bc33423b9b10a270}{keyAddName} (read, key) == -1)
                \{
                        ELEKTRA\_ADD\_VALIDATION\_SYNTACTIC\_WARNINGF (parentKey, \textcolor{stringliteral}{"Key name %s is not valid,
       discarding key"}, key);
                        \hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel} (read);
                        \textcolor{keywordflow}{continue};
                \}
                \hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{keySetString} (read, value);

                \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey} (returned, read);
        \}

        \textcolor{keywordflow}{if} (feof (fp) == 0)
        \{
                fclose (fp);
                ELEKTRA\_SET\_VALIDATION\_SYNTACTIC\_ERROR (parentKey, \textcolor{stringliteral}{"Invalid line encountered: not at the
       end of file"});
                \textcolor{keywordflow}{return} -1;
        \}

        fclose (fp);
\end{DoxyCodeInclude}
 When opening files, make sure to use the macros \hyperlink{group__plugin_gaf526686f01dbacd68671732aad4b5d76}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+S\+ET} and \hyperlink{group__plugin_ga2f5d331ed725c6af0c511a0aa8677daa}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+O\+R\+\_\+\+G\+ET} for errors, as shown here\+:


\begin{DoxyCodeInclude}
        FILE * fp = fopen (\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString} (parentKey), \textcolor{stringliteral}{"w"});
        \textcolor{keywordflow}{if} (!fp)
        \{
                \hyperlink{group__plugin_gaf526686f01dbacd68671732aad4b5d76}{ELEKTRA\_SET\_ERROR\_SET} (parentKey);
                \textcolor{keywordflow}{return} -1;
        \}
\end{DoxyCodeInclude}
 \hypertarget{group__plugin_filter}{}\subsubsection{Filter Plugins}\label{group__plugin_filter}
For filter plugins the actual task is rather unspecified. You basically can do anything with the keyset. To get roundtrip properties you might want to undo any changes you did in \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set()}.

The pseudo functions (which do the real work) are\+:
\begin{DoxyItemize}
\item do\+\_\+action() which processes every key in this filter
\end{DoxyItemize}


\begin{DoxyCodeInclude}
        Key * k;
        \hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind} (returned);
        \textcolor{keywordflow}{while} ((k = \hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext} (returned)) != 0)
        \{
                doAction (k);
        \}

        \textcolor{keywordflow}{return} 1; \textcolor{comment}{// success}
\}
\end{DoxyCodeInclude}


\begin{DoxyPrecond}{Precondition}
The caller \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} will make sure before you are called that the parent\+Key\+:
\begin{DoxyItemize}
\item is a valid key (means that it is a system or user key).
\item is your mountpoint and that your plugin is responsible for it. 
\end{DoxyItemize}

and that the returned\+:
\begin{DoxyItemize}
\item is a valid keyset.
\item your plugin is only called when needed (e.\+g. only if file was modified)
\item has {\ttfamily all} keys related to your plugin.
\item contains only valid keys below (see \hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{key\+Is\+Below()}) your parent\+Key.
\item is in a sorted order (given implicit by Key\+Set) 
\end{DoxyItemize}

and that the handle\+:
\begin{DoxyItemize}
\item is valid for your plugin.
\item that \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data()} contains the same handle for lifetime of your plugin.
\end{DoxyItemize}

The caller \hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} will make sure that afterwards you were called, that\+:
\begin{DoxyItemize}
\item other plugins below your plugin will be called again recursively.
\item that all keys are merged to one keyset the user gets
\item that all keys (that should not be removed) are passed to \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} if writing to disc is needed.
\end{DoxyItemize}
\end{DoxyPrecond}
\begin{DoxyInvariant}{Invariant}
There are no global variables and \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} stores all information. The handle is to be guaranteed to be the same if it is the same plugin.
\end{DoxyInvariant}
\begin{DoxyPostcond}{Postcondition}
The keyset {\ttfamily returned} has the {\ttfamily parent\+Key} and all keys below (\hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{key\+Is\+Below()}) 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}{kdb\+Get()} will drop these keys with additional plugins.
\end{DoxyPostcond}
\begin{DoxyParagraph}{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. For file storage plugins this is automatically done for you by the resolver. For other types (e.\+g. databases) you need to implement your own resolver doing this.
\end{DoxyParagraph}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()} for caller.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened } key database \\
\hline
{\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 updating. \\
\hline
{\em parent\+Key} & contains the information below which key the keys should be gotten.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & when nothing was to do \\
\hline
{\em -\/1} & on failure, the current key in returned shows the position. use \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR} of \hyperlink{kdberrors_8h}{kdberrors.\+h} to define the error code. You additionally can add as many warnings as you would like to add. \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}\label{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Open@{elektra\+Doc\+Open}}
\index{elektra\+Doc\+Open@{elektra\+Doc\+Open}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Open()}{elektraDocOpen()}}
{\footnotesize\ttfamily int elektra\+Doc\+Open (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key $\ast$}]{warnings\+Key }\end{DoxyParamCaption})}



Initialize data for the plugin. 

This is the first method called after dynamically loading this plugin. It is guaranteed, that this method will be called before any other method.

This method is responsible for\+:
\begin{DoxyItemize}
\item plugin\textquotesingle{}s specific configuration gathering
\item initialization of all plugin\textquotesingle{}s internal structs
\item initial setup of all I/O details such as opening a file, connecting to a database, setup connection to a server, iff this cannot be done per invocation in \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} and \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektra\+Doc\+Set()}.
\end{DoxyItemize}

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

\begin{DoxyNote}{Note}
The plugin must not have any global variables. If you have one Elektra will not be threadsafe. Do not assume that your plugin will be opened only once or will not be reopened at a later time.
\end{DoxyNote}
Instead of global variables the methods \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data()} and \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} exist to store and get any information related to your plugin.

The correct substitute for global variables will be\+:


\begin{DoxyCodeInclude}
\textcolor{keyword}{typedef} \textcolor{keyword}{struct}
\{
        \textcolor{keywordtype}{int} global;
\} GlobalData;
\end{DoxyCodeInclude}
 and then initialize it using\+:


\begin{DoxyCodeInclude}
\textcolor{keywordtype}{int} \hyperlink{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}{elektraDocOpen} (Plugin * handle, Key * warningsKey ELEKTRA\_UNUSED)
\{
        GlobalData * data;
        KeySet * config = \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektraPluginGetConfig} (handle);
        Key * kg = \hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName} (config, \textcolor{stringliteral}{"/global"}, 0);

        data = \hyperlink{internal_8c_a35cdc2e5caed3454cb73b4fc7f37858c}{elektraMalloc} (\textcolor{keyword}{sizeof} (GlobalData));
        data->global = 0;
        \textcolor{keywordflow}{if} (kg) data->global = atoi (\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString} (kg));
        \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektraPluginSetData} (handle, data);
\end{DoxyCodeInclude}
 Make sure to free everything you allocate within \hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektra\+Doc\+Close()}.

If your plugin has no useful way to startup without config, the module loader would not be able to load the module. We need, however, to still load the plugin to get the contract.

To solve that problem the module loader adds the configuration key /module. Even if your plugin is basically not able to startup successfully, it should still provide a fallback when /module is present, so that \hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektra\+Doc\+Get()} on system/elektra/modules can be called successfully later on.


\begin{DoxyCodeInclude}
        \textcolor{keywordflow}{if} (\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName} (config, \textcolor{stringliteral}{"/module"}, 0))
        \{
                \textcolor{keywordflow}{return} 0;
        \}
        \textcolor{comment}{// do some setup that will fail without configuration}
\end{DoxyCodeInclude}
 Note that for plugins where the contract will be altered based on configuration this specific configuration should be considered. In fact the idea of /module is to get the correct contract.


\begin{DoxyRetVals}{Return values}
{\em -\/1} & on error, your plugin will be removed then and the missing plugin added instead. Use \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG} to indicate the problem. The system will automatically add the information that the plugin was removed, so you do not need the user give that information.\\
\hline
{\em 1} & on success\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of the plugin \\
\hline
{\em warnings\+Key} & can be used to add warnings with the macro \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG} (Do not add errors!) \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data()}, \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} and \hyperlink{group__plugin_ga644bead796506c172817724051c977c9}{elektra\+Plugin\+Get\+Config()} 

\hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektra\+Doc\+Close()} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}\label{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}} 
\index{Plugins@{Plugins}!elektra\+Doc\+Set@{elektra\+Doc\+Set}}
\index{elektra\+Doc\+Set@{elektra\+Doc\+Set}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Doc\+Set()}{elektraDocSet()}}
{\footnotesize\ttfamily int elektra\+Doc\+Set (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle,  }\item[{Key\+Set $\ast$}]{returned,  }\item[{Key $\ast$}]{parent\+Key }\end{DoxyParamCaption})}



Set data from application to storage. 

This function does everything related to set and remove keys in a plugin. There is only one function for that purpose to make implementation of file based plugins 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 elektra\+Plugin\+Get() can rebuild the keyset as it was before. See the live cycle to understand\+:


\begin{DoxyCodeInclude}
\textcolor{keyword}{static} \textcolor{keywordtype}{void} usercode (KDB * handle, KeySet * keyset, Key * key)
\{
        \textcolor{comment}{// some more user code}
        \hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{keySetString} (key, \textcolor{stringliteral}{"mycomment"}); \textcolor{comment}{// the user changes the key}
        \hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey} (keyset, key);    \textcolor{comment}{// append the key to the keyset}
        \hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet} (handle, keyset, 0);        \textcolor{comment}{// and syncs it to disc}
\}

\textcolor{comment}{// so now kdbSet is called}
\textcolor{keywordtype}{int} elektraKdbSet (KDB * handle, KeySet * keyset, Key * parentKey)
\{
        \textcolor{keywordtype}{int} ret = 0;
        \textcolor{comment}{// find appropriate plugin and then call it:}
        Plugin * plugin = findPlugin (handle);
        ret = \hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektraDocSet} (plugin, keyset, parentKey);
        \textcolor{comment}{// the keyset with the key (and others for this plugin)}
        \textcolor{comment}{// will be passed to this function}
        \textcolor{keywordflow}{return} ret;
\}

\textcolor{comment}{// so now elektraPluginSet(), which is the function described here,}
\textcolor{comment}{// is called:}
\textcolor{keywordtype}{int} elektraPluginSet (Plugin * plugin ELEKTRA\_UNUSED, KeySet * returned, Key * parentKey ELEKTRA\_UNUSED)
\{
        \textcolor{comment}{// the task of elektraPluginSet is now to store the keys}
        Key * k;
        \hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind} (returned);
        \textcolor{keywordflow}{while} ((k = \hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext} (returned)) != 0)
        \{
                saveToDisc (k);
        \}

        \textcolor{keywordflow}{return} 1; \textcolor{comment}{/* success */}
\}
\end{DoxyCodeInclude}
 Of course all information of every key in the keyset {\ttfamily returned} need to be stored permanently. 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.

The {\ttfamily parent\+Key} 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 name of the parent\+Key marks the mountpoint. The string of the parent\+Key is the filename to write to.
\end{DoxyPrecond}
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}{kdb\+Set()} and plugins will sort them out.

\begin{DoxyInvariant}{Invariant}
There are no global variables, but instead \hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data()} will be used. 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}
\begin{DoxySeeAlso}{See also}
\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()} for caller.
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of the plugin \\
\hline
{\em returned} & contains a keyset with relevant keys \\
\hline
{\em parent\+Key} & contains the information where to set the keys (name is mountpoint your plugin is mounted, string is the file to write to)\\
\hline
\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.
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & on success with no changed key in database \\
\hline
{\em -\/1} & on failure. The cause of the error needs to be added in parent\+Key You also have to make sure that \hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor()} shows to the position where the error appeared. Set an error using \hyperlink{group__plugin_gaab1842b82272e6d4235b6a71587a64d9}{E\+L\+E\+K\+T\+R\+A\+\_\+\+S\+E\+T\+\_\+\+E\+R\+R\+OR} to inform the user what went wrong. Additionally you can add any number of warnings with \hyperlink{group__plugin_ga3da3bdb0f41710adda9eee3d7adac9ff}{E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+D\+D\+\_\+\+W\+A\+R\+N\+I\+NG}. \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}\label{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}} 
\index{Plugins@{Plugins}!elektra\+Plugin\+Export@{elektra\+Plugin\+Export}}
\index{elektra\+Plugin\+Export@{elektra\+Plugin\+Export}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Plugin\+Export()}{elektraPluginExport()}}
{\footnotesize\ttfamily Plugin$\ast$ elektra\+Plugin\+Export (\begin{DoxyParamCaption}\item[{const char $\ast$}]{plugin\+Name,  }\item[{}]{... }\end{DoxyParamCaption})}



Allows one to Export Methods for a Plugin. 

This function must be called within E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+E\+X\+P\+O\+RT. It define the plugin\textquotesingle{}s methods that will be exported.

All K\+DB methods implemented by the plugin basically could have random names (convention is elektra\+Name$\ast$), except E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+E\+X\+P\+O\+RT.

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.

You need to use a macro so that both dynamic and static loading of the plugin works. For example for the doc plugin\+: 
\begin{DoxyCodeInclude}
Plugin * ELEKTRA\_PLUGIN\_EXPORT
\{
        \textcolor{comment}{// clang-format off}
        \textcolor{keywordflow}{return} \hyperlink{group__plugin_ga8dd092048e972a3f0c9c9f54eb41576e}{elektraPluginExport}(DOC\_PLUGIN\_NAME,
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814ab7e2dcc6e79af21dd90d2bb62920551d}{ELEKTRA\_PLUGIN\_OPEN}, &\hyperlink{group__plugin_ga23c2eb3584e38a4d494eb8f91e5e3d8d}{elektraDocOpen},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814a449e166b322550b3ad26efd4c46e49e3}{ELEKTRA\_PLUGIN\_CLOSE},       &\hyperlink{group__plugin_ga1236aefe5b2baf8b7bf636ba5aa9ea29}{elektraDocClose},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814a3d5f4a887e68878f1cc3a75985194204}{ELEKTRA\_PLUGIN\_GET},   &\hyperlink{group__plugin_gacb69f3441c6d84241b4362f958fbe313}{elektraDocGet},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814a85c9545261cf0bcc932616e67ea3b70a}{ELEKTRA\_PLUGIN\_SET},   &\hyperlink{group__plugin_gae65781a1deb34efc79c8cb9d9174842c}{elektraDocSet},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814a89e027283d949dd78bb9c1fce1b19a10}{ELEKTRA\_PLUGIN\_ERROR},       &\hyperlink{group__plugin_gad74b35f558ac7c3262f6069c5c47dc79}{elektraDocError},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814ad8ebee0e9b492518a042e5203336eca9}{ELEKTRA\_PLUGIN\_COMMIT},     &
      \hyperlink{group__plugin_ga52807469897b8acbada5bcc6b8c8ceab}{elektraDocCommit},
                \hyperlink{kdbplugin_8h_afed89ef026fb0622918a5de020de7814a64a0bc789482284d9fd27ce974e0959a}{ELEKTRA\_PLUGIN\_END});
\}
\end{DoxyCodeInclude}
 The first parameter is the name of the plugin. Then every plugin should have\+: {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+O\+P\+EN}, {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+C\+L\+O\+SE}, {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+G\+ET}, {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+S\+ET} and optionally {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+E\+R\+R\+OR} and {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+C\+O\+M\+M\+IT}.

The list is terminated with {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+P\+L\+U\+G\+I\+N\+\_\+\+E\+ND}.

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


\begin{DoxyParams}{Parameters}
{\em plugin\+Name} & the name of this plugin \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
an object that contains all plugin information needed by libelektra.\+so 
\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_ga644bead796506c172817724051c977c9}\label{group__plugin_ga644bead796506c172817724051c977c9}} 
\index{Plugins@{Plugins}!elektra\+Plugin\+Get\+Config@{elektra\+Plugin\+Get\+Config}}
\index{elektra\+Plugin\+Get\+Config@{elektra\+Plugin\+Get\+Config}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Plugin\+Get\+Config()}{elektraPluginGetConfig()}}
{\footnotesize\ttfamily Key\+Set$\ast$ elektra\+Plugin\+Get\+Config (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{handle }\end{DoxyParamCaption})}



Returns the configuration of that plugin. 


\begin{DoxyItemize}
\item The user/ config holds plugin specific configuration
\item The system/ config holds backend specific configuration
\end{DoxyItemize}

So prefer cascading lookups to honor both.


\begin{DoxyParams}{Parameters}
{\em handle} & a pointer to the plugin\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
keyset to the configuration for that plugin 
\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}\label{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}} 
\index{Plugins@{Plugins}!elektra\+Plugin\+Get\+Data@{elektra\+Plugin\+Get\+Data}}
\index{elektra\+Plugin\+Get\+Data@{elektra\+Plugin\+Get\+Data}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Plugin\+Get\+Data()}{elektraPluginGetData()}}
{\footnotesize\ttfamily void$\ast$ elektra\+Plugin\+Get\+Data (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{plugin }\end{DoxyParamCaption})}



Get a pointer to the plugin specific data stored before. 

If \hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data()} was not called earlier, N\+U\+LL will be returned.

This data is private to one instance of a plugin.

\begin{DoxySeeAlso}{See also}
\hyperlink{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}{elektra\+Plugin\+Set\+Data} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em plugin} & a pointer to the plugin \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the data 
\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_ga436cda13ed70c0face08661a90620bf6}\label{group__plugin_ga436cda13ed70c0face08661a90620bf6}} 
\index{Plugins@{Plugins}!elektra\+Plugin\+Get\+Global\+Key\+Set@{elektra\+Plugin\+Get\+Global\+Key\+Set}}
\index{elektra\+Plugin\+Get\+Global\+Key\+Set@{elektra\+Plugin\+Get\+Global\+Key\+Set}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Plugin\+Get\+Global\+Key\+Set()}{elektraPluginGetGlobalKeySet()}}
{\footnotesize\ttfamily Key\+Set$\ast$ elektra\+Plugin\+Get\+Global\+Key\+Set (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{plugin }\end{DoxyParamCaption})}



Get a pointer to the global keyset. 

Initialized for all plugins by the K\+DB, except for manually created plugins with {\ttfamily \hyperlink{elektra_2plugin_8c_a32a70a7876542c51d153164ac5108a57}{elektra\+Plugin\+Open()}}. The global keyset is tied to a K\+DB handle, initialized on {\ttfamily \hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} and deleted on {\ttfamily \hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

Plugins using this keyset are responsible for cleaning up their parts of the keyset which they do not need any more.


\begin{DoxyParams}{Parameters}
{\em plugin} & a pointer to the plugin \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a pointer to the global keyset 
\end{DoxyReturn}
\mbox{\Hypertarget{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}\label{group__plugin_gaf4b941a52ff55d0ca2a9158d90208ef2}} 
\index{Plugins@{Plugins}!elektra\+Plugin\+Set\+Data@{elektra\+Plugin\+Set\+Data}}
\index{elektra\+Plugin\+Set\+Data@{elektra\+Plugin\+Set\+Data}!Plugins@{Plugins}}
\subsubsection{\texorpdfstring{elektra\+Plugin\+Set\+Data()}{elektraPluginSetData()}}
{\footnotesize\ttfamily void elektra\+Plugin\+Set\+Data (\begin{DoxyParamCaption}\item[{Plugin $\ast$}]{plugin,  }\item[{void $\ast$}]{data }\end{DoxyParamCaption})}



Store a pointer to plugin specific data. 

This data is private to one instance of a plugin.

\begin{DoxySeeAlso}{See also}
\hyperlink{group__plugin_gaafcf3216b46292f222b8cc7828b4dd20}{elektra\+Plugin\+Get\+Data} 
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em plugin} & a pointer to the plugin \\
\hline
{\em data} & the pointer to the data \\
\hline
\end{DoxyParams}
