9
3

xmlParser.h 42 KB

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