Elektra Projekt
Functions
KDB Backends :: Backend Helper for Elektra

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)

Detailed Description

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.


Function Documentation

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.

Parameters:
kdbbEncodedthe source of ASCII hexadecimal digits.
returnedpreallocated destination for the kdbbDecoded data.
Returns:
the amount of bytes kdbbDecoded
-1 on failure
See also:
kdbbEncode()
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.

Parameters:
fromString containing sequence to decode
intoDecoded char
Returns:
: Positive size of byte read from "from" for decoding the sequence if sucess or -1 if error (into untouched)
See also:
kdbbEncodeChar

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.

Parameters:
kdbbDecodedthe source buffer.
sizethe size of the source buffer in bytes.
returnedthe preallocated destination for the ASCII-kdbbEncoded data.
Returns:
the amount of bytes used in the resulting kdbbEncoded buffer.
See also:
kdbbDecode()
int kdbbEncodeChar ( char  c,
char *  buffer,
size_t  bufSize 
)

Char encoding.

Encode '/', '\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.

Parameters:
cChar to kdbbEncode
bufferstring wich will contain kdbbEncoded char
bufSizeSize of the buffer
Returns:
: Size of the kdbbEncoded string if success or -1 if error * (then buffer is untouched)
See also:
kdbiDecodeChar

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.

Parameters:
stringFilename
bufferdecoded keyName
bufSizeSize of buffer
Returns:
0 on success
-1 on failure
See also:
kdbbKeyNameToRelativeFilename
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

Parameters:
forKeythe key object to work with
handlethe kdb handle to work with
returnedthe buffer to return the calculated filename
maxSizemaximum number of bytes that fit the buffer
See also:
kdbCalcRelativeFilename()
Returns:
number of bytes written to the buffer, or 0 on error
length of returned string on success
-1 on failure
ssize_t kdbbGetFullKeyName ( KDB *  handle,
const char *  forFilename,
const Key *  parentKey,
Key *  returned 
)

Calculates the keyname out of a relative filename.

Parameters:
handleThe kdb handle to work with
forFilenameneeds to be the a null terminated string containing the relative filename
parentKeyis the key above the key which will be returned
returnedThe proper keyname and owner will be stored in returned. A valid key must be passed.
Returns:
number of bytes written to the buffer, or 0 on error
length of returned string on success
-1 on failure
See also:
kdbbKeyNameToRelativeFilename()
ssize_t kdbbKeyCalcRelativeFilename ( const Key *  key,
char *  relativeFilename,
size_t  maxSize 
)

This is a helper to kdbGetFullFilename()

Parameters:
keyhas the relevant name for the relative filename
relativeFilenamethe buffer to return the calculated filename
maxSizemaximum number of bytes that fit the buffer
See also:
kdbGetFullFilename()
Returns:
number of bytes written to the buffer
-1 on failure
int kdbbKeyNameToRelativeFilename ( const char *  string,
char *  buffer,
size_t  bufSize 
)

Translate a key name to a relative file name applying encoding.

Parameters:
stringKeyname
bufferkdbbEncoded filename
bufSizeSize of buffer
Returns:
Number of byte written in buffer on success,
-1 on failure
See also:
kdbbKeyNameToRelativeFilename
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.

Returns:
0 if not needed
anything else if needed
int kdbbReadLock ( FILE *  f)

Locks file for read mode.

Other processes and threads are allowed to read the file too simultaneous.

Parameters:
fis a valid filedescriptor
Returns:
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed
int kdbbUnlock ( FILE *  f)

Unlocks file.

Parameters:
fis a valid filedescriptor
Returns:
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed
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.

Parameters:
directionmust be UTF8_TO (convert from current non-UTF-8 to UTF-8) or UTF8_FROM (convert from UTF-8 to current non-UTF-8)
stringbefore the call: the string to be converted; after the call: reallocated to carry the converted string
inputOutputByteSizebefore the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL
Returns:
0 on success
-1 on failure
int kdbbWriteLock ( FILE *  f)

Locks file for exclusive write mode.

This function will block until all reader and writer have left the file.

Parameters:
fis a valid filedescriptor
Returns:
0 on success
-1 on failure
Error:
sets KDB_ERR_NOLOCK when locking failed