kdb.h

00001 /***************************************************************************
00002                 kdb.h  -  Exported methods of the Elektra Library
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 BSD License (revised).                      *
00013  *                                                                         *
00014  ***************************************************************************/
00015 
00016 
00017 /* Subversion stuff
00018 
00019 $Id: kdb.h 948 2007-02-13 12:11:13Z aviram $
00020 
00021 */
00022 
00023 #ifndef KDB_H
00024 #define KDB_H
00025 
00026 
00027 /*
00028  * @defgroup general Elektra General definitions
00029  * @brief Some global definitions when using the Elektra API
00030  *
00031  */
00032 
00033 /* Windows specific stuff */
00034 #ifdef WIN32
00035 #include <windows.h>
00036 typedef unsigned char uint8_t;
00037 typedef unsigned short uint16_t;
00038 typedef unsigned int uint32_t;
00039 #define ssize_t int
00040 #define strcasecmp stricmp
00041 #define snprintf _snprintf
00042 
00043 #else /* WIN32 */
00044 /* The following file doesn't exist on windows so we need to
00045  * avoid including it */
00046 #include <inttypes.h>
00047 
00048 #endif /* WIN32 */
00049 
00050 #include <sys/types.h>
00051 #include <errno.h>
00052 #include <stdio.h>
00053 
00054 /*#define NO_REGEX_H*/ /* Uncomment to disable regex */
00055 /* Makes it possible to compile elektra without regex.
00056  * For now this has to be defined manually. */
00057 #ifndef NO_REGEX_H
00058 #include <regex.h>
00059 #else
00060 #define regex_t void
00061 #endif
00062 
00063 #define RG_KEY_DELIM            '/'
00064 
00065 
00066 /* When FORMAT_VERSION changes, FORMAT must change too. */
00067 #define RG_KEY_FORMAT_VERSION   2
00068 #define RG_KEY_FORMAT           "RG00" RG_KEY_FORMAT_VERSION
00069 
00070 
00093 enum KeyType {
00094     KEY_TYPE_UNDEFINED=0,  
00095     KEY_TYPE_DIR=1,        
00096     KEY_TYPE_LINK=2,       
00099     KEY_TYPE_BINARY=20,    
00103     KEY_TYPE_STRING=40     
00104 };
00105 
00106 
00107 
00108 
00109 
00110 
00116 enum KeyNamespace {
00117     KEY_NS_SYSTEM=1,       
00118     KEY_NS_USER=2          
00119 };
00120 
00121 
00122 
00123 /*
00124 The key flags bit array. The '.' means whatever:
00125 
00126 7654 3210 7654 3210 7654 3210 7654 3210
00127 ...1 0... .0.. .1.. ..1. ..0. ...0 1... 0x10042008 Initialized
00128 ...1 1... .1.. .1.. ..1. ..1. ...1 1... 0x18442218 Initialized mask
00129 .... .... .... .... .... .... .... ...1 0x00000001 TYPE
00130 .... .... .... .... .... .... .... ..1. 0x00000002 NAME
00131 .... .... .... .... .... .... .... .1.. 0x00000004 VALUE
00132 .... .... .... .... .... .... ..1. .... 0x00000020 DOMAIN
00133 .... .... .... .... .... .... .1.. .... 0x00000040 COMMENT
00134 .... .... .... .... .... .... 1... .... 0x00000060 UID
00135 .... .... .... .... .... ...1 .... .... 0x00000080 GID
00136 .... .... .... .... .... .1.. .... .... 0x00000400 PRM
00137 .... .... .... .... .... 1... .... .... 0x00000800 TIME
00138 .... .... .... .... ...1 .... .... .... 0x00001000 NEEDSYNC
00139 .... .... .... .... .1.. .... .... .... 0x00004000 ACTIVE ***DEPRECATED***
00140 .... .... 1... .... .... .... .... .... 0x00800000 ISSYSTEM
00141 .... ...1 .... .... .... .... .... .... 0x01000000 ISUSER
00142 1... .... .... .... .... .... .... .... 0x80000000 FLAG (general flag)
00143 */
00144 
00145 
00146 
00156 enum KeySwitch {
00157     KEY_SWITCH_TYPE=1,          
00158     KEY_SWITCH_NAME=1<<1,       
00159     KEY_SWITCH_VALUE=1<<2,      
00160     /* do not use 1<<3 see INITMASK */
00161     /* do not use 1<<4 see INITMASK */
00162     KEY_SWITCH_OWNER=1<<5,      
00163     KEY_SWITCH_DOMAIN=KEY_SWITCH_OWNER, 
00164     KEY_SWITCH_COMMENT=1<<6,    
00165     KEY_SWITCH_UID=1<<7,        
00166     KEY_SWITCH_GID=1<<8,        
00167     /* do not use 1<<9 see INITMASK */
00168     KEY_SWITCH_MODE=1<<10,      
00169     KEY_SWITCH_TIME=1<<11,      
00170     KEY_SWITCH_NEEDSYNC=1<<12,  
00171     /* do not use 1<<13 see INITMASK */
00172     KEY_SWITCH_ACTIVE=1<<14,    /* ****deprecated**** */
00173     KEY_SWITCH_UMODE=1<<15,     
00174     /* do not use 1<<18 see INITMASK */
00175     /* do not use 1<<22 see INITMASK */
00176     KEY_SWITCH_ISSYSTEM=1<<23,  
00177     KEY_SWITCH_ISUSER=1<<24,    
00178     /* do not use 1<<27 see INITMASK */
00179     /* do not use 1<<28 see INITMASK */
00180     KEY_SWITCH_FLAG=1<<31,      
00182     KEY_SWITCH_END=0,           
00185     KEY_SWITCH_INITIALIZED=0x10042008,
00186     KEY_SWITCH_INITMASK=0x18442218
00187 };
00188 
00189 
00190 
00191 /*
00192  * Deprecated flag names, here for legacy compatibility.
00193  * Will be removed in the future.
00194  * Use KeySwitches above instead.
00195  */
00196 enum KeyFlags {                                       /* _DEPRECATED_ */
00197     KEY_FLAG_HASTYPE      = KEY_SWITCH_TYPE,          /* _DEPRECATED_ */
00198     KEY_FLAG_HASKEY       = KEY_SWITCH_NAME,          /* _DEPRECATED_ */
00199     KEY_FLAG_HASDATA      = KEY_SWITCH_VALUE,         /* _DEPRECATED_ */
00200     KEY_FLAG_HASDOMAIN    = KEY_SWITCH_DOMAIN,        /* _DEPRECATED_ */
00201     KEY_FLAG_HASCOMMENT   = KEY_SWITCH_COMMENT,       /* _DEPRECATED_ */
00202     KEY_FLAG_HASUID       = KEY_SWITCH_UID,           /* _DEPRECATED_ */
00203     KEY_FLAG_HASGID       = KEY_SWITCH_GID,           /* _DEPRECATED_ */
00204     KEY_FLAG_HASPRM       = KEY_SWITCH_MODE,          /* _DEPRECATED_ */
00205     KEY_FLAG_HASTIME      = KEY_SWITCH_TIME,          /* _DEPRECATED_ */
00206     KEY_FLAG_NEEDSYNC     = KEY_SWITCH_NEEDSYNC,      /* _DEPRECATED_ */
00207     KEY_FLAG_FLAG         = KEY_SWITCH_FLAG,          /* _DEPRECATED_ */
00208     KEY_FLAG_INITIALIZED  = KEY_SWITCH_INITIALIZED,   /* _DEPRECATED_ */
00209     KEY_FLAG_INITMASK     = KEY_SWITCH_INITMASK       /* _DEPRECATED_ */
00210 };                                                    /* _DEPRECATED_ */
00211 
00212 
00213 
00231 enum KDBErr {
00232     KDB_RET_OK=0,                 
00235     /* Errors related to invalid/uninitialized objects */
00236     KDB_RET_NULLKEY=EINVAL,       
00237     KDB_RET_UNINITIALIZED=EINVAL, 
00239     /* Errors related to bad key names or keys not found */
00240     KDB_RET_NOTFOUND=ENOENT,      
00241     KDB_RET_INVALIDKEY=1001, 
00244     /* Errors related to empty internal key properties */
00245     KDB_RET_NOKEY=1002,        
00246     KDB_RET_NODATA=1003,       
00247     KDB_RET_NODESC=1004,       
00248     KDB_RET_NODOMAIN=1005,     
00249     KDB_RET_NOGROUP=1006,      
00250     KDB_RET_NOTIME=1007,       
00253     /* Errors related to permissions, no memory or failed internal operations */
00254     KDB_RET_NOCRED=EACCES,       
00255     KDB_RET_TRUNC=ERANGE,        
00256     KDB_RET_NOMEM=ENOMEM,        
00257     KDB_RET_TYPEMISMATCH=1008,   
00260     /* Errors related to backend access or opening */
00261     KDB_RET_NOSYS=ENOSYS,        
00262     KDB_RET_EBACKEND=1009        
00263 };
00264 
00265 
00275 enum KDBOptions {
00276     KDB_O_RECURSIVE=1,       
00277     KDB_O_DIR=1<<1,          
00278     KDB_O_DIRONLY=1<<2,      
00279     KDB_O_NOEMPTY=1<<3,      /* unused. */
00280     KDB_O_STATONLY=1<<4,     
00281     KDB_O_INACTIVE=1<<5,     
00283     KDB_O_SORT=1<<6,         
00284     KDB_O_NFOLLOWLINK=1<<7,  
00286 /* XML exporting options for keyToStrem() and ksToStream() */
00287     KDB_O_CONDENSED=1<<8,    
00288     KDB_O_NUMBERS=1<<9,      
00289     KDB_O_XMLHEADERS=1<<10,  
00290     KDB_O_FULLNAME=1<<11,    
00292     KDB_O_FULLUGID=1<<12,    
00295     KDB_O_HIER=1<<13,        
00299 /* Options used by ksLookupRE() methods */
00300     KDB_O_NOCASE=1<<15,      
00301     KDB_O_NOSPANPARENT=1<<16,
00303     KDB_O_ALL=1<<17,         
00307 /* Obsolete/renamed options */
00308     KDB_O_NOVALUE  = KDB_O_DIRONLY,
00309     KDB_O_LOOP     = KDB_O_ALL
00310 
00311 };
00312 
00313 
00314 /* Key Name Anatomy
00315 
00316 Key::key is the key name. It is a unique identifier for a kdb key.
00317 An exmaple of a complex key name is:
00318 
00319     user:some.user/My Environment/SOME.VAR
00320 
00321 From this example:
00322   Root name = "user:some.user"
00323       Owner = "some.user"
00324   Base name = "SOME.VAR"
00325 Parent name = "user:some.user/My Environment"
00326 
00327 */
00328 
00329 
00330 
00331 
00332 
00333 typedef struct _Key       Key;
00334 typedef struct _KeySet    KeySet;
00335 
00336 #ifndef KDBBACKEND_H
00337 /* If we are not in a backend implementation context... */
00338 typedef void *            KDBHandle;
00339 #endif
00340 
00352 typedef struct _KDBInfo {
00353     /* all members are pointers because we'll point only to pre-allocated
00354        or static strings. We won't allocate nothing for each member. */
00355     char *version;             
00356     char *backendName;         
00358     uint8_t backendIsOpen;     
00360 } KDBInfo;
00361 
00362 
00363 
00364 
00365 #ifdef __cplusplus
00366 extern "C" {
00367 #endif
00368 
00369 
00370 /**************************************
00371 
00372 KeyDB methods
00373 
00374 ***************************************/
00375 
00376 int kdbOpen(KDBHandle *handle);
00377 int kdbOpenDefault(KDBHandle *handle);
00378 int kdbOpenBackend(KDBHandle *handle, char *backendName);
00379 int kdbClose(KDBHandle *handle);
00380 
00381 int kdbGetValue(KDBHandle handle, const char *keyname, char *returned,
00382     size_t maxSize);
00383 int kdbGetKeyByParent(KDBHandle handle, const char *parentName,
00384     const char *baseName, Key *returned);
00385 int kdbGetKeyByParentKey(KDBHandle handle, const Key *parent,
00386     const char *baseName, Key *returned);
00387 int kdbGetValueByParent(KDBHandle handle, const char *parentName,
00388     const char *baseName, char *returned, size_t maxSize);
00389 
00390 int kdbSetValue(KDBHandle handle, const char *keyname, const char *value);
00391 int kdbSetValueByParent(KDBHandle handle, const char *parentName,
00392     const char *baseName, const char *value);
00393 
00394 int kdbRename(KDBHandle handle, Key *key, const char *newName);
00395 int kdbRemove(KDBHandle handle, const char *keyName);
00396 int kdbRemoveKey(KDBHandle handle, const Key *key);
00397 int kdbLink(KDBHandle handle, const char *oldPath, const char *newKeyName);
00398 
00399 int kdbGetKeyByParent(KDBHandle handle, const char *parentName,
00400     const char *baseName, Key *returned);
00401 int kdbGetKeyByParentKey(KDBHandle handle, const Key *parent,
00402     const char *basename, Key *returned);
00403 int kdbGetValueByParent(KDBHandle handle, const char *parentName,
00404     const char *baseName, char *returned, size_t maxSize);
00405 
00406 
00407 int kdbStatKey(KDBHandle handle, Key *key);
00408 int kdbGetKey(KDBHandle handle, Key *key);
00409 int kdbSetKey(KDBHandle handle, Key *key);
00410 
00411 ssize_t kdbGetKeyChildKeys(KDBHandle handle, const Key *parentName,
00412     KeySet *returned, unsigned long options);
00413 ssize_t kdbGetChildKeys(KDBHandle handle, const char *parentName,
00414     KeySet *returned, unsigned long options);
00415 ssize_t kdbGetRootKeys(KDBHandle handle, KeySet *returned);
00416 
00417 int kdbSetKeys(KDBHandle handle, KeySet *ks);
00418 
00419 uint32_t kdbMonitorKey(KDBHandle handle, Key *interest, uint32_t diffMask,
00420     unsigned long iterations, unsigned usleep);
00421 uint32_t kdbMonitorKeys(KDBHandle handle, KeySet *interests, uint32_t diffMask,
00422     unsigned long iterations, unsigned sleep);
00423 
00424 KDBInfo *kdbGetInfo(KDBHandle handle);
00425 void kdbFreeInfo(KDBInfo *info);
00426 int kdbInfoToString(KDBInfo *info,char *string,size_t maxSize);
00427 
00428 
00429 /**************************************
00430 
00431 Error manipulation methods
00432 
00433 ***************************************/
00434 
00435 
00436 char *kdbStrError(int errnum);
00437 int kdbPrintError(const char * msg);
00438 
00439 
00440 
00441 
00442 /**************************************
00443 
00444 Key methods
00445 
00446 ***************************************/
00447 
00448 int keyInit(Key *key);
00449 int keyClose(Key *key);
00450 
00451 Key *keyNew(const char *keyName, ...);
00452 int keyDel(Key *key);
00453 #define keyFree(x) keyDel(x)
00454 
00455 int keyIsInitialized(const Key *key);
00456 int keyNeedsSync(const Key *key);
00457 int keyDup(const Key *source,Key *dest);
00458 
00459 /* int keySerialize(const Key *key,void *buffer, size_t maxSize);
00460 int keyUnserialize(Key *key,const void *buffer); 
00461 size_t keyGetSerializedSize(const Key *key); */
00462 
00463 uint8_t keyGetType(const Key *key);
00464 uint8_t keySetType(Key *key,uint8_t type);
00465 uint8_t keySetDir(Key *key,mode_t customUmask);
00466 
00467 int keySetFlag(Key *key);
00468 int keyClearFlag(Key *key);
00469 int keyGetFlag(const Key *key);
00470 
00471 ssize_t keyGetRecordSize(const Key *key);
00472 ssize_t keyGetNameSize(const Key *key);
00473 ssize_t keyGetFullNameSize(const Key *key);
00474 
00475 ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize);
00476 char *keyStealName(const Key *key);
00477 ssize_t keySetName(Key *key, const char *newName);
00478 
00479 ssize_t keyGetFullName(const Key *key, char *returnedName, size_t maxSize);
00480 ssize_t keyGetRootName(const Key *key, char *returned, size_t maxSize);
00481 ssize_t keyGetFullRootName(const Key *key, char *returned, size_t maxSize);
00482 
00483 ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize);
00484 char *keyStealBaseName(const Key *key);
00485 ssize_t keyNameGetBaseNameSize(const char *keyName);
00486 ssize_t keyGetBaseNameSize(const Key *key);
00487 ssize_t keyAddBaseName(Key *key,const char *baseName);
00488 ssize_t keySetBaseName(Key *key,const char *baseName);
00489 
00490 char *keyNameGetOneLevel(const char *keyName, size_t *size);
00491 ssize_t keyGetParentName(const Key *key, char *returned, size_t maxSize);
00492 ssize_t keyGetParentNameSize(const Key *key);
00493 
00494 ssize_t keyNameGetRootNameSize(const char *keyName);
00495 ssize_t keyGetRootNameSize(const Key *key);
00496 
00497 ssize_t keyNameGetFullRootNameSize(const char *keyName);
00498 ssize_t keyGetFullRootNameSize(const Key *key);
00499 
00500 ssize_t keyGetCommentSize(const Key *key);
00501 ssize_t keyGetComment(const Key *key, char *returnedDesc, size_t maxSize);
00502 char *keyStealComment(const Key *key);
00503 ssize_t keySetComment(Key *key, const char *newDesc);
00504 
00505 uid_t keyGetUID(const Key *key);
00506 int keySetUID(Key *key, uid_t uid);
00507 
00508 gid_t keyGetGID(const Key *key);
00509 int keySetGID(Key *key, gid_t gid);
00510 
00511 mode_t keyGetAccess(const Key *key);
00512 int keySetAccess(Key *key, mode_t mode);
00513 int keySetUAccess(Key *key, mode_t umask);
00514 
00515 ssize_t keyGetOwnerSize(const Key *key);
00516 ssize_t keyGetOwner(const Key *key, char *returned, size_t maxSize);
00517 char *keyStealOwner(const Key *key);
00518 ssize_t keySetOwner(Key *key, const char *userDomain);
00519 
00520 
00521 ssize_t keyGetValueSize(const Key *key);
00522 ssize_t keyGetDataSize(const Key *key);
00523 
00524 ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
00525 ssize_t keySetString(Key *key, const char *newString);
00526 void *keyStealValue(const Key *key);
00527 
00528 ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
00529 ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);
00530 
00531 ssize_t keySetRaw(Key *key, const void *newBinary, size_t dataSize);
00532 
00533 ssize_t keyGetLink(const Key *key, char *returnedTarget, size_t maxSize);
00534 ssize_t keySetLink(Key *key, const char *target);
00535 
00536 time_t keyGetMTime(const Key *key);
00537 time_t keyGetATime(const Key *key);
00538 time_t keyGetCTime(const Key *key);
00539 
00540 int keyIsSystem(const Key *key);
00541 int keyNameIsSystem(const char *keyName);
00542 
00543 int keyIsUser(const Key *key);
00544 int keyNameIsUser(const char *keyName);
00545 
00546 int keyGetNamespace(const Key *key);
00547 int keyNameGetNamespace(const char *keyName);
00548 
00549 int keyIsDir(const Key *key);
00550 int keyIsLink(const Key *key);
00551 int keyIsBin(const Key *key);
00552 int keyIsString(const Key *key);
00553 
00554 Key *keyNext(Key *key);
00555 
00556 uint32_t keyCompare(const Key *key1, const Key *key2);
00557 
00558 ssize_t keyToStream(const Key *key, FILE* stream, unsigned long options);
00559 ssize_t keyToStreamBasename(const Key *key, FILE* stream,
00560     const char *parent, const size_t parentSize, unsigned long options);
00561 
00562 /*
00563 void *keySerialize(Key *key);
00564 Key *keyUnserialize(void *serialized);
00565 */
00566 
00567 /**************************************
00568 
00569 KeySet methods
00570 
00571 ***************************************/
00572 
00573 KeySet *ksNew();
00574 int ksDel(KeySet *ks);
00575 #define ksFree(x) ksDel(x)
00576 
00577 int ksInit(KeySet *ks);
00578 int ksClose(KeySet *ks);
00579 ssize_t ksGetSize(KeySet *ks);
00580 
00581 ssize_t ksInsert(KeySet *ks, Key *toInsert);
00582 ssize_t ksAppend(KeySet *ks, Key *toAppend);
00583 Key *ksPop(KeySet *ks);
00584 Key *ksPopLast(KeySet *ks);
00585 
00586 ssize_t ksInsertKeys(KeySet *ks, KeySet *toInsert);
00587 ssize_t ksAppendKeys(KeySet *ks, KeySet *toAppend);
00588 
00589 ssize_t ksToStream(const KeySet *ks, FILE* stream, unsigned long options);
00590 ssize_t ksGetCommonParentName(const KeySet *ks,char *returnedCommonParent,
00591     const size_t maxSize);
00592 int ksCompare(KeySet *ks1, KeySet *ks2, KeySet *removed);
00593 void ksSort(KeySet *ks);
00594 
00595 Key *ksLookupByName(KeySet *ks, const char *name,unsigned long options);
00596 Key *ksLookupByValue(KeySet *ks, const char *value,unsigned long options);
00597 Key *ksLookupByBinaryValue(KeySet *ks, void *value, size_t size,
00598     unsigned long options);
00599 uint32_t ksLookupRE(KeySet *ks, uint32_t where,
00600     const regex_t *regexp, unsigned long options);
00601     
00602 int ksRewind(KeySet *ks);
00603 Key *ksNext(KeySet *ks);
00604 Key *ksCurrent(const KeySet *ks);
00605 
00606 Key *ksHead(KeySet *ks);
00607 Key *ksTail(KeySet *ks);
00608 
00609 
00610 
00611 
00612 
00613 /***************************************
00614 
00615 Helpers
00616 
00617 ***************************************/
00618 
00619 
00620 size_t strblen(const char *s);
00621 
00622 #ifdef __cplusplus
00623 }
00624 #endif
00625 
00626 
00627 #endif /* KDB_H */

Generated on Sun Mar 25 21:37:09 2007 for Elektra Project by  doxygen 1.5.1