The qDecoder Project

qEntry.c File Reference

Linked-list Data Structure API. More...


Functions

Q_ENTRYqEntry (void)
 Create new Q_ENTRY linked-list object.
static void _lock (Q_ENTRY *entry)
 Q_ENTRY->lock(): Enter critical section.
static void _unlock (Q_ENTRY *entry)
 Q_ENTRY->unlock(): Leave critical section.
static bool _put (Q_ENTRY *entry, const char *name, const void *data, size_t size, bool replace)
 Q_ENTRY->put(): Store object into linked-list structure.
static bool _putStr (Q_ENTRY *entry, const char *name, const char *str, bool replace)
 Q_ENTRY->putStr(): Add string object into linked-list structure.
static bool _putStrf (Q_ENTRY *entry, bool replace, const char *name, const char *format,...)
 Q_ENTRY->putStrf(): Add formatted string object into linked-list structure.
static bool _putStrParsed (Q_ENTRY *entry, const char *name, const char *str, bool replace)
 Q_ENTRY->putStrParsed(): Add string object with parsed into linked-list structure.
static bool _putInt (Q_ENTRY *entry, const char *name, int num, bool replace)
 Q_ENTRY->putInt(): Add integer object into linked-list structure.
static void * _get (Q_ENTRY *entry, const char *name, size_t *size, bool newmem)
 Q_ENTRY->get(): Find object with given name.
static void * _getCase (Q_ENTRY *entry, const char *name, size_t *size, bool newmem)
 Q_ENTRY->getCase(): Find object with given name.
static void * _getLast (Q_ENTRY *entry, const char *name, size_t *size, bool newmem)
 Q_ENTRY->getLast(): Find lastest matched object with given name.
static char * _getStr (Q_ENTRY *entry, const char *name, bool newmem)
 Q_ENTRY->getStr(): Find string object with given name.
static char * _getStrf (Q_ENTRY *entry, bool newmem, const char *namefmt,...)
 Q_ENTRY->_getStrf(): Find string object with given formatted name.
static char * _getStrCase (Q_ENTRY *entry, const char *name, bool newmem)
 Q_ENTRY->getStrCase(): Find string object with given name.
static char * _getStrLast (Q_ENTRY *entry, const char *name, bool newmem)
 Q_ENTRY->getStrLast(): Find lastest matched string object with given name.
static int _getInt (Q_ENTRY *entry, const char *name)
 Q_ENTRY->getInt(): Find integer object with given name.
static int _getIntCase (Q_ENTRY *entry, const char *name)
 Q_ENTRY->getIntCase(): Find integer object with given name.
static int _getIntLast (Q_ENTRY *entry, const char *name)
 Q_ENTRY->getIntLast(): Find lastest matched integer object with given name.
static bool _getNext (Q_ENTRY *entry, Q_NLOBJ_T *obj, const char *name, bool newmem)
 Q_ENTRY->getNext(): Get next object structure.
static int _remove (Q_ENTRY *entry, const char *name)
 Q_ENTRY->remove(): Remove matched objects as given name.
static int _getNum (Q_ENTRY *entry)
 Q_ENTRY->getNum(): Get total number of stored objects.
static int _getNo (Q_ENTRY *entry, const char *name)
 Q_ENTRY->getNo(): Get stored logical sequence number for the object.
static char * _parseStr (Q_ENTRY *entry, const char *str)
 Q_ENTRY->parseStr(): Parse string with given entries.
static void * _merge (Q_ENTRY *entry, size_t *size)
 Q_ENTRY->merge(): Merge all objects data into single object.
static bool _truncate (Q_ENTRY *entry)
 Q_ENTRY->truncate(): Truncate Q_ENTRY.
static bool _save (Q_ENTRY *entry, const char *filepath, char sepchar, bool encode)
 Q_ENTRY->save(): Save Q_ENTRY as plain text format.
static int _load (Q_ENTRY *entry, const char *filepath, char sepchar, bool decode)
 Q_ENTRY->load(): Load and append entries from given filepath.
static bool _reverse (Q_ENTRY *entry)
 Q_ENTRY->reverse(): Reverse-sort internal stored object.
static bool _print (Q_ENTRY *entry, FILE *out, bool print_data)
 Q_ENTRY->print(): Print out stored objects for debugging purpose.
static bool _free (Q_ENTRY *entry)
 Q_ENTRY->free(): Free Q_ENTRY.


Detailed Description

Linked-list Data Structure API.

   [Code sample - String]

   // sample data
   struct MY_OBJ *my_obj = getNewMyOjb(); // sample object
   char *my_str = "hello"; // sample string
   int my_int = 1; // sample integer

   // store into linked-list
   Q_ENTRY *entry = qEntry();
   entries = entry->put(entry, "obj", (void*)my_obj, sizeof(struct MY_OBJ), true);
   entries = entry->putStr(entry, "obj", my_str, true);
   entries = entry->putInt(entry, "obj", my_int, true);

   // print out
   entry->print(entry, stdout, false);

   // free object
   entry->free(entry);

   [Result]

Note:
Use "--enable-threadsafe" configure script option to use under multi-threaded environments.

Function Documentation

Q_ENTRY* qEntry ( void   ) 

Create new Q_ENTRY linked-list object.

Returns:
a pointer of malloced Q_ENTRY structure in case of successful, otherwise returns NULL.
   Q_ENTRY *entry = qEntry();

static void _lock ( Q_ENTRY entry  )  [static]

Q_ENTRY->lock(): Enter critical section.

Note:
Q_ENTRY uses recursive mutex lock mechanism. And it uses lock at least as possible. User can raise lock to proctect data modification during Q_ENTRY->getNext() operation.

static bool _put ( Q_ENTRY entry,
const char *  name,
const void *  data,
size_t  size,
bool  replace 
) [static]

Q_ENTRY->put(): Store object into linked-list structure.

Parameters:
entry Q_ENTRY pointer
name key name.
object object pointer
size size of the object
replace in case of false, just insert. in case of true, remove all same key then insert object if found.
Returns:
true if successful, otherwise returns false.

static bool _putStr ( Q_ENTRY entry,
const char *  name,
const char *  str,
bool  replace 
) [static]

Q_ENTRY->putStr(): Add string object into linked-list structure.

Parameters:
entry Q_ENTRY pointer
name key name.
str string value
replace in case of false, just insert. in case of true, remove all same key then insert object if found.
Returns:
true if successful, otherwise returns false.

static bool _putStrf ( Q_ENTRY entry,
bool  replace,
const char *  name,
const char *  format,
  ... 
) [static]

Q_ENTRY->putStrf(): Add formatted string object into linked-list structure.

Parameters:
entry Q_ENTRY pointer
replace in case of false, just insert. in case of true, remove all same key then insert object if found.
name key name.
format formatted value string
Returns:
true if successful, otherwise returns false.

static bool _putStrParsed ( Q_ENTRY entry,
const char *  name,
const char *  str,
bool  replace 
) [static]

Q_ENTRY->putStrParsed(): Add string object with parsed into linked-list structure.

Parameters:
entry Q_ENTRY pointer
name key name.
str string value which may contain variables like ${...}
replace in case of false, just insert. in case of true, remove all same key then insert object if found.
Returns:
true if successful, otherwise returns false.
   ${key_name}          variable replacement
   ${!system_command}           external command results
   ${%PATH}                     get environments

   entry->putStrParsed(entry, "BASE", "/usr/local", true);
   entry->putStrParsed(entry, "BIN", "${BASE}/bin", true);
   entry->putStrParsed(entry, "HOSTNAME", "${!/bin/hostname -s}", true);
   entry->putStrParsed(entry, "USER", "${%USER}", true);

static bool _putInt ( Q_ENTRY entry,
const char *  name,
int  num,
bool  replace 
) [static]

Q_ENTRY->putInt(): Add integer object into linked-list structure.

Parameters:
entry Q_ENTRY pointer
name key name.
num number value
replace in case of false, just insert. in case of true, remove all same key then insert object if found.
Returns:
true if successful, otherwise returns false.

static void* _get ( Q_ENTRY entry,
const char *  name,
size_t *  size,
bool  newmem 
) [static]

Q_ENTRY->get(): Find object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
size if size is not NULL, object size will be stored.
newmem whether or not to allocate memory for the data.
Returns:
a pointer of data if key is found, otherwise returns NULL.
   Q_ENTRY *entry = qEntry();
   (...codes...)

   // with newmem flag unset
   size_t size;
   const char *data = entry->get(entry, "key_name", &size, false);

   // with newmem flag set
   size_t size;
   char *data = entry->get(entry, "key_name", &size, true);
   if(data != NULL) free(data);

Note:
If newmem flag is set, returned data will be malloced and should be deallocated by user. Otherwise returned pointer will point internal buffer directly and should not be de-allocated by user. In thread-safe mode, newmem flag always should be true.

static void* _getCase ( Q_ENTRY entry,
const char *  name,
size_t *  size,
bool  newmem 
) [static]

Q_ENTRY->getCase(): Find object with given name.

(case-insensitive)

Parameters:
entry Q_ENTRY pointer
name key name
size if size is not NULL, object size will be stored.
newmem whether or not to allocate memory for the data.
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.

static void* _getLast ( Q_ENTRY entry,
const char *  name,
size_t *  size,
bool  newmem 
) [static]

Q_ENTRY->getLast(): Find lastest matched object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
size if size is not NULL, object size will be stored.
newmem whether or not to allocate memory for the data.
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.
Note:
If you have multiple objects with same name. this method can be used to find out lastest matched object.

static char* _getStr ( Q_ENTRY entry,
const char *  name,
bool  newmem 
) [static]

Q_ENTRY->getStr(): Find string object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
newmem whether or not to allocate memory for the data.
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.

static char* _getStrf ( Q_ENTRY entry,
bool  newmem,
const char *  namefmt,
  ... 
) [static]

Q_ENTRY->_getStrf(): Find string object with given formatted name.

Parameters:
entry Q_ENTRY pointer
newmem whether or not to allocate memory for the data.
namefmt formatted name string
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.

static char* _getStrCase ( Q_ENTRY entry,
const char *  name,
bool  newmem 
) [static]

Q_ENTRY->getStrCase(): Find string object with given name.

(case-insensitive)

Parameters:
entry Q_ENTRY pointer
name key name
newmem whether or not to allocate memory for the data.
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.

static char* _getStrLast ( Q_ENTRY entry,
const char *  name,
bool  newmem 
) [static]

Q_ENTRY->getStrLast(): Find lastest matched string object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
newmem whether or not to allocate memory for the data.
Returns:
a pointer of malloced data if key is found, otherwise returns NULL.

static int _getInt ( Q_ENTRY entry,
const char *  name 
) [static]

Q_ENTRY->getInt(): Find integer object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
Returns:
a integer value of the integer object, otherwise returns 0.

static int _getIntCase ( Q_ENTRY entry,
const char *  name 
) [static]

Q_ENTRY->getIntCase(): Find integer object with given name.

(case-insensitive)

Parameters:
entry Q_ENTRY pointer
name key name
Returns:
a integer value of the object.

static int _getIntLast ( Q_ENTRY entry,
const char *  name 
) [static]

Q_ENTRY->getIntLast(): Find lastest matched integer object with given name.

Parameters:
entry Q_ENTRY pointer
name key name
Returns:
a integer value of the object.

static bool _getNext ( Q_ENTRY entry,
Q_NLOBJ_T obj,
const char *  name,
bool  newmem 
) [static]

Q_ENTRY->getNext(): Get next object structure.

Parameters:
entry Q_ENTRY pointer
obj found data will be stored in this object
name key name, if key name is NULL search every key in the list.
newmem whether or not to allocate memory for the data.
Returns:
true if found otherwise returns false
Note:
obj should be filled with 0 by using memset() before first call. If newmem flag is true, user should de-allocate obj.name and obj.data resources.
   Q_ENTRY *entry = qEntry();
   entry->putStr(entry, "key1", "hello world 1", false);
   entry->putStr(entry, "key2", "hello world 2", false);
   entry->putStr(entry, "key3", "hello world 3", false);

   // non-thread usages
   Q_NLOBJ_T obj;
   memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
   while(entry->getNext(entry, &obj, NULL, false) == true) {
     printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
   }

   // thread model with specific key search
   Q_NLOBJ_T obj;
   memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
   entry->lock(entry);
   while(entry->getNext(entry, &obj, "key2", false) == true) {
     printf("NAME=%s, DATA=%s, SIZE=%zu", obj.name, obj.data, obj.size);
   }
   entry->unlock(entry);

   // thread model 2 with newmem flag
   Q_NLOBJ_T obj;
   memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
   entry->lock(entry);
   while(entry->getNext(entry, &obj, NULL, true) == true) {
     printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
     free(obj.name);
     free(obj.data);
   }
   entry->unlock(entry);

static int _remove ( Q_ENTRY entry,
const char *  name 
) [static]

Q_ENTRY->remove(): Remove matched objects as given name.

Parameters:
entry Q_ENTRY pointer
name key name
Returns:
a number of removed objects.

static int _getNum ( Q_ENTRY entry  )  [static]

Q_ENTRY->getNum(): Get total number of stored objects.

Parameters:
entry Q_ENTRY pointer
Returns:
total number of stored objects.

static int _getNo ( Q_ENTRY entry,
const char *  name 
) [static]

Q_ENTRY->getNo(): Get stored logical sequence number for the object.

Parameters:
entry Q_ENTRY pointer
name key name
Returns:
stored sequence number of the object if found, otherwise 0 will be returned.
Note:
Sequence number starts from 1.

static char* _parseStr ( Q_ENTRY entry,
const char *  str 
) [static]

Q_ENTRY->parseStr(): Parse string with given entries.

Parameters:
entry Q_ENTRY pointer
str string value which may contain variables like ${...}
Returns:
malloced string if successful, otherwise returns NULL.
   ${key_name}          - variable replacement
   ${!system_command}   - external command results
   ${%PATH}             - get environments

   char *info = entry->parseStr(entry, "${SOME_KEY} ${!uname -a} ${%PATH}", true);
   if(info != NULL) free(info);

static void* _merge ( Q_ENTRY entry,
size_t *  size 
) [static]

Q_ENTRY->merge(): Merge all objects data into single object.

Parameters:
entry Q_ENTRY pointer
size if size is not NULL, merged object size will be stored.
Returns:
a malloced pointer, otherwise(if there is no data to merge) returns NULL.
Note:
For the convenience, it allocates 1 byte more than actual total data size and store '' at the end. But size parameter will have actual size(allocated size - 1). Returned memory should be de-allocated by user.

static bool _truncate ( Q_ENTRY entry  )  [static]

Q_ENTRY->truncate(): Truncate Q_ENTRY.

Parameters:
entry Q_ENTRY pointer
Returns:
always returns true.

static bool _save ( Q_ENTRY entry,
const char *  filepath,
char  sepchar,
bool  encode 
) [static]

Q_ENTRY->save(): Save Q_ENTRY as plain text format.

Parameters:
entry Q_ENTRY pointer
filepath save file path
sepchar separator character between name and value. normally '=' is used.
encode flag for encoding value object. false can be used if the value object is string or integer and has no new line. otherwise true must be set.
Returns:
true if successful, otherwise returns false.

static int _load ( Q_ENTRY entry,
const char *  filepath,
char  sepchar,
bool  decode 
) [static]

Q_ENTRY->load(): Load and append entries from given filepath.

Parameters:
entry Q_ENTRY pointer
filepath save file path
sepchar separator character between name and value. normally '=' is used
decode flag for decoding value object
Returns:
a number of loaded entries.

static bool _reverse ( Q_ENTRY entry  )  [static]

Q_ENTRY->reverse(): Reverse-sort internal stored object.

Parameters:
entry Q_ENTRY pointer
Returns:
true if successful otherwise returns false.
Note:
This method can be used to improve look up performance. if your application offen looking for last stored object.

static bool _print ( Q_ENTRY entry,
FILE *  out,
bool  print_data 
) [static]

Q_ENTRY->print(): Print out stored objects for debugging purpose.

Parameters:
entry Q_ENTRY pointer
out output stream FILE descriptor such like stdout, stderr.
print_data true for printing out object value, false for disable printing out object value.

static bool _free ( Q_ENTRY entry  )  [static]

Q_ENTRY->free(): Free Q_ENTRY.

Parameters:
entry Q_ENTRY pointer
Returns:
always returns true.


Copyright (c) 2008 The qDecoder Project