1/****************************************************************************/ 2/*! \mainpage XMLParser library 3 * \section intro_sec Introduction 4 * 5 * This is a basic XML parser written in ANSI C++ for portability. 6 * It works by using recursion and a node tree for breaking 7 * down the elements of an XML document. 8 * 9 * @version V2.41 10 * @author Frank Vanden Berghen 11 * 12 * The following license terms for the "XMLParser library from Business-Insight" apply to projects 13 * that are in some way related to 14 * the "mcpat project", including applications 15 * using "mcpat project" and tools developed 16 * for enhancing "mcpat project". All other projects 17 * (not related to "mcpat project") have to use the "XMLParser library from Business-Insight" 18 * code under the Aladdin Free Public License (AFPL) 19 * See the file "AFPL-license.txt" for more informations about the AFPL license. 20 * (see http://www.artifex.com/downloads/doc/Public.htm for detailed AFPL terms) 21 * 22 * Redistribution and use of the "XMLParser library from Business-Insight" in source and binary forms, with or without 23 * modification, are permitted provided that the following conditions are met: 24 * * Redistributions of source code must retain the above copyright 25 * notice, this list of conditions and the following disclaimer. 26 * * Redistributions in binary form must reproduce the above copyright 27 * notice, this list of conditions and the following disclaimer in the 28 * documentation and/or other materials provided with the distribution. 29 * * Neither the name of Frank Vanden Berghen nor the 30 * names of its contributors may be used to endorse or promote products 31 * derived from this software without specific prior written permission. 32 * 33 * THIS SOFTWARE IS PROVIDED BY Business-Insight ``AS IS'' AND ANY 34 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 35 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 36 * DISCLAIMED. IN NO EVENT SHALL Business-Insight BE LIABLE FOR ANY 37 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 38 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 39 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 40 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 41 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 42 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 43 * 44 * Copyright (c) 2002, Business-Insight 45 * Copyright (c) 2010-2013 Advanced Micro Devices, Inc. 46 * <a href="http://www.Business-Insight.com">Business-Insight</a> 47 * All rights reserved. 48 * 49 * \section tutorial First Tutorial 50 * You can follow a simple <a href="../../xmlParser.html">Tutorial</a> to know the basics... 51 * 52 * \section usage General usage: How to include the XMLParser library inside your project. 53 * 54 * The library is composed of two files: <a href="../../xmlParser.cpp">xmlParser.cpp</a> and 55 * <a href="../../xmlParser.h">xmlParser.h</a>. These are the ONLY 2 files that you need when 56 * using the library inside your own projects. 57 * 58 * All the functions of the library are documented inside the comments of the file 59 * <a href="../../xmlParser.h">xmlParser.h</a>. These comments can be transformed in 60 * full-fledged HTML documentation using the DOXYGEN software: simply type: "doxygen doxy.cfg" 61 * 62 * By default, the XMLParser library uses (char*) for string representation.To use the (wchar_t*) 63 * version of the library, you need to define the "_UNICODE" preprocessor definition variable 64 * (this is usually done inside your project definition file) (This is done automatically for you 65 * when using Visual Studio). 66 * 67 * \section example Advanced Tutorial and Many Examples of usage. 68 * 69 * Some very small introductory examples are described inside the Tutorial file 70 * <a href="../../xmlParser.html">xmlParser.html</a> 71 * 72 * Some additional small examples are also inside the file <a href="../../xmlTest.cpp">xmlTest.cpp</a> 73 * (for the "char*" version of the library) and inside the file 74 * <a href="../../xmlTestUnicode.cpp">xmlTestUnicode.cpp</a> (for the "wchar_t*" 75 * version of the library). If you have a question, please review these additionnal examples 76 * before sending an e-mail to the author. 77 * 78 * To build the examples: 79 * - linux/unix: type "make" 80 * - solaris: type "make -f makefile.solaris" 81 * - windows: Visual Studio: double-click on xmlParser.dsw 82 * (under Visual Studio .NET, the .dsp and .dsw files will be automatically converted to .vcproj and .sln files) 83 * 84 * In order to build the examples you need some additional files: 85 * - linux/unix: makefile 86 * - solaris: makefile.solaris 87 * - windows: Visual Studio: *.dsp, xmlParser.dsw and also xmlParser.lib and xmlParser.dll 88 * 89 * \section debugging Debugging with the XMLParser library 90 * 91 * \subsection debugwin Debugging under WINDOWS 92 * 93 * Inside Visual C++, the "debug versions" of the memory allocation functions are 94 * very slow: Do not forget to compile in "release mode" to get maximum speed. 95 * When I had to debug a software that was using the XMLParser Library, it was usually 96 * a nightmare because the library was sooOOOoooo slow in debug mode (because of the 97 * slow memory allocations in Debug mode). To solve this 98 * problem, during all the debugging session, I am now using a very fast DLL version of the 99 * XMLParser Library (the DLL is compiled in release mode). Using the DLL version of 100 * the XMLParser Library allows me to have lightening XML parsing speed even in debug! 101 * Other than that, the DLL version is useless: In the release version of my tool, 102 * I always use the normal, ".cpp"-based, XMLParser Library (I simply include the 103 * <a href="../../xmlParser.cpp">xmlParser.cpp</a> and 104 * <a href="../../xmlParser.h">xmlParser.h</a> files into the project). 105 * 106 * The file <a href="../../XMLNodeAutoexp.txt">XMLNodeAutoexp.txt</a> contains some 107 * "tweaks" that improve substancially the display of the content of the XMLNode objects 108 * inside the Visual Studio Debugger. Believe me, once you have seen inside the debugger 109 * the "smooth" display of the XMLNode objects, you cannot live without it anymore! 110 * 111 * \subsection debuglinux Debugging under LINUX/UNIX 112 * 113 * The speed of the debug version of the XMLParser library is tolerable so no extra 114 * work.has been done. 115 * 116 ****************************************************************************/ 117 118#ifndef __INCLUDE_XML_NODE__ 119#define __INCLUDE_XML_NODE__ 120 121#include <stdlib.h> 122 123#ifdef _UNICODE 124// If you comment the next "define" line then the library will never "switch to" _UNICODE (wchar_t*) mode (16/32 bits per characters). 125// This is useful when you get error messages like: 126// 'XMLNode::openFileHelper' : cannot convert parameter 2 from 'const char [5]' to 'const wchar_t *' 127// The _XMLWIDECHAR preprocessor variable force the XMLParser library into either utf16/32-mode (the proprocessor variable 128// must be defined) or utf8-mode(the pre-processor variable must be undefined). 129#define _XMLWIDECHAR 130#endif 131 132#if defined(WIN32) || defined(UNDER_CE) || defined(_WIN32) || defined(WIN64) || defined(__BORLANDC__) 133// comment the next line if you are under windows and the compiler is not Microsoft Visual Studio (6.0 or .NET) or Borland 134#define _XMLWINDOWS 135#endif 136 137#ifdef XMLDLLENTRY 138#undef XMLDLLENTRY 139#endif 140#ifdef _USE_XMLPARSER_DLL 141#ifdef _DLL_EXPORTS_ 142#define XMLDLLENTRY __declspec(dllexport) 143#else 144#define XMLDLLENTRY __declspec(dllimport) 145#endif 146#else 147#define XMLDLLENTRY 148#endif 149 150// uncomment the next line if you want no support for wchar_t* (no need for the <wchar.h> or <tchar.h> libraries anymore to compile) 151//#define XML_NO_WIDE_CHAR 152 153#ifdef XML_NO_WIDE_CHAR 154#undef _XMLWINDOWS 155#undef _XMLWIDECHAR 156#endif 157 158#ifdef _XMLWINDOWS 159#include <tchar.h> 160#else 161#define XMLDLLENTRY 162#ifndef XML_NO_WIDE_CHAR 163#include <wchar.h> // to have 'wcsrtombs' for ANSI version 164// to have 'mbsrtowcs' for WIDECHAR version 165#endif 166#endif 167 168// Some common types for char set portable code 169#ifdef _XMLWIDECHAR 170#define _CXML(c) L ## c 171#define XMLCSTR const wchar_t * 172#define XMLSTR wchar_t * 173#define XMLCHAR wchar_t 174#else 175#define _CXML(c) c 176#define XMLCSTR const char * 177#define XMLSTR char * 178#define XMLCHAR char 179#endif 180#ifndef FALSE 181#define FALSE 0 182#endif /* FALSE */ 183#ifndef TRUE 184#define TRUE 1 185#endif /* TRUE */ 186 187 188/// Enumeration for XML parse errors. 189typedef enum XMLError { 190 eXMLErrorNone = 0, 191 eXMLErrorMissingEndTag, 192 eXMLErrorNoXMLTagFound, 193 eXMLErrorEmpty, 194 eXMLErrorMissingTagName, 195 eXMLErrorMissingEndTagName, 196 eXMLErrorUnmatchedEndTag, 197 eXMLErrorUnmatchedEndClearTag, 198 eXMLErrorUnexpectedToken, 199 eXMLErrorNoElements, 200 eXMLErrorFileNotFound, 201 eXMLErrorFirstTagNotFound, 202 eXMLErrorUnknownCharacterEntity, 203 eXMLErrorCharacterCodeAbove255, 204 eXMLErrorCharConversionError, 205 eXMLErrorCannotOpenWriteFile, 206 eXMLErrorCannotWriteFile, 207 208 eXMLErrorBase64DataSizeIsNotMultipleOf4, 209 eXMLErrorBase64DecodeIllegalCharacter, 210 eXMLErrorBase64DecodeTruncatedData, 211 eXMLErrorBase64DecodeBufferTooSmall 212} XMLError; 213 214 215/// Enumeration used to manage type of data. Use in conjunction with structure XMLNodeContents 216typedef enum XMLElementType { 217 eNodeChild = 0, 218 eNodeAttribute = 1, 219 eNodeText = 2, 220 eNodeClear = 3, 221 eNodeNULL = 4 222} XMLElementType; 223 224/// Structure used to obtain error details if the parse fails. 225typedef struct XMLResults { 226 enum XMLError error; 227 int nLine; 228 int nColumn; 229} XMLResults; 230 231/// Structure for XML clear (unformatted) node (usually comments) 232typedef struct XMLClear { 233 XMLCSTR lpszValue; 234 XMLCSTR lpszOpenTag; 235 XMLCSTR lpszCloseTag; 236} XMLClear; 237 238/// Structure for XML attribute. 239typedef struct XMLAttribute { 240 XMLCSTR lpszName; 241 XMLCSTR lpszValue; 242} XMLAttribute; 243 244/// XMLElementPosition are not interchangeable with simple indexes 245typedef int XMLElementPosition; 246 247struct XMLNodeContents; 248 249/** @defgroup XMLParserGeneral The XML parser */ 250 251/// Main Class representing a XML node 252/** 253 * All operations are performed using this class. 254 * \note The constructors of the XMLNode class are protected, so use instead one of these four methods to get your first instance of XMLNode: 255 * <ul> 256 * <li> XMLNode::parseString </li> 257 * <li> XMLNode::parseFile </li> 258 * <li> XMLNode::openFileHelper </li> 259 * <li> XMLNode::createXMLTopNode (or XMLNode::createXMLTopNode_WOSD)</li> 260 * </ul> */ 261typedef struct XMLDLLENTRY XMLNode { 262private: 263 264 struct XMLNodeDataTag; 265 266 /// Constructors are protected, so use instead one of: XMLNode::parseString, XMLNode::parseFile, XMLNode::openFileHelper, XMLNode::createXMLTopNode 267 XMLNode(struct XMLNodeDataTag *pParent, XMLSTR lpszName, char isDeclaration); 268 /// Constructors are protected, so use instead one of: XMLNode::parseString, XMLNode::parseFile, XMLNode::openFileHelper, XMLNode::createXMLTopNode 269 XMLNode(struct XMLNodeDataTag *p); 270 271public: 272 static XMLCSTR getVersion();///< Return the XMLParser library version number 273 274 /** @defgroup conversions Parsing XML files/strings to an XMLNode structure and Rendering XMLNode's to files/string. 275 * @ingroup XMLParserGeneral 276 * @{ */ 277 278 /// Parse an XML string and return the root of a XMLNode tree representing the string. 279 static XMLNode parseString(XMLCSTR lpXMLString, XMLCSTR tag = NULL, 280 XMLResults *pResults = NULL); 281 /**< The "parseString" function parse an XML string and return the root of a XMLNode tree. The "opposite" of this function is 282 * the function "createXMLString" that re-creates an XML string from an XMLNode tree. If the XML document is corrupted, the 283 * "parseString" method will initialize the "pResults" variable with some information that can be used to trace the error. 284 * If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the 285 * beginning of the "xmlParser.cpp" file. 286 * 287 * @param lpXMLString the XML string to parse 288 * @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 (<? ... ?>). 289 * @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. 290 */ 291 292 /// Parse an XML file and return the root of a XMLNode tree representing the file. 293 static XMLNode parseFile(XMLCSTR filename, XMLCSTR tag = NULL, 294 XMLResults *pResults = NULL); 295 /**< The "parseFile" function parse an XML file and return the root of a XMLNode tree. The "opposite" of this function is 296 * the function "writeToFile" that re-creates an XML file from an XMLNode tree. If the XML document is corrupted, the 297 * "parseFile" method will initialize the "pResults" variable with some information that can be used to trace the error. 298 * If you still want to parse the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the 299 * beginning of the "xmlParser.cpp" file. 300 * 301 * @param filename the path to the XML file to parse 302 * @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 (<? ... ?>). 303 * @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. 304 */ 305 306 /// 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. 307 static XMLNode openFileHelper(XMLCSTR filename, XMLCSTR tag = NULL); 308 /**< The "openFileHelper" function reports to the screen all the warnings and errors that occurred during parsing of the XML file. 309 * 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 310 * application has its own way to report and deal with errors, you should rather use the "parseFile" function to parse XML files 311 * and program yourself thereafter an "error reporting" tailored for your needs (instead of using the very crude "error reporting" 312 * mechanism included inside the "openFileHelper" function). 313 * 314 * If the XML document is corrupted, the "openFileHelper" method will: 315 * - display an error message on the console (or inside a messageBox for windows). 316 * - stop execution (exit). 317 * 318 * I strongly suggest that you write your own "openFileHelper" method tailored to your needs. If you still want to parse 319 * the file, you can use the APPROXIMATE_PARSING option as explained inside the note at the beginning of the "xmlParser.cpp" file. 320 * 321 * @param filename the path of the XML file to parse. 322 * @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 (<? ... ?>). 323 */ 324 325 static XMLCSTR getError(XMLError error); ///< this gives you a user-friendly explanation of the parsing error 326 327 /// Create an XML string starting from the current XMLNode. 328 XMLSTR createXMLString(int nFormat = 1, int *pnSize = NULL) const; 329 /**< The returned string should be free'd using the "freeXMLString" function. 330 * 331 * If nFormat==0, no formatting is required otherwise this returns an user friendly XML string from a given element 332 * with appropriate white spaces and carriage returns. if pnSize is given it returns the size in character of the string. */ 333 334 /// Save the content of an xmlNode inside a file 335 XMLError writeToFile(XMLCSTR filename, 336 const char *encoding = NULL, 337 char nFormat = 1) const; 338 /**< 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. 339 * If the global parameter "characterEncoding==encoding_UTF8", then the "encoding" parameter is ignored and always set to "utf-8". 340 * If the global parameter "characterEncoding==encoding_ShiftJIS", then the "encoding" parameter is ignored and always set to "SHIFT-JIS". 341 * If "_XMLWIDECHAR=1", then the "encoding" parameter is ignored and always set to "utf-16". 342 * If no "encoding" parameter is given the "ISO-8859-1" encoding is used. */ 343 /** @} */ 344 345 /** @defgroup navigate Navigate the XMLNode structure 346 * @ingroup XMLParserGeneral 347 * @{ */ 348 XMLCSTR getName() const; ///< name of the node 349 XMLCSTR getText(int i=0) const; ///< return ith text field 350 int nText() const; ///< nbr of text field 351 XMLNode getParentNode() const; ///< return the parent node 352 XMLNode getChildNode(int i=0) const; ///< return ith child node 353 XMLNode getChildNode(XMLCSTR name, int i) 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. 354 XMLNode getChildNode(XMLCSTR name, int *i=NULL) const; ///< return next child node with specific name (return an empty node if failing) 355 XMLNode* getChildNodePtr(XMLCSTR name, int *j) const; 356 XMLNode getChildNodeWithAttribute(XMLCSTR tagName, 357 XMLCSTR attributeName, 358 XMLCSTR attributeValue=NULL, 359 int *i=NULL) const; ///< return child node with specific name/attribute (return an empty node if failing) 360 XMLNode getChildNodeByPath(XMLCSTR path, char createNodeIfMissing=0, XMLCHAR sep='/'); 361 ///< return the first child node with specific path 362 XMLNode getChildNodeByPathNonConst(XMLSTR path, char createNodeIfMissing=0, XMLCHAR sep='/'); 363 ///< return the first child node with specific path. 364 365 int nChildNode(XMLCSTR name) const; ///< return the number of child node with specific name 366 int nChildNode() const; ///< nbr of child node 367 XMLAttribute getAttribute(int i=0) const; ///< return ith attribute 368 XMLCSTR getAttributeName(int i=0) const; ///< return ith attribute name 369 XMLCSTR getAttributeValue(int i=0) const; ///< return ith attribute value 370 char isAttributeSet(XMLCSTR name) const; ///< test if an attribute with a specific name is given 371 XMLCSTR getAttribute(XMLCSTR name, int i) const; ///< return ith attribute content with specific name (return a NULL if failing) 372 XMLCSTR getAttribute(XMLCSTR name, int *i=NULL) const; ///< return next attribute content with specific name (return a NULL if failing) 373 int nAttribute() const; ///< nbr of attribute 374 XMLClear getClear(int i=0) const; ///< return ith clear field (comments) 375 int nClear() const; ///< nbr of clear field 376 XMLNodeContents enumContents(XMLElementPosition i) 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(); 377 int nElement() const; ///< nbr of different contents for current node 378 char isEmpty() const; ///< is this node Empty? 379 char isDeclaration() const; ///< is this node a declaration <? .... ?> 380 XMLNode deepCopy() const; ///< deep copy (duplicate/clone) a XMLNode 381 static XMLNode emptyNode(); ///< return XMLNode::emptyXMLNode; 382 /** @} */ 383 384 ~XMLNode(); 385 XMLNode(const XMLNode &A); ///< to allow shallow/fast copy: 386 XMLNode& operator=( const XMLNode& A ); ///< to allow shallow/fast copy: 387 388 XMLNode(): d(NULL){}; 389 static XMLNode emptyXMLNode; 390 static XMLClear emptyXMLClear; 391 static XMLAttribute emptyXMLAttribute; 392 393 /** @defgroup xmlModify Create or Update the XMLNode structure 394 * @ingroup XMLParserGeneral 395 * The functions in this group allows you to create from scratch (or update) a XMLNode structure. Start by creating your top 396 * node with the "createXMLTopNode" function and then add new nodes with the "addChild" function. The parameter 'pos' gives 397 * the position where the childNode, the text or the XMLClearTag will be inserted. The default value (pos=-1) inserts at the 398 * end. The value (pos=0) insert at the beginning (Insertion at the beginning is slower than at the end). <br> 399 * 400 * REMARK: 0 <= pos < nChild()+nText()+nClear() <br> 401 */ 402 403 /** @defgroup creation Creating from scratch a XMLNode structure 404 * @ingroup xmlModify 405 * @{ */ 406 static XMLNode createXMLTopNode(XMLCSTR lpszName, char isDeclaration=FALSE); ///< Create the top node of an XMLNode structure 407 XMLNode addChild(XMLCSTR lpszName, char isDeclaration=FALSE, XMLElementPosition pos=-1); ///< Add a new child node 408 XMLNode addChild(XMLNode nodeToAdd, XMLElementPosition pos=-1); ///< If the "nodeToAdd" has some parents, it will be detached from it's parents before being attached to the current XMLNode 409 XMLAttribute *addAttribute(XMLCSTR lpszName, XMLCSTR lpszValuev); ///< Add a new attribute 410 XMLCSTR addText(XMLCSTR lpszValue, XMLElementPosition pos=-1); ///< Add a new text content 411 XMLClear *addClear(XMLCSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, XMLElementPosition pos=-1); 412 /**< Add a new clear tag 413 * @param lpszOpen default value "<![CDATA[" 414 * @param lpszClose default value "]]>" 415 */ 416 /** @} */ 417 418 /** @defgroup xmlUpdate Updating Nodes 419 * @ingroup xmlModify 420 * Some update functions: 421 * @{ 422 */ 423 XMLCSTR updateName(XMLCSTR lpszName); ///< change node's name 424 XMLAttribute *updateAttribute(XMLAttribute *newAttribute, XMLAttribute *oldAttribute); ///< if the attribute to update is missing, a new one will be added 425 XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName=NULL, int i=0); ///< if the attribute to update is missing, a new one will be added 426 XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName, XMLCSTR lpszOldName);///< 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 427 XMLCSTR updateText(XMLCSTR lpszNewValue, int i=0); ///< if the text to update is missing, a new one will be added 428 XMLCSTR updateText(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue); ///< if the text to update is missing, a new one will be added 429 XMLClear *updateClear(XMLCSTR lpszNewContent, int i=0); ///< if the clearTag to update is missing, a new one will be added 430 XMLClear *updateClear(XMLClear *newP, XMLClear *oldP); ///< if the clearTag to update is missing, a new one will be added 431 XMLClear *updateClear(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue); ///< if the clearTag to update is missing, a new one will be added 432 /** @} */ 433 434 /** @defgroup xmlDelete Deleting Nodes or Attributes 435 * @ingroup xmlModify 436 * Some deletion functions: 437 * @{ 438 */ 439 /// The "deleteNodeContent" function forces the deletion of the content of this XMLNode and the subtree. 440 void deleteNodeContent(); 441 /**< \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. */ 442 void deleteAttribute(int i=0); ///< Delete the ith attribute of the current XMLNode 443 void deleteAttribute(XMLCSTR lpszName); ///< Delete the attribute with the given name (the "strcmp" function is used to find the right attribute) 444 void deleteAttribute(XMLAttribute *anAttribute); ///< Delete the attribute with the name "anAttribute->lpszName" (the "strcmp" function is used to find the right attribute) 445 void deleteText(int i=0); ///< Delete the Ith text content of the current XMLNode 446 void deleteText(XMLCSTR lpszValue); ///< Delete the text content "lpszValue" inside the current XMLNode (direct "pointer-to-pointer" comparison is used to find the right text) 447 void deleteClear(int i=0); ///< Delete the Ith clear tag inside the current XMLNode 448 void deleteClear(XMLCSTR lpszValue); ///< Delete the clear tag "lpszValue" inside the current XMLNode (direct "pointer-to-pointer" comparison is used to find the clear tag) 449 void deleteClear(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) 450 /** @} */ 451 452 /** @defgroup xmlWOSD ???_WOSD functions. 453 * @ingroup xmlModify 454 * The strings given as parameters for the "add" and "update" methods that have a name with 455 * the postfix "_WOSD" (that means "WithOut String Duplication")(for example "addText_WOSD") 456 * will be free'd by the XMLNode class. For example, it means that this is incorrect: 457 * \code 458 * xNode.addText_WOSD("foo"); 459 * xNode.updateAttribute_WOSD("#newcolor" ,NULL,"color"); 460 * \endcode 461 * In opposition, this is correct: 462 * \code 463 * xNode.addText("foo"); 464 * xNode.addText_WOSD(stringDup("foo")); 465 * xNode.updateAttribute("#newcolor" ,NULL,"color"); 466 * xNode.updateAttribute_WOSD(stringDup("#newcolor"),NULL,"color"); 467 * \endcode 468 * Typically, you will never do: 469 * \code 470 * char *b=(char*)malloc(...); 471 * xNode.addText(b); 472 * free(b); 473 * \endcode 474 * ... but rather: 475 * \code 476 * char *b=(char*)malloc(...); 477 * xNode.addText_WOSD(b); 478 * \endcode 479 * ('free(b)' is performed by the XMLNode class) 480 * @{ */ 481 static XMLNode createXMLTopNode_WOSD(XMLSTR lpszName, char isDeclaration=FALSE); ///< Create the top node of an XMLNode structure 482 XMLNode addChild_WOSD(XMLSTR lpszName, char isDeclaration=FALSE, XMLElementPosition pos=-1); ///< Add a new child node 483 XMLAttribute *addAttribute_WOSD(XMLSTR lpszName, XMLSTR lpszValue); ///< Add a new attribute 484 XMLCSTR addText_WOSD(XMLSTR lpszValue, XMLElementPosition pos=-1); ///< Add a new text content 485 XMLClear *addClear_WOSD(XMLSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, XMLElementPosition pos=-1); ///< Add a new clear Tag 486 487 XMLCSTR updateName_WOSD(XMLSTR lpszName); ///< change node's name 488 XMLAttribute *updateAttribute_WOSD(XMLAttribute *newAttribute, XMLAttribute *oldAttribute); ///< if the attribute to update is missing, a new one will be added 489 XMLAttribute *updateAttribute_WOSD(XMLSTR lpszNewValue, XMLSTR lpszNewName=NULL, int i=0); ///< if the attribute to update is missing, a new one will be added 490 XMLAttribute *updateAttribute_WOSD(XMLSTR lpszNewValue, XMLSTR lpszNewName, XMLCSTR lpszOldName); ///< 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 491 XMLCSTR updateText_WOSD(XMLSTR lpszNewValue, int i=0); ///< if the text to update is missing, a new one will be added 492 XMLCSTR updateText_WOSD(XMLSTR lpszNewValue, XMLCSTR lpszOldValue); ///< if the text to update is missing, a new one will be added 493 XMLClear *updateClear_WOSD(XMLSTR lpszNewContent, int i=0); ///< if the clearTag to update is missing, a new one will be added 494 XMLClear *updateClear_WOSD(XMLClear *newP, XMLClear *oldP); ///< if the clearTag to update is missing, a new one will be added 495 XMLClear *updateClear_WOSD(XMLSTR lpszNewValue, XMLCSTR lpszOldValue); ///< if the clearTag to update is missing, a new one will be added 496 /** @} */ 497 498 /** @defgroup xmlPosition Position helper functions (use in conjunction with the update&add functions 499 * @ingroup xmlModify 500 * These are some useful functions when you want to insert a childNode, a text or a XMLClearTag in the 501 * middle (at a specified position) of a XMLNode tree already constructed. The value returned by these 502 * methods is to be used as last parameter (parameter 'pos') of addChild, addText or addClear. 503 * @{ */ 504 XMLElementPosition positionOfText(int i=0) const; 505 XMLElementPosition positionOfText(XMLCSTR lpszValue) const; 506 XMLElementPosition positionOfClear(int i=0) const; 507 XMLElementPosition positionOfClear(XMLCSTR lpszValue) const; 508 XMLElementPosition positionOfClear(XMLClear *a) const; 509 XMLElementPosition positionOfChildNode(int i=0) const; 510 XMLElementPosition positionOfChildNode(XMLNode x) const; 511 XMLElementPosition positionOfChildNode(XMLCSTR name, int i=0) const; ///< return the position of the ith childNode with the specified name if (name==NULL) return the position of the ith childNode 512 /** @} */ 513 514 /// Enumeration for XML character encoding. 515 typedef enum XMLCharEncoding { 516 char_encoding_error = 0, 517 char_encoding_UTF8 = 1, 518 char_encoding_legacy = 2, 519 char_encoding_ShiftJIS = 3, 520 char_encoding_GB2312 = 4, 521 char_encoding_Big5 = 5, 522 char_encoding_GBK = 6 // this is actually the same as Big5 523 } XMLCharEncoding; 524 525 /** \addtogroup conversions 526 * @{ */ 527 528 /// Sets the global options for the conversions 529 static char setGlobalOptions(XMLCharEncoding characterEncoding=XMLNode::char_encoding_UTF8, char guessWideCharChars=1, 530 char dropWhiteSpace=1, char removeCommentsInMiddleOfText=1); 531 /**< The "setGlobalOptions" function allows you to change four global parameters that affect string & file 532 * parsing. First of all, you most-probably will never have to change these 3 global parameters. 533 * 534 * @param guessWideCharChars If "guessWideCharChars"=1 and if this library is compiled in WideChar mode, then the 535 * XMLNode::parseFile and XMLNode::openFileHelper functions will test if the file contains ASCII 536 * characters. If this is the case, then the file will be loaded and converted in memory to 537 * WideChar before being parsed. If 0, no conversion will be performed. 538 * 539 * @param guessWideCharChars If "guessWideCharChars"=1 and if this library is compiled in ASCII/UTF8/char* mode, then the 540 * XMLNode::parseFile and XMLNode::openFileHelper functions will test if the file contains WideChar 541 * characters. If this is the case, then the file will be loaded and converted in memory to 542 * ASCII/UTF8/char* before being parsed. If 0, no conversion will be performed. 543 * 544 * @param characterEncoding This parameter is only meaningful when compiling in char* mode (multibyte character mode). 545 * In wchar_t* (wide char mode), this parameter is ignored. This parameter should be one of the 546 * three currently recognized encodings: XMLNode::encoding_UTF8, XMLNode::encoding_ascii, 547 * XMLNode::encoding_ShiftJIS. 548 * 549 * @param dropWhiteSpace In most situations, text fields containing only white spaces (and carriage returns) 550 * are useless. Even more, these "empty" text fields are annoying because they increase the 551 * complexity of the user's code for parsing. So, 99% of the time, it's better to drop 552 * the "empty" text fields. However The XML specification indicates that no white spaces 553 * should be lost when parsing the file. So to be perfectly XML-compliant, you should set 554 * dropWhiteSpace=0. A note of caution: if you set "dropWhiteSpace=0", the parser will be 555 * slower and your code will be more complex. 556 * 557 * @param removeCommentsInMiddleOfText To explain this parameter, let's consider this code: 558 * \code 559 * XMLNode x=XMLNode::parseString("<a>foo<!-- hello -->bar<!DOCTYPE world >chu</a>","a"); 560 * \endcode 561 * If removeCommentsInMiddleOfText=0, then we will have: 562 * \code 563 * x.getText(0) -> "foo" 564 * x.getText(1) -> "bar" 565 * x.getText(2) -> "chu" 566 * x.getClear(0) --> "<!-- hello -->" 567 * x.getClear(1) --> "<!DOCTYPE world >" 568 * \endcode 569 * If removeCommentsInMiddleOfText=1, then we will have: 570 * \code 571 * x.getText(0) -> "foobar" 572 * x.getText(1) -> "chu" 573 * x.getClear(0) --> "<!DOCTYPE world >" 574 * \endcode 575 * 576 * \return "0" when there are no errors. If you try to set an unrecognized encoding then the return value will be "1" to signal an error. 577 * 578 * \note Sometime, it's useful to set "guessWideCharChars=0" to disable any conversion 579 * because the test to detect the file-type (ASCII/UTF8/char* or WideChar) may fail (rarely). */ 580 581 /// Guess the character encoding of the string (ascii, utf8 or shift-JIS) 582 static XMLCharEncoding guessCharEncoding(void *buffer, int bufLen, char useXMLEncodingAttribute=1); 583 /**< The "guessCharEncoding" function try to guess the character encoding. You most-probably will never 584 * have to use this function. It then returns the appropriate value of the global parameter 585 * "characterEncoding" described in the XMLNode::setGlobalOptions. The guess is based on the content of a buffer of length 586 * "bufLen" bytes that contains the first bytes (minimum 25 bytes; 200 bytes is a good value) of the 587 * file to be parsed. The XMLNode::openFileHelper function is using this function to automatically compute 588 * the value of the "characterEncoding" global parameter. There are several heuristics used to do the 589 * guess. One of the heuristic is based on the "encoding" attribute. The original XML specifications 590 * forbids to use this attribute to do the guess but you can still use it if you set 591 * "useXMLEncodingAttribute" to 1 (this is the default behavior and the behavior of most parsers). 592 * If an inconsistency in the encoding is detected, then the return value is "0". */ 593 /** @} */ 594 595private: 596 // these are functions and structures used internally by the XMLNode class (don't bother about them): 597 598 typedef struct XMLNodeDataTag { // to allow shallow copy and "intelligent/smart" pointers (automatic delete): 599 XMLCSTR lpszName; // Element name (=NULL if root) 600 int nChild, // Number of child nodes 601 nText, // Number of text fields 602 nClear, // Number of Clear fields (comments) 603 nAttribute; // Number of attributes 604 char isDeclaration; // Whether node is an XML declaration - '<?xml ?>' 605 struct XMLNodeDataTag *pParent; // Pointer to parent element (=NULL if root) 606 XMLNode *pChild; // Array of child nodes 607 XMLCSTR *pText; // Array of text fields 608 XMLClear *pClear; // Array of clear fields 609 XMLAttribute *pAttribute; // Array of attributes 610 int *pOrder; // order of the child_nodes,text_fields,clear_fields 611 int ref_count; // for garbage collection (smart pointers) 612 } XMLNodeData; 613 XMLNodeData *d; 614 615 char parseClearTag(void *px, void *pa); 616 char maybeAddTxT(void *pa, XMLCSTR tokenPStr); 617 int ParseXMLElement(void *pXML); 618 void *addToOrder(int memInc, int *_pos, int nc, void *p, int size, XMLElementType xtype); 619 int indexText(XMLCSTR lpszValue) const; 620 int indexClear(XMLCSTR lpszValue) const; 621 XMLNode addChild_priv(int, XMLSTR, char, int); 622 XMLAttribute *addAttribute_priv(int, XMLSTR, XMLSTR); 623 XMLCSTR addText_priv(int, XMLSTR, int); 624 XMLClear *addClear_priv(int, XMLSTR, XMLCSTR, XMLCSTR, int); 625 void emptyTheNode(char force); 626 static inline XMLElementPosition findPosition(XMLNodeData *d, int index, XMLElementType xtype); 627 static int CreateXMLStringR(XMLNodeData *pEntry, XMLSTR lpszMarker, int nFormat); 628 static int removeOrderElement(XMLNodeData *d, XMLElementType t, int index); 629 static void exactMemory(XMLNodeData *d); 630 static int detachFromParent(XMLNodeData *d); 631} XMLNode; 632 633/// This structure is given by the function XMLNode::enumContents. 634typedef struct XMLNodeContents { 635 /// This dictates what's the content of the XMLNodeContent 636 enum XMLElementType etype; 637 /**< should be an union to access the appropriate data. Compiler does not allow union of object with constructor... too bad. */ 638 XMLNode child; 639 XMLAttribute attrib; 640 XMLCSTR text; 641 XMLClear clear; 642 643} XMLNodeContents; 644 645/** @defgroup StringAlloc String Allocation/Free functions 646 * @ingroup xmlModify 647 * @{ */ 648/// Duplicate (copy in a new allocated buffer) the source string. 649XMLDLLENTRY XMLSTR stringDup(XMLCSTR source, int cbData=-1); 650/**< This is 651 * a very handy function when used with all the "XMLNode::*_WOSD" functions (\link xmlWOSD \endlink). 652 * @param cbData If !=0 then cbData is the number of chars to duplicate. New strings allocated with 653 * this function should be free'd using the "freeXMLString" function. */ 654 655/// to free the string allocated inside the "stringDup" function or the "createXMLString" function. 656XMLDLLENTRY void freeXMLString(XMLSTR t); // {free(t);} 657/** @} */ 658 659/** @defgroup atoX ato? like functions 660 * @ingroup XMLParserGeneral 661 * The "xmlto?" functions are equivalents to the atoi, atol, atof functions. 662 * The only difference is: If the variable "xmlString" is NULL, than the return value 663 * is "defautValue". These 6 functions are only here as "convenience" functions for the 664 * user (they are not used inside the XMLparser). If you don't need them, you can 665 * delete them without any trouble. 666 * 667 * @{ */ 668XMLDLLENTRY char xmltob(XMLCSTR xmlString, char defautValue=0); 669XMLDLLENTRY int xmltoi(XMLCSTR xmlString, int defautValue=0); 670XMLDLLENTRY long xmltol(XMLCSTR xmlString, long defautValue=0); 671XMLDLLENTRY double xmltof(XMLCSTR xmlString, double defautValue=.0); 672XMLDLLENTRY XMLCSTR xmltoa(XMLCSTR xmlString, XMLCSTR defautValue=_CXML("")); 673XMLDLLENTRY XMLCHAR xmltoc(XMLCSTR xmlString, XMLCHAR defautValue=_CXML('\0')); 674/** @} */ 675 676/** @defgroup ToXMLStringTool Helper class to create XML files using "printf", "fprintf", "cout",... functions. 677 * @ingroup XMLParserGeneral 678 * @{ */ 679/// Helper class to create XML files using "printf", "fprintf", "cout",... functions. 680/** The ToXMLStringTool class helps you creating XML files using "printf", "fprintf", "cout",... functions. 681 * The "ToXMLStringTool" class is processing strings so that all the characters 682 * &,",',<,> are replaced by their XML equivalent: 683 * \verbatim &, ", ', <, > \endverbatim 684 * Using the "ToXMLStringTool class" and the "fprintf function" is THE most efficient 685 * way to produce VERY large XML documents VERY fast. 686 * \note If you are creating from scratch an XML file using the provided XMLNode class 687 * you must not use the "ToXMLStringTool" class (because the "XMLNode" class does the 688 * processing job for you during rendering).*/ 689typedef struct XMLDLLENTRY ToXMLStringTool { 690public: 691 ToXMLStringTool(): buf(NULL), buflen(0){} 692 ~ToXMLStringTool(); 693 void freeBuffer();///<call this function when you have finished using this object to release memory used by the internal buffer. 694 695 XMLSTR toXML(XMLCSTR source);///< returns a pointer to an internal buffer that contains a XML-encoded string based on the "source" parameter. 696 697 /** The "toXMLUnSafe" function is deprecated because there is a possibility of 698 * "destination-buffer-overflow". It converts the string 699 * "source" to the string "dest". */ 700 static XMLSTR toXMLUnSafe(XMLSTR dest,XMLCSTR source); ///< deprecated: use "toXML" instead 701 static int lengthXMLString(XMLCSTR source); ///< deprecated: use "toXML" instead 702 703private: 704 XMLSTR buf; 705 int buflen; 706} ToXMLStringTool; 707/** @} */ 708 709/** @defgroup XMLParserBase64Tool Helper class to include binary data inside XML strings using "Base64 encoding". 710 * @ingroup XMLParserGeneral 711 * @{ */ 712/// Helper class to include binary data inside XML strings using "Base64 encoding". 713/** The "XMLParserBase64Tool" class allows you to include any binary data (images, sounds,...) 714 * into an XML document using "Base64 encoding". This class is completely 715 * separated from the rest of the xmlParser library and can be removed without any problem. 716 * To include some binary data into an XML file, you must convert the binary data into 717 * standard text (using "encode"). To retrieve the original binary data from the 718 * b64-encoded text included inside the XML file, use "decode". Alternatively, these 719 * functions can also be used to "encrypt/decrypt" some critical data contained inside 720 * the XML (it's not a strong encryption at all, but sometimes it can be useful). */ 721typedef struct XMLDLLENTRY XMLParserBase64Tool { 722public: 723 XMLParserBase64Tool(): buf(NULL), buflen(0){} 724 ~XMLParserBase64Tool(); 725 void freeBuffer();///< Call this function when you have finished using this object to release memory used by the internal buffer. 726 727 /** 728 * @param formatted If "formatted"=true, some space will be reserved for a carriage-return every 72 chars. */ 729 static int encodeLength(int inBufLen, char formatted=0); ///< return the length of the base64 string that encodes a data buffer of size inBufLen bytes. 730 731 /** 732 * The "base64Encode" function returns a string containing the base64 encoding of "inByteLen" bytes 733 * from "inByteBuf". If "formatted" parameter is true, then there will be a carriage-return every 72 chars. 734 * The string will be free'd when the XMLParserBase64Tool object is deleted. 735 * All returned strings are sharing the same memory space. */ 736 XMLSTR encode(unsigned char *inByteBuf, unsigned int inByteLen, char formatted=0); ///< returns a pointer to an internal buffer containing the base64 string containing the binary data encoded from "inByteBuf" 737 738 /// returns the number of bytes which will be decoded from "inString". 739 static unsigned int decodeSize(XMLCSTR inString, XMLError *xe=NULL); 740 741 /** 742 * The "decode" function returns a pointer to a buffer containing the binary data decoded from "inString" 743 * The output buffer will be free'd when the XMLParserBase64Tool object is deleted. 744 * All output buffer are sharing the same memory space. 745 * @param inString If "instring" is malformed, NULL will be returned */ 746 unsigned char* decode(XMLCSTR inString, int *outByteLen=NULL, XMLError *xe=NULL); ///< returns a pointer to an internal buffer containing the binary data decoded from "inString" 747 748 /** 749 * decodes data from "inString" to "outByteBuf". You need to provide the size (in byte) of "outByteBuf" 750 * in "inMaxByteOutBuflen". If "outByteBuf" is not large enough or if data is malformed, then "FALSE" 751 * will be returned; otherwise "TRUE". */ 752 static unsigned char decode(XMLCSTR inString, unsigned char *outByteBuf, int inMaxByteOutBuflen, XMLError *xe=NULL); ///< deprecated. 753 754private: 755 void *buf; 756 int buflen; 757 void alloc(int newsize); 758}XMLParserBase64Tool; 759/** @} */ 760 761#undef XMLDLLENTRY 762 763#endif 764