qDecoder API Reference

Functions

qEntry.c File Reference


Detailed Description

Linked-list Data Structure API.

   [Code sample - String]

   // init a linked-list.
   Q_ENTRY *entry = qEntry();

   // insert a string element
   entry->putStr(entry, "str", "hello world", true);

   // get the string.
   char *str = entry->getStr(entry, "str", false);
   if(str != NULL) {
     printf("str = %s\n", str);
     free(str);
   }

   // print out all elements in the list.
   entry->print(entry, stdout, false);

   // free the list.
   entry->free(entry);

   [Result]

Functions

Q_ENTRYqEntry (void)
 Create new Q_ENTRY linked-list object.
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 _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_ENTOBJ_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 bool _truncate (Q_ENTRY *entry)
 Q_ENTRY->truncate(): Truncate Q_ENTRY.
static bool _save (Q_ENTRY *entry, const char *filepath)
 Q_ENTRY->save(): Save Q_ENTRY as plain text format.
static int _load (Q_ENTRY *entry, const char *filepath)
 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.

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 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 _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_ENTOBJ_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);

   Q_ENTOBJ_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);
   }

   // with newmem flag
   Q_ENTOBJ_T obj;
   memset((void*)&obj, 0, sizeof(obj)); // must be cleared before call
   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);
   }
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 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 
) [static]

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

Parameters:
entry Q_ENTRY pointer
filepath save file path
Returns:
true if successful, otherwise returns false.
static int _load ( Q_ENTRY entry,
const char *  filepath 
) [static]

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

Parameters:
entry Q_ENTRY pointer
filepath save file path
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.