/*
 * zXml.h
 * 
 * The Zen API 
 * Copyright (C) 2008-2009 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */
#ifndef LMITECH_ZXML_H_INCLUDED
#define LMITECH_ZXML_H_INCLUDED

#include <zApi.h>
#include <zApiBegin.h>

typedef zHandle zXml;               // Represents an XML document.
typedef zHandle zXmlItem;           // Represents an XML element within an XML document.

ZAPI_EXPORT(zStatus) zXml_Construct(zXml* xml); //
//
//  Description:
//      Constructs an XML object. 
//  Arguments:
//      xml - Destination for the constructed object handle.
//  Remarks: 
//      The XML object is initially empty; use zXml_AddItem with parent=kNIL to create a root node.

ZAPI_EXPORT(zStatus) zXml_Destroy(zXml xml);  //
//
//  Description:
//      Destroys the XML document object.
//  Arguments:
//      xml - XML document object.

ZAPI_EXPORT(zStatus) zXml_FromString(zXml xml, const zChar* buffer); //
//
//  Description:
//      Loads an XML document from a null-terminated character array.
//  Arguments:
//      xml - XML document object.
//      buffer - Null-terminated character array to parse. 

ZAPI_EXPORT(zStatus) zXml_ToString(zXml xml, zChar* buffer, z32u* written); //
//
//  Description:
//      Exports the XML document to a null-terminated character array.
//  Arguments:
//      xml - XML document object.
//      buffer - Buffer to receive the XML content, or zNULL (see notes below). 
//      written - Number of characters written to the buffer, including the null terminator.
//  Remarks: 
//      In order to determine the required size of a buffer large enough to contain the exported 
//      characters, call zXml_Write with zNULL as the buffer argument.  When the call 
//      completes, the written argument will report the required buffer size, including
//      the null terminator.  After allocating the buffer, call zXml_Write a second time to 
//      write the characters to the buffer.

ZAPI_EXPORT(zStatus) zXml_SaveBytes(zXml xml, zByte** data, zUIntPtr* size); //
//  
//  Description:
//      Saves an XML document to an in-memory file.
//  Arguments:
//      xml - XML document object.
//      data - Receives the file data. 
//      size - Receives the file size.

ZAPI_EXPORT(zStatus) zXml_LoadBytes(zXml* xml, const zByte* data, zUIntPtr size); //
//  
//  Description:
//      Loads an XML document from an in-memory file.
//  Arguments:
//      xml - Destination for the constructed object handle.
//      data - File data.
//      size - File size. 

ZAPI_EXPORT(zStatus) zXml_ToString(zXml xml, zChar* buffer, z32u* written); //
//
//  Description:
//      Exports the XML document to a null-terminated character array.
//  Arguments:
//      xml - XML document object.
//      buffer - Buffer to receive the XML content, or zNULL (see notes below). 
//      written - Number of characters written to the buffer, including the null terminator.
//  Remarks: 
//      In order to determine the required size of a buffer large enough to contain the exported 
//      characters, call zXml_Write with zNULL as the buffer argument.  When the call 
//      completes, the written argument will report the required buffer size, including
//      the null terminator.  After allocating the buffer, call zXml_Write a second time to 
//      write the characters to the buffer.

ZAPI_EXPORT(zStatus) zXml_Load(zXml* xml, const zChar* fileName); //
//  
//  Description:
//      Loads an XML document from file.
//  Arguments:
//      xml - Destination for the constructed object handle.
//      fileName - Name of the file.

ZAPI_EXPORT(zStatus) zXml_Save(zXml xml, const zChar* fileName); //
//
//  Description:
//      Saves the XML document object to file.
//  Arguments:
//      xml - XML document object.
//      fileName - Name of the file.

ZAPI_EXPORT(zStatus) zXml_Clear(zXml xml); //
//
//  Description:
//      Removes all elements from the XML document. 
//  Arguments:
//      xml - XML document object.

ZAPI_EXPORT(zXmlItem) zXml_Root(zXml xml); //
//
//  Description:
//      Returns the root element of the XML document.
//  Arguments:
//      xml - XML document object.

ZAPI_EXPORT(zXmlItem) zXml_Child(zXml xml, zXmlItem parent, const zChar* path); //
//
//  Description:
//      Returns the child node at the given relative path.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.

ZAPI_EXPORT(zXmlItem) zXml_Parent(zXml xml, zXmlItem item); //
//
//  Description:
//      Returns the parent node of the given element.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(zXmlItem) zXml_FirstChild(zXml xml, zXmlItem parent); //
//
//  Description:
//      Returns the first child element of the given parent node.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 

ZAPI_EXPORT(zXmlItem) zXml_LastChild(zXml xml, zXmlItem parent);  //
//
//  Description:
//      Returns the last child element of the given parent node.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 

ZAPI_EXPORT(zXmlItem) zXml_NextSibling(zXml xml, zXmlItem item);  //
//
//  Description:
//      Returns the next sibling element of the given element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(zXmlItem) zXml_PreviousSibling(zXml xml, zXmlItem item);  //
//
//  Description:
//      Returns the previous sibling element of the given element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(zBool) zXml_ChildExists(zXml xml, zXmlItem parent, const zChar* path);  //
//
//  Description:
//      Reports whether a child node exists at the specified relative path.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.

ZAPI_EXPORT(z32u) zXml_ChildCount(zXml xml, zXmlItem parent);  //
//
//  Description:
//      Returns the number of child nodes for the given parent node.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 

ZAPI_EXPORT(zXmlItem) zXml_ChildAt(zXml xml, zXmlItem parent, z32u index);  //
//
//  Description:
//      Returns a child node at a specific index within the list of child nodes for the given parent node.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      index - Child node index.

ZAPI_EXPORT(zStatus) zXml_AddItem(zXml xml, zXmlItem parent, const zChar* name, zXmlItem* item);  //
//
//  Description:
//      Inserts a new child node at the end of the specified parent node's child list.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      name - Name of the new node.
//      item - Destination for the item handle.

ZAPI_EXPORT(zStatus) zXml_InsertItem(zXml xml, zXmlItem before, const zChar* name, zXmlItem* item); //
//
//  Description:
//      Inserts a new node before the specified sibling node.
//  Arguments:
//      xml - XML document object.
//      before - Sibling node. 
//      name - Name of the new node.
//      item - Destination for the item handle.
 
ZAPI_EXPORT(zStatus) zXml_CopyItem(zXml xml, zXmlItem parent, zXmlItem before, zXml srcXml, zXmlItem srcItem, zXmlItem* item);  //
//
//  Description:
//      Copies a node from one XML document to another XML document.
//  Arguments:
//      xml - Destination XML document object.
//      parent - Destination Parent node.
//      before - Destination sibling node (kNIL appends to end of parent's child list). 
//      srcXml - Source XML document object.
//      srcItem = Source XML element node.
//      item - Destination for the copied item handle.

ZAPI_EXPORT(const zChar*) zXml_ItemName(zXml xml, zXmlItem item);  //
//
//  Description:
//      Returns the name of an XML element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(zStatus) zXml_SetItemName(zXml xml, zXmlItem item, const zChar* name);  //
//
//  Description:
//      Sets the name of an XML element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Element name. 

ZAPI_EXPORT(zStatus) zXml_DeleteItem(zXml xml, zXmlItem item);  //
//
//  Description:
//      Deletes an XML element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(zStatus) zXml_ItemString(zXml xml, zXmlItem item, zChar** str);  //
//
//  Description:
//      Gets XML element node content as a character array.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      str - Receives null-terminated character array. 
//  Remarks: 
//      Use the zFree function to deallocate the received character array.

ZAPI_EXPORT(zStatus) zXml_ItemText(zXml xml, zXmlItem item, zChar* str, z32u capacity);  //
//
//  Description:
//      Gets XML element node content as a character array.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      str - Character array. 
//      capacity - Character array capacity, in bytes (includes null-terminator). 

ZAPI_EXPORT(zStatus) zXml_Item32u(zXml xml, zXmlItem item, z32u* value);  //
//
//  Description:
//      Gets XML element node content as a z32u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Item32s(zXml xml, zXmlItem item, z32s* value);  //
//
//  Description:
//      Gets XML element node content as a z32s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Item64u(zXml xml, zXmlItem item, z64u* value);  //
//
//  Description:
//      Gets XML element node content as a z64u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Item64s(zXml xml, zXmlItem item, z64s* value);  //
//
//  Description:
//      Gets XML element node content as a z64s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Item32f(zXml xml, zXmlItem item, z32f* value);  //
//
//  Description:
//      Gets XML element node content as a z32f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Item64f(zXml xml, zXmlItem item, z64f* value);  //
//
//  Description:
//      Gets XML element node content as a z64f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItemText(zXml xml, zXmlItem item, const zChar* str);  //
//
//  Description:
//      Sets XML element node content from a character array.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      str - Character array. 

ZAPI_EXPORT(zStatus) zXml_SetItem32u(zXml xml, zXmlItem item, z32u value);  //
//
//  Description:
//      Sets XML element node content from a z32u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItem32s(zXml xml, zXmlItem item, z32s value);  //
//
//  Description:
//      Sets XML element node content from a z32s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItem64u(zXml xml, zXmlItem item, z64u value);  //
//
//  Description:
//      Sets XML element node content from a z64u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItem64s(zXml xml, zXmlItem item, z64s value);  //
//
//  Description:
//      Sets XML element node content from a z64s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItem32f(zXml xml, zXmlItem item, z32f value);  //
//
//  Description:
//      Sets XML element node content from a z32f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetItem64f(zXml xml, zXmlItem item, z64f value);  //
//
//  Description:
//      Sets XML element node content from a z64f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_ChildString(zXml xml, zXmlItem parent, const zChar* path, zChar** str); //
//
//  Description:
//      Gets XML element node content as a character array.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      str - Receives null-terminated character array. 
//  Remarks: 
//      Use the zFree function to deallocate the received character array.

ZAPI_EXPORT(zStatus) zXml_ChildText(zXml xml, zXmlItem parent, const zChar* path, zChar* str, z32u capacity);  //
//
//  Description:
//      Gets XML child node content as a character array.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      str - Character array. 
//      capacity - Character array capacity, in bytes (includes null-terminator). 

ZAPI_EXPORT(zStatus) zXml_Child32u(zXml xml, zXmlItem parent, const zChar* path, z32u* value);  //
//
//  Description:
//      Gets XML child node content as a z32u value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Child32s(zXml xml, zXmlItem parent, const zChar* path, z32s* value);  //
//
//  Description:
//      Gets XML child node content as a z32s value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Child64u(zXml xml, zXmlItem parent, const zChar* path, z64u* value);  //
//
//  Description:
//      Gets XML child node content as a z64u value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Child64s(zXml xml, zXmlItem parent, const zChar* path, z64s* value);  //
//
//  Description:
//      Gets XML child node content as a z64s value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Child32f(zXml xml, zXmlItem parent, const zChar* path, z32f* value);  //
//
//  Description:
//      Gets XML child node content as a z32f value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Child64f(zXml xml, zXmlItem parent, const zChar* path, z64f* value);  //
//
//  Description:
//      Gets XML child node content as a z64f value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Returns XML content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetChildText(zXml xml, zXmlItem parent, const zChar* path, const zChar* str);  //
//
//  Description:
//      Sets XML child node content from a character array.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      str - Character array. 

ZAPI_EXPORT(zStatus) zXml_SetChild32u(zXml xml, zXmlItem parent, const zChar* path, z32u value);  //
//
//  Description:
//      Sets XML child node content from a z32u value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetChild32s(zXml xml, zXmlItem parent, const zChar* path, z32s value);  //
//
//  Description:
//      Sets XML child node content from a z32s value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetChild64u(zXml xml, zXmlItem parent, const zChar* path, z64u value);  //
//
//  Description:
//      Sets XML child node content from a z64u value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetChild64s(zXml xml, zXmlItem parent, const zChar* path, z64s value);  //
//
//  Description:
//      Sets XML child node content from a z64s value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetChild32f(zXml xml, zXmlItem parent, const zChar* path, z32f value); //
//
//  Description:
//      Sets XML child node content from a z32f value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 
 
ZAPI_EXPORT(zStatus) zXml_SetChild64f(zXml xml, zXmlItem parent, const zChar* path, z64f value);  //
//
//  Description:
//      Sets XML child node content from a z64f value.
//  Arguments:
//      xml - XML document object.
//      parent - Parent node. 
//      path - Path relative to the parent node.
//      value - Numeric value. 


ZAPI_EXPORT(zBool) zXml_AttrExists(zXml xml, zXmlItem item, const zChar* name);  //
//
//  Description:
//      Reports whether a specific attribute exists for the given XML element.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.

ZAPI_EXPORT(z32u) zXml_AttrCount(zXml xml, zXmlItem item);  //
//
//  Description:
//      Returns the number of attributes for the given XML element.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 

ZAPI_EXPORT(const zChar*) zXml_AttrNameAt(zXml xml, zXmlItem item, z32u index);  //
//
//  Description:
//      Returns an attribute at a specific index within the list of attributes for the given element node.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      index - Attribute index.

ZAPI_EXPORT(zStatus) zXml_DeleteAttr(zXml xml, zXmlItem item, const zChar* name);  //
//
//  Description:
//      Deletes an XML attribute.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.

ZAPI_EXPORT(zStatus) zXml_AttrText(zXml xml, zXmlItem item, const zChar* name, zChar* str, z32u capacity);  //
//
//  Description:
//      Gets XML attribute content as a character array.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      str - Character array. 
//      capacity - Character array capacity, in bytes (includes null-terminator). 

ZAPI_EXPORT(zStatus) zXml_Attr32u(zXml xml, zXmlItem item, const zChar* name, z32u* value);  //
//
//  Description:
//      Gets XML attribute content as a z32u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Attr32s(zXml xml, zXmlItem item, const zChar* name, z32s* value);  //
//
//  Description:
//      Gets XML attribute content as a z32s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Attr64u(zXml xml, zXmlItem item, const zChar* name, z64u* value);  //
//
//  Description:
//      Gets XML attribute content as a z64u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Attr64s(zXml xml, zXmlItem item, const zChar* name, z64s* value);  //
//
//  Description:
//      Gets XML attribute content as a z64s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Attr32f(zXml xml, zXmlItem item, const zChar* name, z32f* value); //
//
//  Description:
//      Gets XML attribute content as a z32f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_Attr64f(zXml xml, zXmlItem item, const zChar* name, z64f* value);  //
//
//  Description:
//      Gets XML attribute content as a z64f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Returns attribute content as a numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetAttrText(zXml xml, zXmlItem item, const zChar* name, const zChar* str); //
//
//  Description:
//      Sets XML attribute content from a character array.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      str - Character array. 
 
ZAPI_EXPORT(zStatus) zXml_SetAttr32u(zXml xml, zXmlItem item, const zChar* name, z32u value);  //
//
//  Description:
//      Sets XML attribute content from a z32u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetAttr32s(zXml xml, zXmlItem item, const zChar* name, z32s value); //
//
//  Description:
//      Sets XML attribute content from a z32s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 
 
ZAPI_EXPORT(zStatus) zXml_SetAttr64u(zXml xml, zXmlItem item, const zChar* name, z64u value); //
//
//  Description:
//      Sets XML attribute content from a z64u value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetAttr64s(zXml xml, zXmlItem item, const zChar* name, z64s value); //
//
//  Description:
//      Sets XML attribute content from a z64s value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetAttr32f(zXml xml, zXmlItem item, const zChar* name, z32f value);  //
//
//  Description:
//      Sets XML attribute content from a z32f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 

ZAPI_EXPORT(zStatus) zXml_SetAttr64f(zXml xml, zXmlItem item, const zChar* name, z64f value);  //
//
//  Description:
//      Sets XML attribute content from a z64f value.
//  Arguments:
//      xml - XML document object.
//      item - Element node. 
//      name - Attribute name.
//      value - Numeric value. 

#include <zApiEnd.h>

#endif      /* #ifndef LMITECH_ZXML_H_INCLUDED */
