Key :: Value Manipulation Methods

Methods to do various operations on Key values. More...

Functions
ssize_t	keyGetDataSize (const Key *key)
	An alias to keyGetValueSize().
ssize_t	keyGetValueSize (const Key *key)
	Returns the number of bytes needed to store the key value, including the NULL terminator.
ssize_t	keySetString (Key *key, const char *newStringValue)
	Set the value for key as newStringValue.
ssize_t	keyGetString (const Key *key, char *returnedString, size_t maxSize)
	Get the value of a key as a string.
void *	keyStealValue (const Key *key)
	Return a pointer to the real internal key value.
ssize_t	keySetLink (Key *key, const char *target)
	Set key as type KeyType::KEY_TYPE_LINK with target target.
ssize_t	keyGetLink (const Key *key, char *returnedTarget, size_t maxSize)
	Get the target key pointed by key.
ssize_t	keyGetBinary (const Key *key, void *returnedValue, size_t maxSize)
	Get the binary or string value of key.
ssize_t	keySetBinary (Key *key, const void *newBinary, size_t dataSize)
	Set the value of a key as a binary.
uint8_t	keyGetType (const Key *key)
	Returns the key data type.
uint8_t	keySetType (Key *key, uint8_t newType)
	Force a key type.
ssize_t	keySetRaw (Key *key, const void *newBinary, size_t dataSize)
	Set raw data as the value of a key.

---

Detailed Description

Methods to do various operations on Key values.

A key can contain a value in different format. The most likely situation is, that the value is interpreted as text. Use keyGetString() for that. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current Environment.

In some situations this idea fails. When you need exactly the same value back without any interpretation of the characters, there is keySetBinary(). If you use that, its very likely that your Configuration is not according to the standard. Also for Numbers, Booleans and Date you should use keyGetString(). To do so, you might use strtod() strtol() and then atol() or atof() to convert back.

A key may also be just a Link. Here you will also find the manipulation methods for keyGetLink().

To use them:

#include <kdb.h>

---

Function Documentation

ssize_t keyGetValueSize (  const Key *  key  )

Returns the number of bytes needed to store the key value, including the NULL terminator. This method is used with malloc() before a keyGetString() or keyGetBinary(). Returns: the number of bytes needed to store the key value See also: keyGetString(), keyGetBinary(), keyStealValue() Definition at line 1398 of file key.c. References _Key::dataSize. Referenced by commandGet(), and keyGetDataSize().

ssize_t keySetString (  Key *  key, const char *  newStringValue )

Set the value for key as newStringValue. The function will allocate and save a private copy of newStringValue, so the parameter can be freed after the call. String values will be saved in backend storage, when kdbSetKey() will be called, in UTF-8 universal encoding,regardeless of the program's current encoding. Parameters: key  the key to set the string value newStringValue  NULL-terminated text string to be set as key's value Returns: the number of bytes actually saved in private struct including final NULL See also: keyGetString(), keyStealValue() Definition at line 1426 of file key.c. References KEY_TYPE_STRING, keySetRaw(), keySetType(), and strblen(). Referenced by commandSet(), kdbSetValue(), and keyNew().

ssize_t keyGetString (  const Key *  key, char *  returnedString, size_t  maxSize )

Get the value of a key as a string. If the value can't be represented as a text string (binary value, see keyIsBin()), errno is set to KDBErr::KDB_RET_TYPEMISMATCH. Example: Key *key; char buffer[300]; // populate key somehow... if (keyIsBin(key)) keyGetBinary(key,buffer,sizeof(buffer)); else keyGetString(key,buffer,sizeof(buffer)); Parameters: key  the object to gather the value returnedString  pre-allocated memory to store a copy of the key value maxSize  number of bytes of pre-allocated memory in returnedString Returns: the number of bytes actually copied to returnedString, including final NULL See also: keyStealValue(), keySetString(), keyGetBinary() Definition at line 1463 of file key.c. References _Key::data, _Key::dataSize, and _Key::type. Referenced by commandGet(), and kdbGetValue().

void* keyStealValue (  const Key *  key  )

Return a pointer to the real internal key value. This is a much more efficient version of keyGetString(), keyGetLink(), keyGetBinary(), and you should use it if you are responsible enough to not mess up things. If key is not binary (keyIsBin()), you may cast the returned as a "char *" because you'll get a NULL terminated regular string. If it is binary, the size of the value can be determined by keyGetValueSize(). Note that the Key structure also has as data size field that is calculated by library internal calls to keySetRaw(), so to avoid inconsistencies, you must never used the pointer returned by keyStealValue() method to set a new value. Use keySetString(), keySetBinary(), keySetLink(), keySetRaw() instead. Example: KeySet *ks=ksNew(); Key *current=0; kdbGetChildKeys("system/sw/my",ks,KDB_O_SORT|KDB_O_RECURSIVE); ksRewind(ks); while(current=ksNext(ks)) { size_t size=0; if (keyIsBin(current)) { size=keyGetValueSize(current); printf("Key %s has a value of size %d bytes. Value: <BINARY>\nComment: %s", keyStealName(current), size, keyStealComment(current)); } else { size=strblen((char *)keyStealValue(current)); printf("Key %s has a value of size %d bytes. Value: %s\nComment: %s", keyStealName(current), size, (char *)keyStealValue(current), keyStealComment(current)); } } Parameters: key  the key object to work with See also: keyGetValueSize(), keyGetString(), keyGetBinary(), keyGetLink() Definition at line 1543 of file key.c. References _Key::data. Referenced by commandMonitor().

ssize_t keySetLink (  Key *  key, const char *  target )

Set key as type KeyType::KEY_TYPE_LINK with target target. Parameters: key  the object to work with target  the value to set to key Returns: whatever returned by keySetRaw() Definition at line 1563 of file key.c. References KEY_TYPE_LINK, keySetRaw(), keySetType(), and strblen(). Referenced by commandSet(), and kdbLink().

ssize_t keyGetLink (  const Key *  key, char *  returnedTarget, size_t  maxSize )

Get the target key pointed by key. Parameters: returnedTarget  a pre-allocated buffer to store the target maxSize  the size in bytes of the returnedTarget buffer key  the link key Returns: the size in bytes of the copied target string TODO: Remove or: update Doc add keyGetLinkSize() Definition at line 1586 of file key.c. References _Key::data, _Key::dataSize, and _Key::type.

ssize_t keyGetBinary (  const Key *  key, void *  returnedValue, size_t  maxSize )

Get the binary or string value of key. Parameters: returnedValue  pre-allocated memory to store a copy of key's value maxSize  number of bytes of pre-allocated memory Returns: the number of bytes actually copied to returnedValue See also: keySetBinary(), keyGetString(), keyStealValue(), keyIsBin() Definition at line 1694 of file key.c. References _Key::data, and _Key::dataSize. Referenced by commandGet().

ssize_t keySetBinary (  Key *  key, const void *  newBinary, size_t  dataSize )

Set the value of a key as a binary. A private copy of newBinary will allocated and saved inside key, so the parameter can be deallocated after the call. The filesys backend, when used through a kdbSetKey(), will make the value be encoded into a human readable hex-digit text format. UNIX sysadmins don't like to deal with binary sand box data. Consider using a string key instead. Parameters: key  the object on which to set the value newBinary  value octet stream dataSize  number of bytes to copy from newBinary Returns: the number of bytes actually copied to internal struct storage See also: keyGetBinary(), keyIsBin(), keyGetString(), keyStealValue(), keySetString() Definition at line 1735 of file key.c. References KEY_TYPE_BINARY, keySetRaw(), and keySetType().

uint8_t keyGetType (  const Key *  key  )

Returns the key data type. See also: keySetType(), keyIsBin(), keyIsDir(), keyIsLink() KeyType Returns: the key type Definition at line 1769 of file key.c. References _Key::type. Referenced by commandGet(), and commandSet().

uint8_t keySetType (  Key *  key, uint8_t  newType )

Force a key type. See the KeyType documentation to understand the concepts behind Elektra key's value types. This method is usually not needed, unless you are working with more semantic value types, or want to force a specific value type for a key. It is not usually needed because the data type is automatically set when setting the key value. The KeyType::KEY_TYPE_DIR is the only type that has no value, so when using this method to set to this type, the key value will be freed. Example: #define KEY_TYPE_COLOR (KEY_TYPE_STRING+4) Key *color1; Key *color2; // Set color1 key color1=keyNew("user/sw/MyApp/colors/someColor", KEY_SWITCH_TYPE,KEY_TYPE_COLOR, KEY_SWITCH_VALUE,"#4B52CA", KEY_SWITCH_COMMENT,"a custom color", KEY_SWITCH_END); // Set color2 key color2=keyNew("system/sw/MyApp/colors/green", KEY_SWITCH_TYPE,KEY_TYPE_COLOR, KEY_SWITCH_VALUE,"green", KEY_SWITCH_COMMENT,"the green color", KEY_SWITCH_END); // Start affairs with Key database kdbOpen(); // Commit the keys kdbSetKey(color1); kdbSetKey(color2); // Reset memory related to our structures to reuse them later keyClose(color1); keyClose(color2); // Retrieve keys from the database keySetName(color1,"user/sw/MyApp/colors/someColor"); kdbGetKey(color1); keySetName(color2,"system/sw/MyApp/colors/green"); kdbGetKey(color2); // End of the affairs with Key database by now kdbClose(); // Get the key types, which should be our user-defined KEY_TYPE_COLOR uint8_t tcolor1=keyGetType(color1); uint8_t tcolor2=keyGetType(color2); keyDel(color1); keyDel(color2); See also: keyGetType() KeyType Returns: the new type Definition at line 1848 of file key.c. References _Key::access, _Key::flags, KEY_TYPE_DIR, keySetRaw(), and _Key::type. Referenced by commandSet(), keyNew(), keySetBinary(), keySetLink(), and keySetString().

ssize_t keySetRaw (  Key *  key, const void *  newBinary, size_t  dataSize )

Set raw data as the value of a key. If NULL pointers are passed, key value is cleaned. This method will not change or set the key type, and should not be used unless working with user-defined value types. Parameters: newBinary  array of bytes to set as the value dataSize  number bytes to use from newBinary, including the final NULL Returns: The number of bytes actually set in internall buffer. See also: keySetType(), keySetString(), keySetBinary() Definition at line 1888 of file key.c. References _Key::data, _Key::dataSize, _Key::flags, and KEY_SWITCH_VALUE. Referenced by commandSet(), keyDup(), keyNew(), keySetBinary(), keySetLink(), keySetString(), and keySetType().

---