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:
kdbbEncoded the source of ASCII hexadecimal digits.
returned preallocated 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:
from String containing sequence to decode
into Decoded 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:
kdbbDecoded the source buffer.
size the size of the source buffer in bytes.
returned the 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:
c Char to kdbbEncode
buffer string wich will contain kdbbEncoded char
bufSize Size 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:
string Filename
buffer decoded keyName
bufSize Size 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:
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
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:
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.
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:
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
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:
string Keyname
buffer kdbbEncoded filename
bufSize Size 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:
f is 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:
f is 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:
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
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:
f is a valid filedescriptor
Returns:
0 on success

-1 on failure

Error:
sets KDB_ERR_NOLOCK when locking failed


Generated on Wed Aug 12 11:46:25 2009 for Elektra Projekt by  doxygen 1.5.9