kernel/src/xmlParser.h

   1 /*
   2  # ---------------------------------------------------------------------
   3  #
   4  # Copyright (c) CREATIS (Centre de Recherche en Acquisition et Traitement de l'Image
   5  #                        pour la SantÈ)
   6  # Authors : Eduardo Davila, Frederic Cervenansky, Claire Mouton
   7  # Previous Authors : Laurent Guigues, Jean-Pierre Roux
   8  # CreaTools website : www.creatis.insa-lyon.fr/site/fr/creatools_accueil
   9  #
  10  #  This software is governed by the CeCILL-B license under French law and
  11  #  abiding by the rules of distribution of free software. You can  use,
  12  #  modify and/ or redistribute the software under the terms of the CeCILL-B
  13  #  license as circulated by CEA, CNRS and INRIA at the following URL
  14  #  http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
  15  #  or in the file LICENSE.txt.
  16  #
  17  #  As a counterpart to the access to the source code and  rights to copy,
  18  #  modify and redistribute granted by the license, users are provided only
  19  #  with a limited warranty  and the software's author,  the holder of the
  20  #  economic rights,  and the successive licensors  have only  limited
  21  #  liability.
  22  #
  23  #  The fact that you are presently reading this means that you have had
  24  #  knowledge of the CeCILL-B license and that you accept its terms.
  25  # ------------------------------------------------------------------------ */
  26
  27
  28 /**
  29  ****************************************************************************
  30  * <P> XML.c - implementation file for basic XML parser written in ANSI C++
  31  * for portability. It works by using recursion and a node tree for breaking
  32  * down the elements of an XML document.  </P>
  33  *
  34  * @version     V2.23
  35  * @author      Frank Vanden Berghen
  36  *
  37  * BSD license:
  38  * Copyright (c) 2002, Frank Vanden Berghen
  39  * All rights reserved.
  40  * Redistribution and use in source and binary forms, with or without
  41  * modification, are permitted provided that the following conditions are met:
  42  *
  43  *     * Redistributions of source code must retain the above copyright
  44  *       notice, this list of conditions and the following disclaimer.
  45  *     * Redistributions in binary form must reproduce the above copyright
  46  *       notice, this list of conditions and the following disclaimer in the
  47  *       documentation and/or other materials provided with the distribution.
  48  *     * Neither the name of the Frank Vanden Berghen nor the
  49  *       names of its contributors may be used to endorse or promote products
  50  *       derived from this software without specific prior written permission.
  51  *
  52  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  53  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  54  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  55  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  56  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  57  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  58  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  59  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  60  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  61  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  62  *
  63  ****************************************************************************
  64  */
  65 #ifndef __INCLUDE_XML_NODE__
  66 #define __INCLUDE_XML_NODE__
  67
  68 #include <stdlib.h>
  69
  70 #ifdef _UNICODE
  71 // If you comment the next "define" line then the library will never "switch to" _UNICODE (wchar_t*) mode (16/32 bits per characters).
  72 // This is useful when you get error messages like:
  73 //    'XMLNode::openFileHelper' : cannot convert parameter 2 from 'const char [5]' to 'const wchar_t *'
  74 // The _XMLUNICODE preprocessor variable force the XMLParser library into either utf16/32-mode (the proprocessor variable
  75 // must be defined) or utf8-mode(the pre-processor variable must be undefined).
  76 #define _XMLUNICODE
  77 #endif /* _UNICODE */
  78
  79 #if defined(WIN32) || defined(UNDER_CE)
  80 // comment the next line if you are under windows and the compiler is not Microsoft Visual Studio (6.0 or .NET)
  81 #define _XMLWINDOWS
  82 // LG
  83 #define _USE_XMLPARSER_DLL
  84 #define _DLL_EXPORTS_
  85 #endif /* _XMLWINDOWS */
  86
  87 #ifdef DLLENTRY
  88 #undef  DLLENTRY
  89 #endif /* DLLENTRY */
  90
  91 //#define _USE_XMLPARSER_DLL
  92
  93 #ifdef _USE_XMLPARSER_DLL
  94  #ifdef _DLL_EXPORTS_
  95         #define DLLENTRY __declspec(dllexport)
  96  #else
  97          #define DLLENTRY __declspec(dllimport)
  98  #endif /* _DLL_EXPORTS_ */
  99 #else
 100   #define DLLENTRY
 101 #endif /* _USE_XMLPARSER_DLL */
 102
 103 // EED  ......OOJJOOO.......
 104 //#define DLLENTRY __declspec(dllexport)
 105
 106
 107 // 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)
 108 //
 109 // --> Very strange compile errors under LINUX when commented out! JPRx
 110 // --> More oddities under Windows when uncommented.
 111 // ==> I try a '#if'
 112 //
 113 #if defined(WIN32)
 114         #ifndef _MSC_VER
 115         #define XML_NO_WIDE_CHAR
 116         #endif
 117 #else
 118         #define XML_NO_WIDE_CHAR
 119 #endif /* WIN32 */
 120
 121 #ifdef XML_NO_WIDE_CHAR
 122 #undef _XMLWINDOWS
 123 #undef _XMLUNICODE
 124 #endif /* XML_NO_WIDE_CHAR */
 125
 126 #ifdef _XMLWINDOWS
 127 #include <tchar.h>
 128 #else
 129
 130
 131         #if defined(WIN32)
 132                 #ifdef _MSC_VER
 133                         #define DLLENTRY
 134                 #endif
 135         #else
 136                 #define DLLENTRY
 137         #endif /* WIN32 */
 138
 139
 140
 141 #ifndef XML_NO_WIDE_CHAR
 142 #include <wchar.h> // to have 'wcsrtombs' for ANSI version
 143                    // to have 'mbsrtowcs' for UNICODE version
 144 #endif /* XML_NO_WIDE_CHAR */
 145 #endif /* _XMLWINDOWS */
 146
 147 // Some common types for char set portable code
 148 #ifdef _XMLUNICODE
 149     #ifndef _T
 150         #define _T(c) L ## c
 151     #endif
 152     #define XMLCSTR const wchar_t *
 153     #define XMLSTR  wchar_t *
 154     #define XMLCHAR wchar_t
 155 #else
 156     #ifndef _T
 157         #define _T(c) c
 158     #endif /* -T */
 159     #define XMLCSTR const char *
 160     #define XMLSTR  char *
 161     #define XMLCHAR char
 162 #endif /* _XMLUNICODE */
 163
 164 #ifndef FALSE
 165     #define FALSE 0
 166 #endif /* FALSE */
 167 #ifndef TRUE
 168     #define TRUE 1
 169 #endif /* TRUE */
 170
 171
 172 // Enumeration for XML parse errors.
 173 typedef enum XMLError
 174 {
 175     eXMLErrorNone = 0,
 176     eXMLErrorMissingEndTag,
 177     eXMLErrorEmpty,
 178     eXMLErrorFirstNotStartTag,
 179     eXMLErrorMissingTagName,
 180     eXMLErrorMissingEndTagName,
 181     eXMLErrorNoMatchingQuote,
 182     eXMLErrorUnmatchedEndTag,
 183     eXMLErrorUnmatchedEndClearTag,
 184     eXMLErrorUnexpectedToken,
 185     eXMLErrorInvalidTag,
 186     eXMLErrorNoElements,
 187     eXMLErrorFileNotFound,
 188     eXMLErrorFirstTagNotFound,
 189     eXMLErrorUnknownCharacterEntity,
 190     eXMLErrorCharConversionError,
 191     eXMLErrorCannotOpenWriteFile,
 192     eXMLErrorCannotWriteFile,
 193
 194     eXMLErrorBase64DataSizeIsNotMultipleOf4,
 195     eXMLErrorBase64DecodeIllegalCharacter,
 196     eXMLErrorBase64DecodeTruncatedData,
 197     eXMLErrorBase64DecodeBufferTooSmall
 198 } XMLError;
 199
 200 // Enumeration used to manage type of data. Use in conjunction with structure XMLNodeContents
 201 typedef enum XMLElementType
 202 {
 203     eNodeChild=0,
 204     eNodeAttribute=1,
 205     eNodeText=2,
 206     eNodeClear=3,
 207     eNodeNULL=4
 208 } XMLElementType;
 209
 210 // Structure used to obtain error details if the parse fails.
 211 typedef struct XMLResults
 212 {
 213     enum XMLError error;
 214     int  nLine,nColumn;
 215 } XMLResults;
 216
 217 // Structure for XML clear (unformatted) node (usually comments)
 218 typedef struct {
 219     XMLCSTR lpszValue; XMLCSTR lpszOpenTag; XMLCSTR lpszCloseTag;
 220 } XMLClear;
 221
 222 // Structure for XML attribute.
 223 typedef struct {
 224     XMLCSTR lpszName; XMLCSTR lpszValue;
 225 } XMLAttribute;
 226
 227 // Structure for XML clear tags.
 228 typedef struct {
 229     XMLCSTR lpszOpen; int openTagLen; XMLCSTR lpszClose;
 230 } ALLXMLClearTag;
 231
 232 struct XMLNodeContents;
 233
 234 typedef struct DLLENTRY XMLNode
 235 {
 236   private:
 237
 238     struct XMLNodeDataTag;
 239
 240     // protected constructors: use one of these four methods to get your first instance of XMLNode:
 241     //  - parseString
 242     //  - parseFile
 243     //  - openFileHelper
 244     //  - createXMLTopNode
 245     XMLNode(struct XMLNodeDataTag *pParent, XMLCSTR lpszName, char isDeclaration);
 246     XMLNode(struct XMLNodeDataTag *p);
 247
 248   public:
 249
 250     // You can create your first instance of XMLNode with these 4 functions:
 251     // (see complete explanation of parameters below)
 252
 253     static XMLNode createXMLTopNode(XMLCSTR lpszName, char isDeclaration=FALSE);
 254     static XMLNode parseString   (XMLCSTR  lpXMLString, XMLCSTR tag=NULL, XMLResults *pResults=NULL);
 255     static XMLNode parseFile     (XMLCSTR     filename, XMLCSTR tag=NULL, XMLResults *pResults=NULL);
 256     static XMLNode openFileHelper(XMLCSTR     filename, XMLCSTR tag=NULL                           );
 257
 258     // The tag parameter should be the name of the first tag inside the XML file.
 259     // If the tag parameter is omitted, the 3 functions return a node that represents
 260     // the head of the xml document including the declaration term (<? ... ?>).
 261
 262     // The "openFileHelper" reports to the screen all the warnings & errors that occurred during
 263     // parsing of the XML file. Since each application has its own way to report and deal with errors,
 264     // you should rather use the "parseFile" function to parse XML files and program yourself thereafter
 265     // an "error reporting" tailored for your needs (instead of using the very crude "error reporting"
 266     // mechanism included inside the "openFileHelper" function).
 267
 268     // If the XML document is corrupted:
 269     //   * The "openFileHelper" method will:
 270     //         - display an error message on the console (or inside a messageBox for windows).
 271     //         - stop execution (exit).
 272     //     I suggest that you write your own "openFileHelper" method tailored to your needs.
 273     //   * The 2 other methods will initialize the "pResults" variable with some information that
 274     //     can be used to trace the error.
 275     //   * If you still want to parse the file, you can use the APPROXIMATE_PARSING option as
 276     //     explained inside the note at the beginning of the "xmlParser.cpp" file.
 277     // You can have a user-friendly explanation of the parsing error with this function:
 278     static XMLCSTR getError(XMLError error);
 279     static XMLCSTR getVersion();
 280     static ALLXMLClearTag* getClearTagTable();
 281
 282     XMLCSTR getName() const;                                         // name of the node
 283     XMLCSTR getText(int i=0) const;                                  // return ith text field
 284     int nText() const;                                               // nbr of text field
 285     XMLNode getParentNode() const;                                   // return the parent node
 286     XMLNode getChildNode(int i=0) const;                             // return ith child node
 287     XMLNode getChildNode(XMLCSTR name, int i)  const;                // return ith child node with specific name
 288                                                                      //     (return an empty node if failing)
 289     XMLNode getChildNode(XMLCSTR name, int *i=NULL) const;           // return next child node with specific name
 290                                                                      //     (return an empty node if failing)
 291     XMLNode getChildNodeWithAttribute(XMLCSTR tagName,               // return child node with specific name/attribute
 292                                       XMLCSTR attributeName,         //     (return an empty node if failing)
 293                                       XMLCSTR attributeValue=NULL,   //
 294                                       int *i=NULL)  const;           //
 295     int nChildNode(XMLCSTR name) const;                              // return the number of child node with specific name
 296     int nChildNode() const;                                          // nbr of child node
 297     XMLAttribute getAttribute(int i=0) const;                        // return ith attribute
 298     XMLCSTR      getAttributeName(int i=0) const;                    // return ith attribute name
 299     XMLCSTR      getAttributeValue(int i=0) const;                   // return ith attribute value
 300     char  isAttributeSet(XMLCSTR name) const;                        // test if an attribute with a specific name is given
 301     XMLCSTR getAttribute(XMLCSTR name, int i) const;                 // return ith attribute content with specific name
 302                                                                      //     (return a NULL if failing)
 303     XMLCSTR getAttribute(XMLCSTR name, int *i=NULL) const;           // return next attribute content with specific name
 304                                                                      //     (return a NULL if failing)
 305     int nAttribute() const;                                          // nbr of attribute
 306     XMLClear getClear(int i=0) const;                                // return ith clear field (comments)
 307     int nClear() const;                                              // nbr of clear field
 308     XMLSTR createXMLString(int nFormat=1, int *pnSize=NULL) const;   // create XML string starting from current XMLNode
 309                                                                      // if nFormat==0, no formatting is required
 310                                                                      // otherwise this returns an user friendly XML string from a
 311                                                                      // given element with appropriate white spaces and carriage returns.
 312                                                                      // if pnSize is given it returns the size in character of the string.
 313     XMLError writeToFile(XMLCSTR filename, const char *encoding=NULL, char nFormat=1) const;
 314                                                                      // save the content of an xmlNode inside a file.
 315                                                                      // the nFormat parameter has the same meaning as in the
 316                                                                      // createXMLString function. If "strictUTF8Parsing=1", the
 317                                                                      // the encoding parameter is ignored and always set to
 318                                                                      // "utf-8". If "_XMLUNICODE=1", the encoding parameter is
 319                                                                      // ignored and always set to "utf-16".
 320     XMLNodeContents enumContents(int i) const;                       // enumerate all the different contents (attribute,child,text,
 321                                                                      //     clear) of the current XMLNode. The order is reflecting
 322                                                                      //     the order of the original file/string.
 323                                                                      //     NOTE: 0 <= i < nElement();
 324     int nElement() const;                                            // nbr of different contents for current node
 325     char isEmpty() const;                                            // is this node Empty?
 326     char isDeclaration() const;                                      // is this node a declaration <? .... ?>
 327
 328 // to allow shallow/fast copy:
 329     ~XMLNode();
 330     XMLNode(const XMLNode &A);
 331     XMLNode& operator=( const XMLNode& A );
 332
 333     XMLNode(): d(NULL){};
 334     static XMLNode emptyXMLNode;
 335     static XMLClear emptyXMLClear;
 336     static XMLAttribute emptyXMLAttribute;
 337
 338     // The following functions allows you to create from scratch (or update) a XMLNode structure
 339     // Start by creating your top node with the "createXMLTopNode" function and then add new nodes with the "addChild" function.
 340     // The parameter 'pos' gives the position where the childNode, the text or the XMLClearTag will be inserted.
 341     // The default value (pos=-1) inserts at the end. The value (pos=0) insert at the beginning (Insertion at the beginning is slower than at the end).
 342     // REMARK: 0 <= pos < nChild()+nText()+nClear()
 343     XMLNode       addChild(XMLCSTR lpszName, char isDeclaration=FALSE, int pos=-1);
 344     XMLAttribute *addAttribute(XMLCSTR lpszName, XMLCSTR lpszValuev);
 345     XMLCSTR       addText(XMLCSTR lpszValue, int pos=-1);
 346     XMLClear     *addClear(XMLCSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, int pos=-1);
 347                                                                     // default values: lpszOpen=XMLNode::getClearTagTable()->lpszOpen;
 348                                                                     //                 lpszClose=XMLNode::getClearTagTable()->lpszClose;
 349     XMLNode       addChild(XMLNode nodeToAdd, int pos=-1);          // If the "nodeToAdd" has some parents, it will be detached
 350                                                                     // from it's parents before being attached to the current XMLNode
 351     // Some update functions:
 352     XMLCSTR       updateName(XMLCSTR lpszName);                                                    // change node's name
 353     XMLAttribute *updateAttribute(XMLAttribute *newAttribute, XMLAttribute *oldAttribute);         // if the attribute to update is missing, a new one will be added
 354     XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName=NULL,int i=0);         // if the attribute to update is missing, a new one will be added
 355     XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName,XMLCSTR lpszOldName);  // set lpszNewName=NULL if you don't want to change the name of the attribute
 356                                                                                                    // if the attribute to update is missing, a new one will be added
 357     XMLCSTR       updateText(XMLCSTR lpszNewValue, int i=0);                                       // if the text to update is missing, a new one will be added
 358     XMLCSTR       updateText(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);                          // if the text to update is missing, a new one will be added
 359     XMLClear     *updateClear(XMLCSTR lpszNewContent, int i=0);                                    // if the clearTag to update is missing, a new one will be added
 360     XMLClear     *updateClear(XMLClear *newP,XMLClear *oldP);                                      // if the clearTag to update is missing, a new one will be added
 361     XMLClear     *updateClear(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);                         // if the clearTag to update is missing, a new one will be added
 362
 363     // Some deletion functions:
 364     void deleteNodeContent(char force=0);  // delete the content of this XMLNode and the subtree.
 365                                            // if force=0, while (references to this node still exist), no memory free occurs
 366                                            // if force=1, always delete the content of this XMLNode and the subtree and free associated memory
 367     void deleteAttribute(XMLCSTR lpszName);
 368     void deleteAttribute(int i=0);
 369     void deleteAttribute(XMLAttribute *anAttribute);
 370     void deleteText(int i=0);
 371     void deleteText(XMLCSTR lpszValue);
 372     void deleteClear(int i=0);
 373     void deleteClear(XMLClear *p);
 374     void deleteClear(XMLCSTR lpszValue);
 375
 376     // The strings given as parameters for the following add and update methods (all these methods have
 377     // a name with the postfix "_WOSD" that means "WithOut String Duplication" ) will be free'd by the
 378     // XMLNode class. For example, it means that this is incorrect:
 379     //    xNode.addText_WOSD("foo");
 380     //    xNode.updateAttribute_WOSD("#newcolor" ,NULL,"color");
 381     // In opposition, this is correct:
 382     //    xNode.addText("foo");
 383     //    xNode.addText_WOSD(stringDup("foo"));
 384     //    xNode.updateAttribute("#newcolor" ,NULL,"color");
 385     //    xNode.updateAttribute_WOSD(stringDup("#newcolor"),NULL,"color");
 386     // Typically, you will never do:
 387     //    char *b=(char*)malloc(...);
 388     //    xNode.addText(b);
 389     //    free(b);
 390     // ... but rather:
 391     //    char *b=(char*)malloc(...);
 392     //    xNode.addText_WOSD(b);
 393     //    ('free(b)' is performed by the XMLNode class)
 394
 395     static XMLNode createXMLTopNode_WOSD(XMLCSTR lpszName, char isDeclaration=FALSE);
 396     XMLNode        addChild_WOSD(XMLCSTR lpszName, char isDeclaration=FALSE, int pos=-1);
 397     XMLAttribute  *addAttribute_WOSD(XMLCSTR lpszName, XMLCSTR lpszValue);
 398     XMLCSTR        addText_WOSD(XMLCSTR lpszValue, int pos=-1);
 399     XMLClear      *addClear_WOSD(XMLCSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, int pos=-1);
 400
 401     XMLCSTR        updateName_WOSD(XMLCSTR lpszName);
 402     XMLAttribute  *updateAttribute_WOSD(XMLAttribute *newAttribute, XMLAttribute *oldAttribute);
 403     XMLAttribute  *updateAttribute_WOSD(XMLCSTR lpszNewValue, XMLCSTR lpszNewName=NULL,int i=0);
 404     XMLAttribute  *updateAttribute_WOSD(XMLCSTR lpszNewValue, XMLCSTR lpszNewName,XMLCSTR lpszOldName);
 405     XMLCSTR        updateText_WOSD(XMLCSTR lpszNewValue, int i=0);
 406     XMLCSTR        updateText_WOSD(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);
 407     XMLClear      *updateClear_WOSD(XMLCSTR lpszNewContent, int i=0);
 408     XMLClear      *updateClear_WOSD(XMLClear *newP,XMLClear *oldP);
 409     XMLClear      *updateClear_WOSD(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);
 410
 411     // These are some useful functions when you want to insert a childNode, a text or a XMLClearTag in the
 412     // middle (at a specified position) of a XMLNode tree already constructed. The value returned by these
 413     // methods is to be used as last parameter (parameter 'pos') of addChild, addText or addClear.
 414     int positionOfText(int i=0) const;
 415     int positionOfText(XMLCSTR lpszValue) const;
 416     int positionOfClear(int i=0) const;
 417     int positionOfClear(XMLCSTR lpszValue) const;
 418     int positionOfClear(XMLClear *a) const;
 419     int positionOfChildNode(int i=0) const;
 420     int positionOfChildNode(XMLNode x) const;
 421     int positionOfChildNode(XMLCSTR name, int i=0) const; // return the position of the ith childNode with the specified name
 422                                                           // if (name==NULL) return the position of the ith childNode
 423
 424     // The setGlobalOptions function allows you to change two global parameters that affect string&file
 425     // parsing. First of all, you most-probably will never have to change these 2 global parameters.
 426     // About the "guessUnicodeChars" parameter:
 427     //     If "guessUnicodeChars=1" and if this library is compiled in UNICODE mode, then the
 428     //     "parseFile" and "openFileHelper" functions will test if the file contains ASCII
 429     //     characters. If this is the case, then the file will be loaded and converted in memory to
 430     //     UNICODE before being parsed. If "guessUnicodeChars=0", no conversion will
 431     //     be performed.
 432     //
 433     //     If "guessUnicodeChars=1" and if this library is compiled in ASCII/UTF8 mode, then the
 434     //     "parseFile" and "openFileHelper" functions will test if the file contains UNICODE
 435     //     characters. If this is the case, then the file will be loaded and converted in memory to
 436     //     ASCII/UTF8 before being parsed. If "guessUnicodeChars=0", no conversion will
 437     //     be performed
 438     //
 439     //     Sometime, it's useful to set "guessUnicodeChars=0" to disable any conversion
 440     //     because the test to detect the file-type (ASCII/UTF8 or UNICODE) may fail (rarely).
 441     //
 442     // About the "strictUTF8Parsing" parameter:
 443     //     If "strictUTF8Parsing=0" then we assume that all characters have the same length of 1 byte.
 444     //     If "strictUTF8Parsing=1" then the characters have different lengths (from 1 byte to 4 bytes)
 445     //     depending on the content of the first byte of the character.
 446     // About the "dropWhiteSpace" parameter:
 447     //
 448
 449     static void setGlobalOptions(char guessUnicodeChars=1, char strictUTF8Parsing=1, char dropWhiteSpace=1);
 450
 451     // The next function try to guess if the character encoding is UTF-8. You most-probably will never
 452     // have to use this function. It then returns the appropriate value of the global parameter
 453     // "strictUTF8Parsing" described above. The guess is based on the content of a buffer of length
 454     // "bufLen" bytes that contains the first bytes (minimum 25 bytes; 200 bytes is a good value) of the
 455     // file to be parsed. The "openFileHelper" function is using this function to automatically compute
 456     // the value of the "strictUTF8Parsing" global parameter. There are several heuristics used to do the
 457     // guess. One of the heuristic is based on the "encoding" attribute. The original XML specifications
 458     // forbids to use this attribute to do the guess but you can still use it if you set
 459     // "useXMLEncodingAttribute" to 1 (this is the default behavior and the behavior of most parsers).
 460
 461     static char guessUTF8ParsingParameterValue(void *buffer, int bufLen, char useXMLEncodingAttribute=1);
 462
 463   private:
 464
 465 // these are functions and structures used internally by the XMLNode class (don't bother about them):
 466
 467       typedef struct XMLNodeDataTag // to allow shallow copy and "intelligent/smart" pointers (automatic delete):
 468       {
 469           XMLCSTR                lpszName;        // Element name (=NULL if root)
 470           int                    nChild,          // Number of child nodes
 471                                  nText,           // Number of text fields
 472                                  nClear,          // Number of Clear fields (comments)
 473                                  nAttribute;      // Number of attributes
 474           char                   isDeclaration;   // Whether node is an XML declaration - '<?xml ?>'
 475           struct XMLNodeDataTag  *pParent;        // Pointer to parent element (=NULL if root)
 476           XMLNode                *pChild;         // Array of child nodes
 477           XMLCSTR                *pText;          // Array of text fields
 478           XMLClear               *pClear;         // Array of clear fields
 479           XMLAttribute           *pAttribute;     // Array of attributes
 480           int                    *pOrder;         // order of the child_nodes,text_fields,clear_fields
 481           int                    ref_count;       // for garbage collection (smart pointers)
 482       } XMLNodeData;
 483       XMLNodeData *d;
 484
 485       char parseClearTag(void *px, ALLXMLClearTag *pa);
 486       char maybeAddTxT(void *pa, XMLCSTR tokenPStr);
 487       int ParseXMLElement(void *pXML);
 488       void *addToOrder(int memInc, int *_pos, int nc, void *p, int size, XMLElementType xtype);
 489       int indexText(XMLCSTR lpszValue) const;
 490       int indexClear(XMLCSTR lpszValue) const;
 491       XMLNode addChild_priv(int,XMLCSTR,char,int);
 492       XMLAttribute *addAttribute_priv(int,XMLCSTR,XMLCSTR);
 493       XMLCSTR addText_priv(int,XMLCSTR,int);
 494       XMLClear *addClear_priv(int,XMLCSTR,XMLCSTR,XMLCSTR,int);
 495       static inline int findPosition(XMLNodeData *d, int index, XMLElementType xtype);
 496       static int CreateXMLStringR(XMLNodeData *pEntry, XMLSTR lpszMarker, int nFormat);
 497       static int removeOrderElement(XMLNodeData *d, XMLElementType t, int index);
 498       static void exactMemory(XMLNodeData *d);
 499       static int detachFromParent(XMLNodeData *d);
 500 } XMLNode;
 501
 502 // This structure is given by the function "enumContents".
 503 typedef struct XMLNodeContents
 504 {
 505     // This dictates what's the content of the XMLNodeContent
 506     enum XMLElementType type;
 507     // should be an union to access the appropriate data.
 508     // compiler does not allow union of object with constructor... too bad.
 509     XMLNode child;
 510     XMLAttribute attrib;
 511     XMLCSTR text;
 512     XMLClear clear;
 513
 514 } XMLNodeContents;
 515
 516 DLLENTRY void free_XMLDLL(void *t); // {free(t);}
 517
 518 // Duplicate (copy in a new allocated buffer) the source string. This is
 519 // a very handy function when used with all the "XMLNode::*_WOSD" functions.
 520 // (If (cbData!=0) then cbData is the number of chars to duplicate)
 521 DLLENTRY XMLSTR stringDup(XMLCSTR source, int cbData=0);
 522
 523 // The 3 following functions are processing strings so that all the characters
 524 // &,",',<,> are replaced by their XML equivalent: &amp;, &quot;, &apos;, &lt;, &gt;.
 525 // These 3 functions are useful when creating from scratch an XML file using the
 526 // "printf", "fprintf", "cout",... functions. If you are creating from scratch an
 527 // XML file using the provided XMLNode class you cannot use these functions (the
 528 // XMLNode class does the processing job for you during rendering). The second
 529 // function ("toXMLStringFast") allows you to re-use the same output buffer
 530 // for all the conversions so that only a few memory allocations are performed.
 531 // If the output buffer is too small to contain thee resulting string, it will
 532 // be enlarged.
 533 DLLENTRY XMLSTR toXMLString(XMLCSTR source);
 534 DLLENTRY XMLSTR toXMLStringFast(XMLSTR *destBuffer,int *destSz, XMLCSTR source);
 535
 536 // you should not use this one (there is a possibility of "destination-buffer-overflow"):
 537 DLLENTRY XMLSTR toXMLString(XMLSTR dest,XMLCSTR source);
 538
 539 // Below is a class that allows you to include any binary data (images, sounds,...)
 540 // into an XML document using "Base64 encoding". This class is completely
 541 // separated from the rest of the xmlParser library and can be removed without any problem.
 542 // To include some binary data into an XML file, you must convert the binary data into
 543 // standard text (using "encode"). To retrieve the original binary data from the
 544 // b64-encoded text included inside the XML file use "decode". Alternatively, these
 545 // functions can also be used to "encrypt/decrypt" some critical data contained inside
 546 // the XML.
 547
 548 class DLLENTRY XMLParserBase64Tool
 549 {
 550 public:
 551     XMLParserBase64Tool(): buf(NULL),buflen(0){}
 552     ~XMLParserBase64Tool();
 553
 554     void freeBuffer();
 555
 556     // returns the length of the base64 string that encodes a data buffer of size inBufLen bytes.
 557     // If "formatted" parameter is true, some space will be reserved for a carriage-return every 72 chars.
 558     static int encodeLength(int inBufLen, char formatted=0);
 559
 560     // The "base64Encode" function returns a string containing the base64 encoding of "inByteLen" bytes
 561     // from "inByteBuf". If "formatted" parameter is true, then there will be a carriage-return every 72 chars.
 562     // The string will be free'd when the XMLParserBase64Tool object is deleted.
 563     // All returned strings are sharing the same memory space.
 564     XMLSTR encode(unsigned char *inByteBuf, unsigned int inByteLen, char formatted=0);
 565
 566     // returns the number of bytes which will be decoded from "inString".
 567     static unsigned int decodeSize(XMLCSTR inString, XMLError *xe=NULL);
 568
 569     // returns a pointer to a buffer containing the binary data decoded from "inString"
 570     // If "inString" is malformed NULL will be returned
 571     // The output buffer will be free'd when the XMLParserBase64Tool object is deleted.
 572     // All output buffer are sharing the same memory space.
 573     unsigned char* decode(XMLCSTR inString, int *outByteLen=NULL, XMLError *xe=NULL);
 574
 575     // The next function is deprecated.
 576     // decodes data from "inString" to "outByteBuf". You need to provide the size (in byte) of "outByteBuf"
 577     // in "inMaxByteOutBuflen". If "outByteBuf" is not large enough or if data is malformed, then "FALSE"
 578     // will be returned; otherwise "TRUE".
 579     static unsigned char decode(XMLCSTR inString, unsigned char *outByteBuf, int inMaxByteOutBuflen, XMLError *xe=NULL);
 580
 581 private:
 582     void *buf;
 583     int buflen;
 584     void alloc(int newsize);
 585 };
 586
 587 #undef  DLLENTRY
 588
 589 #endif