.TH "KDB :: High Level methods" 3 "Fri Aug 26 2011" "Elektra Projekt" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KDB :: High Level methods \- 
.PP
High level methods to access the Key database.  

.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBkdbGetKey\fP (KDB *handle, Key *dest)"
.br
.ti -1c
.RI "int \fBkdbSetKey\fP (KDB *handle, const Key *key)"
.br
.ti -1c
.RI "int \fBkdbGetString\fP (KDB *handle, const char *keyname, char *returned, size_t maxSize)"
.br
.ti -1c
.RI "int \fBkdbSetString\fP (KDB *handle, const char *keyname, const char *value)"
.br
.ti -1c
.RI "int \fBkdbRemove\fP (KDB *handle, const char *keyname)"
.br
.ti -1c
.RI "ssize_t \fBkdbGetByName\fP (KDB *handle, KeySet *returned, const char *name, option_t options)"
.br
.in -1c
.SH "Detailed Description"
.PP 
High level methods to access the Key database. 

To use them: 
.PP
.nf
 #include <kdb.h>

.fi
.PP
.PP
These methods are higher level. They use \fBkdbOpen()\fP, \fBkdbClose()\fP, \fBkdbGet()\fP and \fBkdbSet()\fP methods to do their job, and don't have to be reimplemented for a different backend.
.PP
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.
.PP
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.
.PP
Don't use writing single keys in a loop, prefer always writing out a keyset! 
.SH "Function Documentation"
.PP 
.SS "ssize_t kdbGetByName (KDB *handle, KeySet *returned, const char *name, option_toptions)"This method is similar \fBkdbGet()\fP but the path is given by a string.
.PP
When it is not possible to make a key out of that string -1 is returned .
.PP
When parentName starts with / cascading will be used and both keys from user and system will be fetched.
.PP
A typically app with about 3000 keys may have this line:
.PP
.PP
.nf
KDB *handle = kdbOpen();
KeySet *myConfig = (4096, KS_END);
ssize_t ret = kdbGetByName (handle, myConfig, '/sw/app/current', 0);

// check ret and work with keyset myConfig

ksDel (myConfig);
kdbClose (handle);
 *
.fi
.PP
.PP
myConfig will be loaded with keys from system/sw/app/current but also user/sw/app/current.
.PP
When one of these \fBkdbGet()\fP fails -1 will be returned, but the other \fBkdbGet()\fP will be tried too.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIname\fP the name where to get the keys below 
.br
\fIreturned\fP the (pre-initialized) KeySet returned with all keys found 
.br
\fIoptions\fP ORed options to control approaches Unlike to \fBkdbGet()\fP is KDB_O_POP set per default. 
.RE
.PP
\fBReturns:\fP
.RS 4
number of keys contained by \fCreturned\fP 
.PP
-1 on failure 
.PP
-1 when \fCname\fP is no valid key 
.PP
-1 on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkdbGet()\fP 
.RE
.PP

.SS "int kdbGetKey (KDB *handle, Key *dest)"Fully retrieves the passed \fCkey\fP from the backend storage.
.PP
The backend will try to get the key, identified through its name.
.PP
It uses \fBkdbGet()\fP for retrieving the key and copies the found data to dest.
.PP
While \fBkdbGetKey()\fP is perfect for a simple get of a specific key, \fBkdbGet()\fP and \fBkdbGetByName()\fP gives you more control over the keyset.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIdest\fP a pointer to a Key that has a name set 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success 
.PP
-1 on failure 
.PP
-1 on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkdbSetKey()\fP to set a single \fBKey :: Basic Methods\fP 
.PP
commandGet() code in \fBKDB :: Low Level Methods\fP command for usage example 
.PP
\fBkdbGet()\fP and \fBkdbGetByName()\fP to have more control over \fBKeySet :: Class Methods\fP and options 
.RE
.PP

.SS "int kdbGetString (KDB *handle, const char *keyname, char *returned, size_tmaxSize)"A high-level method to get a key value, by key name.
.PP
This method gets a backend from any backend with \fBkdbGetKey()\fP and extracts the string and store it into returned. It only works with string keys.
.PP
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.
.PP
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.
.PP
.PP
.nf
KDB *handle = kdbOpen();
char buffer [MAX_PATH];

if (kdbGetString(handle, 'user/key/to/get/pathname', buffer, sizeof(buffer)) == -1)
{
        // handle error cases
} else {
        printf ('The keys value is %s\n', buffer);
}
kdbClose(handle);
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIkeyname\fP the name of the key to receive the value 
.br
\fIreturned\fP a buffer to put the key value 
.br
\fImaxSize\fP the size of the buffer 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success 
.PP
-1 on failure 
.PP
-1 on NULL pointers 
.PP
-1 if maxSize is 0 or larger than SSIZE_MAX 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkdbSetString()\fP and \fBkdbRemove()\fP to set and remove a string 
.PP
\fBkdbGetKey()\fP, keySetKey() to work with Keys 
.PP
\fBkdbGet()\fP and \fBkdbGetByName()\fP for full access to \fBKDB Backends :: Internal Helper for Elektra\fP datastructures 
.RE
.PP

.SS "int kdbRemove (KDB *handle, const char *keyname)"Remove a key by its name from the backend storage.
.PP
With \fBkdbSetString()\fP 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.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIkeyname\fP the name of the key to be removed 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success 
.PP
-1 on failure 
.PP
-1 on NULL pointers 
.RE
.PP
\fBSee also:\fP
.RS 4
together with \fBkdbSetString()\fP and \fBkdbGetString()\fP a highlevel interface for \fBKDB :: Low Level Methods\fP 
.PP
commandRemove() code in \fBKDB :: Low Level Methods\fP command for usage example 
.RE
.PP

.SS "int kdbSetKey (KDB *handle, const Key *key)"Sets \fCkey\fP in the backend storage.
.PP
While \fBkdbSetKey()\fP is perfect for a simple get of a specific key, \fBkdbGet()\fP and \fBkdbGetByName()\fP gives you more control over the keyset.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIkey\fP Key to set 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success 
.PP
-1 on failure 
.PP
-1 on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkdbGetKey()\fP to get a single \fBKey :: Basic Methods\fP 
.PP
\fBkdbSet()\fP for more control over \fBKeySet :: Class Methods\fP and options 
.PP
commandSet() code in \fBKDB :: Low Level Methods\fP command for usage example 
.RE
.PP

.SS "int kdbSetString (KDB *handle, const char *keyname, const char *value)"A high-level method to set a value to a key, by key name.
.PP
It will check if key exists first, and keep its metadata. So you'll not loose the previous key comment.
.PP
This will set a text key. So if the key was previously a binary it will be retyped as string.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP contains internal information of \fBopened \fP key database 
.br
\fIkeyname\fP the name of the key to receive the value 
.br
\fIvalue\fP the value to be set 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success 
.PP
-1 on NULL pointers 
.PP
-1 on failure 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkdbGetString()\fP, \fBkeySetString()\fP, \fBkdbSetKey()\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Elektra Projekt from the source code.