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. | |
uint8_t | keySetDir (Key *key, mode_t customUmask) |
Force a key type to be KEY_TYPE_DIR and set permissions. | |
ssize_t | keySetRaw (Key *key, const void *newBinary, size_t dataSize) |
Set raw data as the value of a key. |
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>
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().
Definition at line 1602 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.
key | the key to set the string value | |
newStringValue | NULL-terminated text string to be set as key's value |
Definition at line 1625 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.
Key *key; char buffer[300]; // populate key somehow... if (keyIsBin(key)) keyGetBinary(key,buffer,sizeof(buffer)); else keyGetString(key,buffer,sizeof(buffer));
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 |
returnedString
, including final NULL Definition at line 1662 of file key.c.
References _Key::data, _Key::dataSize, KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_TYPEMISMATCH, KEY_TYPE_STRING, 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.
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)); } }
key | the key object to work with |
Definition at line 1737 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
.
key | the object to work with | |
target | the value to set to key |
Definition at line 1757 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
.
returnedTarget | a pre-allocated buffer to store the target | |
maxSize | the size in bytes of the returnedTarget buffer | |
key | the link key |
TODO: Remove or:
Definition at line 1781 of file key.c.
References _Key::data, _Key::dataSize, KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_TYPEMISMATCH, KEY_TYPE_LINK, and _Key::type.
ssize_t keyGetBinary | ( | const Key * | key, | |
void * | returnedValue, | |||
size_t | maxSize | |||
) |
Get the binary or string value of key
.
returnedValue | pre-allocated memory to store a copy of key's value | |
maxSize | number of bytes of pre-allocated memory |
returnedValue
Definition at line 1873 of file key.c.
References _Key::data, _Key::dataSize, KDB_RET_NODATA, and KDB_RET_TRUNC.
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.
Consider using a string key instead.
key | the object on which to set the value | |
newBinary | value octet stream | |
dataSize | number of bytes to copy from newBinary |
Definition at line 1908 of file key.c.
References KEY_TYPE_BINARY, keySetRaw(), and keySetType().
uint8_t keyGetType | ( | const Key * | key | ) |
Returns the key data type.
Definition at line 1942 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.
#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);
Definition at line 2019 of file key.c.
References _Key::flags, KEY_SWITCH_NEEDSYNC, KEY_TYPE_DIR, keySetDir(), and _Key::type.
Referenced by commandSet(), keyNew(), keySetBinary(), keySetLink(), and keySetString().
uint8_t keySetDir | ( | Key * | key, | |
mode_t | customUmask | |||
) |
Force a key type to be KEY_TYPE_DIR and set permissions.
This method is provided as a convenience to avoid separate calls of keySetType() and keySetAccess() and the complexities of calculating permissions from umask().
Key *key=keyNew(KEY_SWITCH_END); mode_t mask=umask(0); // restore backup umask(mask); // set directory permissions based on my umask keySetDir(key,mask);
key | the key to set type and permissions | |
customUmask | the umask of current session |
Definition at line 2063 of file key.c.
References _Key::access, _Key::flags, KEY_SWITCH_NEEDSYNC, and KEY_TYPE_DIR.
Referenced by commandSet(), keyNew(), and keySetType().
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.
newBinary | array of bytes to set as the value | |
dataSize | number bytes to use from newBinary, including the final NULL |
Definition at line 2088 of file key.c.
References _Key::data, _Key::dataSize, _Key::flags, KEY_SWITCH_NEEDSYNC, and KEY_SWITCH_VALUE.
Referenced by commandSet(), keyDup(), keyNew(), keySetBinary(), keySetLink(), and keySetString().