<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Elektra Projekt: KDB :: High Level methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>KDB :: High Level methods</h1>
<p>High level methods to access the Key database.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey</a> (KDB *handle, Key *dest)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey</a> (KDB *handle, const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#ga1e1b1a2beace8c9ce93d16259564b51f">kdbGetString</a> (KDB *handle, const char *keyname, char *returned, size_t maxSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#ga8e11b3403c9616c7fb3b9b37d1cb849e">kdbSetString</a> (KDB *handle, const char *keyname, const char *value)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#gaf9adbbeb3f49c63fb2f89930445c8060">kdbRemove</a> (KDB *handle, const char *keyname)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName</a> (KDB *handle, KeySet *returned, const char *name, option_t options)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>High level methods to access the Key database. </p>
<p>To use them: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <kdb.h></span>
</pre></div><p>These methods are higher level. They use <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">kdbOpen()</a>, <a class="el" href="group__kdb.html#gad9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a>, <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> methods to do their job, and don't have to be reimplemented for a different backend.</p>
<p>These functions avoid limitations through not implemented capabilities. This will of course cost some effort, so read through the description carefully and decide if it is appropriate for your problem.</p>
<p>Binding writers don't have to implement these functions, use features of the binding language instead. But you can use these functions as ideas what high level methods may be useful.</p>
<p>Don't use writing single keys in a loop, prefer always writing out a keyset! </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga3013d5768bbcf3c34652f489151940e2"></a><!-- doxytag: member="kdbhighlevel.c::kdbGetByName" ref="ga3013d5768bbcf3c34652f489151940e2" args="(KDB *handle, KeySet *returned, const char *name, option_t options)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbGetByName </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>returned</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">option_t </td>
<td class="paramname"> <em>options</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This method is similar <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> but the path is given by a string.</p>
<p>When it is not possible to make a key out of that string -1 is returned .</p>
<p>When parentName starts with / cascading will be used and both keys from user and system will be fetched.</p>
<p>A typically app with about 3000 keys may have this line:</p>
<div class="fragment"><pre class="fragment">KDB *handle = <a class="code" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">kdbOpen</a>();
KeySet *myConfig = (4096, KS_END);
ssize_t ret = <a class="code" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName</a> (handle, myConfig, <span class="stringliteral">"/sw/app/current"</span>, 0);
<span class="comment">// check ret and work with keyset myConfig</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (myConfig);
<a class="code" href="group__kdb.html#gad9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a> (handle);
*
</pre></div><p>myConfig will be loaded with keys from system/sw/app/current but also user/sw/app/current.</p>
<p>When one of these <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> fails -1 will be returned, but the other <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> will be tried too.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>the name where to get the keys below </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>the (pre-initialized) KeySet returned with all keys found </td></tr>
<tr><td valign="top"></td><td valign="top"><em>options</em> </td><td>ORed options to control approaches Unlike to <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> is KDB_O_POP set per default. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>number of keys contained by <code>returned</code> </dd>
<dd>
-1 on failure </dd>
<dd>
-1 when <code>name</code> is no valid key </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaa62877888f0cad395898859395e6635f"></a><!-- doxytag: member="kdbhighlevel.c::kdbGetKey" ref="gaa62877888f0cad395898859395e6635f" args="(KDB *handle, Key *dest)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbGetKey </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>dest</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Fully retrieves the passed <code>key</code> from the backend storage.</p>
<p>The backend will try to get the key, identified through its name.</p>
<p>It uses <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> for retrieving the key and copies the found data to dest.</p>
<p>While <a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a> is perfect for a simple get of a specific key, <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> gives you more control over the keyset.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>a pointer to a Key that has a name set </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey()</a> to set a single <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> </dd>
<dd>
commandGet() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example </dd>
<dd>
<a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> to have more control over <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> and options </dd></dl>
</div>
</div>
<a class="anchor" id="ga1e1b1a2beace8c9ce93d16259564b51f"></a><!-- doxytag: member="kdbhighlevel.c::kdbGetString" ref="ga1e1b1a2beace8c9ce93d16259564b51f" args="(KDB *handle, const char *keyname, char *returned, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbGetString </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>keyname</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>returned</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>maxSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A high-level method to get a key value, by key name.</p>
<p>This method gets a backend from any backend with <a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a> and extracts the string and store it into returned. It only works with string keys.</p>
<p>This method gives you the direct relation between a keyname and the value, without any kdb specific structures. Use it when you just want some values out of the kdb namespace.</p>
<p>You need to know the maximum string length of the object. That could be the case when you e.g. save a path which is limited with MAX_PATH.</p>
<div class="fragment"><pre class="fragment">KDB *handle = <a class="code" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">kdbOpen</a>();
<span class="keywordtype">char</span> buffer [MAX_PATH];
<span class="keywordflow">if</span> (<a class="code" href="group__kdbhighlevel.html#ga1e1b1a2beace8c9ce93d16259564b51f">kdbGetString</a>(handle, <span class="stringliteral">"user/key/to/get/pathname"</span>, buffer, <span class="keyword">sizeof</span>(buffer)) == -1)
{
<span class="comment">// handle error cases</span>
} <span class="keywordflow">else</span> {
printf (<span class="stringliteral">"The keys value is %s\n"</span>, buffer);
}
<a class="code" href="group__kdb.html#gad9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a>(handle);
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>keyname</em> </td><td>the name of the key to receive the value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>a buffer to put the key value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>the size of the buffer </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure </dd>
<dd>
-1 on NULL pointers </dd>
<dd>
-1 if maxSize is 0 or larger than SSIZE_MAX </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdbhighlevel.html#ga8e11b3403c9616c7fb3b9b37d1cb849e">kdbSetString()</a> and <a class="el" href="group__kdbhighlevel.html#gaf9adbbeb3f49c63fb2f89930445c8060">kdbRemove()</a> to set and remove a string </dd>
<dd>
<a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a>, keySetKey() to work with Keys </dd>
<dd>
<a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> for full access to <a class="el" href="group__internal.html" title="Internal Methods for Elektra and Backends.">KDB Backends :: Internal Helper for Elektra</a> datastructures </dd></dl>
</div>
</div>
<a class="anchor" id="gaf9adbbeb3f49c63fb2f89930445c8060"></a><!-- doxytag: member="kdbhighlevel.c::kdbRemove" ref="gaf9adbbeb3f49c63fb2f89930445c8060" args="(KDB *handle, const char *keyname)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbRemove </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>keyname</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Remove a key by its name from the backend storage.</p>
<p>With <a class="el" href="group__kdbhighlevel.html#ga8e11b3403c9616c7fb3b9b37d1cb849e">kdbSetString()</a> its only possible to set a key with an empty string. To really remove a key in a highlevel way you can use this method.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>keyname</em> </td><td>the name of the key to be removed </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure </dd>
<dd>
-1 on NULL pointers </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd>together with <a class="el" href="group__kdbhighlevel.html#ga8e11b3403c9616c7fb3b9b37d1cb849e">kdbSetString()</a> and <a class="el" href="group__kdbhighlevel.html#ga1e1b1a2beace8c9ce93d16259564b51f">kdbGetString()</a> a highlevel interface for <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> </dd>
<dd>
commandRemove() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example </dd></dl>
</div>
</div>
<a class="anchor" id="ga23b2f5fead4cddeb5542051a197ddc20"></a><!-- doxytag: member="kdbhighlevel.c::kdbSetKey" ref="ga23b2f5fead4cddeb5542051a197ddc20" args="(KDB *handle, const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbSetKey </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Sets <code>key</code> in the backend storage.</p>
<p>While <a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey()</a> is perfect for a simple get of a specific key, <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> gives you more control over the keyset.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>Key to set </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a> to get a single <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> </dd>
<dd>
<a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> for more control over <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> and options </dd>
<dd>
commandSet() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example </dd></dl>
</div>
</div>
<a class="anchor" id="ga8e11b3403c9616c7fb3b9b37d1cb849e"></a><!-- doxytag: member="kdbhighlevel.c::kdbSetString" ref="ga8e11b3403c9616c7fb3b9b37d1cb849e" args="(KDB *handle, const char *keyname, const char *value)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbSetString </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>keyname</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>value</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A high-level method to set a value to a key, by key name.</p>
<p>It will check if key exists first, and keep its metadata. So you'll not loose the previous key comment.</p>
<p>This will set a text key. So if the key was previously a binary it will be retyped as string.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>contains internal information of <a class="el" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
<tr><td valign="top"></td><td valign="top"><em>keyname</em> </td><td>the name of the key to receive the value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>value</em> </td><td>the value to be set </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL pointers </dd>
<dd>
-1 on failure </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdbhighlevel.html#ga1e1b1a2beace8c9ce93d16259564b51f">kdbGetString()</a>, <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a>, <a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey()</a> </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
