Main Page | Modules | File List

kdb.h

00001 /***************************************************************************
00002                 kdb.h  -  Exported methods of the Elektra Project
00003                              -------------------
00004     begin                : Mon Dec 29 2003
00005     copyright            : (C) 2003 by Avi Alkalay
00006     email                : avi@unix.sh
00007  ***************************************************************************/
00008 
00009 /***************************************************************************
00010  *                                                                         *
00011  *   This program is free software; you can redistribute it and/or modify  *
00012  *   it under the terms of the GNU General Public License as published by  *
00013  *   the Free Software Foundation; either version 2 of the License, or     *
00014  *   (at your option) any later version.                                   *
00015  *                                                                         *
00016  ***************************************************************************/
00017 
00018 
00019 /* Subversion stuff
00020 
00021 $Id: kdb.h 92 2004-10-18 02:41:15Z aviram $
00022 $LastChangedBy: aviram $
00023 
00024 */
00025 
00026 #ifndef KDB_H
00027 #define KDB_H
00028 
00029 
00030 
00031 /*
00032  * @defgroup general Elektra General definitions
00033  * @brief Some global definitions when using the Elektra API
00034  *
00035  */
00036 
00037 
00038 
00039 #include <sys/types.h>
00040 #include <errno.h>
00041 #include <stdio.h>
00042 
00043 #define RG_KEY_DELIM            '/'
00044 
00045 
00046 /* When FORMAT_VERSION changes, FORMAT must change also. */
00047 #define RG_KEY_FORMAT_VERSION   2
00048 #define RG_KEY_FORMAT           "RG002"
00049 
00050 
00072 enum KeyType {
00073     KEY_TYPE_UNDEFINED=0, 
00074     KEY_TYPE_DIR=1, 
00075     KEY_TYPE_LINK=2, 
00078     KEY_TYPE_BINARY=20, 
00082     KEY_TYPE_STRING=40 
00083 };
00084 
00085 
00086 
00087 
00088 
00089 
00097 enum KeyNamespace {
00098     KEY_NS_SYSTEM=1,  
00099     KEY_NS_USER=2  
00100 };
00101 
00102 
00103 
00104 /*
00105 The key flags bit array. The '.' means whatever:
00106 
00107 7654 3210 7654 3210 7654 3210 7654 3210
00108 ...1 0... .0.. .1.. ..1. ..0. ...0 1... 0x10042008 Initialized
00109 ...1 1... .1.. .1.. ..1. ..1. ...1 1... 0x18442218 Initialized mask
00110 .... .... .... .... .... .... .... ...1 0x00000001 HASTYPE
00111 .... .... .... .... .... .... .... ..1. 0x00000002 HASKEY
00112 .... .... .... .... .... .... .... .1.. 0x00000004 HASDATA
00113 .... .... .... .... .... .... ..1. .... 0x00000020 HASDOMAIN
00114 .... .... .... .... .... .... .1.. .... 0x00000040 HASCOMMENT
00115 .... .... .... .... .... .... 1... .... 0x00000060 HASUID
00116 .... .... .... .... .... ...1 .... .... 0x00000080 HASGID
00117 .... .... .... .... .... .1.. .... .... 0x00000400 HASPRM
00118 .... .... .... .... .... 1... .... .... 0x00000800 HASTIME
00119 .... .... .... .... ...1 .... .... .... 0x00001000 NEEDSYNC
00120 .... .... .... .... .1.. .... .... .... 0x00004000 ACTIVE ***DEPRECATED***
00121 1... .... .... .... .... .... .... .... 0x80000000 FLAG (general flag)
00122 */
00123 
00124 
00125 
00134 enum KeyFlags {
00135     KEY_FLAG_INITIALIZED=0x10042008,
00136     KEY_FLAG_INITMASK=0x18442218,
00137 
00138     KEY_FLAG_HASTYPE=1,       
00139     KEY_FLAG_HASKEY=1<<1,     
00140     KEY_FLAG_HASDATA=1<<2,    
00141     KEY_FLAG_HASDOMAIN=1<<5,  
00142     KEY_FLAG_HASCOMMENT=1<<6, 
00143     KEY_FLAG_HASUID=1<<7,     
00144     KEY_FLAG_HASGID=1<<8,     
00145     KEY_FLAG_HASPRM=1<<10,    
00146     KEY_FLAG_HASTIME=1<<11,   
00147     KEY_FLAG_NEEDSYNC=1<<12,  
00148     KEY_FLAG_ACTIVE=1<<14,  /* ****deprecated**** */
00149     KEY_FLAG_FLAG=1<<31,      
00151 };
00152 
00153 
00154 
00167 enum KDBErr {
00168     KDB_RET_OK=0,                 
00169     KDB_RET_NULLKEY=EINVAL,       
00170     KDB_RET_UNINITIALIZED=EINVAL, 
00171     KDB_RET_NOKEY=ENOMSG,         
00172     KDB_RET_NODATA=ENOMSG,        
00173     KDB_RET_NOGROUP=ENOMSG,       
00174     KDB_RET_NODESC=ENOMSG,        
00175     KDB_RET_NODOMAIN=ENOMSG,      
00176     KDB_RET_NOCRED=EACCES,        
00177     KDB_RET_NOTIME=ENOMSG,        
00178     KDB_RET_TRUNC=ENOBUFS,        
00179     KDB_RET_TYPEMISMATCH=EILSEQ,  
00180     KDB_RET_INVALIDKEY=EAFNOSUPPORT, 
00181     KDB_RET_NOTFOUND=ENOENT,      
00182 };
00183 
00184 
00194 enum KDBOptions {
00195     KDB_O_RECURSIVE=1,      
00196     KDB_O_DIR=1<<1,         
00197     KDB_O_NOVALUE=1<<2,     
00198     KDB_O_NOEMPTY=1<<3,     /* unused ???? */
00199     KDB_O_STATONLY=1<<4,    
00200     KDB_O_INACTIVE=1<<5,    
00201     KDB_O_SORT=1<<6,        
00202     KDB_O_NFOLLOWLINK=1<<7, 
00204 /* XML exporting options for keytoStrem() */
00205     KDB_O_CONDENSED=1<<8,   
00206     KDB_O_NUMBERS=1<<9,     
00207     KDB_O_XMLHEADERS=1<<10, 
00208 };
00209 
00210 
00211 typedef struct _Key {
00212      u_int8_t      type;        /* data type */
00213         uid_t      uid;         /* owner user ID */
00214         uid_t      gid;         /* owner group ID */
00215        mode_t      access;      /* access control */
00216        time_t      atime;       /* time for last access */
00217        time_t      mtime;       /* time for last modidification */
00218        time_t      ctime;       /* time for last change (meta info) */
00219        size_t      commentSize; /* size of the description string */
00220        size_t      dataSize;    /* size of the value */
00221        size_t      recordSize;  /* dataSize + commentSize + control */
00222     u_int32_t      flags;       /* Some control flags */
00223        char *      key;         /* The name of the key */
00224        char *      comment;     /* A comment about this key-value pair */
00225        char *      userDomain;  /* User domain */
00226        void *      data;        /* The value */
00227     struct _Key *  next;
00228 } Key;
00229 
00230 
00231 
00232 /* Key Name Anatomy
00233 
00234 Key::key is the key name. It is a unique identifier for a kdb key.
00235 An exmaple of a complex key name is:
00236 
00237     user:some.user/My Environment/SOME.VAR
00238 
00239 From this example:
00240   Root name = "user:some.user"
00241       Owner = "some.user"
00242   Base name = "SOME.VAR"
00243 Parent name = "user:some.user/My Environment"
00244 
00245 */
00246 
00247 
00248 
00249 
00250 
00251 typedef struct _KeySet {
00252     Key *          start;
00253     Key *          end;
00254     Key *          cursor;
00255     size_t         size;
00256 } KeySet;
00257 
00258 
00259 
00260 
00261 
00262 /**************************************
00263 
00264 KeyDB methods
00265 
00266 ***************************************/
00267 
00268 int kdbOpen();
00269 int kdbClose();
00270 
00271 int kdbGetValue(const char *keyname, char *returned,size_t maxSize);
00272 int kdbGetKeyByParent(const char *parentName, const char *baseName, Key *returned);
00273 int kdbGetKeyByParentKey(const Key *parent, const char *baseName, Key *returned);
00274 int kdbGetValueByParent(const char *parentName, const char *baseName, char *returned,
00275     size_t maxSize);
00276 
00277 int kdbSetValue(const char *keyname, const char *value);
00278 int kdbSetValueByParent(const char *parentName, const char *baseName, const char *value);
00279 
00280 int kdbRemove(const char *keyName);
00281 int kdbLink(const char *oldPath, const char *newKeyName);
00282 
00283 int kdbGetKeyByParent(const char *parentName, const char *baseName, Key *returned);
00284 int kdbGetKeyByParentKey(const Key *parent, const char *basename, Key *returned);
00285 int kdbGetValueByParent(const char *parentName, const char *baseName, char *returned,
00286     size_t maxSize);
00287 
00288 int kdbGetComment(const char *keyname, char *returned, size_t maxSize);
00289 size_t kdbSetComment(const char *keyname, const char *comment);
00290 
00291 int kdbStatKey(Key *key);
00292 int kdbGetKey(Key *key);
00293 int kdbSetKey(Key *key);
00294 
00295 int kdbGetChildKeys(const char *parent, KeySet *returned, unsigned long options);
00296 int kdbGetRootKeys(KeySet *returned);
00297 
00298 int kdbSetKeys(KeySet *ks);
00299 
00300 u_int32_t kdbMonitorKey(Key *interest, u_int32_t diffMask,
00301     unsigned long iterations, unsigned usleep);
00302 u_int32_t kdbMonitorKeys(KeySet *interests, u_int32_t diffMask,
00303     unsigned long iterations, unsigned sleep);
00304 
00305 
00306 
00307 
00308 
00309 
00310 /**************************************
00311 
00312 Key methods
00313 
00314 ***************************************/
00315 
00316 int keyInit(Key *key);
00317 int keyClose(Key *key);
00318 
00319 int keyIsInitialized(const Key *key);
00320 int keyNeedsSync(const Key *key);
00321 int keyDup(const Key *source,Key *dest);
00322 
00323 int keySerialize(const Key *key,void *buffer, size_t maxSize);
00324 int keyUnserialize(Key *key,const void *buffer);
00325 size_t keyGetSerializedSize(const Key *key);
00326 
00327 u_int8_t keyGetType(const Key *key);
00328 u_int8_t keySetType(Key *key,u_int8_t type);
00329 
00330 int keySetFlag(Key *key);
00331 int keyClearFlag(Key *key);
00332 int keyGetFlag(const Key *key);
00333 
00334 size_t keyGetRecordSize(const Key *key);
00335 size_t keyGetNameSize(const Key *key);
00336 size_t keyGetFullNameSize(const Key *key);
00337 
00338 size_t keyGetName(const Key *key, char *returnedName, size_t maxSize);
00339 size_t keySetName(Key *key, const char *newName);
00340 
00341 size_t keyGetFullName(const Key *key, char *returnedName, size_t maxSize);
00342 size_t keyGetRootName(const Key *key, char *returned, size_t maxSize);
00343 size_t keyGetFullRootName(const Key *key, char *returned, size_t maxSize);
00344 
00345 size_t keyGetBaseName(const Key *key, char *returned, size_t maxSize);
00346 size_t keyNameGetBaseNameSize(const char *keyName);
00347 size_t keyGetBaseNameSize(const Key *key);
00348 
00349 size_t keyNameGetRootNameSize(const char *keyName);
00350 size_t keyGetRootNameSize(const Key *key);
00351 size_t keyGetFullRootNameSize(const Key *key);
00352 
00353 
00354 size_t keyGetCommentSize(const Key *key);
00355 size_t keyGetComment(const Key *key, char *returnedDesc, size_t maxSize);
00356 size_t keySetComment(Key *key, const char *newDesc);
00357 
00358 uid_t keyGetUID(const Key *key);
00359 int keySetUID(Key *key, uid_t uid);
00360 
00361 gid_t keyGetGID(const Key *key);
00362 int keySetGID(Key *key, gid_t gid);
00363 
00364 mode_t keyGetAccess(const Key *key);
00365 int keySetAccess(Key *key, mode_t mode);
00366 
00367 size_t keyGetOwnerSize(const Key *key);
00368 size_t keyGetOwner(const Key *key, char *returned, size_t maxSize);
00369 size_t keySetOwner(Key *key, const char *userDomain);
00370 
00371 
00372 size_t keyGetDataSize(const Key *key);
00373 
00374 size_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
00375 size_t keySetString(Key *key, const char *newString);
00376 
00377 size_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
00378 size_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);
00379 
00380 size_t keyGetLink(const Key *key, char *returnedTarget, size_t maxSize);
00381 size_t keySetLink(Key *key, const char *target);
00382 
00383 time_t keyGetMTime(const Key *key);
00384 time_t keyGetATime(const Key *key);
00385 time_t keyGetCTime(const Key *key);
00386 
00387 size_t keyGetParentName(const Key *key, char *returned, size_t maxSize);
00388 
00389 size_t keyToString(const Key *key, char *returned, size_t maxSize);
00390 
00391 int keyIsSystem(const Key *key);
00392 int keyNameIsSystem(const char *keyName);
00393 
00394 int keyIsUser(const Key *key);
00395 int keyNameIsUser(const char *keyName);
00396 
00397 int keyGetNamespace(const Key *key);
00398 int keyNameGetNamespace(const char *keyName);
00399 
00400 int keyIsDir(const Key *key);
00401 int keyIsLink(const Key *key);
00402 
00403 u_int32_t keyCompare(const Key *key1, const Key *key2);
00404 
00405 size_t keyToStream(const Key *key, FILE* stream, unsigned long options);
00406 
00407 
00408 /**************************************
00409 
00410 KeySet methods
00411 
00412 ***************************************/
00413 
00414 int ksInit(KeySet *ks);
00415 int ksClose(KeySet *ks);
00416 size_t ksGetSize(KeySet *ks);
00417 
00418 size_t ksInsert(KeySet *ks, Key *toInsert);
00419 size_t ksAppend(KeySet *ks, Key *toAppend);
00420 
00421 size_t ksInsertKeys(KeySet *ks, KeySet *toInsert);
00422 size_t ksAppendKeys(KeySet *ks, KeySet *toAppend);
00423 
00424 size_t ksToStream(const KeySet *ks, FILE* stream, unsigned long options);
00425 int ksCompare(KeySet *ks1, KeySet *ks2, KeySet *removed);
00426 
00427 int ksRewind(KeySet *ks);
00428 Key *ksNext(KeySet *ks);
00429 Key *ksCurrent(const KeySet *ks);
00430 
00431 
00432 // Key *ksLookupByName(KeySet *ks,char *keyName);
00433 // Key *ksLookupByRegex(KeySet *ks,regex_t *regex);
00434 
00435 
00436 
00437 
00438 /***************************************
00439 
00440 Helpers
00441 
00442 ***************************************/
00443 
00444 
00445 size_t strblen(const char *s);
00446 
00447 
00448 #endif /* KDB\_H */

Generated on Thu Aug 4 03:37:07 2005 for Elektra Project by doxygen 1.3.5