KeyDB :: High Level methods

High level methods to access the Key database. More...

Functions

int kdbGetValue (KDBHandle handle, const char *keyname, char *returned, size_t maxSize)
 A high-level method to get a key value, by key name.
int kdbSetValue (KDBHandle handle, const char *keyname, const char *value)
 A high-level method to set a value to a key, by key name.
int kdbGetValueByParent (KDBHandle handle, const char *parentName, const char *baseName, char *returned, size_t maxSize)
 Fill up the returned buffer with the value of a key, which name is the concatenation of parentName and baseName.
int kdbSetValueByParent (KDBHandle handle, const char *parentName, const char *baseName, const char *value)
 Sets the provided value to the key whose name is the concatenation of parentName and baseName.
int kdbGetKeyByParent (KDBHandle handle, const char *parentName, const char *baseName, Key *returned)
 Given a parent key name plus a basename, returns the key.
int kdbGetKeyByParentKey (KDBHandle handle, const Key *parent, const char *baseName, Key *returned)
 Similar to previous, provided for convenience.
ssize_t kdbGetChildKeys (KDBHandle handle, const char *parentName, KeySet *returned, unsigned long options)
 This method is similar and calls kdbGetKeyChildKeys().
ssize_t kdbGetRootKeys (KDBHandle handle, KeySet *returned)
 Returns a KeySet with all root keys currently recognized and present on the system.
int kdbRemove (KDBHandle handle, const char *keyName)
 Remove a key by its name from the backend storage.

Detailed Description

High level methods to access the Key database.

To use them:

 #include <kdb.h>

These methods are higher level. They use the above methods to do their job, and don't have to be reimplemented for a different backend.

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.


Function Documentation

int kdbGetValue ( KDBHandle  handle,
const char *  keyname,
char *  returned,
size_t  maxSize 
)

A high-level method to get a key value, by key name.

This method is valid only for string keys. You have to use other methods to get non-string keys.

Parameters:
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 and errno is propagated

See also:
kdbSetValue(), kdbGetKey(), kdbGetValueByParent(), keyGetString()

Definition at line 114 of file kdbhighlevel.c.

References kdbGetKey(), KEY_SWITCH_END, keyDel(), keyGetString(), and keyNew().

Referenced by kdbGetValueByParent().

int kdbSetValue ( KDBHandle  handle,
const char *  keyname,
const char *  value 
)

A high-level method to set a value to a key, by key name.

It will obviously check if key exists first, and keep its metadata. So you'll not loose the precious key comment.

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

Parameters:
keyname the name of the key to receive the value
value the value to be set
Returns:
0 on success

-1 on failure and errno is propagated KDB_RET_TYPEMISMATCH if key is a directory

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

Definition at line 145 of file kdbhighlevel.c.

References KDB_RET_TYPEMISMATCH, kdbGetKey(), kdbSetKey(), KEY_SWITCH_END, keyDel(), keyIsDir(), keyNew(), and keySetString().

Referenced by kdbSetValueByParent().

int kdbGetValueByParent ( KDBHandle  handle,
const char *  parentName,
const char *  baseName,
char *  returned,
size_t  maxSize 
)

Fill up the returned buffer with the value of a key, which name is the concatenation of parentName and baseName.

Example:
char *parent="user/sw/MyApp";
char *keys[]={"key1","key2","key3"};
char buffer[150];   // a big buffer
int c;

for (c=0; c<3; c++) {
    kdbGetValueByParent(handle,parent,keys[c],buffer,sizeof(buffer));
    // Do something with buffer....
}
Parameters:
parentName the name of the parent key
baseName the name of the child key
returned pre-allocated buffer to be filled with key value
maxSize size of the returned buffer
Returns:
0 on success

-1 on failure and errno is propagated

See also:
kdbGetKeyByParent()

Definition at line 193 of file kdbhighlevel.c.

References kdbGetValue(), _KDBBackend::name, and strblen().

int kdbSetValueByParent ( KDBHandle  handle,
const char *  parentName,
const char *  baseName,
const char *  value 
)

Sets the provided value to the key whose name is the concatenation of parentName and baseName.

Parameters:
parentName the name of the parent key
baseName the name of the child key
value the value to set
Returns:
0 on success

-1 on failure and errno is propagated

Definition at line 217 of file kdbhighlevel.c.

References kdbSetValue(), _KDBBackend::name, and strblen().

int kdbGetKeyByParent ( KDBHandle  handle,
const char *  parentName,
const char *  baseName,
Key returned 
)

Given a parent key name plus a basename, returns the key.

So here you'll provide something like

Parameters:
parentName parent key name
baseName leaf or child name
returned a pointer to an initialized key to be filled
Returns:
0 on success

-1 on failure and errno is propagated

See also:
kdbGetKey(), kdbGetValueByParent(), kdbGetKeyByParentKey()

Definition at line 245 of file kdbhighlevel.c.

References kdbGetKey(), keySetName(), _KDBBackend::name, and strblen().

int kdbGetKeyByParentKey ( KDBHandle  handle,
const Key parent,
const char *  baseName,
Key returned 
)

Similar to previous, provided for convenience.

Parameters:
parent pointer to the parent key
See also:
kdbGetKey(), kdbGetKeyByParent(), kdbGetValueByParent()
Returns:
0 on success, or what kdbGetKey() returns, and errno is set

Definition at line 263 of file kdbhighlevel.c.

References kdbGetKey(), keyGetFullName(), keyGetFullNameSize(), keySetName(), _KDBBackend::name, and strblen().

ssize_t kdbGetChildKeys ( KDBHandle  handle,
const char *  parentName,
KeySet returned,
unsigned long  options 
)

This method is similar and calls kdbGetKeyChildKeys().

It is provided for convenience.

Instead of passing the parentName with a key it directly uses a string.

Returns:
0 on success

-1 on failure and errno is propagated from kdbGetKeyChildKeys()

See also:
kdbGetKeyChildKeys()

Definition at line 290 of file kdbhighlevel.c.

References kdbGetKeyChildKeys(), KEY_SWITCH_END, keyDel(), and keyNew().

Referenced by commandEdit(), and commandList().

ssize_t kdbGetRootKeys ( KDBHandle  handle,
KeySet returned 
)

Returns a KeySet with all root keys currently recognized and present on the system.

Currently, the system and current user's user keys are returned.

Parameters:
returned the initialized KeySet to be filled
Returns:
the number of root keys found

-1 on failure and errno is propagated

See also:
KeyNamespace

commandList() code in KeyDB :: Class Methods command for usage example

Definition at line 318 of file kdbhighlevel.c.

References _Key::flags, KEY_SWITCH_END, KEY_SWITCH_FLAG, KEY_SWITCH_NEEDSYNC, keyDel(), keyNew(), ksInsert(), and _KeySet::size.

Referenced by commandList().

int kdbRemove ( KDBHandle  handle,
const char *  keyName 
)

Remove a key by its name from the backend storage.

This is a convenience to kdbRemoveKey().

Parameters:
keyName the name of the key to be removed
Returns:
0 on success

-1 on failure and errno is propagated

See also:
commandRemove() code in KeyDB :: Class Methods command for usage example

Definition at line 350 of file kdbhighlevel.c.

References kdbRemoveKey(), KEY_SWITCH_END, keyDel(), keyNew(), and keySetName().

Referenced by commandEdit(), and commandRemove().


Generated on Tue Sep 11 10:38:54 2007 for Elektra Project by  doxygen 1.5.2