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 *
--- 28 unchanged lines hidden (view full) ---
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 *
--- 102 unchanged lines hidden (view full) ---
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,
--- 10 unchanged lines hidden (view full) ---
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).
--- 4 unchanged lines hidden (view full) ---
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)
--- 45 unchanged lines hidden (view full) ---
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 */
--- 42 unchanged lines hidden (view full) ---
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.
--- 4 unchanged lines hidden (view full) ---
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);
--- 56 unchanged lines hidden (view full) ---
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
--- 17 unchanged lines hidden (view full) ---
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". */
--- 13 unchanged lines hidden (view full) ---
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 /**
--- 32 unchanged lines hidden ---
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 *
--- 28 unchanged lines hidden (view full) ---
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 *
--- 102 unchanged lines hidden (view full) ---
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,
--- 10 unchanged lines hidden (view full) ---
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).
--- 4 unchanged lines hidden (view full) ---
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)
--- 45 unchanged lines hidden (view full) ---
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 */
--- 42 unchanged lines hidden (view full) ---
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.
--- 4 unchanged lines hidden (view full) ---
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);
--- 56 unchanged lines hidden (view full) ---
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
--- 17 unchanged lines hidden (view full) ---
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". */
--- 13 unchanged lines hidden (view full) ---
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 /**
--- 32 unchanged lines hidden ---