Elektra Projekt
|
Backend helper Methods for Elektra and Backends. More...
Functions | |
int | kdbbWriteLock (FILE *f) |
int | kdbbReadLock (FILE *f) |
int | kdbbUnlock (FILE *f) |
ssize_t | kdbbEncode (void *kdbbDecoded, size_t size, char *returned) |
ssize_t | kdbbDecode (char *kdbbEncoded, void *returned) |
int | kdbbNeedsUTF8Conversion () |
int | kdbbUTF8Engine (int direction, char **string, size_t *inputOutputByteSize) |
int | kdbbEncodeChar (char c, char *buffer, size_t bufSize) |
int | kdbbDecodeChar (const char *from, char *into) |
int | kdbbFilenameToKeyName (const char *string, char *buffer, int bufSize) |
ssize_t | kdbbGetFullKeyName (KDB *handle, const char *forFilename, const Key *parentKey, Key *returned) |
int | kdbbKeyNameToRelativeFilename (const char *string, char *buffer, size_t bufSize) |
ssize_t | kdbbKeyCalcRelativeFilename (const Key *key, char *relativeFilename, size_t maxSize) |
ssize_t | kdbbGetFullFilename (KDB *handle, const Key *forKey, char *returned, size_t maxSize) |
Backend helper Methods for Elektra and Backends.
To use them:
#include <kdbbackend.h>
These backend helper methods provide functionality commonly used by backends to make backend development easier and to provide the same behaviour between backends.
ssize_t kdbbDecode | ( | char * | kdbbEncoded, |
void * | returned | ||
) |
UnkdbbEncodes a buffer of ASCII hexadecimal values into a byte stream.
The allowed format for the hexadecimal values is just a stream of pairs of plain hex-digits, all together or space-separated.
The returned
data won't be bigger than half the size of the source kdbbEncoded
data.
kdbbEncoded | the source of ASCII hexadecimal digits. |
returned | preallocated destination for the kdbbDecoded data. |
int kdbbDecodeChar | ( | const char * | from, |
char * | into | ||
) |
Char decoding.
Decode one char from %25, %2B, %2F, %2C following RFC 2396 or copy char untouched if different.
from | String containing sequence to decode |
into | Decoded char |
NOTE: No '\0' is added at the end of buffer.
ssize_t kdbbEncode | ( | void * | kdbbDecoded, |
size_t | size, | ||
char * | returned | ||
) |
Encodes a buffer of data onto hexadecimal ASCII.
The resulting data is made up of pairs of ASCII hex-digits, space- and newline-separated. This is the counterpart of kdbbDecode().
The returned
must allocated prior you call this function and won't be bigger than 3 times the size of the source kdbbDecoded
+ 1 byte.
kdbbDecoded | the source buffer. |
size | the size of the source buffer in bytes. |
returned | the preallocated destination for the ASCII-kdbbEncoded data. |
int kdbbEncodeChar | ( | char | c, |
char * | buffer, | ||
size_t | bufSize | ||
) |
Char encoding.
Encode '/', '\', '%', '+', ' ' char following RFC 2396 or copy char untouched if different.
c | Char to kdbbEncode |
buffer | string wich will contain kdbbEncoded char |
bufSize | Size of the buffer |
NOTE: No '\0' is added at the end of buffer.
int kdbbFilenameToKeyName | ( | const char * | string, |
char * | buffer, | ||
int | bufSize | ||
) |
Translate a relative file name to a key name applying decoding.
string | Filename |
buffer | decoded keyName |
bufSize | Size of buffer |
ssize_t kdbbGetFullFilename | ( | KDB * | handle, |
const Key * | forKey, | ||
char * | returned, | ||
size_t | maxSize | ||
) |
Calculate the real file name for a key.
system/ keys will get the prefix KDB_DB_SYSTEM
For the user/ keys the algorithm works as follow: 1.) When the override environment KDB_HOME exists the configuration will be searched below KDB_HOME/KDB_DB_USER 2.) When the owner of the key exists in the elektra user database steps a.) and b.) will be tested: a.) The specific value for configuration storage of the user below system/users/<owner>/kdb b.) The home variable in system/users/<owner>/home will be merged together with KDB_DB_USER 3.) When the environment HOME exists the configuration will be searched below HOME/KDB_DB_USER 4.) Otherwise the KDB_DB_HOME/<owner>/KDB_DB_USER will be used
forKey | the key object to work with |
handle | the kdb handle to work with |
returned | the buffer to return the calculated filename |
maxSize | maximum number of bytes that fit the buffer |
ssize_t kdbbGetFullKeyName | ( | KDB * | handle, |
const char * | forFilename, | ||
const Key * | parentKey, | ||
Key * | returned | ||
) |
Calculates the keyname out of a relative filename.
handle | The kdb handle to work with |
forFilename | needs to be the a null terminated string containing the relative filename |
parentKey | is the key above the key which will be returned |
returned | The proper keyname and owner will be stored in returned. A valid key must be passed. |
ssize_t kdbbKeyCalcRelativeFilename | ( | const Key * | key, |
char * | relativeFilename, | ||
size_t | maxSize | ||
) |
This is a helper to kdbGetFullFilename()
key | has the relevant name for the relative filename |
relativeFilename | the buffer to return the calculated filename |
maxSize | maximum number of bytes that fit the buffer |
int kdbbKeyNameToRelativeFilename | ( | const char * | string, |
char * | buffer, | ||
size_t | bufSize | ||
) |
Translate a key name to a relative file name applying encoding.
string | Keyname |
buffer | kdbbEncoded filename |
bufSize | Size of buffer |
int kdbbNeedsUTF8Conversion | ( | void | ) |
Checks if UTF-8 conversion is needed in current context. if nl_langinfo() is not available, no conversion is ever needed. If iconv usage is disabled there is no need to check if we need to convert. Furthermore, some systems have nl_langinfo(), but lacks ability to get CODESET through it. Look at the comments by the kdbbUTF8Engine() function for more information.
int kdbbReadLock | ( | FILE * | f | ) |
Locks file for read mode.
Other processes and threads are allowed to read the file too simultaneous.
f | is a valid filedescriptor |
int kdbbUnlock | ( | FILE * | f | ) |
Unlocks file.
f | is a valid filedescriptor |
int kdbbUTF8Engine | ( | int | direction, |
char ** | string, | ||
size_t * | inputOutputByteSize | ||
) |
Converts string to (direction
= UTF8_TO
) and from (direction
= UTF8_FROM
) UTF-8.
Since Elektra provides portability for key names and string values between different codesets, you should use this helper in your backend to convert to and from universal UTF-8 strings, when storing key names, values and comments.
Broken locales in applications can cause problems too. Make sure to load the environment locales in your application using
setlocale (LC_ALL, "");
Otherwise kdbbUTF8Engine will quit with -1 leading that backends return with error when non-ascii characters appear. Binary values are not effected.
If iconv() or nl_langinfo() is not available on your system, or if iconv() usage is disabled (--disable-iconv on build time) simply return 0 immediately.
direction | must be UTF8_TO (convert from current non-UTF-8 to UTF-8) or UTF8_FROM (convert from UTF-8 to current non-UTF-8) |
string | before the call: the string to be converted; after the call: reallocated to carry the converted string |
inputOutputByteSize | before the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL |
int kdbbWriteLock | ( | FILE * | f | ) |
Locks file for exclusive write mode.
This function will block until all reader and writer have left the file.
f | is a valid filedescriptor |