\hypertarget{classkdb_1_1KDB}{}\section{kdb\+::K\+DB Class Reference}
\label{classkdb_1_1KDB}\index{kdb::KDB@{kdb::KDB}}


Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}.  




{\ttfamily \#include $<$kdb.\+hpp$>$}



Inheritance diagram for kdb\+::K\+DB\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=191pt]{classkdb_1_1KDB__inherit__graph}
\end{center}
\end{figure}
\subsection*{Public Member Functions}
\begin{DoxyCompactItemize}
\item 
\mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{K\+DB}} ()
\begin{DoxyCompactList}\small\item\em Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. \end{DoxyCompactList}\item 
\mbox{\hyperlink{classkdb_1_1KDB_a98e25c7fe2f47c5a90461676c6d219e7}{K\+DB}} (\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&error\+Key)
\begin{DoxyCompactList}\small\item\em Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. \end{DoxyCompactList}\item 
virtual void \mbox{\hyperlink{classkdb_1_1KDB_aee37484b06164eacc0cc11b7b40ab892}{open}} (\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&error\+Key)
\begin{DoxyCompactList}\small\item\em Open the database. \end{DoxyCompactList}\item 
virtual void \mbox{\hyperlink{classkdb_1_1KDB_a1b3ff4a68c2c935d67dce843bc4ad01b}{close}} ()  throw ()
\begin{DoxyCompactList}\small\item\em Close the database. \end{DoxyCompactList}\item 
virtual void \mbox{\hyperlink{classkdb_1_1KDB_aa027a8f798a2cfee11ff712eb204c35d}{close}} (\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&error\+Key)  throw ()
\begin{DoxyCompactList}\small\item\em Close the database. \end{DoxyCompactList}\item 
virtual int \mbox{\hyperlink{classkdb_1_1KDB_a0419ffbc273c89756bc523b4223ec25a}{get}} (\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&returned, std\+::string const \&keyname)
\begin{DoxyCompactList}\small\item\em Get all keys below keyname inside returned. \end{DoxyCompactList}\item 
virtual int \mbox{\hyperlink{classkdb_1_1KDB_a48770a7290699bf2b7529f3ab67e378f}{get}} (\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&returned, \mbox{\hyperlink{classkdb_1_1Key}{Key}} \&parent\+Key)
\begin{DoxyCompactList}\small\item\em Get all keys below parent\+Key inside returned. \end{DoxyCompactList}\item 
virtual int \mbox{\hyperlink{classkdb_1_1KDB_a29087a6a1a7de334f4e5b62ffe5d6e6e}{set}} (\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&returned, std\+::string const \&keyname)
\begin{DoxyCompactList}\small\item\em Set all keys below keyname. \end{DoxyCompactList}\item 
virtual int \mbox{\hyperlink{classkdb_1_1KDB_a62a4fafbe21d9519b31a7868aa05f3e3}{set}} (\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&returned, \mbox{\hyperlink{classkdb_1_1Key}{Key}} \&parent\+Key)
\begin{DoxyCompactList}\small\item\em Set all keys below parent\+Key. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{classkdb_1_1KDB_a1e2a35e42941b9fee756e528a3ef14b6}{ensure}} (const \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&contract, \mbox{\hyperlink{classkdb_1_1Key}{Key}} \&parent\+Key)
\begin{DoxyCompactList}\small\item\em Ensures that the conditions defined in {\ttfamily contract} are met by this \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. 


\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if database could not be opened\\
\hline
\end{DoxyExceptions}
Opens the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} data structure will be initialized.

You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

The pointer to the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} structure returned will be initialized like described above, and it must be passed along on any kdb$\ast$() method your application calls.

Get a {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} handle for every thread using elektra. Don\textquotesingle{}t share the handle across threads, and also not the pointer accessing it\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread1 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part1"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread2 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part2"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}
 You don\textquotesingle{}t need \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} if you only want to manipulate plain in-\/memory \mbox{\hyperlink{classkdb_1_1Key}{Key}} or \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects.

\begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em error\+Key} & the key which holds errors and warnings which were issued \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to end all affairs to the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em handle} & on success \\
\hline
{\em N\+U\+LL} & on failure\\
\hline
\end{DoxyRetVals}
Access to the key database.

\begin{DoxyInvariant}{Invariant}
the object holds a valid connection to the key database or is empty 
\end{DoxyInvariant}


\subsection{Constructor \& Destructor Documentation}
\mbox{\Hypertarget{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}\label{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}} 
\index{kdb::KDB@{kdb::KDB}!KDB@{KDB}}
\index{KDB@{KDB}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{KDB()}{KDB()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily kdb\+::\+K\+D\+B\+::\+K\+DB (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}



Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. 


\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if database could not be opened\\
\hline
\end{DoxyExceptions}
Opens the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} data structure will be initialized.

You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

The pointer to the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} structure returned will be initialized like described above, and it must be passed along on any kdb$\ast$() method your application calls.

Get a {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} handle for every thread using elektra. Don\textquotesingle{}t share the handle across threads, and also not the pointer accessing it\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread1 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part1"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread2 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part2"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}
 You don\textquotesingle{}t need \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} if you only want to manipulate plain in-\/memory \mbox{\hyperlink{classkdb_1_1Key}{Key}} or \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects.

\begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em error\+Key} & the key which holds errors and warnings which were issued \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to end all affairs to the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em handle} & on success \\
\hline
{\em N\+U\+LL} & on failure \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{classkdb_1_1KDB_a98e25c7fe2f47c5a90461676c6d219e7}\label{classkdb_1_1KDB_a98e25c7fe2f47c5a90461676c6d219e7}} 
\index{kdb::KDB@{kdb::KDB}!KDB@{KDB}}
\index{KDB@{KDB}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{KDB()}{KDB()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily kdb\+::\+K\+D\+B\+::\+K\+DB (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{error\+Key }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [explicit]}}



Constructs a class \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. 


\begin{DoxyParams}{Parameters}
{\em error\+Key} & is useful if you want to get the warnings in the successful case, when no exception is thrown.\\
\hline
\end{DoxyParams}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if database could not be opened\\
\hline
\end{DoxyExceptions}
Opens the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} data structure will be initialized.

You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

The pointer to the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} structure returned will be initialized like described above, and it must be passed along on any kdb$\ast$() method your application calls.

Get a {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} handle for every thread using elektra. Don\textquotesingle{}t share the handle across threads, and also not the pointer accessing it\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread1 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part1"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread2 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part2"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}
 You don\textquotesingle{}t need \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} if you only want to manipulate plain in-\/memory \mbox{\hyperlink{classkdb_1_1Key}{Key}} or \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects.

\begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em error\+Key} & the key which holds errors and warnings which were issued \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to end all affairs to the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em handle} & on success \\
\hline
{\em N\+U\+LL} & on failure \\
\hline
\end{DoxyRetVals}


\subsection{Member Function Documentation}
\mbox{\Hypertarget{classkdb_1_1KDB_a1b3ff4a68c2c935d67dce843bc4ad01b}\label{classkdb_1_1KDB_a1b3ff4a68c2c935d67dce843bc4ad01b}} 
\index{kdb::KDB@{kdb::KDB}!close@{close}}
\index{close@{close}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{close()}{close()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily void kdb\+::\+K\+D\+B\+::close (\begin{DoxyParamCaption}{ }\end{DoxyParamCaption}) throw ( ) \hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Close the database. 

The return value does not matter because its only a null pointer check.

Closes the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
The handle must be a valid handle as returned from \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}

error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
This is the counterpart of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.

You must call this method when you finished your affairs with the key database. You can manipulate \mbox{\hyperlink{classkdb_1_1Key}{Key}} and \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects also after \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}, but you must not use any kdb$\ast$() call afterwards.

The {\ttfamily handle} parameter will be finalized and all resources associated to it will be freed. After a \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}, the {\ttfamily handle} cannot be used anymore.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em error\+Key} & the key which holds error/warning information \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em -\/1} & on N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{classkdb_1_1KDB_aa027a8f798a2cfee11ff712eb204c35d}\label{classkdb_1_1KDB_aa027a8f798a2cfee11ff712eb204c35d}} 
\index{kdb::KDB@{kdb::KDB}!close@{close}}
\index{close@{close}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{close()}{close()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily void kdb\+::\+K\+D\+B\+::close (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{error\+Key }\end{DoxyParamCaption}) throw ( ) \hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Close the database. 

The return value does not matter because its only a null pointer check.


\begin{DoxyParams}{Parameters}
{\em error\+Key} & is useful if you want to get the warnings\\
\hline
\end{DoxyParams}
Closes the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
The handle must be a valid handle as returned from \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}

error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
This is the counterpart of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.

You must call this method when you finished your affairs with the key database. You can manipulate \mbox{\hyperlink{classkdb_1_1Key}{Key}} and \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects also after \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}, but you must not use any kdb$\ast$() call afterwards.

The {\ttfamily handle} parameter will be finalized and all resources associated to it will be freed. After a \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}, the {\ttfamily handle} cannot be used anymore.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em error\+Key} & the key which holds error/warning information \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em -\/1} & on N\+U\+LL pointer \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{classkdb_1_1KDB_a1e2a35e42941b9fee756e528a3ef14b6}\label{classkdb_1_1KDB_a1e2a35e42941b9fee756e528a3ef14b6}} 
\index{kdb::KDB@{kdb::KDB}!ensure@{ensure}}
\index{ensure@{ensure}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{ensure()}{ensure()}}
{\footnotesize\ttfamily int kdb\+::\+K\+D\+B\+::ensure (\begin{DoxyParamCaption}\item[{const \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&}]{contract,  }\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{parent\+Key }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}



Ensures that the conditions defined in {\ttfamily contract} are met by this \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}. 

\begin{DoxySeeAlso}{See also}
ckdb\+::kdb\+Ensure()
\end{DoxySeeAlso}

\begin{DoxyParams}{Parameters}
{\em contract} & The contract to ensure. \\
\hline
{\em parent\+Key} & The parent\+Key to use.\\
\hline
\end{DoxyParams}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if there were problems with the contract or the database \\
\hline
{\em Contract\+Exception} & if the contract couldn\textquotesingle{}t be ensured \\
\hline
\end{DoxyExceptions}
\mbox{\Hypertarget{classkdb_1_1KDB_a0419ffbc273c89756bc523b4223ec25a}\label{classkdb_1_1KDB_a0419ffbc273c89756bc523b4223ec25a}} 
\index{kdb::KDB@{kdb::KDB}!get@{get}}
\index{get@{get}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{get()}{get()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily int kdb\+::\+K\+D\+B\+::get (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&}]{returned,  }\item[{std\+::string const \&}]{keyname }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Get all keys below keyname inside returned. 

Retrieve keys in an atomic and universal way. \begin{DoxyPrecond}{Precondition}
The {\ttfamily handle} must be passed as returned from \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} must be a valid \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}, e.\+g. constructed with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}}.

The {\ttfamily parent\+Key} \mbox{\hyperlink{classkdb_1_1Key}{Key}} must be a valid \mbox{\hyperlink{classkdb_1_1Key}{Key}}, e.\+g. constructed with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}.
\end{DoxyPrecond}
If you pass N\+U\+LL on any parameter \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will fail immediately without doing anything.

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} may already contain some keys, e.\+g. from previous \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} calls. The new retrieved keys will be appended using \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}.

If not done earlier \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will fully retrieve all keys under the {\ttfamily parent\+Key} folder recursively (See Optimization below when it will not be done).

\begin{DoxyNote}{Note}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} might retrieve more keys than requested (that are not below parent\+Key). These keys must be passed to calls of \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}, otherwise they will be lost. This stems from the fact that the user has the only copy of the whole configuration and backends only write configuration that was passed to them. For example, if you \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} \char`\"{}system/mountpoint/interest\char`\"{} you will not only get all keys below system/mountpoint/interest, but also all keys below system/mountpoint (if system/mountpoint is a mountpoint as the name suggests, but system/mountpoint/interest is not a mountpoint). Make sure to not touch or remove keys outside the keys of interest, because others may need them!
\end{DoxyNote}
\begin{DoxyParagraph}{Example\+:}
This example demonstrates the typical usecase within an application (without error handling).
\end{DoxyParagraph}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <kdb.h>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <stdio.h>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        KeySet * myConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{kdbenum_8c_a7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// for error handling see kdbget\_error.c}}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// clang-format off}}
\DoxyCodeLine{\textcolor{comment}{}Key * key = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/sw/tests/myapp/\#0/current/"},  \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * handle = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (key);}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, myConfig, key);}
\DoxyCodeLine{Key * result = \mbox{\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ksLookupByName}} (myConfig, \textcolor{stringliteral}{"/sw/tests/myapp/\#0/current/testkey1"}, 0);}
\DoxyCodeLine{        \textcolor{comment}{// clang-format on}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (key);}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_name = \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (result);}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_value = \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (result);}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_comment = \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{keyGetMeta}} (result, \textcolor{stringliteral}{"comment"}));}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"key: \%s value: \%s comment: \%s\(\backslash\)n"}, key\_name, key\_value, key\_comment);}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (myConfig); \textcolor{comment}{// delete the in-memory configuration}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// maybe you want kdbSet() myConfig here}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (handle, 0); \textcolor{comment}{// no more affairs with the key database.}}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}


When a backend fails \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will return -\/1 with all error and warning information in the {\ttfamily parent\+Key}. The parameter {\ttfamily returned} will not be changed.

\begin{DoxyParagraph}{Optimization\+:}
In the first run of kdb\+Get all requested (or more) keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay in the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} returned as passed.
\end{DoxyParagraph}
It is your responsibility to save the original keyset if you need it afterwards.

If you want to be sure to get a fresh keyset again, you need to open a second handle to the key database using \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em parent\+Key} & is used to add warnings and set an error information. Additionally, its name is a hint which keys should be retrieved (it is possible that more are retrieved, see Note above).
\begin{DoxyItemize}
\item cascading keys (starting with /) will retrieve the same path in all namespaces
\item / will retrieve all keys 
\end{DoxyItemize}\\
\hline
{\em ks} & the (pre-\/initialized) \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} returned with all keys found will not be changed on error or if no update is required \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}}, \mbox{\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\+Lookup\+By\+Name()}} for powerful lookups after the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} was retrieved 

\mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} which needs to be called before 

\mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} to save the configuration afterwards and \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to finish affairs with the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em 1} & if the keys were retrieved successfully \\
\hline
{\em 0} & if there was no update -\/ no changes are made to the keyset then \\
\hline
{\em -\/1} & on failure -\/ no changes are made to the keyset then\\
\hline
\end{DoxyRetVals}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{kdb_8hpp}{kdb.hpp}}>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{keyio_8hpp}{keyio.hpp}}>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{using namespace }\mbox{\hyperlink{namespacekdb}{kdb}};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} ()}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KeySet}{KeySet}} config;}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB}{KDB}} \mbox{\hyperlink{namespacekdb}{kdb}};}
\DoxyCodeLine{        \mbox{\hyperlink{namespacekdb}{kdb}}.get (config, \textcolor{stringliteral}{"/sw/MyApp"});}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1Key}{Key}} k = config.\mbox{\hyperlink{classkdb_1_1KeySet_a78125fb19c6aebb0d8fc1a7238b78ace}{lookup}} (\textcolor{stringliteral}{"/sw/MyApp/mykey"});}
\DoxyCodeLine{        \textcolor{keywordflow}{if} (k)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                std::cout << k << \textcolor{stringliteral}{" is "} << k.\mbox{\hyperlink{classkdb_1_1Key_ac558a1f1b2cb50d77fbabcbb24950c05}{get}}<\textcolor{keywordtype}{int}> () << std::endl;}
\DoxyCodeLine{        \}}
\DoxyCodeLine{        \textcolor{keywordflow}{else}}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                std::cerr << \textcolor{stringliteral}{"No key found"} << std::endl;}
\DoxyCodeLine{                \textcolor{keywordflow}{return} 1;}
\DoxyCodeLine{        \}}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}



\begin{DoxyParams}{Parameters}
{\em returned} & the keyset where the keys will be in \\
\hline
{\em keyname} & the root keyname which should be used to get keys below it\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no key was updated \\
\hline
{\em 1} & if user or system keys were updated \\
\hline
{\em 2} & if user and system keys were updated\\
\hline
\end{DoxyRetVals}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if there were problems with the database\\
\hline
\end{DoxyExceptions}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{classkdb_1_1KDB_a0419ffbc273c89756bc523b4223ec25a}{K\+D\+B\+::get}} (\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \& returned, \mbox{\hyperlink{classkdb_1_1Key}{Key}} \& parent\+Key) 
\end{DoxySeeAlso}


Reimplemented in \mbox{\hyperlink{classkdb_1_1tools_1_1merging_1_1MergingKDB_a0d2a28f24aeb6ba3e81af73ef8b98df7}{kdb\+::tools\+::merging\+::\+Merging\+K\+DB}}.

\mbox{\Hypertarget{classkdb_1_1KDB_a48770a7290699bf2b7529f3ab67e378f}\label{classkdb_1_1KDB_a48770a7290699bf2b7529f3ab67e378f}} 
\index{kdb::KDB@{kdb::KDB}!get@{get}}
\index{get@{get}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{get()}{get()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily int kdb\+::\+K\+D\+B\+::get (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&}]{returned,  }\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{parent\+Key }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Get all keys below parent\+Key inside returned. 

Retrieve keys in an atomic and universal way. \begin{DoxyPrecond}{Precondition}
The {\ttfamily handle} must be passed as returned from \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} must be a valid \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}, e.\+g. constructed with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}}.

The {\ttfamily parent\+Key} \mbox{\hyperlink{classkdb_1_1Key}{Key}} must be a valid \mbox{\hyperlink{classkdb_1_1Key}{Key}}, e.\+g. constructed with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}.
\end{DoxyPrecond}
If you pass N\+U\+LL on any parameter \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will fail immediately without doing anything.

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} may already contain some keys, e.\+g. from previous \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} calls. The new retrieved keys will be appended using \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}.

If not done earlier \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will fully retrieve all keys under the {\ttfamily parent\+Key} folder recursively (See Optimization below when it will not be done).

\begin{DoxyNote}{Note}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} might retrieve more keys than requested (that are not below parent\+Key). These keys must be passed to calls of \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}, otherwise they will be lost. This stems from the fact that the user has the only copy of the whole configuration and backends only write configuration that was passed to them. For example, if you \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} \char`\"{}system/mountpoint/interest\char`\"{} you will not only get all keys below system/mountpoint/interest, but also all keys below system/mountpoint (if system/mountpoint is a mountpoint as the name suggests, but system/mountpoint/interest is not a mountpoint). Make sure to not touch or remove keys outside the keys of interest, because others may need them!
\end{DoxyNote}
\begin{DoxyParagraph}{Example\+:}
This example demonstrates the typical usecase within an application (without error handling).
\end{DoxyParagraph}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <kdb.h>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <stdio.h>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} \mbox{\hyperlink{testio__doc_8c_a3c04138a5bfe5d72780bb7e82a18e627}{main}} (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        KeySet * myConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{kdbenum_8c_a7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// for error handling see kdbget\_error.c}}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// clang-format off}}
\DoxyCodeLine{\textcolor{comment}{}Key * key = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/sw/tests/myapp/\#0/current/"},  \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * handle = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (key);}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, myConfig, key);}
\DoxyCodeLine{Key * result = \mbox{\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ksLookupByName}} (myConfig, \textcolor{stringliteral}{"/sw/tests/myapp/\#0/current/testkey1"}, 0);}
\DoxyCodeLine{        \textcolor{comment}{// clang-format on}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (key);}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_name = \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (result);}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_value = \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (result);}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} * key\_comment = \mbox{\hyperlink{group__keyvalue_ga880936f2481d28e6e2acbe7486a21d05}{keyString}} (\mbox{\hyperlink{group__keymeta_ga9ed3875495ddb3d8a8d29158a60a147c}{keyGetMeta}} (result, \textcolor{stringliteral}{"comment"}));}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"key: \%s value: \%s comment: \%s\(\backslash\)n"}, key\_name, key\_value, key\_comment);}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (myConfig); \textcolor{comment}{// delete the in-memory configuration}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// maybe you want kdbSet() myConfig here}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (handle, 0); \textcolor{comment}{// no more affairs with the key database.}}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}


When a backend fails \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} will return -\/1 with all error and warning information in the {\ttfamily parent\+Key}. The parameter {\ttfamily returned} will not be changed.

\begin{DoxyParagraph}{Optimization\+:}
In the first run of kdb\+Get all requested (or more) keys are retrieved. On subsequent calls only the keys are retrieved where something was changed inside the key database. The other keys stay in the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} returned as passed.
\end{DoxyParagraph}
It is your responsibility to save the original keyset if you need it afterwards.

If you want to be sure to get a fresh keyset again, you need to open a second handle to the key database using \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}}.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em parent\+Key} & is used to add warnings and set an error information. Additionally, its name is a hint which keys should be retrieved (it is possible that more are retrieved, see Note above).
\begin{DoxyItemize}
\item cascading keys (starting with /) will retrieve the same path in all namespaces
\item / will retrieve all keys 
\end{DoxyItemize}\\
\hline
{\em ks} & the (pre-\/initialized) \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} returned with all keys found will not be changed on error or if no update is required \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gaa34fc43a081e6b01e4120daa6c112004}{ks\+Lookup()}}, \mbox{\hyperlink{group__keyset_gad2e30fb6d4739d917c5abb2ac2f9c1a1}{ks\+Lookup\+By\+Name()}} for powerful lookups after the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} was retrieved 

\mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} which needs to be called before 

\mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} to save the configuration afterwards and \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to finish affairs with the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em 1} & if the keys were retrieved successfully \\
\hline
{\em 0} & if there was no update -\/ no changes are made to the keyset then \\
\hline
{\em -\/1} & on failure -\/ no changes are made to the keyset then\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em returned} & the keyset where the keys will be in \\
\hline
{\em parent\+Key} & the parent\+Key of returned\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no key was updated \\
\hline
{\em 1} & if user or system keys were updated \\
\hline
{\em 2} & if user and system keys were updated\\
\hline
\end{DoxyRetVals}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if there were problems with the database \\
\hline
\end{DoxyExceptions}


Reimplemented in \mbox{\hyperlink{classkdb_1_1tools_1_1merging_1_1MergingKDB_a062b1dac733aa3999691f8d70635b09c}{kdb\+::tools\+::merging\+::\+Merging\+K\+DB}}.

\mbox{\Hypertarget{classkdb_1_1KDB_aee37484b06164eacc0cc11b7b40ab892}\label{classkdb_1_1KDB_aee37484b06164eacc0cc11b7b40ab892}} 
\index{kdb::KDB@{kdb::KDB}!open@{open}}
\index{open@{open}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{open()}{open()}}
{\footnotesize\ttfamily void kdb\+::\+K\+D\+B\+::open (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{error\+Key }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Open the database. 


\begin{DoxyParams}{Parameters}
{\em error\+Key} & is useful if you want to get the warnings in the successful case, when no exception is thrown.\\
\hline
\end{DoxyParams}
Opens the session with the \mbox{\hyperlink{classkdb_1_1Key}{Key}} database. \begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}
The method will bootstrap itself the following way. The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} data structure will be initialized.

You must always call this method before retrieving or committing any keys to the database. In the end of the program, after using the key database, you must not forget to \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}}.

The pointer to the {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} structure returned will be initialized like described above, and it must be passed along on any kdb$\ast$() method your application calls.

Get a {\ttfamily \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}}} handle for every thread using elektra. Don\textquotesingle{}t share the handle across threads, and also not the pointer accessing it\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread1 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part1"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\DoxyCodeLine{\textcolor{keywordtype}{void} thread2 (\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * parent = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"/app/part2"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40afc1567f74444ff9c219f7456b652b4ec}{KEY\_CASCADING\_NAME}}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * h = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parent);}
\DoxyCodeLine{        \textcolor{comment}{// fetch keys and work with them}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (h, parent);}
\DoxyCodeLine{\}}
\end{DoxyCodeInclude}
 You don\textquotesingle{}t need \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} if you only want to manipulate plain in-\/memory \mbox{\hyperlink{classkdb_1_1Key}{Key}} or \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} objects.

\begin{DoxyPrecond}{Precondition}
error\+Key must be a valid key, e.\+g. created with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}
\end{DoxyPrecond}

\begin{DoxyParams}{Parameters}
{\em error\+Key} & the key which holds errors and warnings which were issued \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} to end all affairs to the \mbox{\hyperlink{group__key}{Key}} database. 
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em handle} & on success \\
\hline
{\em N\+U\+LL} & on failure \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{classkdb_1_1KDB_a29087a6a1a7de334f4e5b62ffe5d6e6e}\label{classkdb_1_1KDB_a29087a6a1a7de334f4e5b62ffe5d6e6e}} 
\index{kdb::KDB@{kdb::KDB}!set@{set}}
\index{set@{set}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{set()}{set()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily int kdb\+::\+K\+D\+B\+::set (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&}]{returned,  }\item[{std\+::string const \&}]{keyname }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Set all keys below keyname. 

If the keyname of the parent\+Key is invalid (e.\+g. empty) all keys will be set.

Set keys in an atomic and universal way. \begin{DoxyPrecond}{Precondition}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} must be called before \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}\+:
\begin{DoxyItemize}
\item initially (after \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}})
\item after conflict errors in \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}.
\end{DoxyItemize}

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} must be a valid \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}, e.\+g. constructed with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}}.

The {\ttfamily parent\+Key} \mbox{\hyperlink{classkdb_1_1Key}{Key}} must be a valid \mbox{\hyperlink{classkdb_1_1Key}{Key}}, e.\+g. constructed with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}.
\end{DoxyPrecond}
If you pass N\+U\+LL on any parameter \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} will fail immediately without doing anything.

With {\ttfamily parent\+Key} you can give an hint which part of the given keyset is of interest for you. Then you promise to only modify or remove keys below this key. All others would be passed back as they were retrieved by \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}.

\begin{DoxyParagraph}{Errors}
If some error occurs\+:
\begin{DoxyItemize}
\item \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} will leave the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}\textquotesingle{}s $\ast$ internal cursor on the key that generated the error.
\item Error information will be written into the metadata of the parent key.
\item None of the keys are actually committed in this situation, i.\+e. no configuration file will be modified.
\end{DoxyItemize}
\end{DoxyParagraph}
In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are\+:
\begin{DoxyItemize}
\item remove the problematic key and use \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} again (for validation or type errors)
\item change the value of the problematic key and use \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} again (for validation errors)
\item do a \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} (for conflicts, i.\+e. error C02000) and then
\begin{DoxyItemize}
\item set the same keyset again (in favour of what was set by this user)
\item drop the old keyset (in favour of what was set from another application)
\item merge the original, your own and the other keyset
\end{DoxyItemize}
\item export the configuration into a file (for unresolvable errors)
\item repeat the same kdb\+Set might be of limited use if the user does not explicitly request it, because temporary errors are rare and its unlikely that they fix themselves (e.\+g. disc full, permission problems)
\end{DoxyItemize}

\begin{DoxyParagraph}{Optimization}
Each key is checked with \mbox{\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\+Need\+Sync()}} before being actually committed. If no key of a backend needs to be synced any affairs to backends are omitted and 0 is returned.
\end{DoxyParagraph}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * myConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{kdbenum_8c_a7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{Key * parentKey = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"system/sw/MyApp"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * handle = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parentKey);}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, myConfig, parentKey); \textcolor{comment}{// kdbGet needs to be called first!}}
\DoxyCodeLine{KeySet * base = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (myConfig);     \textcolor{comment}{// save a copy of original keyset}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{// change the keys within myConfig}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (myConfig, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"system/sw/MyApp/Test"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"5"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{}
\DoxyCodeLine{KeySet * ours = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (myConfig); \textcolor{comment}{// save a copy of our keyset}}
\DoxyCodeLine{KeySet * theirs;                  \textcolor{comment}{// needed for 3-way merging}}
\DoxyCodeLine{\textcolor{keywordtype}{int} ret = \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}} (handle, myConfig, parentKey);}
\DoxyCodeLine{\textcolor{keywordflow}{while} (ret == -1) \textcolor{comment}{// as long as we have an error}}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{keywordtype}{int} strategy = showElektraErrorDialog (parentKey);}
\DoxyCodeLine{        theirs = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (ours);}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, theirs, parentKey); \textcolor{comment}{// refresh key database}}
\DoxyCodeLine{        KeySet * result = \mbox{\hyperlink{kdbmerge_8h_a5cb2bdc8c7e955afcd37c7fce5de6cf9}{elektraMerge}}(}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(ours, parentKey), parentKey,}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(theirs, parentKey), parentKey,}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(base, parentKey), parentKey,}
\DoxyCodeLine{                parentKey, strategy, parentKey);}
\DoxyCodeLine{        \textcolor{keywordtype}{int} numberOfConflicts = \mbox{\hyperlink{kdbmerge_8h_aeeff18da6e6459f72807bdd7d4767a55}{getConflicts}} (parentKey);}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (theirs);}
\DoxyCodeLine{        \textcolor{keywordflow}{if} (result != NULL) \{}
\DoxyCodeLine{                ret = \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}} (handle, result, parentKey);}
\DoxyCodeLine{        \} \textcolor{keywordflow}{else} \{}
\DoxyCodeLine{                \textcolor{comment}{// an error happened while merging}}
\DoxyCodeLine{                \textcolor{keywordflow}{if} (numberOfConflicts > 0 \&\& strategy == MERGE\_STRATEGY\_ABORT)}
\DoxyCodeLine{                \{}
\DoxyCodeLine{                        \textcolor{comment}{// Error due to merge conflicts}}
\DoxyCodeLine{                        ret = -1;}
\DoxyCodeLine{                \}}
\DoxyCodeLine{                \textcolor{keywordflow}{else}}
\DoxyCodeLine{                \{}
\DoxyCodeLine{                        \textcolor{comment}{// Internal errors, out of memory etc.}}
\DoxyCodeLine{                        ret = -1;}
\DoxyCodeLine{                \}}
\DoxyCodeLine{        \}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ours);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (base);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (myConfig); \textcolor{comment}{// delete the in-memory configuration}}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (handle, parentKey); \textcolor{comment}{// no more affairs with the key database.}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (parentKey);}
\end{DoxyCodeInclude}
 show\+Elektra\+Error\+Dialog() and do\+Elektra\+Merge() need to be implemented by the user of Elektra. For do\+Elektra\+Merge a 3-\/way merge algorithm exists in libelektra-\/tools.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em ks} & a \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} which should contain changed keys, otherwise nothing is done \\
\hline
{\em parent\+Key} & is used to add warnings and set an error information. Additionally, its name is an hint which keys should be committed (it is possible that more are changed).
\begin{DoxyItemize}
\item cascading keys (starting with /) will set the path in all namespaces
\item / will commit all keys
\item metanames will be rejected (error C01320)
\item empty/invalid (error C01320) 
\end{DoxyItemize}\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & if nothing had to be done, no changes in \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}} \\
\hline
{\em -\/1} & on failure, no changes in \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}} \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\+Need\+Sync()}} 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} contains the error \mbox{\hyperlink{group__key}{Key}} 

\mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} and \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} that must be called first 

\mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} that must be called afterwards
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no key was updated \\
\hline
{\em 1} & if user or system keys were updated \\
\hline
{\em 2} & if user and system keys were updated\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em returned} & the keyset where the keys will be in \\
\hline
{\em keyname} & the keyname below the names should be set\\
\hline
\end{DoxyParams}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if there were problems with the database \\
\hline
\end{DoxyExceptions}
\mbox{\Hypertarget{classkdb_1_1KDB_a62a4fafbe21d9519b31a7868aa05f3e3}\label{classkdb_1_1KDB_a62a4fafbe21d9519b31a7868aa05f3e3}} 
\index{kdb::KDB@{kdb::KDB}!set@{set}}
\index{set@{set}!kdb::KDB@{kdb::KDB}}
\subsubsection{\texorpdfstring{set()}{set()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily int kdb\+::\+K\+D\+B\+::set (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} \&}]{returned,  }\item[{\mbox{\hyperlink{classkdb_1_1Key}{Key}} \&}]{parent\+Key }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [virtual]}}



Set all keys below parent\+Key. 

If the keyname of the parent\+Key is invalid (e.\+g. empty) all keys will be set.

Set keys in an atomic and universal way. \begin{DoxyPrecond}{Precondition}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} must be called before \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}\+:
\begin{DoxyItemize}
\item initially (after \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}})
\item after conflict errors in \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}.
\end{DoxyItemize}

The {\ttfamily returned} \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} must be a valid \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}, e.\+g. constructed with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}}.

The {\ttfamily parent\+Key} \mbox{\hyperlink{classkdb_1_1Key}{Key}} must be a valid \mbox{\hyperlink{classkdb_1_1Key}{Key}}, e.\+g. constructed with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}.
\end{DoxyPrecond}
If you pass N\+U\+LL on any parameter \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} will fail immediately without doing anything.

With {\ttfamily parent\+Key} you can give an hint which part of the given keyset is of interest for you. Then you promise to only modify or remove keys below this key. All others would be passed back as they were retrieved by \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}.

\begin{DoxyParagraph}{Errors}
If some error occurs\+:
\begin{DoxyItemize}
\item \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} will leave the \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}}\textquotesingle{}s $\ast$ internal cursor on the key that generated the error.
\item Error information will be written into the metadata of the parent key.
\item None of the keys are actually committed in this situation, i.\+e. no configuration file will be modified.
\end{DoxyItemize}
\end{DoxyParagraph}
In case of errors you should present the error message to the user and let the user decide what to do. Possible solutions are\+:
\begin{DoxyItemize}
\item remove the problematic key and use \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} again (for validation or type errors)
\item change the value of the problematic key and use \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} again (for validation errors)
\item do a \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} (for conflicts, i.\+e. error C02000) and then
\begin{DoxyItemize}
\item set the same keyset again (in favour of what was set by this user)
\item drop the old keyset (in favour of what was set from another application)
\item merge the original, your own and the other keyset
\end{DoxyItemize}
\item export the configuration into a file (for unresolvable errors)
\item repeat the same kdb\+Set might be of limited use if the user does not explicitly request it, because temporary errors are rare and its unlikely that they fix themselves (e.\+g. disc full, permission problems)
\end{DoxyItemize}

\begin{DoxyParagraph}{Optimization}
Each key is checked with \mbox{\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\+Need\+Sync()}} before being actually committed. If no key of a backend needs to be synced any affairs to backends are omitted and 0 is returned.
\end{DoxyParagraph}

\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * myConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{kdbenum_8c_a7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{Key * parentKey = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"system/sw/MyApp"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{classkdb_1_1KDB_a7e0637995ce9f294cdbc6f167df6db40}{KDB}} * handle = \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdbOpen}} (parentKey);}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, myConfig, parentKey); \textcolor{comment}{// kdbGet needs to be called first!}}
\DoxyCodeLine{KeySet * base = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (myConfig);     \textcolor{comment}{// save a copy of original keyset}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{// change the keys within myConfig}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (myConfig, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"system/sw/MyApp/Test"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"5"}, \mbox{\hyperlink{group__key_gga91fb3178848bd682000958089abbaf40aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{}
\DoxyCodeLine{KeySet * ours = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (myConfig); \textcolor{comment}{// save a copy of our keyset}}
\DoxyCodeLine{KeySet * theirs;                  \textcolor{comment}{// needed for 3-way merging}}
\DoxyCodeLine{\textcolor{keywordtype}{int} ret = \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}} (handle, myConfig, parentKey);}
\DoxyCodeLine{\textcolor{keywordflow}{while} (ret == -1) \textcolor{comment}{// as long as we have an error}}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{keywordtype}{int} strategy = showElektraErrorDialog (parentKey);}
\DoxyCodeLine{        theirs = \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ksDup}} (ours);}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, theirs, parentKey); \textcolor{comment}{// refresh key database}}
\DoxyCodeLine{        KeySet * result = \mbox{\hyperlink{kdbmerge_8h_a5cb2bdc8c7e955afcd37c7fce5de6cf9}{elektraMerge}}(}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(ours, parentKey), parentKey,}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(theirs, parentKey), parentKey,}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}}(base, parentKey), parentKey,}
\DoxyCodeLine{                parentKey, strategy, parentKey);}
\DoxyCodeLine{        \textcolor{keywordtype}{int} numberOfConflicts = \mbox{\hyperlink{kdbmerge_8h_aeeff18da6e6459f72807bdd7d4767a55}{getConflicts}} (parentKey);}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (theirs);}
\DoxyCodeLine{        \textcolor{keywordflow}{if} (result != NULL) \{}
\DoxyCodeLine{                ret = \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}} (handle, result, parentKey);}
\DoxyCodeLine{        \} \textcolor{keywordflow}{else} \{}
\DoxyCodeLine{                \textcolor{comment}{// an error happened while merging}}
\DoxyCodeLine{                \textcolor{keywordflow}{if} (numberOfConflicts > 0 \&\& strategy == MERGE\_STRATEGY\_ABORT)}
\DoxyCodeLine{                \{}
\DoxyCodeLine{                        \textcolor{comment}{// Error due to merge conflicts}}
\DoxyCodeLine{                        ret = -1;}
\DoxyCodeLine{                \}}
\DoxyCodeLine{                \textcolor{keywordflow}{else}}
\DoxyCodeLine{                \{}
\DoxyCodeLine{                        \textcolor{comment}{// Internal errors, out of memory etc.}}
\DoxyCodeLine{                        ret = -1;}
\DoxyCodeLine{                \}}
\DoxyCodeLine{        \}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ours);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (base);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (myConfig); \textcolor{comment}{// delete the in-memory configuration}}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (handle, parentKey); \textcolor{comment}{// no more affairs with the key database.}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (parentKey);}
\end{DoxyCodeInclude}
 show\+Elektra\+Error\+Dialog() and do\+Elektra\+Merge() need to be implemented by the user of Elektra. For do\+Elektra\+Merge a 3-\/way merge algorithm exists in libelektra-\/tools.


\begin{DoxyParams}{Parameters}
{\em handle} & contains internal information of \mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{opened }} key database \\
\hline
{\em ks} & a \mbox{\hyperlink{classkdb_1_1KeySet}{Key\+Set}} which should contain changed keys, otherwise nothing is done \\
\hline
{\em parent\+Key} & is used to add warnings and set an error information. Additionally, its name is an hint which keys should be committed (it is possible that more are changed).
\begin{DoxyItemize}
\item cascading keys (starting with /) will set the path in all namespaces
\item / will commit all keys
\item metanames will be rejected (error C01320)
\item empty/invalid (error C01320) 
\end{DoxyItemize}\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & if nothing had to be done, no changes in \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}} \\
\hline
{\em -\/1} & on failure, no changes in \mbox{\hyperlink{classkdb_1_1KDB}{K\+DB}} \\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\+Need\+Sync()}} 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} contains the error \mbox{\hyperlink{group__key}{Key}} 

\mbox{\hyperlink{group__kdb_ga6808defe5870f328dd17910aacbdc6ca}{kdb\+Open()}} and \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} that must be called first 

\mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdb\+Close()}} that must be called afterwards
\end{DoxySeeAlso}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no key was updated \\
\hline
{\em 1} & if user or system keys were updated \\
\hline
{\em 2} & if user and system keys were updated\\
\hline
\end{DoxyRetVals}

\begin{DoxyParams}{Parameters}
{\em returned} & the keyset where the keys are passed to the user \\
\hline
{\em parent\+Key} & the parent\+Key of returned\\
\hline
\end{DoxyParams}

\begin{DoxyExceptions}{Exceptions}
{\em K\+D\+B\+Exception} & if there were problems with the database \\
\hline
\end{DoxyExceptions}


The documentation for this class was generated from the following file\+:\begin{DoxyCompactItemize}
\item 
\mbox{\hyperlink{kdb_8hpp}{kdb.\+hpp}}\end{DoxyCompactItemize}
