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.
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.

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 1602 of file key.c.

References _Key::dataSize.

Referenced by commandGet(), keyGetDataSize(), and listSingleKey().

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 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.

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 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(), kdbGetValue(), and listSingleKey().

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 1737 of file key.c.

References _Key::data.

Referenced by commandMonitor(), and listAllKeysForShell().

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 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.

Parameters:
returnedTarget a pre-allocated buffer to store the target
maxSize the size in bytes of the returnedTarget buffer
key the link key
Deprecated:
link system not perfect that way
Returns:
the size in bytes of the copied target string

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.

Referenced by listSingleKey().

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 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.

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 1908 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 1942 of file key.c.

References _Key::type.

Referenced by commandGet(), commandSet(), and listSingleKey().

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.

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);
When using KeyType::KEY_TYPE_DIR, this method will not set access permissions to the key. You'll have to set it manually after keySetType(), calling keySetAccess() with appropriate permissions. Or use the keySetDir().

See also:
keyGetType()

keySetDir()

KeyType

Returns:
the new type

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().

This method should be used this way:
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);
Parameters:
key the key to set type and permissions
customUmask the umask of current session
Returns:
always KEY_TYPE_DIR
See also:
keySetUAccess()

keySetType()

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.

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 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().


Generated on Mon Dec 17 19:13:47 2007 for Elektra Project by  doxygen 1.4.7