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