libmsn 4.2
/home/salem/libmsn/tags/libmsn-4.2/msn/xmlParser.h
00001 
00038 #ifndef __INCLUDE_XML_NODE__
00039 #define __INCLUDE_XML_NODE__
00040 
00041 #include <stdlib.h>
00042 
00043 #ifdef _UNICODE
00044     // If you comment the next "define" line then the library will never "switch to" _UNICODE (wchar_t*) mode (16/32 bits per characters).
00045     // This is useful when you get error messages like:
00046     //    'XMLNode::openFileHelper' : cannot convert parameter 2 from 'const char [5]' to 'const wchar_t *'
00047     // The _XMLWIDECHAR preprocessor variable force the XMLParser library into either utf16/32-mode (the proprocessor variable
00048     // must be defined) or utf8-mode(the pre-processor variable must be undefined).
00049 #define _XMLWIDECHAR
00050 #endif
00051 
00052 #if defined(WIN32) || defined(UNDER_CE)
00053     // comment the next line if you are under windows and the compiler is not Microsoft Visual Studio (6.0 or .NET)
00054 #define _XMLWINDOWS
00055 #endif
00056 
00057 #ifdef XMLDLLENTRY
00058 #undef XMLDLLENTRY
00059 #endif
00060 #ifdef _USE_XMLPARSER_DLL
00061 #ifdef _DLL_EXPORTS_
00062 #define XMLDLLENTRY __declspec(dllexport)
00063 #else
00064 #define XMLDLLENTRY __declspec(dllimport)
00065 #endif
00066 #else
00067 #define XMLDLLENTRY
00068 #endif
00069 
00070     // 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)
00071     //#define XML_NO_WIDE_CHAR
00072 
00073 #ifdef XML_NO_WIDE_CHAR
00074 #undef _XMLWINDOWS
00075 #undef _XMLWIDECHAR
00076 #endif
00077 
00078 #ifdef _XMLWINDOWS
00079 #include <tchar.h>
00080 #else
00081 #define XMLDLLENTRY
00082 #ifndef XML_NO_WIDE_CHAR
00083 #include <wchar.h> // to have 'wcsrtombs' for ANSI version
00084                        // to have 'mbsrtowcs' for WIDECHAR version
00085 #endif
00086 #endif
00087 
00088     // Some common types for char set portable code
00089 #ifdef _XMLWIDECHAR
00090         #ifndef _T
00091             #define _T(c) L ## c
00092         #endif
00093         #define XMLCSTR const wchar_t *
00094         #define XMLSTR  wchar_t *
00095         #define XMLCHAR wchar_t
00096 #else
00097         #ifndef _T
00098             #define _T(c) c
00099         #endif
00100         #define XMLCSTR const char *
00101         #define XMLSTR  char *
00102         #define XMLCHAR char
00103 #endif
00104 #ifndef FALSE
00105         #define FALSE 0
00106 #endif /* FALSE */
00107 #ifndef TRUE
00108         #define TRUE 1
00109 #endif /* TRUE */
00110 
00111 
00112     // Enumeration for XML parse errors.
00113     typedef enum XMLError
00114     {
00115         eXMLErrorNone = 0,
00116         eXMLErrorMissingEndTag,
00117         eXMLErrorEmpty,
00118         eXMLErrorFirstNotStartTag,
00119         eXMLErrorMissingTagName,
00120         eXMLErrorMissingEndTagName,
00121         eXMLErrorNoMatchingQuote,
00122         eXMLErrorUnmatchedEndTag,
00123         eXMLErrorUnmatchedEndClearTag,
00124         eXMLErrorUnexpectedToken,
00125         eXMLErrorInvalidTag,
00126         eXMLErrorNoElements,
00127         eXMLErrorFileNotFound,
00128         eXMLErrorFirstTagNotFound,
00129         eXMLErrorUnknownCharacterEntity,
00130         eXMLErrorCharConversionError,
00131         eXMLErrorCannotOpenWriteFile,
00132         eXMLErrorCannotWriteFile,
00133 
00134         eXMLErrorBase64DataSizeIsNotMultipleOf4,
00135         eXMLErrorBase64DecodeIllegalCharacter,
00136         eXMLErrorBase64DecodeTruncatedData,
00137         eXMLErrorBase64DecodeBufferTooSmall
00138     } XMLError;
00139 
00140 
00141     // Enumeration used to manage type of data. Use in conjunction with structure XMLNodeContents
00142     typedef enum XMLElementType
00143     {
00144         eNodeChild=0,
00145         eNodeAttribute=1,
00146         eNodeText=2,
00147         eNodeClear=3,
00148         eNodeNULL=4
00149     } XMLElementType;
00150 
00151     // Structure used to obtain error details if the parse fails.
00152     typedef struct XMLResults
00153     {
00154         enum XMLError error;
00155         int  nLine,nColumn;
00156     } XMLResults;
00157 
00158     // Structure for XML clear (unformatted) node (usually comments)
00159     typedef struct XMLClear {
00160         XMLCSTR lpszValue; XMLCSTR lpszOpenTag; XMLCSTR lpszCloseTag;
00161     } XMLClear;
00162 
00163     // Structure for XML attribute.
00164     typedef struct XMLAttribute {
00165         XMLCSTR lpszName; XMLCSTR lpszValue;
00166     } XMLAttribute;
00167 
00168     struct XMLNodeContents;
00169 
00170     typedef struct XMLDLLENTRY XMLNode
00171     {
00172       private:
00173 
00174         struct XMLNodeDataTag;
00175 
00176         // protected constructors: use one of these four methods to get your first instance of XMLNode:
00177         //  - parseString
00178         //  - parseFile
00179         //  - openFileHelper
00180         //  - createXMLTopNode
00181         XMLNode(struct XMLNodeDataTag *pParent, XMLSTR lpszName, char isDeclaration);
00182         XMLNode(struct XMLNodeDataTag *p);
00183 
00184       public:
00185 
00186         // You can create your first instance of XMLNode with these 4 functions:
00187         // (see complete explanation of parameters below)
00188 
00189         static XMLNode createXMLTopNode(XMLCSTR lpszName, char isDeclaration=FALSE);
00190         static XMLNode parseString   (XMLCSTR  lpXMLString, XMLCSTR tag=NULL, XMLResults *pResults=NULL);
00191         static XMLNode parseFile     (XMLCSTR     filename, XMLCSTR tag=NULL, XMLResults *pResults=NULL);
00192         static XMLNode openFileHelper(XMLCSTR     filename, XMLCSTR tag=NULL                           );
00193 
00194         // The tag parameter should be the name of the first tag inside the XML file.
00195         // If the tag parameter is omitted, the 3 functions return a node that represents
00196         // the head of the xml document including the declaration term (<? ... ?>).
00197 
00198         // The "openFileHelper" reports to the screen all the warnings & errors that occurred during
00199         // parsing of the XML file. Since each application has its own way to report and deal with errors,
00200         // you should rather use the "parseFile" function to parse XML files and program yourself thereafter
00201         // an "error reporting" tailored for your needs (instead of using the very crude "error reporting"
00202         // mechanism included inside the "openFileHelper" function).
00203 
00204         // If the XML document is corrupted:
00205         //   * The "openFileHelper" method will:
00206         //         - display an error message on the console (or inside a messageBox for windows).
00207         //         - stop execution (exit).
00208         //     I suggest that you write your own "openFileHelper" method tailored to your needs.
00209     //   * The 2 other methods will initialize the "pResults" variable with some information that
00210     //     can be used to trace the error.
00211     //   * If you still want to parse the file, you can use the APPROXIMATE_PARSING option as
00212     //     explained inside the note at the beginning of the "xmlParser.cpp" file.
00213     // You can have a user-friendly explanation of the parsing error with this function:
00214     static XMLCSTR getError(XMLError error);
00215     static XMLCSTR getVersion();
00216 
00217     XMLCSTR getName() const;                                         // name of the node
00218     XMLCSTR getText(int i=0) const;                                  // return ith text field
00219     int nText() const;                                               // nbr of text field
00220     XMLNode getParentNode() const;                                   // return the parent node
00221     XMLNode getChildNode(int i=0) const;                             // return ith child node
00222     XMLNode getChildNode(XMLCSTR name, int i)  const;                // return ith child node with specific name
00223                                                                      //     (return an empty node if failing)
00224     XMLNode getChildNode(XMLCSTR name, int *i=NULL) const;           // return next child node with specific name
00225                                                                      //     (return an empty node if failing)
00226     XMLNode getChildNodeWithAttribute(XMLCSTR tagName,               // return child node with specific name/attribute
00227                                       XMLCSTR attributeName,         //     (return an empty node if failing)
00228                                       XMLCSTR attributeValue=NULL,   //
00229                                       int *i=NULL)  const;           //
00230     int nChildNode(XMLCSTR name) const;                              // return the number of child node with specific name
00231     int nChildNode() const;                                          // nbr of child node
00232     XMLAttribute getAttribute(int i=0) const;                        // return ith attribute
00233     XMLCSTR      getAttributeName(int i=0) const;                    // return ith attribute name
00234     XMLCSTR      getAttributeValue(int i=0) const;                   // return ith attribute value
00235     char  isAttributeSet(XMLCSTR name) const;                        // test if an attribute with a specific name is given
00236     XMLCSTR getAttribute(XMLCSTR name, int i) const;                 // return ith attribute content with specific name
00237                                                                      //     (return a NULL if failing)
00238     XMLCSTR getAttribute(XMLCSTR name, int *i=NULL) const;           // return next attribute content with specific name
00239                                                                      //     (return a NULL if failing)
00240     int nAttribute() const;                                          // nbr of attribute
00241     XMLClear getClear(int i=0) const;                                // return ith clear field (comments)
00242     int nClear() const;                                              // nbr of clear field
00243     XMLSTR createXMLString(int nFormat=1, int *pnSize=NULL) const;   // create XML string starting from current XMLNode
00244                                                                      // if nFormat==0, no formatting is required
00245                                                                      // otherwise this returns an user friendly XML string from a
00246                                                                      // given element with appropriate white spaces and carriage returns.
00247                                                                      // if pnSize is given it returns the size in character of the string.
00248     XMLError writeToFile(XMLCSTR filename, const char *encoding=NULL, char nFormat=1) const;
00249                                                                      // Save the content of an xmlNode inside a file.
00250                                                                      // The nFormat parameter has the same meaning as in the
00251                                                                      // createXMLString function. If the global parameter
00252                                                                      // "characterEncoding==encoding_UTF8", then the "encoding" parameter is
00253                                                                      // ignored and always set to "utf-8". If the global parameter
00254                                                                      // "characterEncoding==encoding_ShiftJIS", then the "encoding" parameter
00255                                                                      // is ignored and always set to "SHIFT-JIS". If "_XMLWIDECHAR=1", then
00256                                                                      // the "encoding" parameter is ignored and always set to "utf-16".
00257                                                                      // If no "encoding" parameter is given the "ISO-8859-1" encoding is used.
00258     XMLNodeContents enumContents(int i) const;                       // enumerate all the different contents (attribute,child,text,
00259                                                                      //     clear) of the current XMLNode. The order is reflecting
00260                                                                      //     the order of the original file/string.
00261                                                                      //     NOTE: 0 <= i < nElement();
00262     int nElement() const;                                            // nbr of different contents for current node
00263     char isEmpty() const;                                            // is this node Empty?
00264     char isDeclaration() const;                                      // is this node a declaration <? .... ?>
00265     static XMLNode emptyNode();                                      // return XMLNode::emptyXMLNode;
00266 
00267 // to allow shallow/fast copy:
00268     ~XMLNode();
00269     XMLNode(const XMLNode &A);
00270     XMLNode& operator=( const XMLNode& A );
00271 
00272     XMLNode(): d(NULL){};
00273     static XMLNode emptyXMLNode;
00274     static XMLClear emptyXMLClear;
00275     static XMLAttribute emptyXMLAttribute;
00276 
00277     // The following functions allows you to create from scratch (or update) a XMLNode structure
00278     // Start by creating your top node with the "createXMLTopNode" function and then add new nodes with the "addChild" function.
00279     // The parameter 'pos' gives the position where the childNode, the text or the XMLClearTag will be inserted.
00280     // 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).
00281     // REMARK: 0 <= pos < nChild()+nText()+nClear()
00282     XMLNode       addChild(XMLCSTR lpszName, char isDeclaration=FALSE, int pos=-1);
00283     XMLAttribute *addAttribute(XMLCSTR lpszName, XMLCSTR lpszValuev);
00284     XMLCSTR       addText(XMLCSTR lpszValue, int pos=-1);
00285     XMLClear     *addClear(XMLCSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, int pos=-1);
00286                                                                     // default values: lpszOpen ="<![CDATA["
00287                                                                     //                 lpszClose="]]>"
00288     XMLNode       addChild(XMLNode nodeToAdd, int pos=-1);          // If the "nodeToAdd" has some parents, it will be detached
00289                                                                     // from it's parents before being attached to the current XMLNode
00290     // Some update functions:
00291     XMLCSTR       updateName(XMLCSTR lpszName);                                                    // change node's name
00292     XMLAttribute *updateAttribute(XMLAttribute *newAttribute, XMLAttribute *oldAttribute);         // if the attribute to update is missing, a new one will be added
00293     XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName=NULL,int i=0);         // if the attribute to update is missing, a new one will be added
00294     XMLAttribute *updateAttribute(XMLCSTR lpszNewValue, XMLCSTR lpszNewName,XMLCSTR lpszOldName);  // set lpszNewName=NULL if you don't want to change the name of the attribute
00295                                                                                                    // if the attribute to update is missing, a new one will be added
00296     XMLCSTR       updateText(XMLCSTR lpszNewValue, int i=0);                                       // if the text to update is missing, a new one will be added
00297     XMLCSTR       updateText(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);                          // if the text to update is missing, a new one will be added
00298     XMLClear     *updateClear(XMLCSTR lpszNewContent, int i=0);                                    // if the clearTag to update is missing, a new one will be added
00299     XMLClear     *updateClear(XMLClear *newP,XMLClear *oldP);                                      // if the clearTag to update is missing, a new one will be added
00300     XMLClear     *updateClear(XMLCSTR lpszNewValue, XMLCSTR lpszOldValue);                         // if the clearTag to update is missing, a new one will be added
00301 
00302     // Some deletion functions:
00303     void deleteNodeContent(char force=0);  // delete the content of this XMLNode and the subtree.
00304                                            // if force=0, while (references to this node still exist), no memory free occurs
00305                                            // if force=1, always delete the content of this XMLNode and the subtree and free associated memory
00306     void deleteAttribute(XMLCSTR lpszName);
00307     void deleteAttribute(int i=0);
00308     void deleteAttribute(XMLAttribute *anAttribute);
00309     void deleteText(int i=0);
00310     void deleteText(XMLCSTR lpszValue);
00311     void deleteClear(int i=0);
00312     void deleteClear(XMLClear *p);
00313     void deleteClear(XMLCSTR lpszValue);
00314 
00315     // The strings given as parameters for the following add and update methods (all these methods have
00316     // a name with the postfix "_WOSD" that means "WithOut String Duplication" ) will be free'd by the
00317     // XMLNode class. For example, it means that this is incorrect:
00318     //    xNode.addText_WOSD("foo");
00319     //    xNode.updateAttribute_WOSD("#newcolor" ,NULL,"color");
00320     // In opposition, this is correct:
00321     //    xNode.addText("foo");
00322     //    xNode.addText_WOSD(stringDup("foo"));
00323     //    xNode.updateAttribute("#newcolor" ,NULL,"color");
00324     //    xNode.updateAttribute_WOSD(stringDup("#newcolor"),NULL,"color");
00325     // Typically, you will never do:
00326     //    char *b=(char*)malloc(...);
00327     //    xNode.addText(b);
00328     //    free(b);
00329     // ... but rather:
00330     //    char *b=(char*)malloc(...);
00331     //    xNode.addText_WOSD(b);
00332     //    ('free(b)' is performed by the XMLNode class)
00333 
00334     static XMLNode createXMLTopNode_WOSD(XMLSTR lpszName, char isDeclaration=FALSE);
00335     XMLNode        addChild_WOSD(XMLSTR lpszName, char isDeclaration=FALSE, int pos=-1);
00336     XMLAttribute  *addAttribute_WOSD(XMLSTR lpszName, XMLSTR lpszValue);
00337     XMLCSTR        addText_WOSD(XMLSTR lpszValue, int pos=-1);
00338     XMLClear      *addClear_WOSD(XMLSTR lpszValue, XMLCSTR lpszOpen=NULL, XMLCSTR lpszClose=NULL, int pos=-1);
00339 
00340     XMLCSTR        updateName_WOSD(XMLSTR lpszName);
00341     XMLAttribute  *updateAttribute_WOSD(XMLAttribute *newAttribute, XMLAttribute *oldAttribute);
00342     XMLAttribute  *updateAttribute_WOSD(XMLSTR lpszNewValue, XMLSTR lpszNewName=NULL,int i=0);
00343     XMLAttribute  *updateAttribute_WOSD(XMLSTR lpszNewValue, XMLSTR lpszNewName,XMLCSTR lpszOldName);
00344     XMLCSTR        updateText_WOSD(XMLSTR lpszNewValue, int i=0);
00345     XMLCSTR        updateText_WOSD(XMLSTR lpszNewValue, XMLCSTR lpszOldValue);
00346     XMLClear      *updateClear_WOSD(XMLSTR lpszNewContent, int i=0);
00347     XMLClear      *updateClear_WOSD(XMLClear *newP,XMLClear *oldP);
00348     XMLClear      *updateClear_WOSD(XMLSTR lpszNewValue, XMLCSTR lpszOldValue);
00349 
00350     // These are some useful functions when you want to insert a childNode, a text or a XMLClearTag in the
00351     // middle (at a specified position) of a XMLNode tree already constructed. The value returned by these
00352     // methods is to be used as last parameter (parameter 'pos') of addChild, addText or addClear.
00353     int positionOfText(int i=0) const;
00354     int positionOfText(XMLCSTR lpszValue) const;
00355     int positionOfClear(int i=0) const;
00356     int positionOfClear(XMLCSTR lpszValue) const;
00357     int positionOfClear(XMLClear *a) const;
00358     int positionOfChildNode(int i=0) const;
00359     int positionOfChildNode(XMLNode x) const;
00360     int positionOfChildNode(XMLCSTR name, int i=0) const; // return the position of the ith childNode with the specified name
00361                                                           // if (name==NULL) return the position of the ith childNode
00362 
00363     // The setGlobalOptions function allows you to change tree global parameters that affect string&file
00364     // parsing. First of all, you most-probably will never have to change these 3 global parameters.
00365     // The return value of the setGlobalOptions function is "0" when there are no errors. If you try to
00366     // set an unrecognized encoding then the return value will be "1" to signal an error.
00367     //
00368     // About the "guessWideCharChars" parameter:
00369     //     If "guessWideCharChars=1" and if this library is compiled in WideChar mode, then the
00370     //     "parseFile" and "openFileHelper" functions will test if the file contains ASCII
00371     //     characters. If this is the case, then the file will be loaded and converted in memory to
00372     //     WideChar before being parsed. If "guessWideCharChars=0", no conversion will
00373     //     be performed.
00374     //
00375     //     If "guessWideCharChars=1" and if this library is compiled in ASCII/UTF8/char* mode, then the
00376     //     "parseFile" and "openFileHelper" functions will test if the file contains WideChar
00377     //     characters. If this is the case, then the file will be loaded and converted in memory to
00378     //     ASCII/UTF8/char* before being parsed. If "guessWideCharChars=0", no conversion will
00379     //     be performed
00380     //
00381     //     Sometime, it's useful to set "guessWideCharChars=0" to disable any conversion
00382     //     because the test to detect the file-type (ASCII/UTF8/char* or WideChar) may fail (rarely).
00383     //
00384     // About the "characterEncoding" parameter:
00385     //     This parameter is only meaningful when compiling in char* mode (multibyte character mode).
00386     //     In wchar_t* (wide char mode), this parameter is ignored. This parameter should be one of the
00387     //     three currently recognized encodings: XMLNode::encoding_UTF8, XMLNode::encoding_ascii,
00388     //     XMLNode::encoding_ShiftJIS.
00389     //
00390     // About the "dropWhiteSpace" parameter:
00391     //     In most situations, text fields containing only white spaces (and carriage returns)
00392     //     are useless. Even more, these "empty" text fields are annoying because they increase the
00393     //     complexity of the user's code for parsing. So, 99% of the time, it's better to drop
00394     //     the "empty" text fields. However The XML specification indicates that no white spaces
00395     //     should be lost when parsing the file. So to be perfectly XML-compliant, you should set
00396     //     dropWhiteSpace=0. A note of caution: if you set "dropWhiteSpace=0", the parser will be
00397     //     slower and your code will be more complex.
00398 
00399     // Enumeration for XML character encoding.
00400     typedef enum XMLCharEncoding { encoding_UTF8=1, encoding_ascii=2, encoding_ShiftJIS=3 } XMLCharEncoding;
00401 
00402     static char setGlobalOptions(XMLCharEncoding characterEncoding=XMLNode::encoding_UTF8, char guessWideCharChars=1, char dropWhiteSpace=1);
00403 
00404     // The next function try to guess the character encoding. You most-probably will never
00405     // have to use this function. It then returns the appropriate value of the global parameter
00406     // "characterEncoding" described above. The guess is based on the content of a buffer of length
00407     // "bufLen" bytes that contains the first bytes (minimum 25 bytes; 200 bytes is a good value) of the
00408     // file to be parsed. The "openFileHelper" function is using this function to automatically compute
00409     // the value of the "characterEncoding" global parameter. There are several heuristics used to do the
00410     // guess. One of the heuristic is based on the "encoding" attribute. The original XML specifications
00411     // forbids to use this attribute to do the guess but you can still use it if you set
00412     // "useXMLEncodingAttribute" to 1 (this is the default behavior and the behavior of most parsers).
00413     // If an inconsistency in the encoding is detected, then the return value is "0".
00414 
00415     static XMLCharEncoding guessCharEncoding(void *buffer, int bufLen, char useXMLEncodingAttribute=1);
00416 
00417   private:
00418 
00419 // these are functions and structures used internally by the XMLNode class (don't bother about them):
00420 
00421       typedef struct XMLNodeDataTag // to allow shallow copy and "intelligent/smart" pointers (automatic delete):
00422       {
00423           XMLCSTR                lpszName;        // Element name (=NULL if root)
00424           int                    nChild,          // Number of child nodes
00425                                  nText,           // Number of text fields
00426                                  nClear,          // Number of Clear fields (comments)
00427                                  nAttribute;      // Number of attributes
00428           char                   isDeclaration;   // Whether node is an XML declaration - '<?xml ?>'
00429           struct XMLNodeDataTag  *pParent;        // Pointer to parent element (=NULL if root)
00430           XMLNode                *pChild;         // Array of child nodes
00431           XMLCSTR                *pText;          // Array of text fields
00432           XMLClear               *pClear;         // Array of clear fields
00433           XMLAttribute           *pAttribute;     // Array of attributes
00434           int                    *pOrder;         // order of the child_nodes,text_fields,clear_fields
00435           int                    ref_count;       // for garbage collection (smart pointers)
00436       } XMLNodeData;
00437       XMLNodeData *d;
00438 
00439       char parseClearTag(void *px, void *pa);
00440       char maybeAddTxT(void *pa, XMLCSTR tokenPStr);
00441       int ParseXMLElement(void *pXML);
00442       void *addToOrder(int memInc, int *_pos, int nc, void *p, int size, XMLElementType xtype);
00443       int indexText(XMLCSTR lpszValue) const;
00444       int indexClear(XMLCSTR lpszValue) const;
00445       XMLNode addChild_priv(int,XMLSTR,char,int);
00446       XMLAttribute *addAttribute_priv(int,XMLSTR,XMLSTR);
00447       XMLCSTR addText_priv(int,XMLSTR,int);
00448       XMLClear *addClear_priv(int,XMLSTR,XMLCSTR,XMLCSTR,int);
00449       static inline int findPosition(XMLNodeData *d, int index, XMLElementType xtype);
00450       static int CreateXMLStringR(XMLNodeData *pEntry, XMLSTR lpszMarker, int length, int nFormat);
00451       static int removeOrderElement(XMLNodeData *d, XMLElementType t, int index);
00452       static void exactMemory(XMLNodeData *d);
00453       static int detachFromParent(XMLNodeData *d);
00454 } XMLNode;
00455 
00456 // This structure is given by the function "enumContents".
00457 typedef struct XMLNodeContents
00458 {
00459     // This dictates what's the content of the XMLNodeContent
00460     enum XMLElementType type;
00461     // should be an union to access the appropriate data.
00462     // compiler does not allow union of object with constructor... too bad.
00463     XMLNode child;
00464     XMLAttribute attrib;
00465     XMLCSTR text;
00466     XMLClear clear;
00467 
00468 } XMLNodeContents;
00469 
00470 XMLDLLENTRY void freeXMLString(XMLSTR t); // {free(t);}
00471 
00472 // Duplicate (copy in a new allocated buffer) the source string. This is
00473 // a very handy function when used with all the "XMLNode::*_WOSD" functions.
00474 // (If (cbData!=0) then cbData is the number of chars to duplicate)
00475 XMLDLLENTRY XMLSTR stringDup(XMLCSTR source, int cbData=0);
00476 
00477 // The following class is processing strings so that all the characters
00478 // &,",',<,> are replaced by their XML equivalent: &amp;, &quot;, &apos;, &lt;, &gt;.
00479 // This  class is useful when creating from scratch an XML file using the
00480 // "printf", "fprintf", "cout",... functions. If you are creating from scratch an
00481 // XML file using the provided XMLNode class you must not use the "ToXMLStringTool"
00482 // class (the "XMLNode" class does the processing job for you during rendering).
00483 // Using the "ToXMLStringTool class" and the "fprintf function" is THE most efficient
00484 // way to produce VERY large XML documents VERY fast.
00485 typedef struct XMLDLLENTRY ToXMLStringTool
00486 {
00487 public:
00488     ToXMLStringTool(): buf(NULL),buflen(0){}
00489     ~ToXMLStringTool();
00490     void freeBuffer();
00491 
00492     XMLSTR toXML(XMLCSTR source);
00493 
00494     // The next function is deprecated because there is a possibility of
00495     // "destination-buffer-overflow". It converts the string
00496     // "source" to the string "dest".
00497     static XMLSTR toXMLUnSafe(XMLSTR dest,XMLCSTR source);
00498 
00499 private:
00500     XMLSTR buf;
00501     int buflen;
00502 }ToXMLStringTool;
00503 
00504 // Below is a class that allows you to include any binary data (images, sounds,...)
00505 // into an XML document using "Base64 encoding". This class is completely
00506 // separated from the rest of the xmlParser library and can be removed without any problem.
00507 // To include some binary data into an XML file, you must convert the binary data into
00508 // standard text (using "encode"). To retrieve the original binary data from the
00509 // b64-encoded text included inside the XML file use "decode". Alternatively, these
00510 // functions can also be used to "encrypt/decrypt" some critical data contained inside
00511 // the XML (it's not a strong encryption at all, but sometimes it can be useful).
00512 
00513 typedef struct XMLDLLENTRY XMLParserBase64Tool
00514 {
00515 public:
00516     XMLParserBase64Tool(): buf(NULL),buflen(0){}
00517     ~XMLParserBase64Tool();
00518     void freeBuffer();
00519 
00520     // returns the length of the base64 string that encodes a data buffer of size inBufLen bytes.
00521     // If "formatted" parameter is true, some space will be reserved for a carriage-return every 72 chars.
00522     static int encodeLength(int inBufLen, char formatted=0);
00523 
00524     // The "base64Encode" function returns a string containing the base64 encoding of "inByteLen" bytes
00525     // from "inByteBuf". If "formatted" parameter is true, then there will be a carriage-return every 72 chars.
00526     // The string will be free'd when the XMLParserBase64Tool object is deleted.
00527     // All returned strings are sharing the same memory space.
00528     XMLSTR encode(unsigned char *inByteBuf, unsigned int inByteLen, char formatted=0);
00529 
00530     // returns the number of bytes which will be decoded from "inString".
00531     static unsigned int decodeSize(XMLCSTR inString, XMLError *xe=NULL);
00532 
00533     // returns a pointer to a buffer containing the binary data decoded from "inString"
00534     // If "inString" is malformed NULL will be returned
00535     // The output buffer will be free'd when the XMLParserBase64Tool object is deleted.
00536     // All output buffer are sharing the same memory space.
00537     unsigned char* decode(XMLCSTR inString, int *outByteLen=NULL, XMLError *xe=NULL);
00538 
00539     // The next function is deprecated.
00540     // decodes data from "inString" to "outByteBuf". You need to provide the size (in byte) of "outByteBuf"
00541     // in "inMaxByteOutBuflen". If "outByteBuf" is not large enough or if data is malformed, then "FALSE"
00542     // will be returned; otherwise "TRUE".
00543     static unsigned char decode(XMLCSTR inString, unsigned char *outByteBuf, int inMaxByteOutBuflen, XMLError *xe=NULL);
00544 
00545 private:
00546     void *buf;
00547     int buflen;
00548     void alloc(int newsize);
00549 }XMLParserBase64Tool;
00550 
00551 #undef XMLDLLENTRY
00552 
00553 #endif
 All Classes Namespaces Functions Variables Enumerations Enumerator