include/irrXML.h

   1 // Copyright (C) 2002-2012 Nikolaus Gebhardt\r
   2 // This file is part of the "Irrlicht Engine" and the "irrXML" project.\r
   3 // For conditions of distribution and use, see copyright notice in irrlicht.h and/or irrXML.h\r
   4 \r
   5 #ifndef __IRR_XML_H_INCLUDED__\r
   6 #define __IRR_XML_H_INCLUDED__\r
   7 \r
   8 #include <stdio.h>\r
   9 #include "IrrCompileConfig.h"\r
  10 #include "irrArray.h"\r
  11 #include "irrString.h"\r
  12 \r
  13 /** \mainpage irrXML 1.2 API documentation\r
  14  <div align="center"><img src="logobig.png" ></div>\r
  15 \r
  16  \section intro Introduction\r
  17 \r
  18   Welcome to the irrXML API documentation.\r
  19   Here you'll find any information you'll need to develop applications with\r
  20   irrXML. If you look for a tutorial on how to start, take a look at the \ref irrxmlexample,\r
  21   at the homepage of irrXML at <A HREF="http://www.ambiera.com/irrxml/">www.ambiera.com/irrxml/</A>\r
  22   or into the SDK in the directory example.\r
  23 \r
  24   irrXML is intended to be a high speed and easy-to-use XML Parser for C++, and\r
  25   this documentation is an important part of it. If you have any questions or\r
  26   suggestions, just send a email to the author of the engine, Nikolaus Gebhardt\r
  27   (niko (at) irrlicht3d.org). For more information about this parser, see \ref history.\r
  28 \r
  29   \section features Features\r
  30 \r
  31   irrXML provides forward-only, read-only\r
  32      access to a stream of non validated XML data. It was fully implemented by\r
  33         Nikolaus Gebhardt. Its current features are:\r
  34 \r
  35         - It it fast as lighting and has very low memory usage. It was\r
  36         developed with the intention of being used in 3D games, as it already has been.\r
  37         - irrXML is very small: It only consists of 60 KB of code and can be added easily\r
  38         to your existing project.\r
  39         - Of course, it is platform independent and works with lots of compilers.\r
  40         - It is able to parse ASCII, UTF-8, UTF-16 and UTF-32 text files, both in\r
  41         little and big endian format.\r
  42         - Independent of the input file format, the parser can return all strings in ASCII, UTF-8,\r
  43         UTF-16 and UTF-32 format.\r
  44         - With its optional file access abstraction it has the advantage that it can read not\r
  45         only from files but from any type of data (memory, network, ...). For example when\r
  46         used with the Irrlicht Engine, it directly reads from compressed .zip files.\r
  47         - Just like the Irrlicht Engine for which it was originally created, it is extremely easy\r
  48         to use.\r
  49         - It has no external dependencies, it does not even need the STL.\r
  50 \r
  51         Although irrXML has some strengths, it currently also has the following limitations:\r
  52 \r
  53         - The input xml file is not validated and assumed to be correct.\r
  54 \r
  55     \section irrxmlexample Example\r
  56 \r
  57     The following code demonstrates the basic usage of irrXML. A simple xml\r
  58         file like this is parsed:\r
  59     \code\r
  60         <?xml version="1.0"?>\r
  61         <config>\r
  62                 <!-- This is a config file for the mesh viewer -->\r
  63                 <model file="dwarf.dea" />\r
  64                 <messageText caption="Irrlicht Engine Mesh Viewer">\r
  65                 Welcome to the Mesh Viewer of the &quot;Irrlicht Engine&quot;.\r
  66                 </messageText>\r
  67         </config>\r
  68         \endcode\r
  69 \r
  70         The code for parsing this file would look like this:\r
  71         \code\r
  72         #include <irrXML.h>\r
  73         using namespace irr; // irrXML is located in the namespace irr::io\r
  74         using namespace io;\r
  75 \r
  76         #include <string> // we use STL strings to store data in this example\r
  77 \r
  78         void main()\r
  79         {\r
  80                 // create the reader using one of the factory functions\r
  81 \r
  82                 IrrXMLReader* xml = createIrrXMLReader("config.xml");\r
  83 \r
  84                 // strings for storing the data we want to get out of the file\r
  85                 std::string modelFile;\r
  86                 std::string messageText;\r
  87                 std::string caption;\r
  88 \r
  89                 // parse the file until end reached\r
  90 \r
  91                 while(xml && xml->read())\r
  92                 {\r
  93                         switch(xml->getNodeType())\r
  94                         {\r
  95                         case EXN_TEXT:\r
  96                                 // in this xml file, the only text which occurs is the messageText\r
  97                                 messageText = xml->getNodeData();\r
  98                                 break;\r
  99                         case EXN_ELEMENT:\r
 100                                 {\r
 101                                         if (!strcmp("model", xml->getNodeName()))\r
 102                                                 modelFile = xml->getAttributeValue("file");\r
 103                                         else\r
 104                                         if (!strcmp("messageText", xml->getNodeName()))\r
 105                                                 caption = xml->getAttributeValue("caption");\r
 106                                 }\r
 107                                 break;\r
 108                         }\r
 109                 }\r
 110 \r
 111                 // delete the xml parser after usage\r
 112                 delete xml;\r
 113         }\r
 114         \endcode\r
 115 \r
 116         \section howto How to use\r
 117 \r
 118         Simply add the source files in the /src directory of irrXML to your project. Done.\r
 119 \r
 120         \section license License\r
 121 \r
 122         The irrXML license is based on the zlib license. Basically, this means you can do with\r
 123         irrXML whatever you want:\r
 124 \r
 125         Copyright (C) 2002-2012 Nikolaus Gebhardt\r
 126 \r
 127         This software is provided 'as-is', without any express or implied\r
 128         warranty. In no event will the authors be held liable for any damages\r
 129         arising from the use of this software.\r
 130 \r
 131         Permission is granted to anyone to use this software for any purpose,\r
 132         including commercial applications, and to alter it and redistribute it\r
 133         freely, subject to the following restrictions:\r
 134 \r
 135         1. The origin of this software must not be misrepresented; you must not\r
 136                 claim that you wrote the original software. If you use this software\r
 137                 in a product, an acknowledgment in the product documentation would be\r
 138                 appreciated but is not required.\r
 139 \r
 140         2. Altered source versions must be plainly marked as such, and must not be\r
 141                 misrepresented as being the original software.\r
 142 \r
 143         3. This notice may not be removed or altered from any source distribution.\r
 144 \r
 145         \section history History\r
 146 \r
 147         As lots of references in this documentation and the source show, this xml\r
 148         parser has originally been a part of the\r
 149         <A HREF="http://irrlicht.sourceforge.net" >Irrlicht Engine</A>. But because\r
 150         the parser has become very useful with the latest release, people asked for a\r
 151         separate version of it, to be able to use it in non Irrlicht projects. With\r
 152         irrXML 1.0, this has now been done.\r
 153 */\r
 154 \r
 155 namespace irr\r
 156 {\r
 157 namespace io\r
 158 {\r
 159         //! Enumeration of all supported source text file formats\r
 160         enum ETEXT_FORMAT\r
 161         {\r
 162                 //! ASCII, file without byte order mark, or not a text file\r
 163                 ETF_ASCII,\r
 164 \r
 165                 //! UTF-8 format\r
 166                 ETF_UTF8,\r
 167 \r
 168                 //! UTF-16 format, big endian\r
 169                 ETF_UTF16_BE,\r
 170 \r
 171                 //! UTF-16 format, little endian\r
 172                 ETF_UTF16_LE,\r
 173 \r
 174                 //! UTF-32 format, big endian\r
 175                 ETF_UTF32_BE,\r
 176 \r
 177                 //! UTF-32 format, little endian\r
 178                 ETF_UTF32_LE\r
 179         };\r
 180 \r
 181 \r
 182         //! Enumeration for all xml nodes which are parsed by IrrXMLReader\r
 183         enum EXML_NODE\r
 184         {\r
 185                 //! No xml node. This is usually the node if you did not read anything yet.\r
 186                 EXN_NONE,\r
 187 \r
 188                 //! An xml element such as &lt;foo&gt;\r
 189                 EXN_ELEMENT,\r
 190 \r
 191                 //! End of an xml element such as &lt;/foo&gt;\r
 192                 EXN_ELEMENT_END,\r
 193 \r
 194                 //! Text within an xml element: &lt;foo&gt; this is the text. &lt;/foo&gt;\r
 195                 //! Also text between 2 xml elements: &lt;/foo&gt; this is the text. &lt;foo&gt;\r
 196                 EXN_TEXT,\r
 197 \r
 198                 //! An xml comment like &lt;!-- I am a comment --&gt; or a DTD definition.\r
 199                 EXN_COMMENT,\r
 200 \r
 201                 //! An xml cdata section like &lt;![CDATA[ this is some CDATA ]]&gt;\r
 202                 EXN_CDATA,\r
 203 \r
 204                 //! Unknown element.\r
 205                 EXN_UNKNOWN\r
 206         };\r
 207 \r
 208         //! Callback class for file read abstraction.\r
 209         /** With this, it is possible to make the xml parser read in other\r
 210         things than just files. The Irrlicht engine is using this for example to\r
 211         read xml from compressed .zip files. To make the parser read in\r
 212         any other data, derive a class from this interface, implement the\r
 213         two methods to read your data and give a pointer to an instance of\r
 214         your implementation when calling createIrrXMLReader(),\r
 215         createIrrXMLReaderUTF16() or createIrrXMLReaderUTF32() */\r
 216         class IFileReadCallBack\r
 217         {\r
 218         public:\r
 219 \r
 220                 //! Destructor\r
 221                 virtual ~IFileReadCallBack() {}\r
 222 \r
 223                 //! Reads an amount of bytes from the file.\r
 224                 /** \param buffer: Pointer to buffer where to read bytes will be written to.\r
 225                 \param sizeToRead: Amount of bytes to read from the file.\r
 226                 \return Returns how much bytes were read. */\r
 227                 virtual int read(void* buffer, int sizeToRead) = 0;\r
 228 \r
 229                 //! Returns size of file in bytes on success or -1L on failure.\r
 230                 virtual long getSize() const = 0;\r
 231         };\r
 232 \r
 233         //! Empty class to be used as parent class for IrrXMLReader.\r
 234         /** If you need another class as base class for the xml reader, you can do this by creating\r
 235         the reader using for example new CXMLReaderImpl<char, YourBaseClass>(yourcallback);\r
 236         The Irrlicht Engine for example needs IReferenceCounted as base class for every object to\r
 237         let it automatically reference counted, hence it replaces IXMLBase with IReferenceCounted.\r
 238         See irrXML.cpp on how this can be done in detail. */\r
 239         class IXMLBase\r
 240         {\r
 241         };\r
 242 \r
 243         //! Interface providing easy read access to a XML file.\r
 244         /** You can create an instance of this reader using one of the factory functions\r
 245         createIrrXMLReader(), createIrrXMLReaderUTF16() and createIrrXMLReaderUTF32().\r
 246         If using the parser from the Irrlicht Engine, please use IFileSystem::createXMLReader()\r
 247         instead.\r
 248         For a detailed intro how to use the parser, see \ref irrxmlexample and \ref features.\r
 249 \r
 250         The typical usage of this parser looks like this:\r
 251         \code\r
 252         #include <irrXML.h>\r
 253         using namespace irr; // irrXML is located in the namespace irr::io\r
 254         using namespace io;\r
 255 \r
 256         void main()\r
 257         {\r
 258                 // create the reader using one of the factory functions\r
 259                 IrrXMLReader* xml = createIrrXMLReader("config.xml");\r
 260 \r
 261                 if (xml == 0)\r
 262                         return; // file could not be opened\r
 263 \r
 264                 // parse the file until end reached\r
 265                 while(xml->read())\r
 266                 {\r
 267                         // based on xml->getNodeType(), do something.\r
 268                 }\r
 269 \r
 270                 // delete the xml parser after usage\r
 271                 delete xml;\r
 272         }\r
 273         \endcode\r
 274         See \ref irrxmlexample for a more detailed example.\r
 275         */\r
 276         template<class char_type, class super_class>\r
 277         class IIrrXMLReader : public super_class\r
 278         {\r
 279         public:\r
 280 \r
 281                 //! Destructor\r
 282                 virtual ~IIrrXMLReader() {}\r
 283 \r
 284                 //! Reads forward to the next xml node.\r
 285                 /** \return Returns false, if there was no further node. */\r
 286                 virtual bool read() = 0;\r
 287 \r
 288                 //! Returns the type of the current XML node.\r
 289                 virtual EXML_NODE getNodeType() const = 0;\r
 290 \r
 291                 //! Returns attribute count of the current XML node.\r
 292                 /** This is usually\r
 293                 non null if the current node is EXN_ELEMENT, and the element has attributes.\r
 294                 \return Returns amount of attributes of this xml node. */\r
 295                 virtual unsigned int getAttributeCount() const = 0;\r
 296 \r
 297                 //! Returns name of an attribute.\r
 298                 /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.\r
 299                 \return Name of the attribute, 0 if an attribute with this index does not exist. */\r
 300                 virtual const char_type* getAttributeName(int idx) const = 0;\r
 301 \r
 302                 //! Returns the value of an attribute.\r
 303                 /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.\r
 304                 \return Value of the attribute, 0 if an attribute with this index does not exist. */\r
 305                 virtual const char_type* getAttributeValue(int idx) const = 0;\r
 306 \r
 307                 //! Returns the value of an attribute.\r
 308                 /** \param name: Name of the attribute.\r
 309                 \return Value of the attribute, 0 if an attribute with this name does not exist. */\r
 310                 virtual const char_type* getAttributeValue(const char_type* name) const = 0;\r
 311 \r
 312                 //! Returns the value of an attribute in a safe way.\r
 313                 /** Like getAttributeValue(), but does not\r
 314                 return 0 if the attribute does not exist. An empty string ("") is returned then.\r
 315                 \param name: Name of the attribute.\r
 316                 \return Value of the attribute, and "" if an attribute with this name does not exist */\r
 317                 virtual const char_type* getAttributeValueSafe(const char_type* name) const = 0;\r
 318 \r
 319                 //! Returns the value of an attribute as integer.\r
 320                 /** \param name Name of the attribute.\r
 321                 \param defaultNotFound Value returned when name does not exist\r
 322                 \return Value of the attribute as integer or value of defaultNotFound\r
 323                 when name was not found or 0 when value could not be interpreted as integer */\r
 324                 virtual int getAttributeValueAsInt(const char_type* name, int defaultNotFound=0) const = 0;\r
 325 \r
 326                 //! Returns the value of an attribute as integer.\r
 327                 /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.\r
 328                 \param defaultNotFound Value returned when index does not exist.\r
 329                 \return Value of the attribute as integer or value of defaultNotFound parameter for invalid index\r
 330                 or 0 when value could not be interpreted as integer */\r
 331                 virtual int getAttributeValueAsInt(int idx, int defaultNotFound=0) const = 0;\r
 332 \r
 333                 //! Returns the value of an attribute as float.\r
 334                 /** \param name: Name of the attribute.\r
 335                 \param defaultNotFound Value returned when name does not exist.\r
 336                 \return Value of the attribute as float or value of defaultNotFound parameter on failure\r
 337                 or 0 when value could not be interpreted as float. */\r
 338                 virtual float getAttributeValueAsFloat(const char_type* name, float defaultNotFound=0.f) const = 0;\r
 339 \r
 340                 //! Returns the value of an attribute as float.\r
 341                 /** \param idx: Zero based index, should be something between 0 and getAttributeCount()-1.\r
 342                 \param defaultNotFound Value returned when index does not exist.\r
 343                 \return Value of the attribute as float or value of defaultNotFound parameter on failure\r
 344                 or 0 when value could not be interpreted as float. */\r
 345                 virtual float getAttributeValueAsFloat(int idx, float defaultNotFound=0.f) const = 0;\r
 346 \r
 347                 //! Returns the name of the current node.\r
 348                 /** Only valid, if the node type is EXN_ELEMENT.\r
 349                 \return Name of the current node or 0 if the node has no name. */\r
 350                 virtual const char_type* getNodeName() const = 0;\r
 351 \r
 352                 //! Returns data of the current node.\r
 353                 /** Only valid if the node has some\r
 354                 data and it is of type EXN_TEXT, EXN_COMMENT, EXN_CDATA or EXN_UNKNOWN. */\r
 355                 virtual const char_type* getNodeData() const = 0;\r
 356 \r
 357                 //! Returns if an element is an empty element, like &lt;foo />\r
 358                 virtual bool isEmptyElement() const = 0;\r
 359 \r
 360                 //! Returns format of the source xml file.\r
 361                 /** It is not necessary to use\r
 362                 this method because the parser will convert the input file format\r
 363                 to the format wanted by the user when creating the parser. This\r
 364                 method is useful to get/display additional information. */\r
 365                 virtual ETEXT_FORMAT getSourceFormat() const = 0;\r
 366 \r
 367                 //! Returns format of the strings returned by the parser.\r
 368                 /** This will be UTF8 for example when you created a parser with\r
 369                 IrrXMLReaderUTF8() and UTF32 when it has been created using\r
 370                 IrrXMLReaderUTF32. It should not be necessary to call this\r
 371                 method and only exists for informational purposes. */\r
 372                 virtual ETEXT_FORMAT getParserFormat() const = 0;\r
 373         };\r
 374 \r
 375         //! Interface providing methods for making it easier to write XML files.\r
 376         template<class char_type, class super_class>\r
 377         class IIrrXMLWriter : public super_class\r
 378         {\r
 379         public:\r
 380 \r
 381                 //! Destructor\r
 382                 virtual ~IIrrXMLWriter() {}\r
 383 \r
 384                 //! Writes an xml 1.0 header.\r
 385                 /** Looks like &lt;?xml version="1.0"?&gt;. This should always\r
 386                 be called before writing anything other, because also the text\r
 387                 file header for Unicode texts is written out with this method. */\r
 388                 virtual void writeXMLHeader() = 0;\r
 389 \r
 390                 //! Writes an xml element with maximal 5 attributes like "<foo />" or\r
 391                 //! &lt;foo optAttr="value" /&gt;.\r
 392                 /** The element can be empty or not.\r
 393                 \param name: Name of the element\r
 394                 \param empty: Specifies if the element should be empty. Like\r
 395                 "<foo />". If You set this to false, something like this is\r
 396                 written instead: "<foo>".\r
 397                 \param attr1Name: 1st attributes name\r
 398                 \param attr1Value: 1st attributes value\r
 399                 \param attr2Name: 2nd attributes name\r
 400                 \param attr2Value: 2nd attributes value\r
 401                 \param attr3Name: 3rd attributes name\r
 402                 \param attr3Value: 3rd attributes value\r
 403                 \param attr4Name: 4th attributes name\r
 404                 \param attr4Value: 4th attributes value\r
 405                 \param attr5Name: 5th attributes name\r
 406                 \param attr5Value: 5th attributes value */\r
 407                 virtual void writeElement(const char_type* name, bool empty=false,\r
 408                         const char_type* attr1Name = 0, const char_type* attr1Value = 0,\r
 409                         const char_type* attr2Name = 0, const char_type* attr2Value = 0,\r
 410                         const char_type* attr3Name = 0, const char_type* attr3Value = 0,\r
 411                         const char_type* attr4Name = 0, const char_type* attr4Value = 0,\r
 412                         const char_type* attr5Name = 0, const char_type* attr5Value = 0) = 0;\r
 413 \r
 414                 //! Writes an xml element with any number of attributes\r
 415                 virtual void writeElement(const char_type* name, bool empty,\r
 416                                 core::array<core::string<char_type> > &names, core::array<core::string<char_type> > &values) = 0;\r
 417 \r
 418                 //! Writes a comment into the xml file\r
 419                 virtual void writeComment(const char_type* comment) = 0;\r
 420 \r
 421                 //! Writes the closing tag for an element. Like "</foo>"\r
 422                 virtual void writeClosingTag(const char_type* name) = 0;\r
 423 \r
 424                 //! Writes a text into the file.\r
 425                 /** All occurrences of special characters such as\r
 426                 & (&amp;), < (&lt;), > (&gt;), and " (&quot;) are automatically\r
 427                 replaced. */\r
 428                 virtual void writeText(const char_type* text) = 0;\r
 429 \r
 430                 //! Writes a line break\r
 431                 virtual void writeLineBreak() = 0;\r
 432         };\r
 433 \r
 434 \r
 435         template <typename T>\r
 436         struct xmlChar\r
 437         {\r
 438                 T c;\r
 439                 xmlChar<T>() {}\r
 440                 xmlChar<T>(char in) : c(static_cast<T>(in)) {}\r
 441                 xmlChar<T>(wchar_t in) : c(static_cast<T>(in)) {}\r
 442 #if defined(__BORLANDC__)\r
 443                 // Note - removing explicit for Borland was to get it to even compile.\r
 444                 // There haven't been any kind of tests for that besides that.\r
 445                 xmlChar<T>(unsigned char in) : c(static_cast<T>(in)) {}\r
 446                 xmlChar<T>(unsigned short in) : c(static_cast<T>(in)) {}\r
 447                 xmlChar<T>(unsigned int in) : c(static_cast<T>(in)) {}\r
 448                 xmlChar<T>(unsigned long in) : c(static_cast<T>(in)) {}\r
 449 #else\r
 450                 explicit xmlChar<T>(unsigned char in) : c(static_cast<T>(in)) {}\r
 451 \r
 452 #if !defined(_MSC_VER) || defined(_NATIVE_WCHAR_T_DEFINED)      // VS compiling without native wchar_t can't have it\r
 453                 explicit xmlChar<T>(unsigned short in) : c(static_cast<T>(in)) {}\r
 454 #endif\r
 455                 explicit xmlChar<T>(unsigned int in) : c(static_cast<T>(in)) {}\r
 456                 explicit xmlChar<T>(unsigned long in) : c(static_cast<T>(in)) {}\r
 457 #endif\r
 458                 operator T() const { return c; }\r
 459                 void operator=(int t) { c=static_cast<T>(t); }\r
 460         };\r
 461 \r
 462         //! defines the utf-16 type.\r
 463         /** Not using wchar_t for this because\r
 464         wchar_t has 16 bit on windows and 32 bit on other operating systems. */\r
 465         typedef xmlChar<unsigned short> char16;\r
 466 \r
 467         //! defines the utf-32 type.\r
 468         /** Not using wchar_t for this because\r
 469         wchar_t has 16 bit on windows and 32 bit on other operating systems. */\r
 470         typedef xmlChar<unsigned int> char32;\r
 471 \r
 472         //! A UTF-8 or ASCII character xml parser.\r
 473         /** This means that all character data will be returned in 8 bit ASCII or UTF-8 by this parser.\r
 474         The file to read can be in any format, it will be converted to UTF-8 if it is not\r
 475         in this format.\r
 476         Create an instance of this with createIrrXMLReader();\r
 477         See IIrrXMLReader for description on how to use it. */\r
 478         typedef IIrrXMLReader<char, IXMLBase> IrrXMLReader;\r
 479 \r
 480         //! A UTF-16 xml parser.\r
 481         /** This means that all character data will be returned in UTF-16 by this parser.\r
 482         The file to read can be in any format, it will be converted to UTF-16 if it is not\r
 483         in this format.\r
 484         Create an instance of this with createIrrXMLReaderUTF16();\r
 485         See IIrrXMLReader for description on how to use it. */\r
 486         typedef IIrrXMLReader<char16, IXMLBase> IrrXMLReaderUTF16;\r
 487 \r
 488         //! A UTF-32 xml parser.\r
 489         /** This means that all character data will be returned in UTF-32 by this parser.\r
 490         The file to read can be in any format, it will be converted to UTF-32 if it is not\r
 491         in this format.\r
 492         Create an instance of this with createIrrXMLReaderUTF32();\r
 493         See IIrrXMLReader for description on how to use it. */\r
 494         typedef IIrrXMLReader<char32, IXMLBase> IrrXMLReaderUTF32;\r
 495 \r
 496 #ifdef _IRR_COMPILE_WITH_XML_\r
 497 \r
 498         //! Creates an instance of an UFT-8 or ASCII character xml parser.\r
 499         /** This means that all character data will be returned in 8 bit ASCII or UTF-8.\r
 500         The file to read can be in any format, it will be converted to UTF-8 if it is not in this format.\r
 501         If you are using the Irrlicht Engine, it is better not to use this function but\r
 502         IFileSystem::createXMLReaderUTF8() instead.\r
 503         \param filename: Name of file to be opened.\r
 504         \return Returns a pointer to the created xml parser. This pointer should be\r
 505         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 506         and the file could not be opened. */\r
 507         IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(const char* filename);\r
 508 \r
 509         //! Creates an instance of an UFT-8 or ASCII character xml parser.\r
 510         /** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can\r
 511         be in any format, it will be converted to UTF-8 if it is not in this format.\r
 512         If you are using the Irrlicht Engine, it is better not to use this function but\r
 513         IFileSystem::createXMLReaderUTF8() instead.\r
 514         \param file: Pointer to opened file, must have been opened in binary mode, e.g.\r
 515         using fopen("foo.bar", "wb"); The file will not be closed after it has been read.\r
 516         \return Returns a pointer to the created xml parser. This pointer should be\r
 517         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 518         and the file could not be opened. */\r
 519         IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(FILE* file);\r
 520 \r
 521         //! Creates an instance of an UFT-8 or ASCII character xml parser.\r
 522         /** This means that all character data will be returned in 8 bit ASCII or UTF-8. The file to read can\r
 523         be in any format, it will be converted to UTF-8 if it is not in this format.\r
 524         If you are using the Irrlicht Engine, it is better not to use this function but\r
 525         IFileSystem::createXMLReaderUTF8() instead.\r
 526         \param callback: Callback for file read abstraction. Implement your own\r
 527         callback to make the xml parser read in other things than just files. See\r
 528         IFileReadCallBack for more information about this.\r
 529         \param deleteCallback: if true, the callback will be deleted after the file\r
 530         has been read.  Otherwise the caller is responsible for cleaning it up.\r
 531         \return Returns a pointer to the created xml parser. This pointer should be\r
 532         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 533         and the file could not be opened. */\r
 534         IRRLICHT_API IrrXMLReader* IRRCALLCONV createIrrXMLReader(IFileReadCallBack* callback,\r
 535                                                                                                                                 bool deleteCallback = false);\r
 536 \r
 537         //! Creates an instance of an UFT-16 xml parser.\r
 538         /** This means that\r
 539         all character data will be returned in UTF-16. The file to read can\r
 540         be in any format, it will be converted to UTF-16 if it is not in this format.\r
 541         If you are using the Irrlicht Engine, it is better not to use this function but\r
 542         IFileSystem::createXMLReader() instead.\r
 543         \param filename: Name of file to be opened.\r
 544         \return Returns a pointer to the created xml parser. This pointer should be\r
 545         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 546         and the file could not be opened. */\r
 547         IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(const char* filename);\r
 548 \r
 549         //! Creates an instance of an UFT-16 xml parser.\r
 550         /** This means that all character data will be returned in UTF-16. The file to read can\r
 551         be in any format, it will be converted to UTF-16 if it is not in this format.\r
 552         If you are using the Irrlicht Engine, it is better not to use this function but\r
 553         IFileSystem::createXMLReader() instead.\r
 554         \param file: Pointer to opened file, must have been opened in binary mode, e.g.\r
 555         using fopen("foo.bar", "wb"); The file will not be closed after it has been read.\r
 556         \return Returns a pointer to the created xml parser. This pointer should be\r
 557         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 558         and the file could not be opened. */\r
 559         IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(FILE* file);\r
 560 \r
 561         //! Creates an instance of an UFT-16 xml parser.\r
 562         /** This means that all character data will be returned in UTF-16. The file to read can\r
 563         be in any format, it will be converted to UTF-16 if it is not in this format.\r
 564         If you are using the Irrlicht Engine, it is better not to use this function but\r
 565         IFileSystem::createXMLReader() instead.\r
 566         \param callback: Callback for file read abstraction. Implement your own\r
 567         callback to make the xml parser read in other things than just files. See\r
 568         IFileReadCallBack for more information about this.\r
 569         \param deleteCallback: if true, the callback will be deleted after the file\r
 570         has been read.  Otherwise the caller is responsible for cleaning it up.\r
 571         \return Returns a pointer to the created xml parser. This pointer should be\r
 572         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 573         and the file could not be opened. */\r
 574         IRRLICHT_API IrrXMLReaderUTF16* IRRCALLCONV createIrrXMLReaderUTF16(IFileReadCallBack* callback,\r
 575                                                                                                                                                 bool deleteCallback = false);\r
 576 \r
 577 \r
 578         //! Creates an instance of an UFT-32 xml parser.\r
 579         /** This means that all character data will be returned in UTF-32. The file to read can\r
 580         be in any format, it will be converted to UTF-32 if it is not in this format.\r
 581         If you are using the Irrlicht Engine, it is better not to use this function but\r
 582         IFileSystem::createXMLReader() instead.\r
 583         \param filename: Name of file to be opened.\r
 584         \return Returns a pointer to the created xml parser. This pointer should be\r
 585         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 586         and the file could not be opened. */\r
 587         IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(const char* filename);\r
 588 \r
 589         //! Creates an instance of an UFT-32 xml parser.\r
 590         /** This means that all character data will be returned in UTF-32. The file to read can\r
 591         be in any format, it will be converted to UTF-32 if it is not in this format.\r
 592         if you are using the Irrlicht Engine, it is better not to use this function but\r
 593         IFileSystem::createXMLReader() instead.\r
 594         \param file: Pointer to opened file, must have been opened in binary mode, e.g.\r
 595         using fopen("foo.bar", "wb"); The file will not be closed after it has been read.\r
 596         \return Returns a pointer to the created xml parser. This pointer should be\r
 597         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 598         and the file could not be opened. */\r
 599         IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(FILE* file);\r
 600 \r
 601         //! Creates an instance of an UFT-32 xml parser.\r
 602         /** This means that\r
 603         all character data will be returned in UTF-32. The file to read can\r
 604         be in any format, it will be converted to UTF-32 if it is not in this format.\r
 605         If you are using the Irrlicht Engine, it is better not to use this function but\r
 606         IFileSystem::createXMLReader() instead.\r
 607         \param callback: Callback for file read abstraction. Implement your own\r
 608         callback to make the xml parser read in other things than just files. See\r
 609         IFileReadCallBack for more information about this.\r
 610         \param deleteCallback: if true, the callback will be deleted after the file\r
 611         has been read.  Otherwise the caller is responsible for cleaning it up.\r
 612         \return Returns a pointer to the created xml parser. This pointer should be\r
 613         deleted using 'delete' after no longer needed. Returns 0 if an error occurred\r
 614         and the file could not be opened. */\r
 615         IRRLICHT_API IrrXMLReaderUTF32* IRRCALLCONV createIrrXMLReaderUTF32(IFileReadCallBack* callback,\r
 616                                                                                                                                                 bool deleteCallback = false);\r
 617 \r
 618 #endif // _IRR_COMPILE_WITH_XML_\r
 619 \r
 620         /*! \file irrXML.h\r
 621         \brief Header file of the irrXML, the Irrlicht XML parser.\r
 622 \r
 623         This file includes everything needed for using irrXML,\r
 624         the XML parser of the Irrlicht Engine. To use irrXML,\r
 625         you only need to include this file in your project:\r
 626 \r
 627         \code\r
 628         #include <irrXML.h>\r
 629         \endcode\r
 630 \r
 631         It is also common to use the two namespaces in which irrXML is included,\r
 632         directly after including irrXML.h:\r
 633 \r
 634         \code\r
 635         #include <irrXML.h>\r
 636         using namespace irr;\r
 637         using namespace io;\r
 638         \endcode\r
 639         */\r
 640 \r
 641 } // end namespace io\r
 642 } // end namespace irr\r
 643 \r
 644 #endif // __IRR_XML_H_INCLUDED__\r
 645 \r