KDB 
:: High Level methods(3)				     Library Functions Manual				      KDB :: High Level methods(3)

NAME

       KDB :: High Level methods -

       High level methods to access the Key database.

   Functions
       int kdbGetKey (KDB *handle, Key *dest)
       int kdbSetKey (KDB *handle, const Key *key)
       int kdbGetString (KDB *handle, const char *keyname, char *returned, size_t maxSize)
       int kdbSetString (KDB *handle, const char *keyname, const char *value)
       int kdbRemove (KDB *handle, const char *keyname)
       ssize_t kdbGetByName (KDB *handle, KeySet *returned, const char *name, option_t options)

Detailed Description
       High level methods to access the Key database.

       To use them:

	#include <kdb.h>

       These methods are higher level. They use kdbOpen(), kdbClose(), kdbGet() and kdbSet() methods to do their job, and don't have to be
       reimplemented for a different backend.

       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.

       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.

       Don't use writing single keys in a loop, prefer always writing out a keyset!

Function Documentation
   ssize_t kdbGetByName (KDB *handle, KeySet *returned, const char *name, option_toptions) This method is similar kdbGet() but the path is given
       by a string.
       When it is not possible to make a key out of that string -1 is returned .

       When parentName starts with / cascading will be used and both keys from user and system will be fetched.

       A typically app with about 3000 keys may have this line:

       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);
	*

       myConfig will be loaded with keys from system/sw/app/current but also user/sw/app/current.

       When one of these kdbGet() fails -1 will be returned, but the other kdbGet() will be tried too.

       Parameters:
	   handle contains internal information of opened  key database
	   name the name where to get the keys below
	   returned the (pre-initialized) KeySet returned with all keys found
	   options ORed options to control approaches Unlike to kdbGet() is KDB_O_POP set per default.

       Returns:
	   number of keys contained by returned

	   -1 on failure

	   -1 when name is no valid key

	   -1 on NULL pointer

       See also:
	   kdbGet()

   int kdbGetKey (KDB *handle, Key *dest) Fully retrieves the passed key from the backend storage.
       The backend will try to get the key, identified through its name.

       It uses kdbGet() for retrieving the key and copies the found data to dest.

       While kdbGetKey() is perfect for a simple get of a specific key, kdbGet() and kdbGetByName() gives you more control over the keyset.

       Parameters:
	   handle contains internal information of opened  key database
	   dest a pointer to a Key that has a name set

       Returns:
	   0 on success

	   -1 on failure

	   -1 on NULL pointer

       See also:
	   kdbSetKey() to set a single Key :: Basic Methods

	   commandGet() code in KDB :: Low Level Methods command for usage example

	   kdbGet() and kdbGetByName() to have more control over KeySet :: Class Methods and options

   int kdbGetString (KDB *handle, const char *keyname, char *returned, size_tmaxSize) A high-level method to get a key value, by key name.
       This method gets a backend from any backend with kdbGetKey() and extracts the string and store it into returned. It only works with string
       keys.

       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.

       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.

       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 %s0, buffer);
       }
       kdbClose(handle);

       Parameters:
	   handle contains internal information of opened  key database
	   keyname the name of the key to receive the value
	   returned a buffer to put the key value
	   maxSize the size of the buffer

       Returns:
	   0 on success

	   -1 on failure

	   -1 on NULL pointers

	   -1 if maxSize is 0 or larger than SSIZE_MAX

       See also:
	   kdbSetString() and kdbRemove() to set and remove a string

	   kdbGetKey(), keySetKey() to work with Keys

	   kdbGet() and kdbGetByName() for full access to KDB Backends :: Internal Helper for Elektra datastructures

   int kdbRemove (KDB *handle, const char *keyname) Remove a key by its name from the backend storage.
       With kdbSetString() 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.

       Parameters:
	   handle contains internal information of opened  key database
	   keyname the name of the key to be removed

       Returns:
	   0 on success

	   -1 on failure

	   -1 on NULL pointers

       See also:
	   together with kdbSetString() and kdbGetString() a highlevel interface for KDB :: Low Level Methods

	   commandRemove() code in KDB :: Low Level Methods command for usage example

   int kdbSetKey (KDB *handle, const Key *key) Sets key in the backend storage.
       While kdbSetKey() is perfect for a simple get of a specific key, kdbGet() and kdbGetByName() gives you more control over the keyset.

       Parameters:
	   handle contains internal information of opened  key database
	   key Key to set

       Returns:
	   0 on success

	   -1 on failure

	   -1 on NULL pointer

       See also:
	   kdbGetKey() to get a single Key :: Basic Methods

	   kdbSet() for more control over KeySet :: Class Methods and options

	   commandSet() code in KDB :: Low Level Methods command for usage example

   int kdbSetString (KDB *handle, const char *keyname, const char *value) A high-level method to set a value to a key, by key name.
       It will check if key exists first, and keep its metadata. So you'll not loose the previous key comment.

       This will set a text key. So if the key was previously a binary it will be retyped as string.

       Parameters:
	   handle contains internal information of opened  key database
	   keyname the name of the key to receive the value
	   value the value to be set

       Returns:
	   0 on success

	   -1 on NULL pointers

	   -1 on failure

       See also:
	   kdbGetString(), keySetString(), kdbSetKey()

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

Elektra Projekt 						  Fri Aug 26 2011				      KDB :: High Level methods(3)