db.h File Reference

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

Go to the source code of this file.

Iterating Through Groups

typedef void *(* GWEN_DB_NODES_CB )(GWEN_DB_NODE *node, void *user_data)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_FindFirstGroup (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_FindNextGroup (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_GetFirstGroup (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODEGWEN_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)

Defines

#define GWEN_DB_DEFAULT_LOCK_TIMEOUT   1000
#define GWEN_DB_LINE_MAXSIZE   1024
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_DOSMODE   0x80000000
#define GWEN_DB_FLAGS_ESCAPE_CHARVALUES   0x10000000
#define GWEN_DB_FLAGS_HTTP
#define GWEN_DB_FLAGS_INDEND   0x00400000
#define GWEN_DB_FLAGS_INSERT   0x40000000
#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_UNESCAPE_CHARVALUES   0x10000000
#define GWEN_DB_FLAGS_UNTIL_EMPTY_LINE   0x02000000
#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

Typedefs

typedef struct GWEN_DB_NODE GWEN_DB_NODE

Enumerations

enum  GWEN_DB_NODE_TYPE {
  GWEN_DB_NodeType_Unknown = -1, GWEN_DB_NodeType_Group = 0, GWEN_DB_NodeType_Var, GWEN_DB_NodeType_ValueChar,
  GWEN_DB_NodeType_ValueInt, GWEN_DB_NodeType_ValueBin, GWEN_DB_NodeType_ValuePtr, GWEN_DB_NodeType_ValueLast
}

Functions

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_RemoveCharValue (GWEN_DB_NODE *n, const char *path, const char *val, int senseCase)
GWENHYWFAR_API int GWEN_DB_SetBinValue (GWEN_DB_NODE *n, uint32_t flags, const char *path, const void *val, unsigned int valSize)
GWENHYWFAR_API int GWEN_DB_SetCharValue (GWEN_DB_NODE *n, uint32_t flags, const char *path, const char *val)
GWENHYWFAR_API int GWEN_DB_SetIntValue (GWEN_DB_NODE *n, uint32_t flags, const char *path, int val)
GWENHYWFAR_API int GWEN_DB_SetPtrValue (GWEN_DB_NODE *n, uint32_t 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_NODEGWEN_DB_GetGroup (GWEN_DB_NODE *n, uint32_t flags, const char *path)
GWENHYWFAR_API uint32_t 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)
GWENHYWFAR_API void GWEN_DB_ModifyBranchFlagsDown (GWEN_DB_NODE *n, uint32_t newflags, uint32_t mask)
GWENHYWFAR_API void GWEN_DB_ModifyBranchFlagsUp (GWEN_DB_NODE *n, uint32_t newflags, uint32_t mask)
GWENHYWFAR_API void GWEN_DB_SetNodeFlags (GWEN_DB_NODE *n, uint32_t 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_NODEGWEN_DB_FindFirstVar (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_FindNextVar (GWEN_DB_NODE *n, const char *name)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_GetFirstVar (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_GetNextVar (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE_TYPE 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 void GWEN_DB_VariableRename (GWEN_DB_NODE *n, const char *newname)
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 const void * GWEN_DB_GetBinValueFromNode (const GWEN_DB_NODE *n, unsigned int *size)
GWENHYWFAR_API const char * GWEN_DB_GetCharValueFromNode (const GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_GetFirstValue (GWEN_DB_NODE *n)
GWENHYWFAR_API int GWEN_DB_GetIntValueFromNode (const GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_GetNextValue (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE_TYPE GWEN_DB_GetValueType (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODE_TYPE 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 int GWEN_DB_SetCharValueInNode (GWEN_DB_NODE *n, const char *s)
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_NODEGWEN_DB_Group_dup (const GWEN_DB_NODE *n)
GWENHYWFAR_API void GWEN_DB_Group_free (GWEN_DB_NODE *n)
GWENHYWFAR_API GWEN_DB_NODEGWEN_DB_Group_new (const char *name)
Reading and Writing From/To IO Layers
These functions read or write a DB from/to GWEN_IO_LAYER. This allows to use any source or target supported by GWEN_IO_LAYER 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, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_ReadFileAs (GWEN_DB_NODE *n, const char *fname, const char *type, GWEN_DB_NODE *params, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_ReadFromFastBuffer (GWEN_DB_NODE *n, GWEN_FAST_BUFFER *fb, uint32_t dbflags)
GWENHYWFAR_API int GWEN_DB_ReadFromFd (GWEN_DB_NODE *n, int fd, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_ReadFromIo (GWEN_DB_NODE *n, GWEN_IO_LAYER *io, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_ReadFromString (GWEN_DB_NODE *n, const char *str, int len, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_WriteFile (GWEN_DB_NODE *n, const char *fname, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_WriteFileAs (GWEN_DB_NODE *n, const char *fname, const char *type, GWEN_DB_NODE *params, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_WriteToBuffer (GWEN_DB_NODE *n, GWEN_BUFFER *buf, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_WriteToFastBuffer (GWEN_DB_NODE *node, GWEN_FAST_BUFFER *fb, uint32_t dbflags)
GWENHYWFAR_API int GWEN_DB_WriteToFd (GWEN_DB_NODE *n, int fd, uint32_t dbflags, uint32_t guiid, int msecs)
GWENHYWFAR_API int GWEN_DB_WriteToIo (GWEN_DB_NODE *node, GWEN_IO_LAYER *io, uint32_t dbflags, uint32_t guiid, int msecs)


Detailed Description

Definition in file db.h.


Generated on Wed Sep 3 15:22:00 2008 for gwenhywfar by  doxygen 1.5.6