\label{doc_decisions_high_level_api_md_md_doc_decisions_high_level_api}%
\Hypertarget{doc_decisions_high_level_api_md_md_doc_decisions_high_level_api}%
 \hypertarget{doc_decisions_high_level_api_md_autotoc_md1932}{}\doxysection{Problem}\label{doc_decisions_high_level_api_md_autotoc_md1932}
Projects usually do not want to use low-\/level APIs. {\ttfamily KDB} and {\ttfamily Key\+Set} is useful for plugins and to implement APIs but not to be directly used in applications.\hypertarget{doc_decisions_high_level_api_md_autotoc_md1933}{}\doxysection{Constraints}\label{doc_decisions_high_level_api_md_autotoc_md1933}

\begin{DoxyEnumerate}
\item should be extremely easy to get started with
\item should be very hard to use it wrong
\item all high-\/level APIs should work together very nicely
\begin{DoxyItemize}
\item same principles
\item same API style
\item same error handling
\item can be arbitrarily intermixed
\end{DoxyItemize}
\end{DoxyEnumerate}\hypertarget{doc_decisions_high_level_api_md_autotoc_md1934}{}\doxysection{Assumptions}\label{doc_decisions_high_level_api_md_autotoc_md1934}

\begin{DoxyItemize}
\item Thread-\/safety\+: a handle is the accepted better solution than having to care about whether it is reentrant, thread-\/safe, ...
\item assumes that spec is available (either by compiled-\/in {\ttfamily Key\+Set} or exit after elektra\+Open)
\item many projects do not care about some limitations (no binary, no metadata) but prefer a straightforward way to get/set config
\item When people hit limitations they fall back to direct use of $^\wedge$\+Key\+Set$^\wedge$, $^\wedge$\+Key$^\wedge$
\end{DoxyItemize}\hypertarget{doc_decisions_high_level_api_md_autotoc_md1935}{}\doxysection{Considered Alternatives}\label{doc_decisions_high_level_api_md_autotoc_md1935}

\begin{DoxyItemize}
\item storing errors in the handle\+:
\begin{DoxyItemize}
\item Maintenance problem if error handling is added later
\end{DoxyItemize}
\item only provide {\ttfamily KDB}, applications need to implement their own APIs\+:
\begin{DoxyItemize}
\item reduces consistency of how the API is used
\end{DoxyItemize}
\item only provide generated API
\item assume type as {\ttfamily string} if not given
\item force {\ttfamily default} to be part of parameters
\end{DoxyItemize}\hypertarget{doc_decisions_high_level_api_md_autotoc_md1936}{}\doxysection{Decision}\label{doc_decisions_high_level_api_md_autotoc_md1936}
We provide 3 high-\/level C APIs\+:


\begin{DoxyEnumerate}
\item libelektra-\/highlevel (generic key-\/value getter/setter)
\item libelektra-\/hierarchy (generic hierarchical getter/setter in a tree)
\item code generator (specified key-\/value getter/setter with function names, Key\+Sets, or strings from specifications)
\end{DoxyEnumerate}

Furthermore, we will\+:


\begin{DoxyItemize}
\item have as goal that no errors in specified keys with default can occur
\item if you use {\ttfamily elektra\+Get\+Type} before getting a value, no error can occur when getting it later
\item enforce that every key has a type
\item use {\ttfamily elektra\+Error} as extra parameter (for prototyping and examples you can pass 0)
\end{DoxyItemize}\hypertarget{doc_decisions_high_level_api_md_autotoc_md1937}{}\doxysection{Rationale}\label{doc_decisions_high_level_api_md_autotoc_md1937}

\begin{DoxyEnumerate}
\item Very easy to get started with, to get a key needs 3 lines of codes (without error handling)\+:
\end{DoxyEnumerate}


\begin{DoxyCode}{0}
\DoxyCodeLine{Elektra *handle = \mbox{\hyperlink{group__highlevel_ga45de58b05c7a8ab02f6c54ddd31a56e1}{elektraOpen}} (\textcolor{stringliteral}{"{}/sw/elektra/kdb/\#0/current"{}}, 0);}
\DoxyCodeLine{printf (\textcolor{stringliteral}{"{}number /mykey is "{}} ELEKTRA\_LONG\_F \textcolor{stringliteral}{"{}\(\backslash\)n"{}}, \mbox{\hyperlink{group__highlevel_gad4198ec223f01c3a6cfb1b78de34bc9e}{elektraGetLong}} (handle, \textcolor{stringliteral}{"{}/mykey"{}}));}
\DoxyCodeLine{\mbox{\hyperlink{group__highlevel_ga9b688b7250e5f9d8ea6701cc2cc269af}{elektraClose}} (handle);}

\end{DoxyCode}



\begin{DoxyEnumerate}
\item It is also easier to get started with writing new bindings.
\item User can combine the different APIs.
\end{DoxyEnumerate}\hypertarget{doc_decisions_high_level_api_md_autotoc_md1938}{}\doxysection{Implications}\label{doc_decisions_high_level_api_md_autotoc_md1938}
\hypertarget{doc_decisions_high_level_api_md_autotoc_md1939}{}\doxysection{Related Decisions}\label{doc_decisions_high_level_api_md_autotoc_md1939}
\hypertarget{doc_decisions_high_level_api_md_autotoc_md1940}{}\doxysection{Notes}\label{doc_decisions_high_level_api_md_autotoc_md1940}
\href{https://issues.libelektra.org/1359}{\texttt{ https\+://issues.\+libelektra.\+org/1359}} 