qentry.c File Reference

# qDecoder API Reference

- Main Page
- Data Structures
- Files

- File List
- Globals

Functions
qentry.c File Reference

## Detailed Description

Linked-list Data Structure API.

[Code sample - String]
// init a linked-list.
qentry_t *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
qentry_t * | qEntry (void)
| Create new qentry_t linked-list object.
static bool | _put (qentry_t *entry, const char *name, const void *data, size_t size, bool replace)
| qentry_t->put(): Store object into linked-list structure.
static bool | _putstr (qentry_t *entry, const char *name, const char *str, bool replace)
| qentry_t->putstr(): Add string object into linked-list structure.
static bool | _putstrf (qentry_t *entry, bool replace, const char *name, const char *format,...)
| qentry_t->putstrf(): Add formatted string object into linked-list structure.
static bool | _putint (qentry_t *entry, const char *name, int num, bool replace)
| qentry_t->putint(): Add integer object into linked-list structure.
static void * | _get (qentry_t *entry, const char *name, size_t *size, bool newmem)
| qentry_t->get(): Find object with given name
static void * | _getlast (qentry_t *entry, const char *name, size_t *size, bool newmem)
| qentry_t->getlast(): Find lastest matched object with given name.
static char * | _getstr (qentry_t *entry, const char *name, bool newmem)
| qentry_t->getstr(): Find string object with given name.
static char * | _getstrf (qentry_t *entry, bool newmem, const char *namefmt,...)
| qentry_t->_getstrf(): Find string object with given formatted name.
static char * | _getstrlast (qentry_t *entry, const char *name, bool newmem)
| qentry_t->getstrlast(): Find lastest matched string object with given name.
static int | _getint (qentry_t *entry, const char *name)
| qentry_t->getint(): Find integer object with given name.
static int | _getintlast (qentry_t *entry, const char *name)
| qentry_t->getintlast(): Find lastest matched integer object with given name.
static void * | _caseget (qentry_t *entry, const char *name, size_t *size, bool newmem)
| qentry_t->caseget(): Find object with given name.
static char * | _casegetstr (qentry_t *entry, const char *name, bool newmem)
| qentry_t->casegetstr(): Find string object with given name in case-insensitive way.
static int | _casegetint (qentry_t *entry, const char *name)
| qentry_t->casegetint(): Find integer object with given name in case-insensitive way.
static bool | _getnext (qentry_t *entry, qentobj_t *obj, const char *name, bool newmem)
| qentry_t->getnext(): Get next object structure.
static int | _size (qentry_t *entry)
| qentry_t->size(): Get total number of stored objects
static int | _remove (qentry_t *entry, const char *name)
| qentry_t->remove(): Remove matched objects as given name.
static bool | _truncate (qentry_t *entry)
| qentry_t->truncate(): Truncate qentry_t
static bool | _reverse (qentry_t *entry)
| qentry_t->reverse(): Reverse-sort internal stored object.
static bool | _save (qentry_t *entry, const char *filepath)
| qentry_t->save(): Save qentry_t as plain text format
static int | _load (qentry_t *entry, const char *filepath)
| qentry_t->load(): Load and append entries from given filepath
static bool | _print (qentry_t *entry, FILE *out, bool print_data)
| qentry_t->print(): Print out stored objects for debugging purpose.
static bool | _free (qentry_t *entry)
| qentry_t->free(): Free qentry_t

## Function Documentation

qentry_t* qEntry | ( | void |  | ) |

Create new qentry_t linked-list object.

Returns
  a pointer of malloced qentry_t structure in case of successful, otherwise returns NULL.

qentry_t *entry = qEntry();

static bool _put | ( | qentry_t * | entry,
|  | const char * | name,
|  | const void * | data,
|  | size_t | size,
|  | bool | replace
| ) |  |
| static

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

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | const char * | name,
|  | const char * | str,
|  | bool | replace
| ) |  |
| static

qentry_t->putstr(): Add string object into linked-list structure.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | bool | replace,
|  | const char * | name,
|  | const char * | format,
|  |  | ...
| ) |  |
| static

qentry_t->putstrf(): Add formatted string object into linked-list structure.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | const char * | name,
|  | int | num,
|  | bool | replace
| ) |  |
| static

qentry_t->putint(): Add integer object into linked-list structure.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | const char * | name,
|  | size_t * | size,
|  | bool | newmem
| ) |  |
| static

qentry_t->get(): Find object with given name

Parameters

  entry | qentry_t 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.

qentry_t *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* _getlast | ( | qentry_t * | entry,
|  | const char * | name,
|  | size_t * | size,
|  | bool | newmem
| ) |  |
| static

qentry_t->getlast(): Find lastest matched object with given name.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | const char * | name,
|  | bool | newmem
| ) |  |
| static

qentry_t->getstr(): Find string object with given name.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | bool | newmem,
|  | const char * | namefmt,
|  |  | ...
| ) |  |
| static

qentry_t->_getstrf(): Find string object with given formatted name.

Parameters

  entry | qentry_t 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* _getstrlast | ( | qentry_t * | entry,
|  | const char * | name,
|  | bool | newmem
| ) |  |
| static

qentry_t->getstrlast(): Find lastest matched string object with given name.

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry,
|  | const char * | name
| ) |  |
| static

qentry_t->getint(): Find integer object with given name.

Parameters

  entry | qentry_t pointer
  name | key name

Returns
  a integer value of the integer object, otherwise returns 0.

static int _getintlast | ( | qentry_t * | entry,
|  | const char * | name
| ) |  |
| static

qentry_t->getintlast(): Find lastest matched integer object with given name.

Parameters

  entry | qentry_t pointer
  name | key name

Returns
  a integer value of the object.

static void* _caseget | ( | qentry_t * | entry,
|  | const char * | name,
|  | size_t * | size,
|  | bool | newmem
| ) |  |
| static

qentry_t->caseget(): Find object with given name.

(case-insensitive)

Parameters

  entry | qentry_t 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 char* _casegetstr | ( | qentry_t * | entry,
|  | const char * | name,
|  | bool | newmem
| ) |  |
| static

qentry_t->casegetstr(): Find string object with given name in case-insensitive way.

Parameters

  entry | qentry_t 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 _casegetint | ( | qentry_t * | entry,
|  | const char * | name
| ) |  |
| static

qentry_t->casegetint(): Find integer object with given name in case-insensitive way.

Parameters

  entry | qentry_t pointer
  name | key name

Returns
  a integer value of the object.

static bool _getnext | ( | qentry_t * | entry,
|  | qentobj_t * | obj,
|  | const char * | name,
|  | bool | newmem
| ) |  |
| static

qentry_t->getnext(): Get next object structure.

Parameters

  entry | qentry_t 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.

qentry_t *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);
qentobj_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
qentobj_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 _size | ( | qentry_t * | entry | ) |
| static

qentry_t->size(): Get total number of stored objects

Parameters

  entry | qentry_t pointer

Returns
  total number of stored objects.

static int _remove | ( | qentry_t * | entry,
|  | const char * | name
| ) |  |
| static

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

Parameters

  entry | qentry_t pointer
  name | key name

Returns
  a number of removed objects.

static bool _truncate | ( | qentry_t * | entry | ) |
| static

qentry_t->truncate(): Truncate qentry_t

Parameters

  entry | qentry_t pointer

Returns
  always returns true.

static bool _reverse | ( | qentry_t * | entry | ) |
| static

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

Parameters

  entry | qentry_t 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 _save | ( | qentry_t * | entry,
|  | const char * | filepath
| ) |  |
| static

qentry_t->save(): Save qentry_t as plain text format

Parameters

  entry | qentry_t pointer
  filepath | save file path

Returns
  true if successful, otherwise returns false.

static int _load | ( | qentry_t * | entry,
|  | const char * | filepath
| ) |  |
| static

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

Parameters

  entry | qentry_t pointer
  filepath | save file path

Returns
  a number of loaded entries.

static bool _print | ( | qentry_t * | entry,
|  | FILE * | out,
|  | bool | print_data
| ) |  |
| static

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

Parameters

  entry | qentry_t 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 | ( | qentry_t * | entry | ) |
| static

qentry_t->free(): Free qentry_t

Parameters

  entry | qentry_t pointer

Returns
  always returns true.