Main Page | Modules | File List

KeyDB Class Methods

General methods to access the Key database. More...

Enumerations

enum  KDBErr {
  KDB_RET_OK = 0,
  KDB_RET_NULLKEY = EINVAL,
  KDB_RET_UNINITIALIZED = EINVAL,
  KDB_RET_NOKEY = ENOMSG,
  KDB_RET_NODATA = ENOMSG,
  KDB_RET_NOGROUP = ENOMSG,
  KDB_RET_NODESC = ENOMSG,
  KDB_RET_NODOMAIN = ENOMSG,
  KDB_RET_NOCRED = EACCES,
  KDB_RET_NOTIME = ENOMSG,
  KDB_RET_TRUNC = ENOBUFS,
  KDB_RET_TYPEMISMATCH = EILSEQ,
  KDB_RET_INVALIDKEY = EAFNOSUPPORT,
  KDB_RET_NOTFOUND = ENOENT
}
enum  KDBOptions {
  KDB_O_RECURSIVE = 1,
  KDB_O_DIR = 1<<1,
  KDB_O_NOVALUE = 1<<2 ,
  KDB_O_STATONLY = 1<<4,
  KDB_O_INACTIVE = 1<<5,
  KDB_O_SORT = 1<<6,
  KDB_O_NFOLLOWLINK = 1<<7,
  KDB_O_CONDENSED = 1<<8,
  KDB_O_NUMBERS = 1<<9,
  KDB_O_XMLHEADERS = 1<<10
}

Functions

int kdbOpen ()
int kdbClose ()
int kdbGetValue (const char *keyname, char *returned, size_t maxSize)
int kdbSetValue (const char *keyname, const char *value)
int kdbGetValueByParent (const char *parentName, const char *baseName, char *returned, size_t maxSize)
int kdbSetValueByParent (const char *parentName, const char *baseName, const char *value)
int kdbGetKeyByParent (const char *parentName, const char *baseName, Key *returned)
int kdbGetKeyByParentKey (const Key *parent, const char *baseName, Key *returned)
int kdbGetChildKeys (const char *parentName, KeySet *returned, unsigned long options)
int kdbGetRootKeys (KeySet *returned)
int kdbStatKey (Key *key)
int kdbGetKey (Key *key)
int kdbSetKeys (KeySet *ks)
int kdbSetKey (Key *key)
int kdbRename (Key *key, const char *newName)
int kdbRemove (const char *keyName)
int kdbLink (const char *oldPath, const char *newKeyName)
u_int32_t kdbMonitorKeys (KeySet *interests, u_int32_t diffMask, unsigned long iterations, unsigned sleep)
u_int32_t kdbMonitorKey (Key *interest, u_int32_t diffMask, unsigned long iterations, unsigned sleep)

Detailed Description

General methods to access the Key database.

To use them:

#include <kdb.h>

This is the class that accesses the storage backend. When writing a new backend, these are the methods you'll have to reimplement: kdbGetKey(), kdbSetKey(), kdbStatKey(), kdbRemove(), kdbRename(), kdbGetChildKeys()

And methods that is suggested to reimplement (but not needed) if you want them to get the benefits of your new backend: kdbOpen(), kdbClose(), kdbMonitorKey(), kdbMonitorKeys()

The other methods are higher level. They use the above methods to do their job, and generally don't have to be reimplemented for a different backend.

Language binding writers should follow the same rules:


Enumeration Type Documentation

enum KDBErr
 

Some return codes generated by the Elektra library.

These are only specific Elektra errors, that the library sets in errno. Other error can be generated by system calls that the API uses. Then errno is propagated.

A very robust program should check errno after each API call.

See also:
kdbGetChildKeys() for an example on how to handle errors
Enumeration values:
KDB_RET_OK  No error
KDB_RET_NULLKEY  Invalid Key object
KDB_RET_UNINITIALIZED  Object not initilized
KDB_RET_NOKEY  Key has no name
KDB_RET_NODATA  Key has no data
KDB_RET_NOGROUP  Key has no group
KDB_RET_NODESC  Key has no comment/description
KDB_RET_NODOMAIN  Key has no user domain set
KDB_RET_NOCRED  No credentials to access resource
KDB_RET_NOTIME  Key has no access time set
KDB_RET_TRUNC  Buffer was too small
KDB_RET_TYPEMISMATCH  Failed to convert key data due to data type
KDB_RET_INVALIDKEY  Key name is no 'system/' or 'user/'
KDB_RET_NOTFOUND  Key was not found

Definition at line 167 of file kdb.h.

enum KDBOptions
 

Options to change the default behavior of some methods.

These options should be ORed.

See also:
kdbGetChildKeys()

ksToStream()

keyToStream()

Enumeration values:
KDB_O_RECURSIVE  Act recursively
KDB_O_DIR  Include dir keys in result
KDB_O_NOVALUE  Retrieve only keys that don't have values (a.k.a dir keys)
KDB_O_STATONLY  Only stat key, instead of getting entirelly
KDB_O_INACTIVE  Do not ignore inactive keys (that name begins with .)
KDB_O_SORT  Sort keys
KDB_O_NFOLLOWLINK  Do not follow symlinks
KDB_O_CONDENSED  Compressed XML, not usefull for human eyes
KDB_O_NUMBERS  Use UID and GID intead of user and group names
KDB_O_XMLHEADERS  Show also the XML header of the document

Definition at line 194 of file kdb.h.


Function Documentation

int kdbClose  ) 
 

Closes a session with the Key database.

You should call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects after kdbClose().

This is the counterpart of kdbOpen().

See also:
kdbOpen()

Definition at line 153 of file localkdb.c.

Referenced by commandExport().

int kdbGetChildKeys const char *  parentName,
KeySet *  returned,
unsigned long  options
 

Retrieve a number of inter-related keys in one shot. This is one of the most practicall methods of the library. Returns a KeySet with all retrieved keys. So if your application keys live bellow system/sw/myApp, you'll use this method to get them all.

Option can be any of the following, ORed:

  • KDB_O_RECURSIVE
    Retrieve also the keys under the child keys, recursively. The kdb(1) ls command, with switch -R uses this option.
  • KDB_O_DIR
    By default, folder keys will not be returned because they don't have values and exist only to define hierarchy. Use this option if you need them to be included in the returned KeySet.
  • KDB_O_NOVALUE
    Do not include in returned the regular value keys. The resulting KeySet will be only the skeleton of the tree.
  • KDB_O_STATONLY
    Only stat(2) the keys; do not retrieve the value, comment and key data type. The resulting keys will be empty and usefull only for informational purposes. The kdb(1) ls command, without the -v switch uses this option.
  • KDB_O_INACTIVE
    Will make it not ignore inactive keys. So returned will be filled also with inactive keys. See registry(7) to understand how inactive keys work.
  • KDB_O_SORT
    Will sort keys alphabetically by their names.

Example:
char errormsg[300];
KeySet myConfig;
ksInit(&myConfig);

kdbOpen();
rc=kdbGetChildKeys("system/sw/MyApp", &myConfig, KDB_O_RECURSIVE);
kdbClose();

// Check and handle propagated error
if (rc) switch (errno) {
    case KDB_RET_INVALIDKEY:
        sprintf(errormsg,"Something invalid");
        perror(errormsg); // use system error messages
        break;
    case KDB_RET_NOTFOUND:
        fprintf(stderr,"Key not found"); // custom error message
        break;
    default:
        sprintf(errormsg,"My application");
        perror(errormsg); // use system error messages
        break;
}

ksRewind(&myConfig); // go to begining of KeySet
Key *key=ksNext(&myConfig);
while (key) {
    // do something with key . . .

    key=ksNext(&myConfig); // next key
}
Parameters:
parentName name of the parent key
returned the KeySet returned with all keys found
options ORed options to control approaches
See also:
KDBOptions

commandList() code in kdb command for usage example

commandEdit() code in kdb command for usage example

commandExport() code in kdb command for usage example

Returns:
0 on success, other value on error and errno is set

Definition at line 1100 of file localkdb.c.

References KDB_O_SORT, kdbGetKey(), kdbStatKey(), keyClose(), keyGetFullName(), keyGetFullNameSize(), keyInit(), keyIsLink(), keySetName(), ksAppend(), ksAppendKeys(), and ksInit().

Referenced by commandEdit(), and commandList().

int kdbGetKey Key *  key  ) 
 

Fully retrieves the passed key from the backend storage.

Parameters:
key a pointer to a Key that has a name set
Returns:
0 on success, or other value and errno is set
See also:
kdbSetKey()

commandGet() code in kdb command for usage example

Definition at line 1318 of file localkdb.c.

References keyIsDir().

Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandSet(), kdbGetChildKeys(), kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbGetRootKeys(), kdbGetValue(), kdbMonitorKey(), and kdbSetValue().

int kdbGetKeyByParent const char *  parentName,
const char *  baseName,
Key *  returned
 

Given a parent key name plus a basename, returns the key.

So here you'll provide something like

  • system/sw/myApp plus key1 to get system/sw/myApp/key1
  • user/sw/MyApp plus dir1/key2 to get user/sw/MyApp/dir1/key2

Parameters:
parentName parent key name
baseName leaf or child name
returned a pointer to an initialized key to be filled
Returns:
0 on success, or what kdbGetKey() returns, and errno is set
See also:
kdbGetKey()

kdbGetValueByParent()

kdbGetKeyByParentKey()

Definition at line 982 of file localkdb.c.

References kdbGetKey(), and keySetName().

int kdbGetKeyByParentKey const Key *  parent,
const char *  basename,
Key *  returned
 

Similar to previous, provided for convenience.

Parameters:
parent pointer to the parent key
See also:
kdbGetKey()

kdbGetKeyByParent()

kdbGetValueByParent()

Returns:
0 on success, or what kdbGetKey() returns, and errno is set

Definition at line 1001 of file localkdb.c.

References kdbGetKey(), keyGetFullName(), keyGetFullNameSize(), and keySetName().

int kdbGetRootKeys KeySet *  returned  ) 
 

Returns a KeySet with all root keys currently recognized. Currently, the system and current user's user keys are returned.

Parameters:
returned the initialized KeySet to be filled
Returns:
0
See also:
KeyNamespace

commandList() code in kdb command for usage example

Definition at line 1240 of file localkdb.c.

References kdbGetKey(), keyInit(), keySetName(), ksAppend(), and ksInsert().

Referenced by commandList().

int kdbGetValue const char *  keyname,
char *  returned,
size_t  maxSize
 

A high-level method to get a key value, by key name. This method is valid only for string keys. You should use other methods to get non-string keys.

See also:
kdbSetValue()

kdbGetKey()

kdbGetValueByParent()

keyGetString()

Returns:
0 on success, or other value and errno is set
Parameters:
keyname the name of the key to receive the value
returned a buffer to put the key value
maxSize the size of the buffer

Definition at line 867 of file localkdb.c.

References kdbGetKey(), keyClose(), keyGetString(), keyInit(), and keySetName().

Referenced by kdbGetValueByParent().

int kdbGetValueByParent const char *  parentName,
const char *  baseName,
char *  returned,
size_t  maxSize
 

Fills the returned buffer with the value of a key, which name is the concatenation of parentName and baseName.

Example:
char *parent="user/sw/MyApp";
char *keys[]={"key1","key2","key3"};
char buffer[150];   // a big buffer
int c;

for (c=0; c<3; c++) {
    kdbGetValueByParent(parent,keys[c],buffer,sizeof(buffer));
    // Do something with buffer....
}
See also:
kdbGetKeyByParent()
Parameters:
parentName the name of the parent key
baseName the name of the child key
returned pre-allocated buffer to be filled with key value
maxSize size of the returned buffer
Returns:
whathever is returned by kdbGetValue()

Definition at line 939 of file localkdb.c.

References kdbGetValue().

int kdbLink const char *  oldPath,
const char *  newKeyName
 

Create a link key that points to other key.

Parameters:
oldPath destination key name
newKeyName name of the key that will be created and will point to
oldPath 
Returns:
whathever is returned by kdbSetKey(), and errno is set
See also:
commandLink() code in kdb command for usage example

commandSet() code in kdb command for usage example

Definition at line 1592 of file localkdb.c.

References kdbSetKey(), keyClose(), keyInit(), and keySetName().

Referenced by commandLink().

u_int32_t kdbMonitorKey Key *  interest,
u_int32_t  diffMask,
unsigned long  iterations,
unsigned  sleep
 

Monitor a key change.

This method will block your program until one of the folowing happens:

  • All requested iterations, with requested sleep times, finish. If no change happens, zero is returned.
  • Requested key info and meta-info (defined by diffMask) changes when keyCompare()ed with the original interest.

interest should be a full key with name, value, comments, permissions, etc, and all will be compared and then masked by diffMask.

If interest is a folder key, use KEY_FLAG_HASTIME in diffMask to detect a time change, so you'll know something happened (key modification, creation, deletion) inside the folder.

If interest was not found, or deleted, the method will return immediatly a KEY_FLAG_FLAG value.

If you don't have access rights to interest, the method will return immediatly a KEY_FLAG_NEEDSYNC value.

If something from diffMask has changed in interest, it will be updated, so when method returns, you'll have an updated version of the key.

Parameters:
interest key that will be monitored
diffMask what particular info change we are interested
iterations how many times to test, when 0 means until some change happens
sleep time to sleep, in microseconds, between iterations. 0 defaults to 1 second.
Returns:
the ORed KEY_FLAG_* flags of what changed
See also:
KeyFlags

keyCompare()

kdbMonitorKeys() to monitor KeySets, and for a code example

commandMonitor() code in kdb command for usage example

Definition at line 1739 of file localkdb.c.

References KDB_RET_NOCRED, KDB_RET_NOTFOUND, kdbGetKey(), keyClose(), keyCompare(), keyDup(), keyGetNameSize(), and keyInit().

Referenced by commandMonitor(), and kdbMonitorKeys().

u_int32_t kdbMonitorKeys KeySet *  interests,
u_int32_t  diffMask,
unsigned long  iterations,
unsigned  sleep
 

Monitor a KeySet for some key change.

This method will scan the interests KeySet, starting and finishing in the KeySet next cursor position, in a circular behavior, looking for some change defined in the diffMask mask. It will use kdbMonitorKey() and will return at the first key change ocurrence, or when requested iterations finish.

You may check the return code to see if some key changed, and get the updated key using ksCurrent().

Example:
KeySet myConfigs;

ksInit(&myConfigs);
kdbGetChildKeys("system/sw/MyApp",&myConfigs,KDB_O_ALL);

// use the keys . . . .

// now monitor any key change
ksRewind(&myConfigs);
while (1) {
    Key *changed=0;
    char keyName[300];
    char keyData[300];
    u_int32_t diff;

    // block until any change in key value or comment . . .
    diff=kdbMonitorKeys(&myConfigs,
        KEY_FLAG_HASDATA | KEY_FLAG_HASCOMMENT,
        0,0); // ad-infinitum

    changed=ksCurrent(&myConfigs);
    keyGetName(changed,keyName,sizeof(keyName));

    switch (diff) {
        case KEY_FLAG_FLAG:
            printf("Key %s was deleted\n",keyName);
            break;
        case KEY_FLAG_NEEDSYNC:
            printf("No cretentials to access Key %s\n",keyName);
            break;
        default:
            keyGetString(changed,keyData,sizeof(keyData));
            printf("Key %s has changed its value to %s\n",keyName,keyData);
    }
}
See also:
kdbMonitorKey()

ksCurrent()

ksRewind()

ksNext()

KeyFlags

commandMonitor() code in kdb command for usage example

Definition at line 1669 of file localkdb.c.

References kdbMonitorKey(), ksCurrent(), and ksNext().

int kdbOpen  ) 
 

Opens a session with the Key database

You should allways call this method before retrieving or commiting any keys to the database. Otherwise, consequences are unpredictable.

To simply manipulate Key or KeySet objects, you don't need to open the key database before with this method.

See also:
kdbClose()

Definition at line 136 of file localkdb.c.

Referenced by commandExport().

int kdbRemove const char *  keyName  ) 
 

Remove a key from the backend storage. This method is not recursive.

Parameters:
keyName the name of the key to be removed
Returns:
whathever is returned by remove(), and errno is propagated
See also:
commandRemove() code in kdb command for usage example

Definition at line 1562 of file localkdb.c.

References keyClose(), keyInit(), and keySetName().

Referenced by commandEdit(), and commandRemove().

int kdbRename Key *  key,
const char *  newName
 

Rename a key.

Parameters:
key the key to be renamed
newName the new key name
Returns:
whathever is returned by rename(), and errno is propagated

Definition at line 1532 of file localkdb.c.

References keyInit(), and keySetName().

int kdbSetKey Key *  key  ) 
 

Commits a key to the backend storage. If failed (see return), the errno global is set accordingly.

See also:
kdbGetKey()

kdbSetKeys()

commandSet() code in kdb command for usage example

Returns:
0 on success, or other value and errno is set

Definition at line 1404 of file localkdb.c.

References keyClose(), keyGetAccess(), keyGetGID(), keyGetLink(), keyGetUID(), keyInit(), keyIsDir(), keyIsLink(), and keySetName().

Referenced by commandSet(), kdbLink(), kdbSetKeys(), and kdbSetValue().

int kdbSetKeys KeySet *  ks  ) 
 

Commits the ks KeySet to the backend storage, starting from ks's current cursor until its end. This is why it is suggested that you call ksRewind() on ks beffore calling this method. Each key is checked with keyNeedsSync() before being actually commited. So only changed keys are updated.

If some error occurs, kdbSetKeys() stops and returns whatever kdbSetKey() returned. The KeySet internal cursor is left on the key that generated the error (so you may check it latter with ksCurrent()). The internal kdbSetKey() also sets errno in case of error.

Parameters:
ks a KeySet full of changed keys
Returns:
0 on success, or whatever kdbSetKey() returns
See also:
kdbSetKey()

keyNeedsSync()

ksNext()

ksCurrent()

commandEdit() code in kdb command for usage example

commandImport() code in kdb command for usage example

Definition at line 1376 of file localkdb.c.

References kdbSetKey(), keyNeedsSync(), ksCurrent(), and ksNext().

Referenced by commandEdit(), and commandImport().

int kdbSetValue const char *  keyname,
const char *  value
 

A high-level method to set a value to a key, by key name. It will obviously check if key exists first, and keep its metadata. So you'll not loose the precious key comment.

This will set a text key. So if the key was previously a binary, etc key, it will be retyped as text.

See also:
kdbGetValue()

keySetString()

kdbSetKey()

Parameters:
keyname the name of the key to receive the value
value the value to be set
Returns:
0 on success, other value otherwise, and errno is set

Definition at line 898 of file localkdb.c.

References kdbGetKey(), kdbSetKey(), keyClose(), keySetName(), and keySetString().

Referenced by kdbSetValueByParent().

int kdbSetValueByParent const char *  parentName,
const char *  baseName,
const char *  value
 

Sets the provided value to the key whose name is the concatenation of parentName and baseName.

Parameters:
parentName the name of the parent key
baseName the name of the child key
value the value to set

Definition at line 957 of file localkdb.c.

References kdbSetValue().

int kdbStatKey Key *  key  ) 
 

Retrieves only the meta-info of a key from backend storage. The bahavior may change from backend to backend. In the filesystem backend, it will make only a stat to the key.

Info like comments and key data type are not retrieved.

Parameters:
key an initialized Key pointer to be filled.
Returns:
0 on success, -1 otherwise

Definition at line 1278 of file localkdb.c.

References keyIsLink().

Referenced by commandList(), and kdbGetChildKeys().


Generated on Sun May 8 02:29:55 2005 for Elektra Project by  doxygen 1.3.9.1