# db.h File Reference

`#include <gwenhywfar/gwenhywfarapi.h>`
`#include <gwenhywfar/path.h>`
`#include <gwenhywfar/bufferedio.h>`
`#include <gwenhywfar/types.h>`
`#include <stdio.h>`

Go to the source code of this file.

## DB Flags

Please note that the setter functions also take the flags from the module Paths (e.g. GWEN_PATH_FLAGS_PATHMUSTEXIST) into account. So you most likely need to specify them, too. However, for your conveniance there is a default flag value which suffices in most cases (GWEN_DB_FLAGS_DEFAULT).
#define | GWEN_DB_FLAGS_ADD_GROUP_NEWLINES 0x00800000
#define | GWEN_DB_FLAGS_APPEND_FILE 0x08000000
#define | GWEN_DB_FLAGS_COMPACT
#define | GWEN_DB_FLAGS_DEFAULT
#define | GWEN_DB_FLAGS_DETAILED_GROUPS 0x00200000
#define | GWEN_DB_FLAGS_ESCAPE_CHARVALUES 0x10000000
#define | GWEN_DB_FLAGS_HTTP
#define | GWEN_DB_FLAGS_INDEND 0x00400000
#define | GWEN_DB_FLAGS_LOCKFILE 0x20000000
#define | GWEN_DB_FLAGS_OMIT_TYPES 0x04000000
#define | GWEN_DB_FLAGS_OVERWRITE_GROUPS 0x00020000
#define | GWEN_DB_FLAGS_OVERWRITE_VARS 0x00010000
#define | GWEN_DB_FLAGS_QUOTE_VALUES 0x00080000
#define | GWEN_DB_FLAGS_QUOTE_VARNAMES 0x00040000
#define | GWEN_DB_FLAGS_STOP_ON_EMPTY_LINE 0x02000000
#define | GWEN_DB_FLAGS_UNESCAPE_CHARVALUES 0x10000000
#define | GWEN_DB_FLAGS_USE_COLON 0x01000000
#define | GWEN_DB_FLAGS_WRITE_SUBGROUPS 0x00100000

## Node Flags

#define | GWEN_DB_NODE_FLAGS_DIRTY 0x00000001
#define | GWEN_DB_NODE_FLAGS_INHERIT_HASH_MECHANISM 0x00000004
#define | GWEN_DB_NODE_FLAGS_VOLATILE 0x00000002

## Hash Mechanism

These functions allow for the implementation of hash mechanisms for DB groups. Those mechanisms can be applied to group nodes to speed up the lookup of subnodes to groups.
typedef int(* | GWEN_DB_HASH_ADDNODE_FN )(GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_NODE *parent, GWEN_DB_NODE *node, int appendOrInsert, void *hashData)
typedef int(* | GWEN_DB_HASH_FININODE_FN )(GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_NODE *node, void **hashData)
typedef GWEN_DB_NODE *(* | GWEN_DB_HASH_GETNODE_FN )(GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_NODE *parent, const char *name, int idx, void *hashData)
typedef int(* | GWEN_DB_HASH_INITNODE_FN )(GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_NODE *node, void **hashData)
typedef GWEN_DB_HASH_MECHANISM | GWEN_DB_HASH_MECHANISM
typedef int(* | GWEN_DB_HASH_UNLINKNODE_FN )(GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_NODE *parent, GWEN_DB_NODE *node, void *hashData)
GWENHYWFAR_API int | GWEN_DB_Group_SetHashMechanism (GWEN_DB_NODE *node, GWEN_DB_HASH_MECHANISM *hm)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_Attach (GWEN_DB_HASH_MECHANISM *hm)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_free (GWEN_DB_HASH_MECHANISM *hm)
GWENHYWFAR_API GWEN_DB_HASH_MECHANISM * | GWEN_DB_HashMechanism_new ()
GWENHYWFAR_API void | GWEN_DB_HashMechanism_SetAddNodeFn (GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_HASH_ADDNODE_FN f)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_SetFiniNodeFn (GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_HASH_FININODE_FN f)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_SetGetNodeFn (GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_HASH_GETNODE_FN f)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_SetInitNodeFn (GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_HASH_INITNODE_FN f)
GWENHYWFAR_API void | GWEN_DB_HashMechanism_SetUnlinkNodeFn (GWEN_DB_HASH_MECHANISM *hm, GWEN_DB_HASH_UNLINKNODE_FN f)

## Iterating Through Groups

typedef void *(* | GWEN_DB_NODES_CB )(GWEN_DB_NODE *node, void *user_data)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_FindFirstGroup (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_FindNextGroup (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetFirstGroup (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetNextGroup (GWEN_DB_NODE *n)
GWENHYWFAR_API unsigned int | GWEN_DB_Groups_Count (const GWEN_DB_NODE *node)
GWENHYWFAR_API void * | GWEN_DB_Groups_Foreach (GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, void *user_data)

## Variable Getter and Setter

These getter functions check for the existence of the given variable and return the value specified by an index. Under the following circumstances the also given default value will be returned:

- the variable does not exist
- the variable exists but has no values (should not occur)
- the variable exists but the given value index is out of range (e.g. specifying index 1 with a variable that has only one value)
- a string value is expected but the variable is not of that type. However, if you want an integer value but the variable only has a char value then the getter functions try to convert the char to an integer. Other conversions do not take place.

The setter functions either replace an existing variable, create a missing variable, add a value or return an error if the variable does not exist (see description of the flags). All setter functions make deep copies of the given values, so you may free the params after calling the setter function.

All getter functions return a const pointer to the variable's retrieved value. All setter functions return Zero if ok and Nonzero on error.

This module knows about the following types (see GWEN_DB_VALUETYPE):

- char (simple null terminated C strings)
- int (integer values)
- bin (binary, user specified data)

Note:
  The value returned by a getter function is only valid as long as the corresponding variable (node) exists.
  So if you retrieve the value of a variable and delete the variable (or even the whole DB) afterwards the pointer becomes invalid and using it will most likely crash your program.
  If you want to use such a value even after the corresponding variable has been deleted you need to make a copy.

GWENHYWFAR_API int | GWEN_DB_AddCharValue (GWEN_DB_NODE *n, const char *path, const char *val, int senseCase, int check)
GWENHYWFAR_API const void * | GWEN_DB_GetBinValue (GWEN_DB_NODE *n, const char *path, int idx, const void *defVal, unsigned int defValSize, unsigned int *returnValueSize)
GWENHYWFAR_API const char * | GWEN_DB_GetCharValue (GWEN_DB_NODE *n, const char *path, int idx, const char *defVal)
GWENHYWFAR_API int | GWEN_DB_GetIntValue (GWEN_DB_NODE *n, const char *path, int idx, int defVal)
GWENHYWFAR_API void * | GWEN_DB_GetPtrValue (GWEN_DB_NODE *n, const char *path, int idx, void *defVal)
GWENHYWFAR_API int | GWEN_DB_SetBinValue (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags, const char *path, const void *val, unsigned int valSize)
GWENHYWFAR_API int | GWEN_DB_SetCharValue (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags, const char *path, const char *val)
GWENHYWFAR_API int | GWEN_DB_SetIntValue (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags, const char *path, int val)
GWENHYWFAR_API int | GWEN_DB_SetPtrValue (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags, const char *path, void *val)

## Group Handling

GWENHYWFAR_API int | GWEN_DB_AddGroup (GWEN_DB_NODE *parent, GWEN_DB_NODE *node)
GWENHYWFAR_API int | GWEN_DB_AddGroupChildren (GWEN_DB_NODE *n, GWEN_DB_NODE *nn)
GWENHYWFAR_API int | GWEN_DB_ClearGroup (GWEN_DB_NODE *n, const char *path)
GWENHYWFAR_API int | GWEN_DB_DeleteGroup (GWEN_DB_NODE *n, const char *path)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetGroup (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags, const char *path)
GWENHYWFAR_API GWEN_TYPE_UINT32 | GWEN_DB_GetNodeFlags (const GWEN_DB_NODE *n)
GWENHYWFAR_API const char * | GWEN_DB_GroupName (GWEN_DB_NODE *n)
GWENHYWFAR_API void | GWEN_DB_GroupRename (GWEN_DB_NODE *n, const char *newname)
GWENHYWFAR_API int | GWEN_DB_InsertGroup (GWEN_DB_NODE *parent, GWEN_DB_NODE *node)
GWENHYWFAR_API int | GWEN_DB_IsGroup (const GWEN_DB_NODE *n)
void | GWEN_DB_ModifyBranchFlagsDown (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 newflags, GWEN_TYPE_UINT32 mask)
void | GWEN_DB_ModifyBranchFlagsUp (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 newflags, GWEN_TYPE_UINT32 mask)
GWENHYWFAR_API void | GWEN_DB_SetNodeFlags (GWEN_DB_NODE *n, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API void | GWEN_DB_UnlinkGroup (GWEN_DB_NODE *n)

## Iterating Through Variables and variable handling

GWENHYWFAR_API int | GWEN_DB_DeleteVar (GWEN_DB_NODE *n, const char *path)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetFirstVar (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetNextVar (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_VALUETYPE | GWEN_DB_GetVariableType (GWEN_DB_NODE *n, const char *p)
GWENHYWFAR_API int | GWEN_DB_IsVariable (const GWEN_DB_NODE *n)
GWENHYWFAR_API int | GWEN_DB_ValueExists (GWEN_DB_NODE *n, const char *path, unsigned int idx)
GWENHYWFAR_API int | GWEN_DB_VariableExists (GWEN_DB_NODE *n, const char *path)
GWENHYWFAR_API const char * | GWEN_DB_VariableName (GWEN_DB_NODE *n)
GWENHYWFAR_API unsigned int | GWEN_DB_Variables_Count (const GWEN_DB_NODE *node)
GWENHYWFAR_API void * | GWEN_DB_Variables_Foreach (GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, void *user_data)

## Debugging

These functions are for debugging purposes only. You should NOT consider them part of the API.
GWENHYWFAR_API void | GWEN_DB_Dump (GWEN_DB_NODE *n, FILE *f, int insert)

## Iterating Through Values and value handling

GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetFirstValue (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_GetNextValue (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_VALUETYPE | GWEN_DB_GetValueType (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_VALUETYPE | GWEN_DB_GetValueTypeByPath (GWEN_DB_NODE *n, const char *p, unsigned int i)
GWENHYWFAR_API int | GWEN_DB_IsValue (const GWEN_DB_NODE *n)
GWENHYWFAR_API unsigned int | GWEN_DB_Values_Count (const GWEN_DB_NODE *node)
GWENHYWFAR_API void * | GWEN_DB_Values_Foreach (GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, void *user_data)

## Constructing, Destructing, Copying

GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_Group_dup (const GWEN_DB_NODE *n)
GWENHYWFAR_API void | GWEN_DB_Group_free (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE * | GWEN_DB_Group_new (const char *name)

## Reading and Writing From/To Streams

These functions read or write a DB from/to GWEN_BUFFEREDIO. This allows to use any source or target supported by GWEN_BUFFEREDIO for data storage (these are currently sockets, files and memory buffers). The flags determine how to read/write the data (e.g. if sub-groups are to be written etc).
GWENHYWFAR_API int | GWEN_DB_ReadFile (GWEN_DB_NODE *n, const char *fname, GWEN_TYPE_UINT32 dbflags)
GWENHYWFAR_API int | GWEN_DB_ReadFileAs (GWEN_DB_NODE *n, const char *fname, const char *type, GWEN_DB_NODE *params, GWEN_TYPE_UINT32 dbflags)
GWENHYWFAR_API int | GWEN_DB_ReadFromStream (GWEN_DB_NODE *n, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 dbflags)
GWENHYWFAR_API int | GWEN_DB_WriteFile (GWEN_DB_NODE *n, const char *fname, GWEN_TYPE_UINT32 dbflags)
GWENHYWFAR_API int | GWEN_DB_WriteFileAs (GWEN_DB_NODE *n, const char *fname, const char *type, GWEN_DB_NODE *params, GWEN_TYPE_UINT32 dbflags)
GWENHYWFAR_API int | GWEN_DB_WriteToStream (GWEN_DB_NODE *n, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 dbflags)

## Defines

#define | GWEN_DB_LINE_MAXSIZE 1024

## Typedefs

typedef GWEN_DB_NODE | GWEN_DB_NODE

## Enumerations

enum | GWEN_DB_VALUETYPE { GWEN_DB_VALUETYPE_UNKNOWN = 0, GWEN_DB_VALUETYPE_CHAR, GWEN_DB_VALUETYPE_INT, GWEN_DB_VALUETYPE_BIN, GWEN_DB_VALUETYPE_PTR }

## Detailed Description