# xml.h File Reference

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

Go to the source code of this file.

## Read Flags

#define | GWEN_XML_FLAGS_DEFAULT
#define | GWEN_XML_FLAGS_HANDLE_HEADERS 0x1000
#define | GWEN_XML_FLAGS_HANDLE_OPEN_HTMLTAGS 0x0040
#define | GWEN_XML_FLAGS_IGNORE_DESCR 0x0200
#define | GWEN_XML_FLAGS_IGNORE_INCLUDE 0x0008
#define | GWEN_XML_FLAGS_INCLUDE_TO_TOPLEVEL 0x0004
#define | GWEN_XML_FLAGS_INDENT 0x0020
#define | GWEN_XML_FLAGS_KEEP_BLANKS 0x0400
#define | GWEN_XML_FLAGS_KEEP_CNTRL 0x0100
#define | GWEN_XML_FLAGS_NO_CONDENSE 0x0080
#define | GWEN_XML_FLAGS_READ_COMMENTS 0x0001
#define | GWEN_XML_FLAGS_SHARE_TOPLEVEL 0x0002
#define | GWEN_XML_FLAGS_SIMPLE 0x0800
#define | GWEN_XML_FLAGS_WRITE_COMMENTS 0x0010

## Reading And Writing From/To Streams

GWENHYWFAR_API int | GWEN_XML_Parse (GWEN_XMLNODE *n, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API int | GWEN_XML_ReadFile (GWEN_XMLNODE *n, const char *filepath, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API int | GWEN_XML_ReadFileSearch (GWEN_XMLNODE *n, const char *filepath, GWEN_TYPE_UINT32 flags, GWEN_STRINGLIST *searchPath)
GWENHYWFAR_API int | GWEN_XMLNode_NormalizeNameSpaces (GWEN_XMLNODE *n)
GWENHYWFAR_API int | GWEN_XMLNode_WriteFile (const GWEN_XMLNODE *n, const char *fname, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API int | GWEN_XMLNode_WriteToStream (const GWEN_XMLNODE *n, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags)

## Managing Nodes

GWENHYWFAR_API void | GWEN_XMLNode_AddChild (GWEN_XMLNODE *n, GWEN_XMLNODE *child)
GWENHYWFAR_API void | GWEN_XMLNode_AddChildrenOnly (GWEN_XMLNODE *n, GWEN_XMLNODE *nn, int copythem)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_FindNode (const GWEN_XMLNODE *n, GWEN_XMLNODE_TYPE t, const char *data)
GWENHYWFAR_API void | GWEN_XMLNode_RemoveChildren (GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_UnlinkChild (GWEN_XMLNODE *n, GWEN_XMLNODE *child)

## Managing Headers

Headers are special tags in XML files which describe the document (such as <?xml?> or <!DOCTYPE>).

If the flag GWEN_XML_FLAGS_HANDLE_HEADERS is on upon reading of files these special toplevel tags are added to the current node's header list instead of the normal children node list.

If the same flag is given when writing files the header tags of the given root node are written to the output stream before its children.

Header nodes are identified as nodes whose name begins with '?' or '!'.

GWENHYWFAR_API void | GWEN_XMLNode_AddHeader (GWEN_XMLNODE *root, GWEN_XMLNODE *nh)
GWENHYWFAR_API void | GWEN_XMLNode_ClearHeaders (GWEN_XMLNODE *root)
GWENHYWFAR_API void | GWEN_XMLNode_DelHeader (GWEN_XMLNODE *root, GWEN_XMLNODE *nh)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetHeader (const GWEN_XMLNODE *n)

## Managing Properties/Attributes

A property (in XML notation this is called attribute) is given within a tag (in XML notation this is called element), like in this example:

     <tag property="1" />

GWENHYWFAR_API void | GWEN_XMLNode_CopyProperties (GWEN_XMLNODE *tn, const GWEN_XMLNODE *sn, int overwrite)
GWENHYWFAR_API const char * | GWEN_XMLNode_GetProperty (const GWEN_XMLNODE *n, const char *name, const char *defaultValue)
GWENHYWFAR_API void | GWEN_XMLNode_SetProperty (GWEN_XMLNODE *n, const char *name, const char *value)

## Usage Counter

The usage counter of a node is only used by applications, not by Gwenhywfar itself. So if the application does not set this counter it will always be zero. An application could use this counter to check whether a given node is still in use by some parts of the application in order to free unused nodes.
GWENHYWFAR_API void | GWEN_XMLNode_DecUsage (GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_TYPE_UINT32 | GWEN_XMLNode_GetUsage (const GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_IncUsage (GWEN_XMLNODE *n)

## Debugging

GWENHYWFAR_API void | GWEN_XMLNode_Dump (const GWEN_XMLNODE *n, FILE *f, int ind)

## Constructors and Destructors

GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_dup (const GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_free (GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_freeAll (GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_fromString (const char *s, int len, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_new (GWEN_XMLNODE_TYPE t, const char *data)

## Iterating Through an XML Tree

GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_FindFirstTag (const GWEN_XMLNODE *n, const char *tname, const char *pname, const char *pvalue)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_FindNextTag (const GWEN_XMLNODE *n, const char *tname, const char *pname, const char *pvalue)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetChild (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetFirstData (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetFirstTag (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetNextData (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetNextTag (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetNodeByXPath (GWEN_XMLNODE *n, const char *path, GWEN_TYPE_UINT32 flags)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_GetParent (const GWEN_XMLNODE *n)
GWENHYWFAR_API int | GWEN_XMLNode_GetXPath (const GWEN_XMLNODE *n1, const GWEN_XMLNODE *n2, GWEN_BUFFER *nbuf)
GWENHYWFAR_API int | GWEN_XMLNode_IsChildOf (const GWEN_XMLNODE *parent, const GWEN_XMLNODE *child)
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_Next (const GWEN_XMLNODE *n)

## Handling Tags As Variables

These functions look for a tag, read their first data element and return it as if it was a DB variable. This simplifies access to simple tags containing simple data tags only. E.g. if your XML structure is this:

     <test>
       <X> 15 </X>
       <Y> 10 </Y>
     </test>

... then you can access the value of X with the following call:

     x=GWEN_XMLNode_GetIntValue(testNode, "X", 0);

If the given variables do not exist or have no value then the also given default value will be returned.

GWENHYWFAR_API const char * | GWEN_XMLNode_GetCharValue (const GWEN_XMLNODE *n, const char *name, const char *defValue)
GWENHYWFAR_API int | GWEN_XMLNode_GetIntValue (const GWEN_XMLNODE *n, const char *name, int defValue)
GWENHYWFAR_API const char * | GWEN_XMLNode_GetLocalizedCharValue (const GWEN_XMLNODE *n, const char *name, const char *defValue)
GWENHYWFAR_API void | GWEN_XMLNode_SetCharValue (GWEN_XMLNODE *n, const char *name, const char *value)
GWENHYWFAR_API void | GWEN_XMLNode_SetIntValue (GWEN_XMLNODE *n, const char *name, int value)

## Type And Data

GWENHYWFAR_API const char * | GWEN_XMLNode_GetData (const GWEN_XMLNODE *n)
GWENHYWFAR_API GWEN_XMLNODE_TYPE | GWEN_XMLNode_GetType (const GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_SetData (GWEN_XMLNODE *n, const char *data)

## Typedefs

typedef int(* | GWEN_XML_INCLUDE_FN )(GWEN_XMLNODE *n, const char *path, const char *file, GWEN_STRINGLIST *sl, GWEN_TYPE_UINT32 flags)
typedef GWEN__XMLNODE | GWEN_XMLNODE
typedef GWEN_XMLNODE_PATH | GWEN_XMLNODE_PATH

## Enumerations

enum | GWEN_XMLNODE_TYPE { GWEN_XMLNodeTypeTag = 0, GWEN_XMLNodeTypeData, GWEN_XMLNodeTypeComment }

## Functions

| GWEN_LIST2_FUNCTION_LIB_DEFS (GWEN_XMLNODE, GWEN_XMLNode, GWENHYWFAR_API)
GWENHYWFAR_API int | GWEN_XMLNode_Path_Dive (GWEN_XMLNODE_PATH *np, GWEN_XMLNODE *n)
GWENHYWFAR_API void | GWEN_XMLNode_Path_Dump (GWEN_XMLNODE_PATH *np)
GWENHYWFAR_API GWEN_XMLNODE_PATH * | GWEN_XMLNode_Path_dup (const GWEN_XMLNODE_PATH *np)
GWENHYWFAR_API void | GWEN_XMLNode_Path_free (GWEN_XMLNODE_PATH *np)
GWENHYWFAR_API GWEN_XMLNODE_PATH * | GWEN_XMLNode_Path_new ()
GWENHYWFAR_API GWEN_XMLNODE * | GWEN_XMLNode_Path_Surface (GWEN_XMLNODE_PATH *np)