/**< The "parseString" function parse an XML string and return the root of a XMLNode tree. The "opposite" of this function is
* the function "createXMLString" that re-creates an XML string from an XMLNode tree. If the XML document is corrupted, the
* "parseString" method will initialize the "pResults" variable with some information that can be used to trace the error.
* If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the
* beginning of the "xmlParser.cpp" file.
*
* @param lpXMLString the XML string to parse
* @param tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
* @param pResults a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.
*/
/// Parse an XML file and return the root of a XMLNode tree representing the file.
/**< The "parseFile" function parse an XML file and return the root of a XMLNode tree. The "opposite" of this function is
* the function "writeToFile" that re-creates an XML file from an XMLNode tree. If the XML document is corrupted, the
* "parseFile" method will initialize the "pResults" variable with some information that can be used to trace the error.
* If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the
* beginning of the "xmlParser.cpp" file.
*
* @param filename the path to the XML file to parse
* @param tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
* @param pResults a pointer to a XMLResults variable that will contain some information that can be used to trace the XML parsing error. You can have a user-friendly explanation of the parsing error with the "getError" function.
*/
/// Parse an XML file and return the root of a XMLNode tree representing the file. A very crude error checking is made. An attempt to guess the Char Encoding used in the file is made.
/**< The "openFileHelper" function reports to the screen all the warnings and errors that occurred during parsing of the XML file.
* This function also tries to guess char Encoding (UTF-8, ASCII or SHIT-JIS) based on the first 200 bytes of the file. Since each
* application has its own way to report and deal with errors, you should rather use the "parseFile" function to parse XML files
* and program yourself thereafter an "error reporting" tailored for your needs (instead of using the very crude "error reporting"
* mechanism included inside the "openFileHelper" function).
*
* If the XML document is corrupted, the "openFileHelper" method will:
* - display an error message on the console (or inside a messageBox for windows).
* - stop execution (exit).
*
* I strongly suggest that you write your own "openFileHelper" method tailored to your needs. If you still want to parse
* the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "xmlParser.cpp" file.
*
* @param filename the path of the XML file to parse.
* @param tag the name of the first tag inside the XML file. If the tag parameter is omitted, this function returns a node that represents the head of the xml document including the declaration term (<? ... ?>).
*/
staticXMLCSTRgetError(XMLErrorerror);///< this gives you a user-friendly explanation of the parsing error
/// Create an XML string starting from the current XMLNode.
/**< The returned string should be free'd using the "freeXMLString" function.
*
* If nFormat==0, no formatting is required otherwise this returns an user friendly XML string from a given element
* with appropriate white spaces and carriage returns. if pnSize is given it returns the size in character of the string. */
/// Save the content of an xmlNode inside a file
XMLErrorwriteToFile(XMLCSTRfilename,
constchar*encoding=NULL,
charnFormat=1)const;
/**< If nFormat==0, no formatting is required otherwise this returns an user friendly XML string from a given element with appropriate white spaces and carriage returns.
* If the global parameter "characterEncoding==encoding_UTF8", then the "encoding" parameter is ignored and always set to "utf-8".
* If the global parameter "characterEncoding==encoding_ShiftJIS", then the "encoding" parameter is ignored and always set to "SHIFT-JIS".
* If "_XMLWIDECHAR=1", then the "encoding" parameter is ignored and always set to "utf-16".
* If no "encoding" parameter is given the "ISO-8859-1" encoding is used. */
/** @} */
/** @defgroup navigate Navigate the XMLNode structure
* @ingroup XMLParserGeneral
* @{ */
XMLCSTRgetName()const;///< name of the node
XMLCSTRgetText(inti=0)const;///< return ith text field
intnText()const;///< nbr of text field
XMLNodegetParentNode()const;///< return the parent node
XMLNodegetChildNode(XMLCSTRname,inti)const;///< return ith child node with specific name (return an empty node if failing). If i==-1, this returns the last XMLNode with the given name.
XMLNodegetChildNode(XMLCSTRname,int*i=NULL)const;///< return next child node with specific name (return an empty node if failing)
XMLNodegetChildNodeWithAttribute(XMLCSTRtagName,
XMLCSTRattributeName,
XMLCSTRattributeValue=NULL,
int*i=NULL)const;///< return child node with specific name/attribute (return an empty node if failing)
XMLCSTRgetAttributeName(inti=0)const;///< return ith attribute name
XMLCSTRgetAttributeValue(inti=0)const;///< return ith attribute value
charisAttributeSet(XMLCSTRname)const;///< test if an attribute with a specific name is given
XMLCSTRgetAttribute(XMLCSTRname,inti)const;///< return ith attribute content with specific name (return a NULL if failing)
XMLCSTRgetAttribute(XMLCSTRname,int*i=NULL)const;///< return next attribute content with specific name (return a NULL if failing)
intnAttribute()const;///< nbr of attribute
XMLCleargetClear(inti=0)const;///< return ith clear field (comments)
intnClear()const;///< nbr of clear field
XMLNodeContentsenumContents(XMLElementPositioni)const;///< enumerate all the different contents (attribute,child,text, clear) of the current XMLNode. The order is reflecting the order of the original file/string. NOTE: 0 <= i < nElement();
intnElement()const;///< nbr of different contents for current node
charisEmpty()const;///< is this node Empty?
charisDeclaration()const;///< is this node a declaration <? .... ?>
XMLNodedeepCopy()const;///< deep copy (duplicate/clone) a XMLNode
/** @defgroup creation Creating from scratch a XMLNode structure
* @ingroup xmlModify
* @{ */
staticXMLNodecreateXMLTopNode(XMLCSTRlpszName,charisDeclaration=FALSE);///< Create the top node of an XMLNode structure
XMLNodeaddChild(XMLCSTRlpszName,charisDeclaration=FALSE,XMLElementPositionpos=-1);///< Add a new child node
XMLNodeaddChild(XMLNodenodeToAdd,XMLElementPositionpos=-1);///< If the "nodeToAdd" has some parents, it will be detached from it's parents before being attached to the current XMLNode
XMLAttribute*addAttribute(XMLCSTRlpszName,XMLCSTRlpszValuev);///< Add a new attribute
XMLCSTRaddText(XMLCSTRlpszValue,XMLElementPositionpos=-1);///< Add a new text content
XMLCSTRupdateName(XMLCSTRlpszName);///< change node's name
XMLAttribute*updateAttribute(XMLAttribute*newAttribute,XMLAttribute*oldAttribute);///< if the attribute to update is missing, a new one will be added
XMLAttribute*updateAttribute(XMLCSTRlpszNewValue,XMLCSTRlpszNewName=NULL,inti=0);///< if the attribute to update is missing, a new one will be added
XMLAttribute*updateAttribute(XMLCSTRlpszNewValue,XMLCSTRlpszNewName,XMLCSTRlpszOldName);///< set lpszNewName=NULL if you don't want to change the name of the attribute if the attribute to update is missing, a new one will be added
XMLCSTRupdateText(XMLCSTRlpszNewValue,inti=0);///< if the text to update is missing, a new one will be added
XMLCSTRupdateText(XMLCSTRlpszNewValue,XMLCSTRlpszOldValue);///< if the text to update is missing, a new one will be added
XMLClear*updateClear(XMLCSTRlpszNewContent,inti=0);///< if the clearTag to update is missing, a new one will be added
XMLClear*updateClear(XMLClear*newP,XMLClear*oldP);///< if the clearTag to update is missing, a new one will be added
XMLClear*updateClear(XMLCSTRlpszNewValue,XMLCSTRlpszOldValue);///< if the clearTag to update is missing, a new one will be added
/** @} */
/** @defgroup xmlDelete Deleting Nodes or Attributes
* @ingroup xmlModify
* Some deletion functions:
* @{
*/
/// The "deleteNodeContent" function forces the deletion of the content of this XMLNode and the subtree.
voiddeleteNodeContent();
/**< \note The XMLNode instances that are referring to the part of the subtree that has been deleted CANNOT be used anymore!!. Unexpected results will occur if you continue using them. */
voiddeleteAttribute(inti=0);///< Delete the ith attribute of the current XMLNode
voiddeleteAttribute(XMLCSTRlpszName);///< Delete the attribute with the given name (the "strcmp" function is used to find the right attribute)
voiddeleteAttribute(XMLAttribute*anAttribute);///< Delete the attribute with the name "anAttribute->lpszName" (the "strcmp" function is used to find the right attribute)
voiddeleteText(inti=0);///< Delete the Ith text content of the current XMLNode
voiddeleteText(XMLCSTRlpszValue);///< Delete the text content "lpszValue" inside the current XMLNode (direct "pointer-to-pointer" comparison is used to find the right text)
voiddeleteClear(inti=0);///< Delete the Ith clear tag inside the current XMLNode
voiddeleteClear(XMLCSTRlpszValue);///< Delete the clear tag "lpszValue" inside the current XMLNode (direct "pointer-to-pointer" comparison is used to find the clear tag)
voiddeleteClear(XMLClear*p);///< Delete the clear tag "p" inside the current XMLNode (direct "pointer-to-pointer" comparison on the lpszName of the clear tag is used to find the clear tag)
/** @} */
/** @defgroup xmlWOSD ???_WOSD functions.
* @ingroup xmlModify
* The strings given as parameters for the "add" and "update" methods that have a name with
* the postfix "_WOSD" (that means "WithOut String Duplication")(for example "addText_WOSD")
* will be free'd by the XMLNode class. For example, it means that this is incorrect:
staticXMLNodecreateXMLTopNode_WOSD(XMLSTRlpszName,charisDeclaration=FALSE);///< Create the top node of an XMLNode structure
XMLNodeaddChild_WOSD(XMLSTRlpszName,charisDeclaration=FALSE,XMLElementPositionpos=-1);///< Add a new child node
XMLAttribute*addAttribute_WOSD(XMLSTRlpszName,XMLSTRlpszValue);///< Add a new attribute
XMLCSTRaddText_WOSD(XMLSTRlpszValue,XMLElementPositionpos=-1);///< Add a new text content
XMLClear*addClear_WOSD(XMLSTRlpszValue,XMLCSTRlpszOpen=NULL,XMLCSTRlpszClose=NULL,XMLElementPositionpos=-1);///< Add a new clear Tag
XMLCSTRupdateName_WOSD(XMLSTRlpszName);///< change node's name
XMLAttribute*updateAttribute_WOSD(XMLAttribute*newAttribute,XMLAttribute*oldAttribute);///< if the attribute to update is missing, a new one will be added
XMLAttribute*updateAttribute_WOSD(XMLSTRlpszNewValue,XMLSTRlpszNewName=NULL,inti=0);///< if the attribute to update is missing, a new one will be added
XMLAttribute*updateAttribute_WOSD(XMLSTRlpszNewValue,XMLSTRlpszNewName,XMLCSTRlpszOldName);///< set lpszNewName=NULL if you don't want to change the name of the attribute if the attribute to update is missing, a new one will be added
XMLCSTRupdateText_WOSD(XMLSTRlpszNewValue,inti=0);///< if the text to update is missing, a new one will be added
XMLCSTRupdateText_WOSD(XMLSTRlpszNewValue,XMLCSTRlpszOldValue);///< if the text to update is missing, a new one will be added
XMLClear*updateClear_WOSD(XMLSTRlpszNewContent,inti=0);///< if the clearTag to update is missing, a new one will be added
XMLClear*updateClear_WOSD(XMLClear*newP,XMLClear*oldP);///< if the clearTag to update is missing, a new one will be added
XMLClear*updateClear_WOSD(XMLSTRlpszNewValue,XMLCSTRlpszOldValue);///< if the clearTag to update is missing, a new one will be added
/** @} */
/** @defgroup xmlPosition Position helper functions (use in conjunction with the update&add functions
* @ingroup xmlModify
* These are some useful functions when you want to insert a childNode, a text or a XMLClearTag in the
* middle (at a specified position) of a XMLNode tree already constructed. The value returned by these
* methods is to be used as last parameter (parameter 'pos') of addChild, addText or addClear.
XMLElementPositionpositionOfChildNode(XMLCSTRname,inti=0)const;///< return the position of the ith childNode with the specified name if (name==NULL) return the position of the ith childNode
/** @} */
/// Enumeration for XML character encoding.
typedefenumXMLCharEncoding
{
char_encoding_error=0,
char_encoding_UTF8=1,
char_encoding_legacy=2,
char_encoding_ShiftJIS=3,
char_encoding_GB2312=4,
char_encoding_Big5=5,
char_encoding_GBK=6// this is actually the same as Big5
* Using the "ToXMLStringTool class" and the "fprintf function" is THE most efficient
* way to produce VERY large XML documents VERY fast.
* \note If you are creating from scratch an XML file using the provided XMLNode class
* you must not use the "ToXMLStringTool" class (because the "XMLNode" class does the
* processing job for you during rendering).*/
typedefstructXMLDLLENTRYToXMLStringTool
{
public:
ToXMLStringTool():buf(NULL),buflen(0){}
~ToXMLStringTool();
voidfreeBuffer();///<call this function when you have finished using this object to release memory used by the internal buffer.
XMLSTRtoXML(XMLCSTRsource);///< returns a pointer to an internal buffer that contains a XML-encoded string based on the "source" parameter.
/** The "toXMLUnSafe" function is deprecated because there is a possibility of
* "destination-buffer-overflow". It converts the string
* "source" to the string "dest". */
staticXMLSTRtoXMLUnSafe(XMLSTRdest,XMLCSTRsource);///< deprecated: use "toXML" instead
staticintlengthXMLString(XMLCSTRsource);///< deprecated: use "toXML" instead
private:
XMLSTRbuf;
intbuflen;
}ToXMLStringTool;
/** @} */
/** @defgroup XMLParserBase64Tool Helper class to include binary data inside XML strings using "Base64 encoding".
* @ingroup XMLParserGeneral
* @{ */
/// Helper class to include binary data inside XML strings using "Base64 encoding".
/** The "XMLParserBase64Tool" class allows you to include any binary data (images, sounds,...)
* into an XML document using "Base64 encoding". This class is completely
* separated from the rest of the xmlParser library and can be removed without any problem.
* To include some binary data into an XML file, you must convert the binary data into
* standard text (using "encode"). To retrieve the original binary data from the
* b64-encoded text included inside the XML file, use "decode". Alternatively, these
* functions can also be used to "encrypt/decrypt" some critical data contained inside
* the XML (it's not a strong encryption at all, but sometimes it can be useful). */
typedefstructXMLDLLENTRYXMLParserBase64Tool
{
public:
XMLParserBase64Tool():buf(NULL),buflen(0){}
~XMLParserBase64Tool();
voidfreeBuffer();///< Call this function when you have finished using this object to release memory used by the internal buffer.
/**
* @param formatted If "formatted"=true, some space will be reserved for a carriage-return every 72 chars. */
staticintencodeLength(intinBufLen,charformatted=0);///< return the length of the base64 string that encodes a data buffer of size inBufLen bytes.
/**
* The "base64Encode" function returns a string containing the base64 encoding of "inByteLen" bytes
* from "inByteBuf". If "formatted" parameter is true, then there will be a carriage-return every 72 chars.
* The string will be free'd when the XMLParserBase64Tool object is deleted.
* All returned strings are sharing the same memory space. */
XMLSTRencode(unsignedchar*inByteBuf,unsignedintinByteLen,charformatted=0);///< returns a pointer to an internal buffer containing the base64 string containing the binary data encoded from "inByteBuf"
/// returns the number of bytes which will be decoded from "inString".
* The "decode" function returns a pointer to a buffer containing the binary data decoded from "inString"
* The output buffer will be free'd when the XMLParserBase64Tool object is deleted.
* All output buffer are sharing the same memory space.
* @param inString If "instring" is malformed, NULL will be returned */
unsignedchar*decode(XMLCSTRinString,int*outByteLen=NULL,XMLError*xe=NULL);///< returns a pointer to an internal buffer containing the binary data decoded from "inString"
/**
* decodes data from "inString" to "outByteBuf". You need to provide the size (in byte) of "outByteBuf"
* in "inMaxByteOutBuflen". If "outByteBuf" is not large enough or if data is malformed, then "FALSE"
