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