Key :: Basic Methods

Key construction and initialization methods. More...

Enumerations

enum  KeyType {
  KEY_TYPE_UNDEFINED = 0,
  KEY_TYPE_DIR = 1,
  KEY_TYPE_LINK = 2,
  KEY_TYPE_BINARY = 20,
  KEY_TYPE_STRING = 40
}
 Key data types. More...
enum  KeyNamespace {
  KEY_NS_SYSTEM = 1,
  KEY_NS_USER = 2
}
 Elektra currently supported Key namespaces. More...
enum  KeySwitch {
  KEY_SWITCH_TYPE = 1,
  KEY_SWITCH_NAME = 1<<1,
  KEY_SWITCH_VALUE = 1<<2,
  KEY_SWITCH_OWNER = 1<<5,
  KEY_SWITCH_DOMAIN = KEY_SWITCH_OWNER,
  KEY_SWITCH_COMMENT = 1<<6,
  KEY_SWITCH_UID = 1<<7,
  KEY_SWITCH_GID = 1<<8,
  KEY_SWITCH_MODE = 1<<10,
  KEY_SWITCH_TIME = 1<<11,
  KEY_SWITCH_NEEDSYNC = 1<<12 ,
  KEY_SWITCH_UMODE = 1<<15,
  KEY_SWITCH_ISSYSTEM = 1<<23,
  KEY_SWITCH_ISUSER = 1<<24,
  KEY_SWITCH_FLAG = 1<<31,
  KEY_SWITCH_END = 0
}
 Switches to denote the various Key attributes in methods throughout this library. More...

Functions

KeykeyNew (const char *keyName,...)
 A practical way to fully create a Key object in one step.
int keyDel (Key *key)
 A destructor for Key objects.
int keyDup (const Key *source, Key *dest)
 Duplicate a key in memory.
int keyInit (Key *key)
 Initializes the Key object with some default values.
int keyClose (Key *key)
 Finishes the usage of a Key object.

Detailed Description

Key construction and initialization methods.

To use them:

#include <kdb.h>

A Key is the essential class that encapsulates key name , value and metainfo . Key properties are:

Described here the methods to allocate and free the key.


Enumeration Type Documentation

enum KeyType

Key data types.

Key type values grow from the semantically poor to the semantically rich. The gaps between them is for user-defined types.

If your application needs value types with more semantics, like Color, Font, etc, you can still use it. You'll have to define a new type number in the scope of your application, and force the type with keySetType(), or keyNew().

The type number is a value between 0 and 255. If your user-defined type >= KEY_TYPE_STRING, it will be still treated as a string (in the terms of Unicode handling). If KEY_TYPE_BINARY <= type < KEY_TYPE_STRING, Elektra will handle it as a binary value, will not make Unicode handling and will save it hex-encoded.

See also:
keyGetType()

keySetType() for an example of how to define custom types

Enumerator:
KEY_TYPE_UNDEFINED  Undefined key type
KEY_TYPE_DIR  A directory key
KEY_TYPE_LINK  A symbolink link key. This gap is for special key meta types, that can't go into regular files.
KEY_TYPE_BINARY  A binary key. This gap is for binary data types that have some semantics that somebody can invent in the future
KEY_TYPE_STRING  A string key

Definition at line 92 of file kdb.h.

enum KeyNamespace

Elektra currently supported Key namespaces.

See also:
kdbGetRootKeys(), keyGetNamespace(), keyNameGetNamespace()
Enumerator:
KEY_NS_SYSTEM  The system keys
KEY_NS_USER  The user keys

Definition at line 115 of file kdb.h.

enum KeySwitch

Switches to denote the various Key attributes in methods throughout this library.

See also:
keyNew()

keyCompare()

kdbMonitorKey(), kdbMonitorKeys(), the diffMask parameter

keyGetFlag(), keySetFlag()

Enumerator:
KEY_SWITCH_TYPE  Flag for the key type
KEY_SWITCH_NAME  Flag for the key name
KEY_SWITCH_VALUE  Flag for the key data
KEY_SWITCH_OWNER  Flag for the key user domain
KEY_SWITCH_DOMAIN  An alias
KEY_SWITCH_COMMENT  Flag for the key comment
KEY_SWITCH_UID  Flag for the key UID
KEY_SWITCH_GID  Flag for the key GID
KEY_SWITCH_MODE  Flag for the key permissions
KEY_SWITCH_TIME  Flag for the key change time
KEY_SWITCH_NEEDSYNC  Flags that key needs syncronization
KEY_SWITCH_UMODE  Flag for key permissions based on umask
KEY_SWITCH_ISSYSTEM  Flag to denote a "system" key
KEY_SWITCH_ISUSER  Flag to denote a "user" key
KEY_SWITCH_FLAG  General purpose flag that has semantics only to your app
KEY_SWITCH_END  Used as a parameter terminator to keyNew()

Definition at line 155 of file kdb.h.


Function Documentation

Key* keyNew ( const char *  keyName,
  ... 
)

A practical way to fully create a Key object in one step.

This function tries to mimic the C++ way for constructors.

Due to ABI compatibility, the Key structure is not defined in kdb.h, only declared. So you can only declare pointers to Keys in your program, and allocate and free memory for them with keyNew() and keyDel() respectively. See http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135

You can call it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as the KeySwitch values, and tell keyNew() which Key attribute comes next.

The simplest and minimum way to use it is with no tags, only a key name:

Key *nullKey,*emptyNamedKey;

// Create a key that has no name, is completely empty, but is initialized
nullKey=keyNew(KEY_SWITCH_END);

// Create and initialize a key with a name and nothing else
emptyNamedKey=keyNew("user/some/example",KEY_SWITCH_END);

keyNew() allocates memory for a key object and then calls keyInit(). After that, it processes the given argument list.

The Key attribute tags are the following:

Example:
KeySet *ks=ksNew();

kdbOpen();
    
ksAppend(ks,keyNew(KEY_SWITCH_END));       // an empty key
    
ksAppend(ks,keyNew("user/sw",              // a simple key
    KEY_SWITCH_END));                      // no more args
    
ksAppend(ks,keyNew("system/sw",
    KEY_SWITCH_NEEDSYNC, handle,           // a key retrieved from storage
    KEY_SWITCH_END));                      // end of args
    
ksAppend(ks,keyNew("user/tmp/ex1",
    KEY_SWITCH_VALUE,"some data",          // with a simple value
    KEY_SWITCH_END));                      // end of args
    
ksAppend(ks,keyNew("user/tmp/ex2",
    KEY_SWITCH_VALUE,"some data",          // with a simple value
    KEY_SWITCH_MODE,0777,                  // permissions
    KEY_SWITCH_END));                      // end of args
    
ksAppend(ks,keyNew("user/tmp/ex3",
    KEY_SWITCH_TYPE,KEY_TYPE_LINK,         // only type
    KEY_SWITCH_VALUE,"system/mtp/x",       // link destination
    KEY_SWITCH_MODE,0654,                  // weird permissions
    KEY_SWITCH_END));                      // end of args
    
ksAppend(ks,keyNew("user/tmp/ex4",
    KEY_SWITCH_TYPE,KEY_TYPE_BINARY,       // key type
    KEY_SWITCH_VALUE,"some data",7,        // value that will be truncated in 7 bytes
    KEY_SWITCH_COMMENT,"value is truncated",
    KEY_SWITCH_DOMAIN,"root",              // owner (not uid) is root
    KEY_SWITCH_UID,0,                      // root uid
    KEY_SWITCH_END));                      // end of args

ksAppend(ks,keyNew("user/tmp/ex5",
    KEY_SWITCH_TYPE,KEY_TYPE_DIR,          // dir key with...
    KEY_SWITCH_TYPE,KEY_TYPE_BINARY,       // ...a binary value
    KEY_SWITCH_VALUE,"some data",7,        // value that will be truncated in 7 bytes
    KEY_SWITCH_COMMENT,"value is truncated",
    KEY_SWITCH_DOMAIN,"root",              // owner (not uid) is root
    KEY_SWITCH_UID,0,                      // root uid
    KEY_SWITCH_END));                      // end of args

ksAppend(ks,keyNew("user/env/alias/ls",    // a key we know we have
    KEY_SWITCH_NEEDSYNC, handle,           // retrieve from storage, passing the KDB handle
    KEY_SWITCH_END));                      // do nothing more
    
ksAppend(ks,keyNew("user/env/alias/ls",    // same key
    KEY_SWITCH_NEEDSYNC, handle,           // retrieve from storage
    KEY_SWITCH_DOMAIN,"root",              // set new owner (not uid) as root
    KEY_SWITCH_COMMENT,"new comment",      // set new comment
    KEY_SWITCH_END));                      // end of args
    
ksToStream(ks,stdout,KDB_O_XMLHEADERS);
    
ksDel(ks);
kdbClose();
Parameters:
keyName a valid name to the key, or NULL to get a simple initialized, but really empty, object
See also:
keyDel()
Returns:
a pointer to a new allocated and initialized Key object, or NULL if an invalid keyName was passed (see keySetName()).

Definition at line 373 of file key.c.

References _Key::flags, kdbGetKey(), KEY_SWITCH_COMMENT, KEY_SWITCH_DOMAIN, KEY_SWITCH_FLAG, KEY_SWITCH_GID, KEY_SWITCH_MODE, KEY_SWITCH_NEEDSYNC, KEY_SWITCH_TYPE, KEY_SWITCH_UID, KEY_SWITCH_UMODE, KEY_SWITCH_VALUE, KEY_TYPE_BINARY, KEY_TYPE_DIR, KEY_TYPE_STRING, KEY_TYPE_UNDEFINED, keyInit(), keyIsDir(), keySetAccess(), keySetComment(), keySetDir(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetString(), keySetType(), keySetUAccess(), and keySetUID().

Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbRemove(), kdbSetValue(), and keyUnserialize().

int keyDel ( Key key  ) 

A destructor for Key objects.

Every key created by keyNew() must be deleted with keyDel(). It will keyClose() and free() the key pointer.

There is the keyFree() macro if you prefer this method name.

See also:
keyNew()
Returns:
whatever is returned by keyClose()

Definition at line 490 of file key.c.

References keyClose().

Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbRemove(), kdbSetValue(), ksClose(), and ksCompare().

int keyDup ( const Key source,
Key dest 
)

Duplicate a key in memory.

Both keys have to be initialized with keyInit(). If you have set any dynamic allocated memory for dest, make sure that you keyClose() it before keyDup().

All private attributes of the source key will be copied, including its context on a KeySet, and nothing will be shared between both keys.

Memory will be allocated as needed for dynamic properties as value, comment, etc.

Parameters:
source has to be an initializised source Key
dest will be the new copy of the Key
Returns:
0 on success
See also:
keyClose(), keyInit()

Definition at line 2572 of file key.c.

References _Key::comment, _Key::data, _Key::dataSize, _Key::flags, _Key::key, KEY_SWITCH_NEEDSYNC, keySetComment(), keySetName(), keySetOwner(), keySetRaw(), and _Key::userDomain.

int keyInit ( Key key  ) 

Initializes the Key object with some default values.

This function should not be used by backends or applications, use keyNew() instead.

keyInit() sets the key to a clear state. It uses memset to clear the memory. The type of the key is KeyType::KEY_TYPE_UNDEFINED afterwards.

uid, gid and access masks are set with the current values of your system.

keyNew() and keyDel() are better ways to deal with initialization than keyInit() and keyClose()

Example
Key *key=keyNew("system/some/name");
...
// Use the key
...
keyClose(key);
keyInit(key);
...
// Reuse the key
...
keyDel(key);
See also:
keyClose() to free the memory allocated within that function.

keyNew() and keyDel() for construction and destruction of Keys

Returns:
always 0;

Definition at line 3173 of file key.c.

References _Key::flags, _Key::gid, KEY_TYPE_UNDEFINED, keySetUAccess(), _Key::type, and _Key::uid.

Referenced by keyNew().

int keyClose ( Key key  ) 

Finishes the usage of a Key object.

The key must be keyInit() before any attempt to close it.

Frees all internally allocated memory like value, comment, and leave the Key object ready to be keyInit()ed to reuse, or deallocated.

All internal states of the key will be NULL. After this process there is no information inside the key.

keyNew() and keyDel() are better ways to deal with initialization than keyInit() and keyClose()

See also:
keyInit() how to allocate internal memory and an example

keyNew() and keyDel() for construction and destruction of Keys

Returns:
always 0;

Definition at line 3218 of file key.c.

References _Key::comment, _Key::data, _Key::key, and _Key::userDomain.

Referenced by keyDel().


Generated on Mon Dec 17 18:47:55 2007 for Elektra Project by  doxygen 1.5.4