Home | History | Annotate | Line # | Download | only in doc
reference.html revision 1.1.1.2.2.2 
      1  1.1.1.2.2.2  yamt <?xml version="1.0" encoding="iso-8859-1"?>
      2  1.1.1.2.2.2  yamt <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      3  1.1.1.2.2.2  yamt                       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
      4  1.1.1.2.2.2  yamt <html>
      5  1.1.1.2.2.2  yamt <head>
      6  1.1.1.2.2.2  yamt <!-- Copyright 1999,2000 Clark Cooper <coopercc (a] netheaven.com>
      7  1.1.1.2.2.2  yamt      All rights reserved.
      8  1.1.1.2.2.2  yamt      This is free software. You may distribute or modify according to
      9  1.1.1.2.2.2  yamt      the terms of the MIT/X License -->
     10  1.1.1.2.2.2  yamt   <title>Expat XML Parser</title>
     11  1.1.1.2.2.2  yamt   <meta name="author" content="Clark Cooper, coopercc (a] netheaven.com" />
     12  1.1.1.2.2.2  yamt   <meta http-equiv="Content-Style-Type" content="text/css" />
     13  1.1.1.2.2.2  yamt   <link href="style.css" rel="stylesheet" type="text/css" />
     14  1.1.1.2.2.2  yamt </head>
     15  1.1.1.2.2.2  yamt <body>
     16  1.1.1.2.2.2  yamt   <table cellspacing="0" cellpadding="0" width="100%">
     17  1.1.1.2.2.2  yamt     <tr>
     18  1.1.1.2.2.2  yamt       <td class="corner"><img src="expat.png" alt="(Expat logo)" /></td>
     19  1.1.1.2.2.2  yamt       <td class="banner"><h1>The Expat XML Parser</h1></td>
     20  1.1.1.2.2.2  yamt     </tr>
     21  1.1.1.2.2.2  yamt     <tr>
     22  1.1.1.2.2.2  yamt       <td class="releaseno">Release 2.0.1</td>
     23  1.1.1.2.2.2  yamt       <td></td>
     24  1.1.1.2.2.2  yamt     </tr>
     25  1.1.1.2.2.2  yamt   </table>
     26  1.1.1.2.2.2  yamt <div class="content">
     27  1.1.1.2.2.2  yamt 
     28  1.1.1.2.2.2  yamt <p>Expat is a library, written in C, for parsing XML documents. It's
     29  1.1.1.2.2.2  yamt the underlying XML parser for the open source Mozilla project, Perl's
     30  1.1.1.2.2.2  yamt <code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and
     31  1.1.1.2.2.2  yamt other open-source XML parsers.</p>
     32  1.1.1.2.2.2  yamt 
     33  1.1.1.2.2.2  yamt <p>This library is the creation of James Clark, who's also given us
     34  1.1.1.2.2.2  yamt groff (an nroff look-alike), Jade (an implemention of ISO's DSSSL
     35  1.1.1.2.2.2  yamt stylesheet language for SGML), XP (a Java XML parser package), XT (a
     36  1.1.1.2.2.2  yamt Java XSL engine).  James was also the technical lead on the XML
     37  1.1.1.2.2.2  yamt Working Group at W3C that produced the XML specification.</p>
     38  1.1.1.2.2.2  yamt 
     39  1.1.1.2.2.2  yamt <p>This is free software, licensed under the <a
     40  1.1.1.2.2.2  yamt href="../COPYING">MIT/X Consortium license</a>. You may download it
     41  1.1.1.2.2.2  yamt from <a href="http://www.libexpat.org/">the Expat home page</a>.
     42  1.1.1.2.2.2  yamt </p>
     43  1.1.1.2.2.2  yamt 
     44  1.1.1.2.2.2  yamt <p>The bulk of this document was originally commissioned as an article
     45  1.1.1.2.2.2  yamt by <a href="http://www.xml.com/">XML.com</a>. They graciously allowed
     46  1.1.1.2.2.2  yamt Clark Cooper to retain copyright and to distribute it with Expat.
     47  1.1.1.2.2.2  yamt This version has been substantially extended to include documentation
     48  1.1.1.2.2.2  yamt on features which have been added since the original article was
     49  1.1.1.2.2.2  yamt published, and additional information on using the original
     50  1.1.1.2.2.2  yamt interface.</p>
     51  1.1.1.2.2.2  yamt 
     52  1.1.1.2.2.2  yamt <hr />
     53  1.1.1.2.2.2  yamt <h2>Table of Contents</h2>
     54  1.1.1.2.2.2  yamt <ul>
     55  1.1.1.2.2.2  yamt   <li><a href="#overview">Overview</a></li>
     56  1.1.1.2.2.2  yamt   <li><a href="#building">Building and Installing</a></li>
     57  1.1.1.2.2.2  yamt   <li><a href="#using">Using Expat</a></li>
     58  1.1.1.2.2.2  yamt   <li><a href="#reference">Reference</a>
     59  1.1.1.2.2.2  yamt   <ul>
     60  1.1.1.2.2.2  yamt     <li><a href="#creation">Parser Creation Functions</a>
     61  1.1.1.2.2.2  yamt     <ul>
     62  1.1.1.2.2.2  yamt       <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li>
     63  1.1.1.2.2.2  yamt       <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li>
     64  1.1.1.2.2.2  yamt       <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li>
     65  1.1.1.2.2.2  yamt       <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li>
     66  1.1.1.2.2.2  yamt       <li><a href="#XML_ParserFree">XML_ParserFree</a></li>
     67  1.1.1.2.2.2  yamt       <li><a href="#XML_ParserReset">XML_ParserReset</a></li>
     68  1.1.1.2.2.2  yamt     </ul>
     69  1.1.1.2.2.2  yamt     </li>
     70  1.1.1.2.2.2  yamt     <li><a href="#parsing">Parsing Functions</a>
     71  1.1.1.2.2.2  yamt     <ul>
     72  1.1.1.2.2.2  yamt       <li><a href="#XML_Parse">XML_Parse</a></li>
     73  1.1.1.2.2.2  yamt       <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li>
     74  1.1.1.2.2.2  yamt       <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li>
     75  1.1.1.2.2.2  yamt       <li><a href="#XML_StopParser">XML_StopParser</a></li>
     76  1.1.1.2.2.2  yamt       <li><a href="#XML_ResumeParser">XML_ResumeParser</a></li>
     77  1.1.1.2.2.2  yamt       <li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li>
     78  1.1.1.2.2.2  yamt     </ul>
     79  1.1.1.2.2.2  yamt     </li>
     80  1.1.1.2.2.2  yamt     <li><a href="#setting">Handler Setting Functions</a>
     81  1.1.1.2.2.2  yamt     <ul>
     82  1.1.1.2.2.2  yamt       <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li>
     83  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li>
     84  1.1.1.2.2.2  yamt       <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li>
     85  1.1.1.2.2.2  yamt       <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li>
     86  1.1.1.2.2.2  yamt       <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li>
     87  1.1.1.2.2.2  yamt       <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li>
     88  1.1.1.2.2.2  yamt       <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li>
     89  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li>
     90  1.1.1.2.2.2  yamt       <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li>
     91  1.1.1.2.2.2  yamt       <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li>
     92  1.1.1.2.2.2  yamt       <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li>
     93  1.1.1.2.2.2  yamt       <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li>
     94  1.1.1.2.2.2  yamt       <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li>
     95  1.1.1.2.2.2  yamt       <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li>
     96  1.1.1.2.2.2  yamt       <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li>
     97  1.1.1.2.2.2  yamt       <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li>
     98  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li>
     99  1.1.1.2.2.2  yamt       <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li>
    100  1.1.1.2.2.2  yamt       <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li>		  
    101  1.1.1.2.2.2  yamt       <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li>
    102  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li>
    103  1.1.1.2.2.2  yamt       <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li>
    104  1.1.1.2.2.2  yamt       <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li>
    105  1.1.1.2.2.2  yamt       <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li>
    106  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li>
    107  1.1.1.2.2.2  yamt       <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li>
    108  1.1.1.2.2.2  yamt       <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li>
    109  1.1.1.2.2.2  yamt       <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li>
    110  1.1.1.2.2.2  yamt     </ul>
    111  1.1.1.2.2.2  yamt     </li>
    112  1.1.1.2.2.2  yamt     <li><a href="#position">Parse Position and Error Reporting Functions</a>
    113  1.1.1.2.2.2  yamt     <ul>
    114  1.1.1.2.2.2  yamt       <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li>
    115  1.1.1.2.2.2  yamt       <li><a href="#XML_ErrorString">XML_ErrorString</a></li>
    116  1.1.1.2.2.2  yamt       <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li>
    117  1.1.1.2.2.2  yamt       <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li>
    118  1.1.1.2.2.2  yamt       <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li>
    119  1.1.1.2.2.2  yamt       <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li>
    120  1.1.1.2.2.2  yamt       <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li>
    121  1.1.1.2.2.2  yamt     </ul>
    122  1.1.1.2.2.2  yamt     </li>
    123  1.1.1.2.2.2  yamt     <li><a href="#miscellaneous">Miscellaneous Functions</a>
    124  1.1.1.2.2.2  yamt     <ul>
    125  1.1.1.2.2.2  yamt       <li><a href="#XML_SetUserData">XML_SetUserData</a></li>
    126  1.1.1.2.2.2  yamt       <li><a href="#XML_GetUserData">XML_GetUserData</a></li>
    127  1.1.1.2.2.2  yamt       <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li>
    128  1.1.1.2.2.2  yamt       <li><a href="#XML_SetBase">XML_SetBase</a></li>
    129  1.1.1.2.2.2  yamt       <li><a href="#XML_GetBase">XML_GetBase</a></li>
    130  1.1.1.2.2.2  yamt       <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li>
    131  1.1.1.2.2.2  yamt       <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li>
    132  1.1.1.2.2.2  yamt       <li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li>
    133  1.1.1.2.2.2  yamt       <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li>
    134  1.1.1.2.2.2  yamt       <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li>
    135  1.1.1.2.2.2  yamt       <li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li>
    136  1.1.1.2.2.2  yamt       <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li>
    137  1.1.1.2.2.2  yamt       <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li>
    138  1.1.1.2.2.2  yamt       <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li>
    139  1.1.1.2.2.2  yamt       <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li>
    140  1.1.1.2.2.2  yamt       <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li>
    141  1.1.1.2.2.2  yamt       <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li>
    142  1.1.1.2.2.2  yamt       <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li>
    143  1.1.1.2.2.2  yamt       <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li>
    144  1.1.1.2.2.2  yamt       <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li>
    145  1.1.1.2.2.2  yamt       <li><a href="#XML_MemFree">XML_MemFree</a></li>
    146  1.1.1.2.2.2  yamt     </ul>
    147  1.1.1.2.2.2  yamt     </li>
    148  1.1.1.2.2.2  yamt   </ul>  
    149  1.1.1.2.2.2  yamt   </li>
    150  1.1.1.2.2.2  yamt </ul>
    151  1.1.1.2.2.2  yamt 
    152  1.1.1.2.2.2  yamt <hr />
    153  1.1.1.2.2.2  yamt <h2><a name="overview">Overview</a></h2>
    154  1.1.1.2.2.2  yamt 
    155  1.1.1.2.2.2  yamt <p>Expat is a stream-oriented parser. You register callback (or
    156  1.1.1.2.2.2  yamt handler) functions with the parser and then start feeding it the
    157  1.1.1.2.2.2  yamt document.  As the parser recognizes parts of the document, it will
    158  1.1.1.2.2.2  yamt call the appropriate handler for that part (if you've registered one.) 
    159  1.1.1.2.2.2  yamt The document is fed to the parser in pieces, so you can start parsing
    160  1.1.1.2.2.2  yamt before you have all the document. This also allows you to parse really
    161  1.1.1.2.2.2  yamt huge documents that won't fit into memory.</p>
    162  1.1.1.2.2.2  yamt 
    163  1.1.1.2.2.2  yamt <p>Expat can be intimidating due to the many kinds of handlers and
    164  1.1.1.2.2.2  yamt options you can set. But you only need to learn four functions in
    165  1.1.1.2.2.2  yamt order to do 90% of what you'll want to do with it:</p>
    166  1.1.1.2.2.2  yamt 
    167  1.1.1.2.2.2  yamt <dl>
    168  1.1.1.2.2.2  yamt 
    169  1.1.1.2.2.2  yamt <dt><code><a href= "#XML_ParserCreate"
    170  1.1.1.2.2.2  yamt              >XML_ParserCreate</a></code></dt>
    171  1.1.1.2.2.2  yamt   <dd>Create a new parser object.</dd>
    172  1.1.1.2.2.2  yamt 
    173  1.1.1.2.2.2  yamt <dt><code><a href= "#XML_SetElementHandler"
    174  1.1.1.2.2.2  yamt              >XML_SetElementHandler</a></code></dt>
    175  1.1.1.2.2.2  yamt   <dd>Set handlers for start and end tags.</dd>
    176  1.1.1.2.2.2  yamt 
    177  1.1.1.2.2.2  yamt <dt><code><a href= "#XML_SetCharacterDataHandler"
    178  1.1.1.2.2.2  yamt              >XML_SetCharacterDataHandler</a></code></dt>
    179  1.1.1.2.2.2  yamt   <dd>Set handler for text.</dd>
    180  1.1.1.2.2.2  yamt 
    181  1.1.1.2.2.2  yamt <dt><code><a href= "#XML_Parse"
    182  1.1.1.2.2.2  yamt              >XML_Parse</a></code></dt>
    183  1.1.1.2.2.2  yamt   <dd>Pass a buffer full of document to the parser</dd>
    184  1.1.1.2.2.2  yamt </dl>
    185  1.1.1.2.2.2  yamt 
    186  1.1.1.2.2.2  yamt <p>These functions and others are described in the <a
    187  1.1.1.2.2.2  yamt href="#reference">reference</a> part of this document. The reference
    188  1.1.1.2.2.2  yamt section also describes in detail the parameters passed to the
    189  1.1.1.2.2.2  yamt different types of handlers.</p>
    190  1.1.1.2.2.2  yamt 
    191  1.1.1.2.2.2  yamt <p>Let's look at a very simple example program that only uses 3 of the
    192  1.1.1.2.2.2  yamt above functions (it doesn't need to set a character handler.) The
    193  1.1.1.2.2.2  yamt program <a href="../examples/outline.c">outline.c</a> prints an
    194  1.1.1.2.2.2  yamt element outline, indenting child elements to distinguish them from the
    195  1.1.1.2.2.2  yamt parent element that contains them. The start handler does all the
    196  1.1.1.2.2.2  yamt work.  It prints two indenting spaces for every level of ancestor
    197  1.1.1.2.2.2  yamt elements, then it prints the element and attribute
    198  1.1.1.2.2.2  yamt information. Finally it increments the global <code>Depth</code>
    199  1.1.1.2.2.2  yamt variable.</p>
    200  1.1.1.2.2.2  yamt 
    201  1.1.1.2.2.2  yamt <pre class="eg">
    202  1.1.1.2.2.2  yamt int Depth;
    203  1.1.1.2.2.2  yamt 
    204  1.1.1.2.2.2  yamt void XMLCALL
    205  1.1.1.2.2.2  yamt start(void *data, const char *el, const char **attr) {
    206  1.1.1.2.2.2  yamt   int i;
    207  1.1.1.2.2.2  yamt 
    208  1.1.1.2.2.2  yamt   for (i = 0; i &lt; Depth; i++)
    209  1.1.1.2.2.2  yamt     printf("  ");
    210  1.1.1.2.2.2  yamt 
    211  1.1.1.2.2.2  yamt   printf("%s", el);
    212  1.1.1.2.2.2  yamt 
    213  1.1.1.2.2.2  yamt   for (i = 0; attr[i]; i += 2) {
    214  1.1.1.2.2.2  yamt     printf(" %s='%s'", attr[i], attr[i + 1]);
    215  1.1.1.2.2.2  yamt   }
    216  1.1.1.2.2.2  yamt 
    217  1.1.1.2.2.2  yamt   printf("\n");
    218  1.1.1.2.2.2  yamt   Depth++;
    219  1.1.1.2.2.2  yamt }  /* End of start handler */
    220  1.1.1.2.2.2  yamt </pre>
    221  1.1.1.2.2.2  yamt 
    222  1.1.1.2.2.2  yamt <p>The end tag simply does the bookkeeping work of decrementing
    223  1.1.1.2.2.2  yamt <code>Depth</code>.</p>
    224  1.1.1.2.2.2  yamt <pre class="eg">
    225  1.1.1.2.2.2  yamt void XMLCALL
    226  1.1.1.2.2.2  yamt end(void *data, const char *el) {
    227  1.1.1.2.2.2  yamt   Depth--;
    228  1.1.1.2.2.2  yamt }  /* End of end handler */
    229  1.1.1.2.2.2  yamt </pre>
    230  1.1.1.2.2.2  yamt 
    231  1.1.1.2.2.2  yamt <p>Note the <code>XMLCALL</code> annotation used for the callbacks.
    232  1.1.1.2.2.2  yamt This is used to ensure that the Expat and the callbacks are using the
    233  1.1.1.2.2.2  yamt same calling convention in case the compiler options used for Expat
    234  1.1.1.2.2.2  yamt itself and the client code are different.  Expat tries not to care
    235  1.1.1.2.2.2  yamt what the default calling convention is, though it may require that it
    236  1.1.1.2.2.2  yamt be compiled with a default convention of "cdecl" on some platforms.
    237  1.1.1.2.2.2  yamt For code which uses Expat, however, the calling convention is
    238  1.1.1.2.2.2  yamt specified by the <code>XMLCALL</code> annotation on most platforms;
    239  1.1.1.2.2.2  yamt callbacks should be defined using this annotation.</p>
    240  1.1.1.2.2.2  yamt 
    241  1.1.1.2.2.2  yamt <p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but
    242  1.1.1.2.2.2  yamt existing working Expat applications don't need to add it (since they
    243  1.1.1.2.2.2  yamt are already using the "cdecl" calling convention, or they wouldn't be
    244  1.1.1.2.2.2  yamt working).  The annotation is only needed if the default calling
    245  1.1.1.2.2.2  yamt convention may be something other than "cdecl".  To use the annotation
    246  1.1.1.2.2.2  yamt safely with older versions of Expat, you can conditionally define it
    247  1.1.1.2.2.2  yamt <em>after</em> including Expat's header file:</p>
    248  1.1.1.2.2.2  yamt 
    249  1.1.1.2.2.2  yamt <pre class="eg">
    250  1.1.1.2.2.2  yamt #include &lt;expat.h&gt;
    251  1.1.1.2.2.2  yamt 
    252  1.1.1.2.2.2  yamt #ifndef XMLCALL
    253  1.1.1.2.2.2  yamt #if defined(_MSC_EXTENSIONS) &amp;&amp; !defined(__BEOS__) &amp;&amp; !defined(__CYGWIN__)
    254  1.1.1.2.2.2  yamt #define XMLCALL __cdecl
    255  1.1.1.2.2.2  yamt #elif defined(__GNUC__)
    256  1.1.1.2.2.2  yamt #define XMLCALL __attribute__((cdecl))
    257  1.1.1.2.2.2  yamt #else
    258  1.1.1.2.2.2  yamt #define XMLCALL
    259  1.1.1.2.2.2  yamt #endif
    260  1.1.1.2.2.2  yamt #endif
    261  1.1.1.2.2.2  yamt </pre>
    262  1.1.1.2.2.2  yamt 
    263  1.1.1.2.2.2  yamt <p>After creating the parser, the main program just has the job of
    264  1.1.1.2.2.2  yamt shoveling the document to the parser so that it can do its work.</p>
    265  1.1.1.2.2.2  yamt 
    266  1.1.1.2.2.2  yamt <hr />
    267  1.1.1.2.2.2  yamt <h2><a name="building">Building and Installing Expat</a></h2>
    268  1.1.1.2.2.2  yamt 
    269  1.1.1.2.2.2  yamt <p>The Expat distribution comes as a compressed (with GNU gzip) tar
    270  1.1.1.2.2.2  yamt file.  You may download the latest version from <a href=
    271  1.1.1.2.2.2  yamt "http://sourceforge.net/projects/expat/" >Source Forge</a>.  After
    272  1.1.1.2.2.2  yamt unpacking this, cd into the directory. Then follow either the Win32
    273  1.1.1.2.2.2  yamt directions or Unix directions below.</p>
    274  1.1.1.2.2.2  yamt 
    275  1.1.1.2.2.2  yamt <h3>Building under Win32</h3>
    276  1.1.1.2.2.2  yamt 
    277  1.1.1.2.2.2  yamt <p>If you're using the GNU compiler under cygwin, follow the Unix
    278  1.1.1.2.2.2  yamt directions in the next section. Otherwise if you have Microsoft's
    279  1.1.1.2.2.2  yamt Developer Studio installed, then from Windows Explorer double-click on
    280  1.1.1.2.2.2  yamt "expat.dsp" in the lib directory and build and install in the usual
    281  1.1.1.2.2.2  yamt manner.</p>
    282  1.1.1.2.2.2  yamt 
    283  1.1.1.2.2.2  yamt <p>Alternatively, you may download the Win32 binary package that
    284  1.1.1.2.2.2  yamt contains the "expat.h" include file and a pre-built DLL.</p>
    285  1.1.1.2.2.2  yamt 
    286  1.1.1.2.2.2  yamt <h3>Building under Unix (or GNU)</h3>
    287  1.1.1.2.2.2  yamt 
    288  1.1.1.2.2.2  yamt <p>First you'll need to run the configure shell script in order to
    289  1.1.1.2.2.2  yamt configure the Makefiles and headers for your system.</p>
    290  1.1.1.2.2.2  yamt 
    291  1.1.1.2.2.2  yamt <p>If you're happy with all the defaults that configure picks for you,
    292  1.1.1.2.2.2  yamt and you have permission on your system to install into /usr/local, you
    293  1.1.1.2.2.2  yamt can install Expat with this sequence of commands:</p>
    294  1.1.1.2.2.2  yamt 
    295  1.1.1.2.2.2  yamt <pre class="eg">
    296  1.1.1.2.2.2  yamt ./configure
    297  1.1.1.2.2.2  yamt make
    298  1.1.1.2.2.2  yamt make install
    299  1.1.1.2.2.2  yamt </pre>
    300  1.1.1.2.2.2  yamt 
    301  1.1.1.2.2.2  yamt <p>There are some options that you can provide to this script, but the
    302  1.1.1.2.2.2  yamt only one we'll mention here is the <code>--prefix</code> option. You
    303  1.1.1.2.2.2  yamt can find out all the options available by running configure with just
    304  1.1.1.2.2.2  yamt the <code>--help</code> option.</p>
    305  1.1.1.2.2.2  yamt 
    306  1.1.1.2.2.2  yamt <p>By default, the configure script sets things up so that the library
    307  1.1.1.2.2.2  yamt gets installed in <code>/usr/local/lib</code> and the associated
    308  1.1.1.2.2.2  yamt header file in <code>/usr/local/include</code>.  But if you were to
    309  1.1.1.2.2.2  yamt give the option, <code>--prefix=/home/me/mystuff</code>, then the
    310  1.1.1.2.2.2  yamt library and header would get installed in
    311  1.1.1.2.2.2  yamt <code>/home/me/mystuff/lib</code> and
    312  1.1.1.2.2.2  yamt <code>/home/me/mystuff/include</code> respectively.</p>
    313  1.1.1.2.2.2  yamt 
    314  1.1.1.2.2.2  yamt <h3>Configuring Expat Using the Pre-Processor</h3>
    315  1.1.1.2.2.2  yamt 
    316  1.1.1.2.2.2  yamt <p>Expat's feature set can be configured using a small number of
    317  1.1.1.2.2.2  yamt pre-processor definitions.  The definition of this symbols does not
    318  1.1.1.2.2.2  yamt affect the set of entry points for Expat, only the behavior of the API
    319  1.1.1.2.2.2  yamt and the definition of character types in the case of
    320  1.1.1.2.2.2  yamt <code>XML_UNICODE_WCHAR_T</code>.  The symbols are:</p>
    321  1.1.1.2.2.2  yamt 
    322  1.1.1.2.2.2  yamt <dl class="cpp-symbols">
    323  1.1.1.2.2.2  yamt <dt>XML_DTD</dt>
    324  1.1.1.2.2.2  yamt <dd>Include support for using and reporting DTD-based content.  If
    325  1.1.1.2.2.2  yamt this is defined, default attribute values from an external DTD subset
    326  1.1.1.2.2.2  yamt are reported and attribute value normalization occurs based on the
    327  1.1.1.2.2.2  yamt type of attributes defined in the external subset.  Without
    328  1.1.1.2.2.2  yamt this, Expat has a smaller memory footprint and can be faster, but will
    329  1.1.1.2.2.2  yamt not load external entities or process conditional sections.  This does
    330  1.1.1.2.2.2  yamt not affect the set of functions available in the API.</dd>
    331  1.1.1.2.2.2  yamt 
    332  1.1.1.2.2.2  yamt <dt>XML_NS</dt>
    333  1.1.1.2.2.2  yamt <dd>When defined, support for the <cite><a href=
    334  1.1.1.2.2.2  yamt "http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite>
    335  1.1.1.2.2.2  yamt specification is included.</dd>
    336  1.1.1.2.2.2  yamt 
    337  1.1.1.2.2.2  yamt <dt>XML_UNICODE</dt>
    338  1.1.1.2.2.2  yamt <dd>When defined, character data reported to the application is
    339  1.1.1.2.2.2  yamt encoded in UTF-16 using wide characters of the type
    340  1.1.1.2.2.2  yamt <code>XML_Char</code>.  This is implied if
    341  1.1.1.2.2.2  yamt <code>XML_UNICODE_WCHAR_T</code> is defined.</dd>
    342  1.1.1.2.2.2  yamt 
    343  1.1.1.2.2.2  yamt <dt>XML_UNICODE_WCHAR_T</dt>
    344  1.1.1.2.2.2  yamt <dd>If defined, causes the <code>XML_Char</code> character type to be
    345  1.1.1.2.2.2  yamt defined using the <code>wchar_t</code> type; otherwise, <code>unsigned
    346  1.1.1.2.2.2  yamt short</code> is used.  Defining this implies
    347  1.1.1.2.2.2  yamt <code>XML_UNICODE</code>.</dd>
    348  1.1.1.2.2.2  yamt 
    349  1.1.1.2.2.2  yamt <dt>XML_LARGE_SIZE</dt>
    350  1.1.1.2.2.2  yamt <dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code>
    351  1.1.1.2.2.2  yamt integer types to be at least 64 bits in size. This is intended to support
    352  1.1.1.2.2.2  yamt processing of very large input streams, where the return values of
    353  1.1.1.2.2.2  yamt <code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>,
    354  1.1.1.2.2.2  yamt <code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and
    355  1.1.1.2.2.2  yamt <code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>
    356  1.1.1.2.2.2  yamt could overflow. It may not be supported by all compilers, and is turned
    357  1.1.1.2.2.2  yamt off by default.</dd>
    358  1.1.1.2.2.2  yamt 
    359  1.1.1.2.2.2  yamt <dt>XML_CONTEXT_BYTES</dt>
    360  1.1.1.2.2.2  yamt <dd>The number of input bytes of markup context which the parser will
    361  1.1.1.2.2.2  yamt ensure are available for reporting via <code><a href=
    362  1.1.1.2.2.2  yamt "#XML_GetInputContext" >XML_GetInputContext</a></code>.  This is
    363  1.1.1.2.2.2  yamt normally set to 1024, and must be set to a positive interger.  If this
    364  1.1.1.2.2.2  yamt is not defined, the input context will not be available and <code><a
    365  1.1.1.2.2.2  yamt href= "#XML_GetInputContext" >XML_GetInputContext</a></code> will
    366  1.1.1.2.2.2  yamt always report NULL.  Without this, Expat has a smaller memory
    367  1.1.1.2.2.2  yamt footprint and can be faster.</dd>
    368  1.1.1.2.2.2  yamt 
    369  1.1.1.2.2.2  yamt <dt>XML_STATIC</dt>
    370  1.1.1.2.2.2  yamt <dd>On Windows, this should be set if Expat is going to be linked
    371  1.1.1.2.2.2  yamt statically with the code that calls it; this is required to get all
    372  1.1.1.2.2.2  yamt the right MSVC magic annotations correct.  This is ignored on other
    373  1.1.1.2.2.2  yamt platforms.</dd>
    374  1.1.1.2.2.2  yamt 
    375  1.1.1.2.2.2  yamt <dt>XML_ATTR_INFO</dt>
    376  1.1.1.2.2.2  yamt <dd>If defined, makes the the additional function <code><a href=
    377  1.1.1.2.2.2  yamt "#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available
    378  1.1.1.2.2.2  yamt for reporting attribute byte offsets.</dd>
    379  1.1.1.2.2.2  yamt </dl>
    380  1.1.1.2.2.2  yamt 
    381  1.1.1.2.2.2  yamt <hr />
    382  1.1.1.2.2.2  yamt <h2><a name="using">Using Expat</a></h2>
    383  1.1.1.2.2.2  yamt 
    384  1.1.1.2.2.2  yamt <h3>Compiling and Linking Against Expat</h3>
    385  1.1.1.2.2.2  yamt 
    386  1.1.1.2.2.2  yamt <p>Unless you installed Expat in a location not expected by your
    387  1.1.1.2.2.2  yamt compiler and linker, all you have to do to use Expat in your programs
    388  1.1.1.2.2.2  yamt is to include the Expat header (<code>#include &lt;expat.h&gt;</code>)
    389  1.1.1.2.2.2  yamt in your files that make calls to it and to tell the linker that it
    390  1.1.1.2.2.2  yamt needs to link against the Expat library.  On Unix systems, this would
    391  1.1.1.2.2.2  yamt usually be done with the <code>-lexpat</code> argument.  Otherwise,
    392  1.1.1.2.2.2  yamt you'll need to tell the compiler where to look for the Expat header
    393  1.1.1.2.2.2  yamt and the linker where to find the Expat library.  You may also need to
    394  1.1.1.2.2.2  yamt take steps to tell the operating system where to find this library at
    395  1.1.1.2.2.2  yamt run time.</p>
    396  1.1.1.2.2.2  yamt 
    397  1.1.1.2.2.2  yamt <p>On a Unix-based system, here's what a Makefile might look like when
    398  1.1.1.2.2.2  yamt Expat is installed in a standard location:</p>
    399  1.1.1.2.2.2  yamt 
    400  1.1.1.2.2.2  yamt <pre class="eg">
    401  1.1.1.2.2.2  yamt CC=cc
    402  1.1.1.2.2.2  yamt LDFLAGS=
    403  1.1.1.2.2.2  yamt LIBS= -lexpat
    404  1.1.1.2.2.2  yamt xmlapp: xmlapp.o
    405  1.1.1.2.2.2  yamt         $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
    406  1.1.1.2.2.2  yamt </pre>
    407  1.1.1.2.2.2  yamt 
    408  1.1.1.2.2.2  yamt <p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then
    409  1.1.1.2.2.2  yamt the Makefile would look like this:</p>
    410  1.1.1.2.2.2  yamt 
    411  1.1.1.2.2.2  yamt <pre class="eg">
    412  1.1.1.2.2.2  yamt CC=cc
    413  1.1.1.2.2.2  yamt CFLAGS= -I/home/me/mystuff/include
    414  1.1.1.2.2.2  yamt LDFLAGS=
    415  1.1.1.2.2.2  yamt LIBS= -L/home/me/mystuff/lib -lexpat
    416  1.1.1.2.2.2  yamt xmlapp: xmlapp.o
    417  1.1.1.2.2.2  yamt         $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
    418  1.1.1.2.2.2  yamt </pre>
    419  1.1.1.2.2.2  yamt 
    420  1.1.1.2.2.2  yamt <p>You'd also have to set the environment variable
    421  1.1.1.2.2.2  yamt <code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or
    422  1.1.1.2.2.2  yamt to <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if
    423  1.1.1.2.2.2  yamt LD_LIBRARY_PATH already has some directories in it) in order to run
    424  1.1.1.2.2.2  yamt your application.</p>
    425  1.1.1.2.2.2  yamt 
    426  1.1.1.2.2.2  yamt <h3>Expat Basics</h3>
    427  1.1.1.2.2.2  yamt 
    428  1.1.1.2.2.2  yamt <p>As we saw in the example in the overview, the first step in parsing
    429  1.1.1.2.2.2  yamt an XML document with Expat is to create a parser object. There are <a
    430  1.1.1.2.2.2  yamt href="#creation">three functions</a> in the Expat API for creating a
    431  1.1.1.2.2.2  yamt parser object.  However, only two of these (<code><a href=
    432  1.1.1.2.2.2  yamt "#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href=
    433  1.1.1.2.2.2  yamt "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for
    434  1.1.1.2.2.2  yamt constructing a parser for a top-level document.  The object returned
    435  1.1.1.2.2.2  yamt by these functions is an opaque pointer (i.e. "expat.h" declares it as
    436  1.1.1.2.2.2  yamt void *) to data with further internal structure. In order to free the
    437  1.1.1.2.2.2  yamt memory associated with this object you must call <code><a href=
    438  1.1.1.2.2.2  yamt "#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have
    439  1.1.1.2.2.2  yamt provided any <a href="#userdata">user data</a> that gets stored in the
    440  1.1.1.2.2.2  yamt parser, then your application is responsible for freeing it prior to
    441  1.1.1.2.2.2  yamt calling <code>XML_ParserFree</code>.</p>
    442  1.1.1.2.2.2  yamt 
    443  1.1.1.2.2.2  yamt <p>The objects returned by the parser creation functions are good for
    444  1.1.1.2.2.2  yamt parsing only one XML document or external parsed entity. If your
    445  1.1.1.2.2.2  yamt application needs to parse many XML documents, then it needs to create
    446  1.1.1.2.2.2  yamt a parser object for each one. The best way to deal with this is to
    447  1.1.1.2.2.2  yamt create a higher level object that contains all the default
    448  1.1.1.2.2.2  yamt initialization you want for your parser objects.</p>
    449  1.1.1.2.2.2  yamt 
    450  1.1.1.2.2.2  yamt <p>Walking through a document hierarchy with a stream oriented parser
    451  1.1.1.2.2.2  yamt will require a good stack mechanism in order to keep track of current
    452  1.1.1.2.2.2  yamt context.  For instance, to answer the simple question, "What element
    453  1.1.1.2.2.2  yamt does this text belong to?" requires a stack, since the parser may have
    454  1.1.1.2.2.2  yamt descended into other elements that are children of the current one and
    455  1.1.1.2.2.2  yamt has encountered this text on the way out.</p>
    456  1.1.1.2.2.2  yamt 
    457  1.1.1.2.2.2  yamt <p>The things you're likely to want to keep on a stack are the
    458  1.1.1.2.2.2  yamt currently opened element and it's attributes. You push this
    459  1.1.1.2.2.2  yamt information onto the stack in the start handler and you pop it off in
    460  1.1.1.2.2.2  yamt the end handler.</p>
    461  1.1.1.2.2.2  yamt 
    462  1.1.1.2.2.2  yamt <p>For some tasks, it is sufficient to just keep information on what
    463  1.1.1.2.2.2  yamt the depth of the stack is (or would be if you had one.) The outline
    464  1.1.1.2.2.2  yamt program shown above presents one example. Another such task would be
    465  1.1.1.2.2.2  yamt skipping over a complete element. When you see the start tag for the
    466  1.1.1.2.2.2  yamt element you want to skip, you set a skip flag and record the depth at
    467  1.1.1.2.2.2  yamt which the element started.  When the end tag handler encounters the
    468  1.1.1.2.2.2  yamt same depth, the skipped element has ended and the flag may be
    469  1.1.1.2.2.2  yamt cleared. If you follow the convention that the root element starts at
    470  1.1.1.2.2.2  yamt 1, then you can use the same variable for skip flag and skip
    471  1.1.1.2.2.2  yamt depth.</p>
    472  1.1.1.2.2.2  yamt 
    473  1.1.1.2.2.2  yamt <pre class="eg">
    474  1.1.1.2.2.2  yamt void
    475  1.1.1.2.2.2  yamt init_info(Parseinfo *info) {
    476  1.1.1.2.2.2  yamt   info->skip = 0;
    477  1.1.1.2.2.2  yamt   info->depth = 1;
    478  1.1.1.2.2.2  yamt   /* Other initializations here */
    479  1.1.1.2.2.2  yamt }  /* End of init_info */
    480  1.1.1.2.2.2  yamt 
    481  1.1.1.2.2.2  yamt void XMLCALL
    482  1.1.1.2.2.2  yamt rawstart(void *data, const char *el, const char **attr) {
    483  1.1.1.2.2.2  yamt   Parseinfo *inf = (Parseinfo *) data;
    484  1.1.1.2.2.2  yamt 
    485  1.1.1.2.2.2  yamt   if (! inf->skip) {
    486  1.1.1.2.2.2  yamt     if (should_skip(inf, el, attr)) {
    487  1.1.1.2.2.2  yamt       inf->skip = inf->depth;
    488  1.1.1.2.2.2  yamt     }
    489  1.1.1.2.2.2  yamt     else
    490  1.1.1.2.2.2  yamt       start(inf, el, attr);     /* This does rest of start handling */
    491  1.1.1.2.2.2  yamt   }
    492  1.1.1.2.2.2  yamt 
    493  1.1.1.2.2.2  yamt   inf->depth++;
    494  1.1.1.2.2.2  yamt }  /* End of rawstart */
    495  1.1.1.2.2.2  yamt 
    496  1.1.1.2.2.2  yamt void XMLCALL
    497  1.1.1.2.2.2  yamt rawend(void *data, const char *el) {
    498  1.1.1.2.2.2  yamt   Parseinfo *inf = (Parseinfo *) data;
    499  1.1.1.2.2.2  yamt 
    500  1.1.1.2.2.2  yamt   inf->depth--;
    501  1.1.1.2.2.2  yamt 
    502  1.1.1.2.2.2  yamt   if (! inf->skip)
    503  1.1.1.2.2.2  yamt     end(inf, el);              /* This does rest of end handling */
    504  1.1.1.2.2.2  yamt 
    505  1.1.1.2.2.2  yamt   if (inf->skip == inf->depth)
    506  1.1.1.2.2.2  yamt     inf->skip = 0;
    507  1.1.1.2.2.2  yamt }  /* End rawend */
    508  1.1.1.2.2.2  yamt </pre>
    509  1.1.1.2.2.2  yamt 
    510  1.1.1.2.2.2  yamt <p>Notice in the above example the difference in how depth is
    511  1.1.1.2.2.2  yamt manipulated in the start and end handlers. The end tag handler should
    512  1.1.1.2.2.2  yamt be the mirror image of the start tag handler. This is necessary to
    513  1.1.1.2.2.2  yamt properly model containment. Since, in the start tag handler, we
    514  1.1.1.2.2.2  yamt incremented depth <em>after</em> the main body of start tag code, then
    515  1.1.1.2.2.2  yamt in the end handler, we need to manipulate it <em>before</em> the main
    516  1.1.1.2.2.2  yamt body.  If we'd decided to increment it first thing in the start
    517  1.1.1.2.2.2  yamt handler, then we'd have had to decrement it last thing in the end
    518  1.1.1.2.2.2  yamt handler.</p>
    519  1.1.1.2.2.2  yamt 
    520  1.1.1.2.2.2  yamt <h3 id="userdata">Communicating between handlers</h3>
    521  1.1.1.2.2.2  yamt 
    522  1.1.1.2.2.2  yamt <p>In order to be able to pass information between different handlers
    523  1.1.1.2.2.2  yamt without using globals, you'll need to define a data structure to hold
    524  1.1.1.2.2.2  yamt the shared variables. You can then tell Expat (with the <code><a href=
    525  1.1.1.2.2.2  yamt "#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a
    526  1.1.1.2.2.2  yamt pointer to this structure to the handlers.  This is the first
    527  1.1.1.2.2.2  yamt argument received by most handlers.  In the <a href="#reference"
    528  1.1.1.2.2.2  yamt >reference section</a>, an argument to a callback function is named
    529  1.1.1.2.2.2  yamt <code>userData</code> and have type <code>void *</code> if the user
    530  1.1.1.2.2.2  yamt data is passed; it will have the type <code>XML_Parser</code> if the
    531  1.1.1.2.2.2  yamt parser itself is passed.  When the parser is passed, the user data may
    532  1.1.1.2.2.2  yamt be retrieved using <code><a href="#XML_GetUserData"
    533  1.1.1.2.2.2  yamt >XML_GetUserData</a></code>.</p>
    534  1.1.1.2.2.2  yamt 
    535  1.1.1.2.2.2  yamt <p>One common case where multiple calls to a single handler may need
    536  1.1.1.2.2.2  yamt to communicate using an application data structure is the case when
    537  1.1.1.2.2.2  yamt content passed to the character data handler (set by <code><a href=
    538  1.1.1.2.2.2  yamt "#XML_SetCharacterDataHandler"
    539  1.1.1.2.2.2  yamt >XML_SetCharacterDataHandler</a></code>) needs to be accumulated.  A
    540  1.1.1.2.2.2  yamt common first-time mistake with any of the event-oriented interfaces to
    541  1.1.1.2.2.2  yamt an XML parser is to expect all the text contained in an element to be
    542  1.1.1.2.2.2  yamt reported by a single call to the character data handler.  Expat, like
    543  1.1.1.2.2.2  yamt many other XML parsers, reports such data as a sequence of calls;
    544  1.1.1.2.2.2  yamt there's no way to know when the end of the sequence is reached until a
    545  1.1.1.2.2.2  yamt different callback is made.  A buffer referenced by the user data
    546  1.1.1.2.2.2  yamt structure proves both an effective and convenient place to accumulate
    547  1.1.1.2.2.2  yamt character data.</p>
    548  1.1.1.2.2.2  yamt 
    549  1.1.1.2.2.2  yamt <!-- XXX example needed here -->
    550  1.1.1.2.2.2  yamt 
    551  1.1.1.2.2.2  yamt 
    552  1.1.1.2.2.2  yamt <h3>XML Version</h3>
    553  1.1.1.2.2.2  yamt 
    554  1.1.1.2.2.2  yamt <p>Expat is an XML 1.0 parser, and as such never complains based on
    555  1.1.1.2.2.2  yamt the value of the <code>version</code> pseudo-attribute in the XML
    556  1.1.1.2.2.2  yamt declaration, if present.</p>
    557  1.1.1.2.2.2  yamt 
    558  1.1.1.2.2.2  yamt <p>If an application needs to check the version number (to support
    559  1.1.1.2.2.2  yamt alternate processing), it should use the <code><a href=
    560  1.1.1.2.2.2  yamt "#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to
    561  1.1.1.2.2.2  yamt set a handler that uses the information in the XML declaration to
    562  1.1.1.2.2.2  yamt determine what to do.  This example shows how to check that only a
    563  1.1.1.2.2.2  yamt version number of <code>"1.0"</code> is accepted:</p>
    564  1.1.1.2.2.2  yamt 
    565  1.1.1.2.2.2  yamt <pre class="eg">
    566  1.1.1.2.2.2  yamt static int wrong_version;
    567  1.1.1.2.2.2  yamt static XML_Parser parser;
    568  1.1.1.2.2.2  yamt 
    569  1.1.1.2.2.2  yamt static void XMLCALL
    570  1.1.1.2.2.2  yamt xmldecl_handler(void            *userData,
    571  1.1.1.2.2.2  yamt                 const XML_Char  *version,
    572  1.1.1.2.2.2  yamt                 const XML_Char  *encoding,
    573  1.1.1.2.2.2  yamt                 int              standalone)
    574  1.1.1.2.2.2  yamt {
    575  1.1.1.2.2.2  yamt   static const XML_Char Version_1_0[] = {'1', '.', '0', 0};
    576  1.1.1.2.2.2  yamt 
    577  1.1.1.2.2.2  yamt   int i;
    578  1.1.1.2.2.2  yamt 
    579  1.1.1.2.2.2  yamt   for (i = 0; i &lt; (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) {
    580  1.1.1.2.2.2  yamt     if (version[i] != Version_1_0[i]) {
    581  1.1.1.2.2.2  yamt       wrong_version = 1;
    582  1.1.1.2.2.2  yamt       /* also clear all other handlers: */
    583  1.1.1.2.2.2  yamt       XML_SetCharacterDataHandler(parser, NULL);
    584  1.1.1.2.2.2  yamt       ...
    585  1.1.1.2.2.2  yamt       return;
    586  1.1.1.2.2.2  yamt     }
    587  1.1.1.2.2.2  yamt   }
    588  1.1.1.2.2.2  yamt   ...
    589  1.1.1.2.2.2  yamt }
    590  1.1.1.2.2.2  yamt </pre>
    591  1.1.1.2.2.2  yamt 
    592  1.1.1.2.2.2  yamt <h3>Namespace Processing</h3>
    593  1.1.1.2.2.2  yamt 
    594  1.1.1.2.2.2  yamt <p>When the parser is created using the <code><a href=
    595  1.1.1.2.2.2  yamt "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat
    596  1.1.1.2.2.2  yamt performs namespace processing. Under namespace processing, Expat
    597  1.1.1.2.2.2  yamt consumes <code>xmlns</code> and <code>xmlns:...</code> attributes,
    598  1.1.1.2.2.2  yamt which declare namespaces for the scope of the element in which they
    599  1.1.1.2.2.2  yamt occur. This means that your start handler will not see these
    600  1.1.1.2.2.2  yamt attributes.  Your application can still be informed of these
    601  1.1.1.2.2.2  yamt declarations by setting namespace declaration handlers with <a href=
    602  1.1.1.2.2.2  yamt "#XML_SetNamespaceDeclHandler"
    603  1.1.1.2.2.2  yamt ><code>XML_SetNamespaceDeclHandler</code></a>.</p>
    604  1.1.1.2.2.2  yamt 
    605  1.1.1.2.2.2  yamt <p>Element type and attribute names that belong to a given namespace
    606  1.1.1.2.2.2  yamt are passed to the appropriate handler in expanded form. By default
    607  1.1.1.2.2.2  yamt this expanded form is a concatenation of the namespace URI, the
    608  1.1.1.2.2.2  yamt separator character (which is the 2nd argument to <code><a href=
    609  1.1.1.2.2.2  yamt "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local
    610  1.1.1.2.2.2  yamt name (i.e. the part after the colon). Names with undeclared prefixes
    611  1.1.1.2.2.2  yamt are not well-formed when namespace processing is enabled, and will
    612  1.1.1.2.2.2  yamt trigger an error. Unprefixed attribute names are never expanded,
    613  1.1.1.2.2.2  yamt and unprefixed element names are only expanded when they are in the
    614  1.1.1.2.2.2  yamt scope of a default namespace.</p>
    615  1.1.1.2.2.2  yamt 
    616  1.1.1.2.2.2  yamt <p>However if <code><a href= "#XML_SetReturnNSTriplet"
    617  1.1.1.2.2.2  yamt >XML_SetReturnNSTriplet</a></code> has been called with a non-zero
    618  1.1.1.2.2.2  yamt <code>do_nst</code> parameter, then the expanded form for names with
    619  1.1.1.2.2.2  yamt an explicit prefix is a concatenation of: URI, separator, local name,
    620  1.1.1.2.2.2  yamt separator, prefix.</p>
    621  1.1.1.2.2.2  yamt 
    622  1.1.1.2.2.2  yamt <p>You can set handlers for the start of a namespace declaration and
    623  1.1.1.2.2.2  yamt for the end of a scope of a declaration with the <code><a href=
    624  1.1.1.2.2.2  yamt "#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code>
    625  1.1.1.2.2.2  yamt function.  The StartNamespaceDeclHandler is called prior to the start
    626  1.1.1.2.2.2  yamt tag handler and the EndNamespaceDeclHandler is called after the
    627  1.1.1.2.2.2  yamt corresponding end tag that ends the namespace's scope.  The namespace
    628  1.1.1.2.2.2  yamt start handler gets passed the prefix and URI for the namespace.  For a
    629  1.1.1.2.2.2  yamt default namespace declaration (xmlns='...'), the prefix will be null.
    630  1.1.1.2.2.2  yamt The URI will be null for the case where the default namespace is being
    631  1.1.1.2.2.2  yamt unset.  The namespace end handler just gets the prefix for the closing
    632  1.1.1.2.2.2  yamt scope.</p>
    633  1.1.1.2.2.2  yamt 
    634  1.1.1.2.2.2  yamt <p>These handlers are called for each declaration. So if, for
    635  1.1.1.2.2.2  yamt instance, a start tag had three namespace declarations, then the
    636  1.1.1.2.2.2  yamt StartNamespaceDeclHandler would be called three times before the start
    637  1.1.1.2.2.2  yamt tag handler is called, once for each declaration.</p>
    638  1.1.1.2.2.2  yamt 
    639  1.1.1.2.2.2  yamt <h3>Character Encodings</h3>
    640  1.1.1.2.2.2  yamt 
    641  1.1.1.2.2.2  yamt <p>While XML is based on Unicode, and every XML processor is required
    642  1.1.1.2.2.2  yamt to recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode),
    643  1.1.1.2.2.2  yamt other encodings may be declared in XML documents or entities. For the
    644  1.1.1.2.2.2  yamt main document, an XML declaration may contain an encoding
    645  1.1.1.2.2.2  yamt declaration:</p>
    646  1.1.1.2.2.2  yamt <pre>
    647  1.1.1.2.2.2  yamt &lt;?xml version="1.0" encoding="ISO-8859-2"?&gt;
    648  1.1.1.2.2.2  yamt </pre>
    649  1.1.1.2.2.2  yamt 
    650  1.1.1.2.2.2  yamt <p>External parsed entities may begin with a text declaration, which
    651  1.1.1.2.2.2  yamt looks like an XML declaration with just an encoding declaration:</p>
    652  1.1.1.2.2.2  yamt <pre>
    653  1.1.1.2.2.2  yamt &lt;?xml encoding="Big5"?&gt;
    654  1.1.1.2.2.2  yamt </pre>
    655  1.1.1.2.2.2  yamt 
    656  1.1.1.2.2.2  yamt <p>With Expat, you may also specify an encoding at the time of
    657  1.1.1.2.2.2  yamt creating a parser. This is useful when the encoding information may
    658  1.1.1.2.2.2  yamt come from a source outside the document itself (like a higher level
    659  1.1.1.2.2.2  yamt protocol.)</p>
    660  1.1.1.2.2.2  yamt 
    661  1.1.1.2.2.2  yamt <p><a name="builtin_encodings"></a>There are four built-in encodings
    662  1.1.1.2.2.2  yamt in Expat:</p>
    663  1.1.1.2.2.2  yamt <ul>
    664  1.1.1.2.2.2  yamt <li>UTF-8</li>
    665  1.1.1.2.2.2  yamt <li>UTF-16</li>
    666  1.1.1.2.2.2  yamt <li>ISO-8859-1</li>
    667  1.1.1.2.2.2  yamt <li>US-ASCII</li>
    668  1.1.1.2.2.2  yamt </ul>
    669  1.1.1.2.2.2  yamt 
    670  1.1.1.2.2.2  yamt <p>Anything else discovered in an encoding declaration or in the
    671  1.1.1.2.2.2  yamt protocol encoding specified in the parser constructor, triggers a call
    672  1.1.1.2.2.2  yamt to the <code>UnknownEncodingHandler</code>. This handler gets passed
    673  1.1.1.2.2.2  yamt the encoding name and a pointer to an <code>XML_Encoding</code> data
    674  1.1.1.2.2.2  yamt structure. Your handler must fill in this structure and return
    675  1.1.1.2.2.2  yamt <code>XML_STATUS_OK</code> if it knows how to deal with the
    676  1.1.1.2.2.2  yamt encoding. Otherwise the handler should return
    677  1.1.1.2.2.2  yamt <code>XML_STATUS_ERROR</code>.  The handler also gets passed a pointer
    678  1.1.1.2.2.2  yamt to an optional application data structure that you may indicate when
    679  1.1.1.2.2.2  yamt you set the handler.</p>
    680  1.1.1.2.2.2  yamt 
    681  1.1.1.2.2.2  yamt <p>Expat places restrictions on character encodings that it can
    682  1.1.1.2.2.2  yamt support by filling in the <code>XML_Encoding</code> structure.
    683  1.1.1.2.2.2  yamt include file:</p>
    684  1.1.1.2.2.2  yamt <ol>
    685  1.1.1.2.2.2  yamt <li>Every ASCII character that can appear in a well-formed XML document
    686  1.1.1.2.2.2  yamt must be represented by a single byte, and that byte must correspond to
    687  1.1.1.2.2.2  yamt it's ASCII encoding (except for the characters $@\^'{}~)</li>
    688  1.1.1.2.2.2  yamt <li>Characters must be encoded in 4 bytes or less.</li>
    689  1.1.1.2.2.2  yamt <li>All characters encoded must have Unicode scalar values less than or
    690  1.1.1.2.2.2  yamt equal to 65535 (0xFFFF)<em>This does not apply to the built-in support
    691  1.1.1.2.2.2  yamt for UTF-16 and UTF-8</em></li>
    692  1.1.1.2.2.2  yamt <li>No character may be encoded by more that one distinct sequence of
    693  1.1.1.2.2.2  yamt bytes</li>
    694  1.1.1.2.2.2  yamt </ol>
    695  1.1.1.2.2.2  yamt 
    696  1.1.1.2.2.2  yamt <p><code>XML_Encoding</code> contains an array of integers that
    697  1.1.1.2.2.2  yamt correspond to the 1st byte of an encoding sequence. If the value in
    698  1.1.1.2.2.2  yamt the array for a byte is zero or positive, then the byte is a single
    699  1.1.1.2.2.2  yamt byte encoding that encodes the Unicode scalar value contained in the
    700  1.1.1.2.2.2  yamt array. A -1 in this array indicates a malformed byte. If the value is
    701  1.1.1.2.2.2  yamt -2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte
    702  1.1.1.2.2.2  yamt sequence respectively. Multi-byte sequences are sent to the convert
    703  1.1.1.2.2.2  yamt function pointed at in the <code>XML_Encoding</code> structure. This
    704  1.1.1.2.2.2  yamt function should return the Unicode scalar value for the sequence or -1
    705  1.1.1.2.2.2  yamt if the sequence is malformed.</p>
    706  1.1.1.2.2.2  yamt 
    707  1.1.1.2.2.2  yamt <p>One pitfall that novice Expat users are likely to fall into is that
    708  1.1.1.2.2.2  yamt although Expat may accept input in various encodings, the strings that
    709  1.1.1.2.2.2  yamt it passes to the handlers are always encoded in UTF-8 or UTF-16
    710  1.1.1.2.2.2  yamt (depending on how Expat was compiled). Your application is responsible
    711  1.1.1.2.2.2  yamt for any translation of these strings into other encodings.</p>
    712  1.1.1.2.2.2  yamt 
    713  1.1.1.2.2.2  yamt <h3>Handling External Entity References</h3>
    714  1.1.1.2.2.2  yamt 
    715  1.1.1.2.2.2  yamt <p>Expat does not read or parse external entities directly. Note that
    716  1.1.1.2.2.2  yamt any external DTD is a special case of an external entity.  If you've
    717  1.1.1.2.2.2  yamt set no <code>ExternalEntityRefHandler</code>, then external entity
    718  1.1.1.2.2.2  yamt references are silently ignored. Otherwise, it calls your handler with
    719  1.1.1.2.2.2  yamt the information needed to read and parse the external entity.</p>
    720  1.1.1.2.2.2  yamt 
    721  1.1.1.2.2.2  yamt <p>Your handler isn't actually responsible for parsing the entity, but
    722  1.1.1.2.2.2  yamt it is responsible for creating a subsidiary parser with <code><a href=
    723  1.1.1.2.2.2  yamt "#XML_ExternalEntityParserCreate"
    724  1.1.1.2.2.2  yamt >XML_ExternalEntityParserCreate</a></code> that will do the job. This
    725  1.1.1.2.2.2  yamt returns an instance of <code>XML_Parser</code> that has handlers and
    726  1.1.1.2.2.2  yamt other data structures initialized from the parent parser. You may then
    727  1.1.1.2.2.2  yamt use <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a
    728  1.1.1.2.2.2  yamt href= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this
    729  1.1.1.2.2.2  yamt parser.  Since external entities my refer to other external entities,
    730  1.1.1.2.2.2  yamt your handler should be prepared to be called recursively.</p>
    731  1.1.1.2.2.2  yamt 
    732  1.1.1.2.2.2  yamt <h3>Parsing DTDs</h3>
    733  1.1.1.2.2.2  yamt 
    734  1.1.1.2.2.2  yamt <p>In order to parse parameter entities, before starting the parse,
    735  1.1.1.2.2.2  yamt you must call <code><a href= "#XML_SetParamEntityParsing"
    736  1.1.1.2.2.2  yamt >XML_SetParamEntityParsing</a></code> with one of the following
    737  1.1.1.2.2.2  yamt arguments:</p>
    738  1.1.1.2.2.2  yamt <dl>
    739  1.1.1.2.2.2  yamt <dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt>
    740  1.1.1.2.2.2  yamt <dd>Don't parse parameter entities or the external subset</dd>
    741  1.1.1.2.2.2  yamt <dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt>
    742  1.1.1.2.2.2  yamt <dd>Parse parameter entites and the external subset unless
    743  1.1.1.2.2.2  yamt <code>standalone</code> was set to "yes" in the XML declaration.</dd>
    744  1.1.1.2.2.2  yamt <dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt>
    745  1.1.1.2.2.2  yamt <dd>Always parse parameter entities and the external subset</dd>
    746  1.1.1.2.2.2  yamt </dl>
    747  1.1.1.2.2.2  yamt 
    748  1.1.1.2.2.2  yamt <p>In order to read an external DTD, you also have to set an external
    749  1.1.1.2.2.2  yamt entity reference handler as described above.</p>
    750  1.1.1.2.2.2  yamt 
    751  1.1.1.2.2.2  yamt <h3 id="stop-resume">Temporarily Stopping Parsing</h3>
    752  1.1.1.2.2.2  yamt 
    753  1.1.1.2.2.2  yamt <p>Expat 1.95.8 introduces a new feature: its now possible to stop
    754  1.1.1.2.2.2  yamt parsing temporarily from within a handler function, even if more data
    755  1.1.1.2.2.2  yamt has already been passed into the parser.  Applications for this
    756  1.1.1.2.2.2  yamt include</p>
    757  1.1.1.2.2.2  yamt 
    758  1.1.1.2.2.2  yamt <ul>
    759  1.1.1.2.2.2  yamt   <li>Supporting the <a href= "http://www.w3.org/TR/xinclude/"
    760  1.1.1.2.2.2  yamt   >XInclude</a> specification.</li>
    761  1.1.1.2.2.2  yamt 
    762  1.1.1.2.2.2  yamt   <li>Delaying further processing until additional information is
    763  1.1.1.2.2.2  yamt   available from some other source.</li>
    764  1.1.1.2.2.2  yamt 
    765  1.1.1.2.2.2  yamt   <li>Adjusting processor load as task priorities shift within an
    766  1.1.1.2.2.2  yamt   application.</li>
    767  1.1.1.2.2.2  yamt 
    768  1.1.1.2.2.2  yamt   <li>Stopping parsing completely (simply free or reset the parser
    769  1.1.1.2.2.2  yamt   instead of resuming in the outer parsing loop).  This can be useful
    770  1.1.1.2.2.2  yamt   if a application-domain error is found in the XML being parsed or if
    771  1.1.1.2.2.2  yamt   the result of the parse is determined not to be useful after
    772  1.1.1.2.2.2  yamt   all.</li>
    773  1.1.1.2.2.2  yamt </ul>
    774  1.1.1.2.2.2  yamt 
    775  1.1.1.2.2.2  yamt <p>To take advantage of this feature, the main parsing loop of an
    776  1.1.1.2.2.2  yamt application needs to support this specifically.  It cannot be
    777  1.1.1.2.2.2  yamt supported with a parsing loop compatible with Expat 1.95.7 or
    778  1.1.1.2.2.2  yamt earlier (though existing loops will continue to work without
    779  1.1.1.2.2.2  yamt supporting the stop/resume feature).</p>
    780  1.1.1.2.2.2  yamt 
    781  1.1.1.2.2.2  yamt <p>An application that uses this feature for a single parser will have
    782  1.1.1.2.2.2  yamt the rough structure (in pseudo-code):</p>
    783  1.1.1.2.2.2  yamt 
    784  1.1.1.2.2.2  yamt <pre class="pseudocode">
    785  1.1.1.2.2.2  yamt fd = open_input()
    786  1.1.1.2.2.2  yamt p = create_parser()
    787  1.1.1.2.2.2  yamt 
    788  1.1.1.2.2.2  yamt if parse_xml(p, fd) {
    789  1.1.1.2.2.2  yamt   /* suspended */
    790  1.1.1.2.2.2  yamt 
    791  1.1.1.2.2.2  yamt   int suspended = 1;
    792  1.1.1.2.2.2  yamt 
    793  1.1.1.2.2.2  yamt   while (suspended) {
    794  1.1.1.2.2.2  yamt     do_something_else()
    795  1.1.1.2.2.2  yamt     if ready_to_resume() {
    796  1.1.1.2.2.2  yamt       suspended = continue_parsing(p, fd);
    797  1.1.1.2.2.2  yamt     }
    798  1.1.1.2.2.2  yamt   }
    799  1.1.1.2.2.2  yamt }
    800  1.1.1.2.2.2  yamt </pre>
    801  1.1.1.2.2.2  yamt 
    802  1.1.1.2.2.2  yamt <p>An application that may resume any of several parsers based on
    803  1.1.1.2.2.2  yamt input (either from the XML being parsed or some other source) will
    804  1.1.1.2.2.2  yamt certainly have more interesting control structures.</p>
    805  1.1.1.2.2.2  yamt 
    806  1.1.1.2.2.2  yamt <p>This C function could be used for the <code>parse_xml</code>
    807  1.1.1.2.2.2  yamt function mentioned in the pseudo-code above:</p>
    808  1.1.1.2.2.2  yamt 
    809  1.1.1.2.2.2  yamt <pre class="eg">
    810  1.1.1.2.2.2  yamt #define BUFF_SIZE 10240
    811  1.1.1.2.2.2  yamt 
    812  1.1.1.2.2.2  yamt /* Parse a document from the open file descriptor 'fd' until the parse
    813  1.1.1.2.2.2  yamt    is complete (the document has been completely parsed, or there's
    814  1.1.1.2.2.2  yamt    been an error), or the parse is stopped.  Return non-zero when
    815  1.1.1.2.2.2  yamt    the parse is merely suspended.
    816  1.1.1.2.2.2  yamt */
    817  1.1.1.2.2.2  yamt int
    818  1.1.1.2.2.2  yamt parse_xml(XML_Parser p, int fd)
    819  1.1.1.2.2.2  yamt {
    820  1.1.1.2.2.2  yamt   for (;;) {
    821  1.1.1.2.2.2  yamt     int last_chunk;
    822  1.1.1.2.2.2  yamt     int bytes_read;
    823  1.1.1.2.2.2  yamt     enum XML_Status status;
    824  1.1.1.2.2.2  yamt 
    825  1.1.1.2.2.2  yamt     void *buff = XML_GetBuffer(p, BUFF_SIZE);
    826  1.1.1.2.2.2  yamt     if (buff == NULL) {
    827  1.1.1.2.2.2  yamt       /* handle error... */
    828  1.1.1.2.2.2  yamt       return 0;
    829  1.1.1.2.2.2  yamt     }
    830  1.1.1.2.2.2  yamt     bytes_read = read(fd, buff, BUFF_SIZE);
    831  1.1.1.2.2.2  yamt     if (bytes_read &lt; 0) {
    832  1.1.1.2.2.2  yamt       /* handle error... */
    833  1.1.1.2.2.2  yamt       return 0;
    834  1.1.1.2.2.2  yamt     }
    835  1.1.1.2.2.2  yamt     status = XML_ParseBuffer(p, bytes_read, bytes_read == 0);
    836  1.1.1.2.2.2  yamt     switch (status) {
    837  1.1.1.2.2.2  yamt       case XML_STATUS_ERROR:
    838  1.1.1.2.2.2  yamt         /* handle error... */
    839  1.1.1.2.2.2  yamt         return 0;
    840  1.1.1.2.2.2  yamt       case XML_STATUS_SUSPENDED:
    841  1.1.1.2.2.2  yamt         return 1;
    842  1.1.1.2.2.2  yamt     }
    843  1.1.1.2.2.2  yamt     if (bytes_read == 0)
    844  1.1.1.2.2.2  yamt       return 0;
    845  1.1.1.2.2.2  yamt   }
    846  1.1.1.2.2.2  yamt }
    847  1.1.1.2.2.2  yamt </pre>
    848  1.1.1.2.2.2  yamt 
    849  1.1.1.2.2.2  yamt <p>The corresponding <code>continue_parsing</code> function is
    850  1.1.1.2.2.2  yamt somewhat simpler, since it only need deal with the return code from
    851  1.1.1.2.2.2  yamt <code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can
    852  1.1.1.2.2.2  yamt delegate the input handling to the <code>parse_xml</code>
    853  1.1.1.2.2.2  yamt function:</p>
    854  1.1.1.2.2.2  yamt 
    855  1.1.1.2.2.2  yamt <pre class="eg">
    856  1.1.1.2.2.2  yamt /* Continue parsing a document which had been suspended.  The 'p' and
    857  1.1.1.2.2.2  yamt    'fd' arguments are the same as passed to parse_xml().  Return
    858  1.1.1.2.2.2  yamt    non-zero when the parse is suspended.
    859  1.1.1.2.2.2  yamt */
    860  1.1.1.2.2.2  yamt int
    861  1.1.1.2.2.2  yamt continue_parsing(XML_Parser p, int fd)
    862  1.1.1.2.2.2  yamt {
    863  1.1.1.2.2.2  yamt   enum XML_Status status = XML_ResumeParser(p);
    864  1.1.1.2.2.2  yamt   switch (status) {
    865  1.1.1.2.2.2  yamt     case XML_STATUS_ERROR:
    866  1.1.1.2.2.2  yamt       /* handle error... */
    867  1.1.1.2.2.2  yamt       return 0;
    868  1.1.1.2.2.2  yamt     case XML_ERROR_NOT_SUSPENDED:
    869  1.1.1.2.2.2  yamt       /* handle error... */
    870  1.1.1.2.2.2  yamt       return 0;.
    871  1.1.1.2.2.2  yamt     case XML_STATUS_SUSPENDED:
    872  1.1.1.2.2.2  yamt       return 1;
    873  1.1.1.2.2.2  yamt   }
    874  1.1.1.2.2.2  yamt   return parse_xml(p, fd);
    875  1.1.1.2.2.2  yamt }
    876  1.1.1.2.2.2  yamt </pre>
    877  1.1.1.2.2.2  yamt 
    878  1.1.1.2.2.2  yamt <p>Now that we've seen what a mess the top-level parsing loop can
    879  1.1.1.2.2.2  yamt become, what have we gained?  Very simply, we can now use the <code><a
    880  1.1.1.2.2.2  yamt href= "#XML_StopParser" >XML_StopParser</a></code> function to stop
    881  1.1.1.2.2.2  yamt parsing, without having to go to great lengths to avoid additional
    882  1.1.1.2.2.2  yamt processing that we're expecting to ignore.  As a bonus, we get to stop
    883  1.1.1.2.2.2  yamt parsing <em>temporarily</em>, and come back to it when we're
    884  1.1.1.2.2.2  yamt ready.</p>
    885  1.1.1.2.2.2  yamt 
    886  1.1.1.2.2.2  yamt <p>To stop parsing from a handler function, use the <code><a href=
    887  1.1.1.2.2.2  yamt "#XML_StopParser" >XML_StopParser</a></code> function.  This function
    888  1.1.1.2.2.2  yamt takes two arguments; the parser being stopped and a flag indicating
    889  1.1.1.2.2.2  yamt whether the parse can be resumed in the future.</p>
    890  1.1.1.2.2.2  yamt 
    891  1.1.1.2.2.2  yamt <!-- XXX really need more here -->
    892  1.1.1.2.2.2  yamt 
    893  1.1.1.2.2.2  yamt 
    894  1.1.1.2.2.2  yamt <hr />
    895  1.1.1.2.2.2  yamt <!-- ================================================================ -->
    896  1.1.1.2.2.2  yamt 
    897  1.1.1.2.2.2  yamt <h2><a name="reference">Expat Reference</a></h2>
    898  1.1.1.2.2.2  yamt 
    899  1.1.1.2.2.2  yamt <h3><a name="creation">Parser Creation</a></h3>
    900  1.1.1.2.2.2  yamt 
    901  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParserCreate">
    902  1.1.1.2.2.2  yamt XML_Parser XMLCALL
    903  1.1.1.2.2.2  yamt XML_ParserCreate(const XML_Char *encoding);
    904  1.1.1.2.2.2  yamt </pre>
    905  1.1.1.2.2.2  yamt <div class="fcndef">
    906  1.1.1.2.2.2  yamt Construct a new parser. If encoding is non-null, it specifies a
    907  1.1.1.2.2.2  yamt character encoding to use for the document. This overrides the document
    908  1.1.1.2.2.2  yamt encoding declaration. There are four built-in encodings:
    909  1.1.1.2.2.2  yamt <ul>
    910  1.1.1.2.2.2  yamt <li>US-ASCII</li>
    911  1.1.1.2.2.2  yamt <li>UTF-8</li>
    912  1.1.1.2.2.2  yamt <li>UTF-16</li>
    913  1.1.1.2.2.2  yamt <li>ISO-8859-1</li>
    914  1.1.1.2.2.2  yamt </ul>
    915  1.1.1.2.2.2  yamt Any other value will invoke a call to the UnknownEncodingHandler.
    916  1.1.1.2.2.2  yamt </div>
    917  1.1.1.2.2.2  yamt 
    918  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParserCreateNS">
    919  1.1.1.2.2.2  yamt XML_Parser XMLCALL
    920  1.1.1.2.2.2  yamt XML_ParserCreateNS(const XML_Char *encoding,
    921  1.1.1.2.2.2  yamt                    XML_Char sep);
    922  1.1.1.2.2.2  yamt </pre>
    923  1.1.1.2.2.2  yamt <div class="fcndef">
    924  1.1.1.2.2.2  yamt Constructs a new parser that has namespace processing in effect. Namespace
    925  1.1.1.2.2.2  yamt expanded element names and attribute names are returned as a concatenation
    926  1.1.1.2.2.2  yamt of the namespace URI, <em>sep</em>, and the local part of the name. This
    927  1.1.1.2.2.2  yamt means that you should pick a character for <em>sep</em> that can't be part
    928  1.1.1.2.2.2  yamt of an URI. Since Expat does not check namespace URIs for conformance, the
    929  1.1.1.2.2.2  yamt only safe choice for a namespace separator is a character that is illegal
    930  1.1.1.2.2.2  yamt in XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and
    931  1.1.1.2.2.2  yamt <code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when
    932  1.1.1.2.2.2  yamt <em>sep</em> is the null character <code>'\0'</code>: the namespace URI and
    933  1.1.1.2.2.2  yamt the local part will be concatenated without any separator - this is intended
    934  1.1.1.2.2.2  yamt to support RDF processors. It is a programming error to use the null separator
    935  1.1.1.2.2.2  yamt with <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div>
    936  1.1.1.2.2.2  yamt 
    937  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParserCreate_MM">
    938  1.1.1.2.2.2  yamt XML_Parser XMLCALL
    939  1.1.1.2.2.2  yamt XML_ParserCreate_MM(const XML_Char *encoding,
    940  1.1.1.2.2.2  yamt                     const XML_Memory_Handling_Suite *ms,
    941  1.1.1.2.2.2  yamt 		    const XML_Char *sep);
    942  1.1.1.2.2.2  yamt </pre>
    943  1.1.1.2.2.2  yamt <pre class="signature">
    944  1.1.1.2.2.2  yamt typedef struct {
    945  1.1.1.2.2.2  yamt   void *(XMLCALL *malloc_fcn)(size_t size);
    946  1.1.1.2.2.2  yamt   void *(XMLCALL *realloc_fcn)(void *ptr, size_t size);
    947  1.1.1.2.2.2  yamt   void (XMLCALL *free_fcn)(void *ptr);
    948  1.1.1.2.2.2  yamt } XML_Memory_Handling_Suite;
    949  1.1.1.2.2.2  yamt </pre>
    950  1.1.1.2.2.2  yamt <div class="fcndef">
    951  1.1.1.2.2.2  yamt <p>Construct a new parser using the suite of memory handling functions
    952  1.1.1.2.2.2  yamt specified in <code>ms</code>. If <code>ms</code> is NULL, then use the
    953  1.1.1.2.2.2  yamt standard set of memory management functions. If <code>sep</code> is
    954  1.1.1.2.2.2  yamt non NULL, then namespace processing is enabled in the created parser
    955  1.1.1.2.2.2  yamt and the character pointed at by sep is used as the separator between
    956  1.1.1.2.2.2  yamt the namespace URI and the local part of the name.</p>
    957  1.1.1.2.2.2  yamt </div>
    958  1.1.1.2.2.2  yamt 
    959  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ExternalEntityParserCreate">
    960  1.1.1.2.2.2  yamt XML_Parser XMLCALL
    961  1.1.1.2.2.2  yamt XML_ExternalEntityParserCreate(XML_Parser p,
    962  1.1.1.2.2.2  yamt                                const XML_Char *context,
    963  1.1.1.2.2.2  yamt                                const XML_Char *encoding);
    964  1.1.1.2.2.2  yamt </pre>
    965  1.1.1.2.2.2  yamt <div class="fcndef">
    966  1.1.1.2.2.2  yamt Construct a new <code>XML_Parser</code> object for parsing an external
    967  1.1.1.2.2.2  yamt general entity. Context is the context argument passed in a call to a
    968  1.1.1.2.2.2  yamt ExternalEntityRefHandler. Other state information such as handlers,
    969  1.1.1.2.2.2  yamt user data, namespace processing is inherited from the parser passed as
    970  1.1.1.2.2.2  yamt the 1st argument. So you shouldn't need to call any of the behavior
    971  1.1.1.2.2.2  yamt changing functions on this parser (unless you want it to act
    972  1.1.1.2.2.2  yamt differently than the parent parser).
    973  1.1.1.2.2.2  yamt </div>
    974  1.1.1.2.2.2  yamt 
    975  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParserFree">
    976  1.1.1.2.2.2  yamt void XMLCALL
    977  1.1.1.2.2.2  yamt XML_ParserFree(XML_Parser p);
    978  1.1.1.2.2.2  yamt </pre>
    979  1.1.1.2.2.2  yamt <div class="fcndef">
    980  1.1.1.2.2.2  yamt Free memory used by the parser. Your application is responsible for
    981  1.1.1.2.2.2  yamt freeing any memory associated with <a href="#userdata">user data</a>.
    982  1.1.1.2.2.2  yamt </div>
    983  1.1.1.2.2.2  yamt 
    984  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParserReset">
    985  1.1.1.2.2.2  yamt XML_Bool XMLCALL
    986  1.1.1.2.2.2  yamt XML_ParserReset(XML_Parser p,
    987  1.1.1.2.2.2  yamt                 const XML_Char *encoding);
    988  1.1.1.2.2.2  yamt </pre>
    989  1.1.1.2.2.2  yamt <div class="fcndef">
    990  1.1.1.2.2.2  yamt Clean up the memory structures maintained by the parser so that it may
    991  1.1.1.2.2.2  yamt be used again.  After this has been called, <code>parser</code> is
    992  1.1.1.2.2.2  yamt ready to start parsing a new document.  All handlers are cleared from
    993  1.1.1.2.2.2  yamt the parser, except for the unknownEncodingHandler.  The parser's external
    994  1.1.1.2.2.2  yamt state is re-initialized except for the values of ns and ns_triplets.
    995  1.1.1.2.2.2  yamt This function may not be used on a parser created using <code><a href=
    996  1.1.1.2.2.2  yamt "#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a
    997  1.1.1.2.2.2  yamt ></code>; it will return <code>XML_FALSE</code> in that case.  Returns
    998  1.1.1.2.2.2  yamt <code>XML_TRUE</code> on success.  Your application is responsible for
    999  1.1.1.2.2.2  yamt dealing with any memory associated with <a href="#userdata">user data</a>.
   1000  1.1.1.2.2.2  yamt </div>
   1001  1.1.1.2.2.2  yamt 
   1002  1.1.1.2.2.2  yamt <h3><a name="parsing">Parsing</a></h3>
   1003  1.1.1.2.2.2  yamt 
   1004  1.1.1.2.2.2  yamt <p>To state the obvious: the three parsing functions <code><a href=
   1005  1.1.1.2.2.2  yamt "#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer">
   1006  1.1.1.2.2.2  yamt XML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer">
   1007  1.1.1.2.2.2  yamt XML_GetBuffer</a></code> must not be called from within a handler
   1008  1.1.1.2.2.2  yamt unless they operate on a separate parser instance, that is, one that
   1009  1.1.1.2.2.2  yamt did not call the handler. For example, it is OK to call the parsing
   1010  1.1.1.2.2.2  yamt functions from within an <code>XML_ExternalEntityRefHandler</code>,
   1011  1.1.1.2.2.2  yamt if they apply to the parser created by
   1012  1.1.1.2.2.2  yamt <code><a href= "#XML_ExternalEntityParserCreate"
   1013  1.1.1.2.2.2  yamt >XML_ExternalEntityParserCreate</a></code>.</p>
   1014  1.1.1.2.2.2  yamt 
   1015  1.1.1.2.2.2  yamt <p>Note: the <code>len</code> argument passed to these functions
   1016  1.1.1.2.2.2  yamt should be considerably less than the maximum value for an integer,
   1017  1.1.1.2.2.2  yamt as it could create an integer overflow situation if the added
   1018  1.1.1.2.2.2  yamt lengths of a buffer and the unprocessed portion of the previous buffer
   1019  1.1.1.2.2.2  yamt exceed the maximum integer value. Input data at the end of a buffer
   1020  1.1.1.2.2.2  yamt will remain unprocessed if it is part of an XML token for which the
   1021  1.1.1.2.2.2  yamt end is not part of that buffer.</p>
   1022  1.1.1.2.2.2  yamt 
   1023  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_Parse">
   1024  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   1025  1.1.1.2.2.2  yamt XML_Parse(XML_Parser p,
   1026  1.1.1.2.2.2  yamt           const char *s,
   1027  1.1.1.2.2.2  yamt           int len,
   1028  1.1.1.2.2.2  yamt           int isFinal);
   1029  1.1.1.2.2.2  yamt </pre>
   1030  1.1.1.2.2.2  yamt <pre class="signature">
   1031  1.1.1.2.2.2  yamt enum XML_Status {
   1032  1.1.1.2.2.2  yamt   XML_STATUS_ERROR = 0,
   1033  1.1.1.2.2.2  yamt   XML_STATUS_OK = 1
   1034  1.1.1.2.2.2  yamt };
   1035  1.1.1.2.2.2  yamt </pre>
   1036  1.1.1.2.2.2  yamt <div class="fcndef">
   1037  1.1.1.2.2.2  yamt Parse some more of the document. The string <code>s</code> is a buffer
   1038  1.1.1.2.2.2  yamt containing part (or perhaps all) of the document. The number of bytes of s
   1039  1.1.1.2.2.2  yamt that are part of the document is indicated by <code>len</code>. This means
   1040  1.1.1.2.2.2  yamt that <code>s</code> doesn't have to be null terminated. It also means that
   1041  1.1.1.2.2.2  yamt if <code>len</code> is larger than the number of bytes in the block of
   1042  1.1.1.2.2.2  yamt memory that <code>s</code> points at, then a memory fault is likely. The
   1043  1.1.1.2.2.2  yamt <code>isFinal</code> parameter informs the parser that this is the last
   1044  1.1.1.2.2.2  yamt piece of the document. Frequently, the last piece is empty (i.e.
   1045  1.1.1.2.2.2  yamt <code>len</code> is zero.)
   1046  1.1.1.2.2.2  yamt If a parse error occurred, it returns <code>XML_STATUS_ERROR</code>.
   1047  1.1.1.2.2.2  yamt Otherwise it returns <code>XML_STATUS_OK</code> value.
   1048  1.1.1.2.2.2  yamt </div>
   1049  1.1.1.2.2.2  yamt 
   1050  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ParseBuffer">
   1051  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   1052  1.1.1.2.2.2  yamt XML_ParseBuffer(XML_Parser p,
   1053  1.1.1.2.2.2  yamt                 int len,
   1054  1.1.1.2.2.2  yamt                 int isFinal);
   1055  1.1.1.2.2.2  yamt </pre>
   1056  1.1.1.2.2.2  yamt <div class="fcndef">
   1057  1.1.1.2.2.2  yamt This is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>,
   1058  1.1.1.2.2.2  yamt except in this case Expat provides the buffer.  By obtaining the
   1059  1.1.1.2.2.2  yamt buffer from Expat with the <code><a href= "#XML_GetBuffer"
   1060  1.1.1.2.2.2  yamt >XML_GetBuffer</a></code> function, the application can avoid double
   1061  1.1.1.2.2.2  yamt copying of the input.
   1062  1.1.1.2.2.2  yamt </div>
   1063  1.1.1.2.2.2  yamt 
   1064  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetBuffer">
   1065  1.1.1.2.2.2  yamt void * XMLCALL
   1066  1.1.1.2.2.2  yamt XML_GetBuffer(XML_Parser p,
   1067  1.1.1.2.2.2  yamt               int len);
   1068  1.1.1.2.2.2  yamt </pre>
   1069  1.1.1.2.2.2  yamt <div class="fcndef">
   1070  1.1.1.2.2.2  yamt Obtain a buffer of size <code>len</code> to read a piece of the document
   1071  1.1.1.2.2.2  yamt into. A NULL value is returned if Expat can't allocate enough memory for
   1072  1.1.1.2.2.2  yamt this buffer. This has to be called prior to every call to
   1073  1.1.1.2.2.2  yamt <code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A
   1074  1.1.1.2.2.2  yamt typical use would look like this:
   1075  1.1.1.2.2.2  yamt 
   1076  1.1.1.2.2.2  yamt <pre class="eg">
   1077  1.1.1.2.2.2  yamt for (;;) {
   1078  1.1.1.2.2.2  yamt   int bytes_read;
   1079  1.1.1.2.2.2  yamt   void *buff = XML_GetBuffer(p, BUFF_SIZE);
   1080  1.1.1.2.2.2  yamt   if (buff == NULL) {
   1081  1.1.1.2.2.2  yamt     /* handle error */
   1082  1.1.1.2.2.2  yamt   }
   1083  1.1.1.2.2.2  yamt 
   1084  1.1.1.2.2.2  yamt   bytes_read = read(docfd, buff, BUFF_SIZE);
   1085  1.1.1.2.2.2  yamt   if (bytes_read &lt; 0) {
   1086  1.1.1.2.2.2  yamt     /* handle error */
   1087  1.1.1.2.2.2  yamt   }
   1088  1.1.1.2.2.2  yamt 
   1089  1.1.1.2.2.2  yamt   if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) {
   1090  1.1.1.2.2.2  yamt     /* handle parse error */
   1091  1.1.1.2.2.2  yamt   }
   1092  1.1.1.2.2.2  yamt 
   1093  1.1.1.2.2.2  yamt   if (bytes_read == 0)
   1094  1.1.1.2.2.2  yamt     break;
   1095  1.1.1.2.2.2  yamt }
   1096  1.1.1.2.2.2  yamt </pre>
   1097  1.1.1.2.2.2  yamt </div>
   1098  1.1.1.2.2.2  yamt 
   1099  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_StopParser">
   1100  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   1101  1.1.1.2.2.2  yamt XML_StopParser(XML_Parser p,
   1102  1.1.1.2.2.2  yamt                XML_Bool resumable);
   1103  1.1.1.2.2.2  yamt </pre>
   1104  1.1.1.2.2.2  yamt <div class="fcndef">
   1105  1.1.1.2.2.2  yamt 
   1106  1.1.1.2.2.2  yamt <p>Stops parsing, causing <code><a href= "#XML_Parse"
   1107  1.1.1.2.2.2  yamt >XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer"
   1108  1.1.1.2.2.2  yamt >XML_ParseBuffer</a></code> to return.  Must be called from within a
   1109  1.1.1.2.2.2  yamt call-back handler, except when aborting (when <code>resumable</code>
   1110  1.1.1.2.2.2  yamt is <code>XML_FALSE</code>) an already suspended parser.  Some
   1111  1.1.1.2.2.2  yamt call-backs may still follow because they would otherwise get
   1112  1.1.1.2.2.2  yamt lost, including
   1113  1.1.1.2.2.2  yamt <ul>
   1114  1.1.1.2.2.2  yamt   <li> the end element handler for empty elements when stopped in the
   1115  1.1.1.2.2.2  yamt        start element handler,</li>
   1116  1.1.1.2.2.2  yamt   <li> the end namespace declaration handler when stopped in the end
   1117  1.1.1.2.2.2  yamt        element handler,</li>
   1118  1.1.1.2.2.2  yamt   <li> the character data handler when stopped in the character data handler
   1119  1.1.1.2.2.2  yamt        while making multiple call-backs on a contiguous chunk of characters,</li>
   1120  1.1.1.2.2.2  yamt </ul>
   1121  1.1.1.2.2.2  yamt and possibly others.</p>
   1122  1.1.1.2.2.2  yamt 
   1123  1.1.1.2.2.2  yamt <p>This can be called from most handlers, including DTD related
   1124  1.1.1.2.2.2  yamt call-backs, except when parsing an external parameter entity and
   1125  1.1.1.2.2.2  yamt <code>resumable</code> is <code>XML_TRUE</code>.  Returns
   1126  1.1.1.2.2.2  yamt <code>XML_STATUS_OK</code> when successful,
   1127  1.1.1.2.2.2  yamt <code>XML_STATUS_ERROR</code> otherwise.  The possible error codes
   1128  1.1.1.2.2.2  yamt are:</p>
   1129  1.1.1.2.2.2  yamt <dl>
   1130  1.1.1.2.2.2  yamt   <dt><code>XML_ERROR_SUSPENDED</code></dt>
   1131  1.1.1.2.2.2  yamt   <dd>when suspending an already suspended parser.</dd>
   1132  1.1.1.2.2.2  yamt   <dt><code>XML_ERROR_FINISHED</code></dt>
   1133  1.1.1.2.2.2  yamt   <dd>when the parser has already finished.</dd>
   1134  1.1.1.2.2.2  yamt   <dt><code>XML_ERROR_SUSPEND_PE</code></dt>
   1135  1.1.1.2.2.2  yamt   <dd>when suspending while parsing an external PE.</dd>
   1136  1.1.1.2.2.2  yamt </dl>
   1137  1.1.1.2.2.2  yamt 
   1138  1.1.1.2.2.2  yamt <p>Since the stop/resume feature requires application support in the
   1139  1.1.1.2.2.2  yamt outer parsing loop, it is an error to call this function for a parser
   1140  1.1.1.2.2.2  yamt not being handled appropriately; see <a href= "#stop-resume"
   1141  1.1.1.2.2.2  yamt >Temporarily Stopping Parsing</a> for more information.</p>
   1142  1.1.1.2.2.2  yamt 
   1143  1.1.1.2.2.2  yamt <p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing
   1144  1.1.1.2.2.2  yamt is <em>suspended</em>, that is, <code><a href= "#XML_Parse"
   1145  1.1.1.2.2.2  yamt >XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer"
   1146  1.1.1.2.2.2  yamt >XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>.
   1147  1.1.1.2.2.2  yamt Otherwise, parsing is <em>aborted</em>, that is, <code><a href=
   1148  1.1.1.2.2.2  yamt "#XML_Parse" >XML_Parse</a></code> and <code><a href=
   1149  1.1.1.2.2.2  yamt "#XML_ParseBuffer" >XML_ParseBuffer</a></code> return
   1150  1.1.1.2.2.2  yamt <code>XML_STATUS_ERROR</code> with error code
   1151  1.1.1.2.2.2  yamt <code>XML_ERROR_ABORTED</code>.</p>
   1152  1.1.1.2.2.2  yamt 
   1153  1.1.1.2.2.2  yamt <p><strong>Note:</strong>
   1154  1.1.1.2.2.2  yamt This will be applied to the current parser instance only, that is, if
   1155  1.1.1.2.2.2  yamt there is a parent parser then it will continue parsing when the
   1156  1.1.1.2.2.2  yamt external entity reference handler returns.  It is up to the
   1157  1.1.1.2.2.2  yamt implementation of that handler to call <code><a href=
   1158  1.1.1.2.2.2  yamt "#XML_StopParser" >XML_StopParser</a></code> on the parent parser
   1159  1.1.1.2.2.2  yamt (recursively), if one wants to stop parsing altogether.</p>
   1160  1.1.1.2.2.2  yamt 
   1161  1.1.1.2.2.2  yamt <p>When suspended, parsing can be resumed by calling <code><a href=
   1162  1.1.1.2.2.2  yamt "#XML_ResumeParser" >XML_ResumeParser</a></code>.</p>
   1163  1.1.1.2.2.2  yamt 
   1164  1.1.1.2.2.2  yamt <p>New in Expat 1.95.8.</p>
   1165  1.1.1.2.2.2  yamt </div>
   1166  1.1.1.2.2.2  yamt 
   1167  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ResumeParser">
   1168  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   1169  1.1.1.2.2.2  yamt XML_ResumeParser(XML_Parser p);
   1170  1.1.1.2.2.2  yamt </pre>
   1171  1.1.1.2.2.2  yamt <div class="fcndef">
   1172  1.1.1.2.2.2  yamt <p>Resumes parsing after it has been suspended with <code><a href=
   1173  1.1.1.2.2.2  yamt "#XML_StopParser" >XML_StopParser</a></code>.  Must not be called from
   1174  1.1.1.2.2.2  yamt within a handler call-back.  Returns same status codes as <code><a
   1175  1.1.1.2.2.2  yamt href= "#XML_Parse">XML_Parse</a></code> or <code><a href=
   1176  1.1.1.2.2.2  yamt "#XML_ParseBuffer" >XML_ParseBuffer</a></code>.  An additional error
   1177  1.1.1.2.2.2  yamt code, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the
   1178  1.1.1.2.2.2  yamt parser was not currently suspended.</p>
   1179  1.1.1.2.2.2  yamt 
   1180  1.1.1.2.2.2  yamt <p><strong>Note:</strong>
   1181  1.1.1.2.2.2  yamt This must be called on the most deeply nested child parser instance
   1182  1.1.1.2.2.2  yamt first, and on its parent parser only after the child parser has
   1183  1.1.1.2.2.2  yamt finished, to be applied recursively until the document entity's parser
   1184  1.1.1.2.2.2  yamt is restarted.  That is, the parent parser will not resume by itself
   1185  1.1.1.2.2.2  yamt and it is up to the application to call <code><a href=
   1186  1.1.1.2.2.2  yamt "#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the
   1187  1.1.1.2.2.2  yamt appropriate moment.</p>
   1188  1.1.1.2.2.2  yamt 
   1189  1.1.1.2.2.2  yamt <p>New in Expat 1.95.8.</p>
   1190  1.1.1.2.2.2  yamt </div>
   1191  1.1.1.2.2.2  yamt 
   1192  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetParsingStatus">
   1193  1.1.1.2.2.2  yamt void XMLCALL
   1194  1.1.1.2.2.2  yamt XML_GetParsingStatus(XML_Parser p,
   1195  1.1.1.2.2.2  yamt                      XML_ParsingStatus *status);
   1196  1.1.1.2.2.2  yamt </pre>
   1197  1.1.1.2.2.2  yamt <pre class="signature">
   1198  1.1.1.2.2.2  yamt enum XML_Parsing {
   1199  1.1.1.2.2.2  yamt   XML_INITIALIZED,
   1200  1.1.1.2.2.2  yamt   XML_PARSING,
   1201  1.1.1.2.2.2  yamt   XML_FINISHED,
   1202  1.1.1.2.2.2  yamt   XML_SUSPENDED
   1203  1.1.1.2.2.2  yamt };
   1204  1.1.1.2.2.2  yamt 
   1205  1.1.1.2.2.2  yamt typedef struct {
   1206  1.1.1.2.2.2  yamt   enum XML_Parsing parsing;
   1207  1.1.1.2.2.2  yamt   XML_Bool finalBuffer;
   1208  1.1.1.2.2.2  yamt } XML_ParsingStatus;
   1209  1.1.1.2.2.2  yamt </pre>
   1210  1.1.1.2.2.2  yamt <div class="fcndef">
   1211  1.1.1.2.2.2  yamt <p>Returns status of parser with respect to being initialized,
   1212  1.1.1.2.2.2  yamt parsing, finished, or suspended, and whether the final buffer is being
   1213  1.1.1.2.2.2  yamt processed.  The <code>status</code> parameter <em>must not</em> be
   1214  1.1.1.2.2.2  yamt NULL.</p>
   1215  1.1.1.2.2.2  yamt 
   1216  1.1.1.2.2.2  yamt <p>New in Expat 1.95.8.</p>
   1217  1.1.1.2.2.2  yamt </div>
   1218  1.1.1.2.2.2  yamt 
   1219  1.1.1.2.2.2  yamt 
   1220  1.1.1.2.2.2  yamt <h3><a name="setting">Handler Setting</a></h3>
   1221  1.1.1.2.2.2  yamt 
   1222  1.1.1.2.2.2  yamt <p>Although handlers are typically set prior to parsing and left alone, an
   1223  1.1.1.2.2.2  yamt application may choose to set or change the handler for a parsing event
   1224  1.1.1.2.2.2  yamt while the parse is in progress. For instance, your application may choose
   1225  1.1.1.2.2.2  yamt to ignore all text not descended from a <code>para</code> element. One
   1226  1.1.1.2.2.2  yamt way it could do this is to set the character handler when a para start tag
   1227  1.1.1.2.2.2  yamt is seen, and unset it for the corresponding end tag.</p>
   1228  1.1.1.2.2.2  yamt 
   1229  1.1.1.2.2.2  yamt <p>A handler may be <em>unset</em> by providing a NULL pointer to the
   1230  1.1.1.2.2.2  yamt appropriate handler setter. None of the handler setting functions have
   1231  1.1.1.2.2.2  yamt a return value.</p>
   1232  1.1.1.2.2.2  yamt 
   1233  1.1.1.2.2.2  yamt <p>Your handlers will be receiving strings in arrays of type
   1234  1.1.1.2.2.2  yamt <code>XML_Char</code>. This type is conditionally defined in expat.h as
   1235  1.1.1.2.2.2  yamt either <code>char</code>, <code>wchar_t</code> or <code>unsigned short</code>.
   1236  1.1.1.2.2.2  yamt The former implies UTF-8 encoding, the latter two imply UTF-16 encoding.
   1237  1.1.1.2.2.2  yamt Note that you'll receive them in this form independent of the original
   1238  1.1.1.2.2.2  yamt encoding of the document.</p>
   1239  1.1.1.2.2.2  yamt 
   1240  1.1.1.2.2.2  yamt <div class="handler">
   1241  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetStartElementHandler">
   1242  1.1.1.2.2.2  yamt void XMLCALL
   1243  1.1.1.2.2.2  yamt XML_SetStartElementHandler(XML_Parser p,
   1244  1.1.1.2.2.2  yamt                            XML_StartElementHandler start);
   1245  1.1.1.2.2.2  yamt </pre>
   1246  1.1.1.2.2.2  yamt <pre class="signature">
   1247  1.1.1.2.2.2  yamt typedef void
   1248  1.1.1.2.2.2  yamt (XMLCALL *XML_StartElementHandler)(void *userData,
   1249  1.1.1.2.2.2  yamt                                    const XML_Char *name,
   1250  1.1.1.2.2.2  yamt                                    const XML_Char **atts);
   1251  1.1.1.2.2.2  yamt </pre>
   1252  1.1.1.2.2.2  yamt <p>Set handler for start (and empty) tags. Attributes are passed to the start
   1253  1.1.1.2.2.2  yamt handler as a pointer to a vector of char pointers. Each attribute seen in
   1254  1.1.1.2.2.2  yamt a start (or empty) tag occupies 2 consecutive places in this vector: the
   1255  1.1.1.2.2.2  yamt attribute name followed by the attribute value. These pairs are terminated
   1256  1.1.1.2.2.2  yamt by a null pointer.</p>
   1257  1.1.1.2.2.2  yamt <p>Note that an empty tag generates a call to both start and end handlers
   1258  1.1.1.2.2.2  yamt (in that order).</p>
   1259  1.1.1.2.2.2  yamt </div>
   1260  1.1.1.2.2.2  yamt 
   1261  1.1.1.2.2.2  yamt <div class="handler">
   1262  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetEndElementHandler">
   1263  1.1.1.2.2.2  yamt void XMLCALL
   1264  1.1.1.2.2.2  yamt XML_SetEndElementHandler(XML_Parser p,
   1265  1.1.1.2.2.2  yamt                          XML_EndElementHandler);
   1266  1.1.1.2.2.2  yamt </pre>
   1267  1.1.1.2.2.2  yamt <pre class="signature">
   1268  1.1.1.2.2.2  yamt typedef void
   1269  1.1.1.2.2.2  yamt (XMLCALL *XML_EndElementHandler)(void *userData,
   1270  1.1.1.2.2.2  yamt                                  const XML_Char *name);
   1271  1.1.1.2.2.2  yamt </pre>
   1272  1.1.1.2.2.2  yamt <p>Set handler for end (and empty) tags. As noted above, an empty tag
   1273  1.1.1.2.2.2  yamt generates a call to both start and end handlers.</p>
   1274  1.1.1.2.2.2  yamt </div>
   1275  1.1.1.2.2.2  yamt 
   1276  1.1.1.2.2.2  yamt <div class="handler">
   1277  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetElementHandler">
   1278  1.1.1.2.2.2  yamt void XMLCALL
   1279  1.1.1.2.2.2  yamt XML_SetElementHandler(XML_Parser p,
   1280  1.1.1.2.2.2  yamt                       XML_StartElementHandler start,
   1281  1.1.1.2.2.2  yamt                       XML_EndElementHandler end);
   1282  1.1.1.2.2.2  yamt </pre>
   1283  1.1.1.2.2.2  yamt <p>Set handlers for start and end tags with one call.</p>
   1284  1.1.1.2.2.2  yamt </div>
   1285  1.1.1.2.2.2  yamt 
   1286  1.1.1.2.2.2  yamt <div class="handler">
   1287  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetCharacterDataHandler">
   1288  1.1.1.2.2.2  yamt void XMLCALL
   1289  1.1.1.2.2.2  yamt XML_SetCharacterDataHandler(XML_Parser p,
   1290  1.1.1.2.2.2  yamt                             XML_CharacterDataHandler charhndl)
   1291  1.1.1.2.2.2  yamt </pre>
   1292  1.1.1.2.2.2  yamt <pre class="signature">
   1293  1.1.1.2.2.2  yamt typedef void
   1294  1.1.1.2.2.2  yamt (XMLCALL *XML_CharacterDataHandler)(void *userData,
   1295  1.1.1.2.2.2  yamt                                     const XML_Char *s,
   1296  1.1.1.2.2.2  yamt                                     int len);
   1297  1.1.1.2.2.2  yamt </pre>
   1298  1.1.1.2.2.2  yamt <p>Set a text handler. The string your handler receives
   1299  1.1.1.2.2.2  yamt is <em>NOT nul-terminated</em>. You have to use the length argument
   1300  1.1.1.2.2.2  yamt to deal with the end of the string. A single block of contiguous text
   1301  1.1.1.2.2.2  yamt free of markup may still result in a sequence of calls to this handler.
   1302  1.1.1.2.2.2  yamt In other words, if you're searching for a pattern in the text, it may
   1303  1.1.1.2.2.2  yamt be split across calls to this handler. Note: Setting this handler to NULL
   1304  1.1.1.2.2.2  yamt may <em>NOT immediately</em> terminate call-backs if the parser is currently
   1305  1.1.1.2.2.2  yamt processing such a single block of contiguous markup-free text, as the parser
   1306  1.1.1.2.2.2  yamt will continue calling back until the end of the block is reached.</p>
   1307  1.1.1.2.2.2  yamt </div>
   1308  1.1.1.2.2.2  yamt 
   1309  1.1.1.2.2.2  yamt <div class="handler">
   1310  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetProcessingInstructionHandler">
   1311  1.1.1.2.2.2  yamt void XMLCALL
   1312  1.1.1.2.2.2  yamt XML_SetProcessingInstructionHandler(XML_Parser p,
   1313  1.1.1.2.2.2  yamt                                     XML_ProcessingInstructionHandler proc)
   1314  1.1.1.2.2.2  yamt </pre>
   1315  1.1.1.2.2.2  yamt <pre class="signature">
   1316  1.1.1.2.2.2  yamt typedef void
   1317  1.1.1.2.2.2  yamt (XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
   1318  1.1.1.2.2.2  yamt                                             const XML_Char *target,
   1319  1.1.1.2.2.2  yamt                                             const XML_Char *data);
   1320  1.1.1.2.2.2  yamt 
   1321  1.1.1.2.2.2  yamt </pre>
   1322  1.1.1.2.2.2  yamt <p>Set a handler for processing instructions. The target is the first word
   1323  1.1.1.2.2.2  yamt in the processing instruction. The data is the rest of the characters in
   1324  1.1.1.2.2.2  yamt it after skipping all whitespace after the initial word.</p>
   1325  1.1.1.2.2.2  yamt </div>
   1326  1.1.1.2.2.2  yamt 
   1327  1.1.1.2.2.2  yamt <div class="handler">
   1328  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetCommentHandler">
   1329  1.1.1.2.2.2  yamt void XMLCALL
   1330  1.1.1.2.2.2  yamt XML_SetCommentHandler(XML_Parser p,
   1331  1.1.1.2.2.2  yamt                       XML_CommentHandler cmnt)
   1332  1.1.1.2.2.2  yamt </pre>
   1333  1.1.1.2.2.2  yamt <pre class="signature">
   1334  1.1.1.2.2.2  yamt typedef void
   1335  1.1.1.2.2.2  yamt (XMLCALL *XML_CommentHandler)(void *userData,
   1336  1.1.1.2.2.2  yamt                               const XML_Char *data);
   1337  1.1.1.2.2.2  yamt </pre>
   1338  1.1.1.2.2.2  yamt <p>Set a handler for comments. The data is all text inside the comment
   1339  1.1.1.2.2.2  yamt delimiters.</p>
   1340  1.1.1.2.2.2  yamt </div>
   1341  1.1.1.2.2.2  yamt 
   1342  1.1.1.2.2.2  yamt <div class="handler">
   1343  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetStartCdataSectionHandler">
   1344  1.1.1.2.2.2  yamt void XMLCALL
   1345  1.1.1.2.2.2  yamt XML_SetStartCdataSectionHandler(XML_Parser p,
   1346  1.1.1.2.2.2  yamt                                 XML_StartCdataSectionHandler start);
   1347  1.1.1.2.2.2  yamt </pre>
   1348  1.1.1.2.2.2  yamt <pre class="signature">
   1349  1.1.1.2.2.2  yamt typedef void
   1350  1.1.1.2.2.2  yamt (XMLCALL *XML_StartCdataSectionHandler)(void *userData);
   1351  1.1.1.2.2.2  yamt </pre>
   1352  1.1.1.2.2.2  yamt <p>Set a handler that gets called at the beginning of a CDATA section.</p>
   1353  1.1.1.2.2.2  yamt </div>
   1354  1.1.1.2.2.2  yamt 
   1355  1.1.1.2.2.2  yamt <div class="handler">
   1356  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetEndCdataSectionHandler">
   1357  1.1.1.2.2.2  yamt void XMLCALL
   1358  1.1.1.2.2.2  yamt XML_SetEndCdataSectionHandler(XML_Parser p,
   1359  1.1.1.2.2.2  yamt                               XML_EndCdataSectionHandler end);
   1360  1.1.1.2.2.2  yamt </pre>
   1361  1.1.1.2.2.2  yamt <pre class="signature">
   1362  1.1.1.2.2.2  yamt typedef void
   1363  1.1.1.2.2.2  yamt (XMLCALL *XML_EndCdataSectionHandler)(void *userData);
   1364  1.1.1.2.2.2  yamt </pre>
   1365  1.1.1.2.2.2  yamt <p>Set a handler that gets called at the end of a CDATA section.</p>
   1366  1.1.1.2.2.2  yamt </div>
   1367  1.1.1.2.2.2  yamt 
   1368  1.1.1.2.2.2  yamt <div class="handler">
   1369  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetCdataSectionHandler">
   1370  1.1.1.2.2.2  yamt void XMLCALL
   1371  1.1.1.2.2.2  yamt XML_SetCdataSectionHandler(XML_Parser p,
   1372  1.1.1.2.2.2  yamt                            XML_StartCdataSectionHandler start,
   1373  1.1.1.2.2.2  yamt                            XML_EndCdataSectionHandler end)
   1374  1.1.1.2.2.2  yamt </pre>
   1375  1.1.1.2.2.2  yamt <p>Sets both CDATA section handlers with one call.</p>
   1376  1.1.1.2.2.2  yamt </div>
   1377  1.1.1.2.2.2  yamt 
   1378  1.1.1.2.2.2  yamt <div class="handler">
   1379  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetDefaultHandler">
   1380  1.1.1.2.2.2  yamt void XMLCALL
   1381  1.1.1.2.2.2  yamt XML_SetDefaultHandler(XML_Parser p,
   1382  1.1.1.2.2.2  yamt                       XML_DefaultHandler hndl)
   1383  1.1.1.2.2.2  yamt </pre>
   1384  1.1.1.2.2.2  yamt <pre class="signature">
   1385  1.1.1.2.2.2  yamt typedef void
   1386  1.1.1.2.2.2  yamt (XMLCALL *XML_DefaultHandler)(void *userData,
   1387  1.1.1.2.2.2  yamt                               const XML_Char *s,
   1388  1.1.1.2.2.2  yamt                               int len);
   1389  1.1.1.2.2.2  yamt </pre>
   1390  1.1.1.2.2.2  yamt 
   1391  1.1.1.2.2.2  yamt <p>Sets a handler for any characters in the document which wouldn't
   1392  1.1.1.2.2.2  yamt otherwise be handled. This includes both data for which no handlers
   1393  1.1.1.2.2.2  yamt can be set (like some kinds of DTD declarations) and data which could
   1394  1.1.1.2.2.2  yamt be reported but which currently has no handler set.  The characters
   1395  1.1.1.2.2.2  yamt are passed exactly as they were present in the XML document except
   1396  1.1.1.2.2.2  yamt that they will be encoded in UTF-8 or UTF-16. Line boundaries are not
   1397  1.1.1.2.2.2  yamt normalized. Note that a byte order mark character is not passed to the
   1398  1.1.1.2.2.2  yamt default handler. There are no guarantees about how characters are
   1399  1.1.1.2.2.2  yamt divided between calls to the default handler: for example, a comment
   1400  1.1.1.2.2.2  yamt might be split between multiple calls.  Setting the handler with
   1401  1.1.1.2.2.2  yamt this call has the side effect of turning off expansion of references
   1402  1.1.1.2.2.2  yamt to internally defined general entities. Instead these references are
   1403  1.1.1.2.2.2  yamt passed to the default handler.</p>
   1404  1.1.1.2.2.2  yamt 
   1405  1.1.1.2.2.2  yamt <p>See also <code><a
   1406  1.1.1.2.2.2  yamt href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p>
   1407  1.1.1.2.2.2  yamt </div>
   1408  1.1.1.2.2.2  yamt 
   1409  1.1.1.2.2.2  yamt <div class="handler">
   1410  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetDefaultHandlerExpand">
   1411  1.1.1.2.2.2  yamt void XMLCALL
   1412  1.1.1.2.2.2  yamt XML_SetDefaultHandlerExpand(XML_Parser p,
   1413  1.1.1.2.2.2  yamt                             XML_DefaultHandler hndl)
   1414  1.1.1.2.2.2  yamt </pre>
   1415  1.1.1.2.2.2  yamt <pre class="signature">
   1416  1.1.1.2.2.2  yamt typedef void
   1417  1.1.1.2.2.2  yamt (XMLCALL *XML_DefaultHandler)(void *userData,
   1418  1.1.1.2.2.2  yamt                               const XML_Char *s,
   1419  1.1.1.2.2.2  yamt                               int len);
   1420  1.1.1.2.2.2  yamt </pre>
   1421  1.1.1.2.2.2  yamt <p>This sets a default handler, but doesn't inhibit the expansion of
   1422  1.1.1.2.2.2  yamt internal entity references.  The entity reference will not be passed
   1423  1.1.1.2.2.2  yamt to the default handler.</p>
   1424  1.1.1.2.2.2  yamt 
   1425  1.1.1.2.2.2  yamt <p>See also <code><a
   1426  1.1.1.2.2.2  yamt href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p>
   1427  1.1.1.2.2.2  yamt </div>
   1428  1.1.1.2.2.2  yamt 
   1429  1.1.1.2.2.2  yamt <div class="handler">
   1430  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetExternalEntityRefHandler">
   1431  1.1.1.2.2.2  yamt void XMLCALL
   1432  1.1.1.2.2.2  yamt XML_SetExternalEntityRefHandler(XML_Parser p,
   1433  1.1.1.2.2.2  yamt                                 XML_ExternalEntityRefHandler hndl)
   1434  1.1.1.2.2.2  yamt </pre>
   1435  1.1.1.2.2.2  yamt <pre class="signature">
   1436  1.1.1.2.2.2  yamt typedef int
   1437  1.1.1.2.2.2  yamt (XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p,
   1438  1.1.1.2.2.2  yamt                                         const XML_Char *context,
   1439  1.1.1.2.2.2  yamt                                         const XML_Char *base,
   1440  1.1.1.2.2.2  yamt                                         const XML_Char *systemId,
   1441  1.1.1.2.2.2  yamt                                         const XML_Char *publicId);
   1442  1.1.1.2.2.2  yamt </pre>
   1443  1.1.1.2.2.2  yamt <p>Set an external entity reference handler. This handler is also
   1444  1.1.1.2.2.2  yamt called for processing an external DTD subset if parameter entity parsing
   1445  1.1.1.2.2.2  yamt is in effect. (See <a href="#XML_SetParamEntityParsing">
   1446  1.1.1.2.2.2  yamt <code>XML_SetParamEntityParsing</code></a>.)</p>
   1447  1.1.1.2.2.2  yamt 
   1448  1.1.1.2.2.2  yamt <p>The <code>context</code> parameter specifies the parsing context in
   1449  1.1.1.2.2.2  yamt the format expected by the <code>context</code> argument to <code><a
   1450  1.1.1.2.2.2  yamt href="#XML_ExternalEntityParserCreate"
   1451  1.1.1.2.2.2  yamt >XML_ExternalEntityParserCreate</a></code>.  <code>code</code> is
   1452  1.1.1.2.2.2  yamt valid only until the handler returns, so if the referenced entity is
   1453  1.1.1.2.2.2  yamt to be parsed later, it must be copied.  <code>context</code> is NULL
   1454  1.1.1.2.2.2  yamt only when the entity is a parameter entity, which is how one can
   1455  1.1.1.2.2.2  yamt differentiate between general and parameter entities.</p>
   1456  1.1.1.2.2.2  yamt 
   1457  1.1.1.2.2.2  yamt <p>The <code>base</code> parameter is the base to use for relative
   1458  1.1.1.2.2.2  yamt system identifiers.  It is set by <code><a
   1459  1.1.1.2.2.2  yamt href="#XML_SetBase">XML_SetBase</a></code> and may be NULL. The
   1460  1.1.1.2.2.2  yamt <code>publicId</code> parameter is the public id given in the entity
   1461  1.1.1.2.2.2  yamt declaration and may be NULL.  <code>systemId</code> is the system
   1462  1.1.1.2.2.2  yamt identifier specified in the entity declaration and is never NULL.</p>
   1463  1.1.1.2.2.2  yamt 
   1464  1.1.1.2.2.2  yamt <p>There are a couple of ways in which this handler differs from
   1465  1.1.1.2.2.2  yamt others.  First, this handler returns a status indicator (an
   1466  1.1.1.2.2.2  yamt integer). <code>XML_STATUS_OK</code> should be returned for successful
   1467  1.1.1.2.2.2  yamt handling of the external entity reference.  Returning
   1468  1.1.1.2.2.2  yamt <code>XML_STATUS_ERROR</code> indicates failure, and causes the
   1469  1.1.1.2.2.2  yamt calling parser to return an
   1470  1.1.1.2.2.2  yamt <code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p>
   1471  1.1.1.2.2.2  yamt 
   1472  1.1.1.2.2.2  yamt <p>Second, instead of having the user data as its first argument, it
   1473  1.1.1.2.2.2  yamt receives the parser that encountered the entity reference. This, along
   1474  1.1.1.2.2.2  yamt with the context parameter, may be used as arguments to a call to
   1475  1.1.1.2.2.2  yamt <code><a href= "#XML_ExternalEntityParserCreate"
   1476  1.1.1.2.2.2  yamt >XML_ExternalEntityParserCreate</a></code>.  Using the returned
   1477  1.1.1.2.2.2  yamt parser, the body of the external entity can be recursively parsed.</p>
   1478  1.1.1.2.2.2  yamt 
   1479  1.1.1.2.2.2  yamt <p>Since this handler may be called recursively, it should not be saving
   1480  1.1.1.2.2.2  yamt information into global or static variables.</p>
   1481  1.1.1.2.2.2  yamt </div>
   1482  1.1.1.2.2.2  yamt 
   1483  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg">
   1484  1.1.1.2.2.2  yamt void XMLCALL
   1485  1.1.1.2.2.2  yamt XML_SetExternalEntityRefHandlerArg(XML_Parser p,
   1486  1.1.1.2.2.2  yamt                                    void *arg)
   1487  1.1.1.2.2.2  yamt </pre>
   1488  1.1.1.2.2.2  yamt <div class="fcndef">
   1489  1.1.1.2.2.2  yamt <p>Set the argument passed to the ExternalEntityRefHandler.  If
   1490  1.1.1.2.2.2  yamt <code>arg</code> is not NULL, it is the new value passed to the
   1491  1.1.1.2.2.2  yamt handler set using <code><a href="#XML_SetExternalEntityRefHandler"
   1492  1.1.1.2.2.2  yamt >XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is
   1493  1.1.1.2.2.2  yamt NULL, the argument passed to the handler function will be the parser
   1494  1.1.1.2.2.2  yamt object itself.</p>
   1495  1.1.1.2.2.2  yamt 
   1496  1.1.1.2.2.2  yamt <p><strong>Note:</strong>
   1497  1.1.1.2.2.2  yamt The type of <code>arg</code> and the type of the first argument to the
   1498  1.1.1.2.2.2  yamt ExternalEntityRefHandler do not match.  This function takes a
   1499  1.1.1.2.2.2  yamt <code>void *</code> to be passed to the handler, while the handler
   1500  1.1.1.2.2.2  yamt accepts an <code>XML_Parser</code>.  This is a historical accident,
   1501  1.1.1.2.2.2  yamt but will not be corrected before Expat 2.0 (at the earliest) to avoid
   1502  1.1.1.2.2.2  yamt causing compiler warnings for code that's known to work with this
   1503  1.1.1.2.2.2  yamt API.  It is the responsibility of the application code to know the
   1504  1.1.1.2.2.2  yamt actual type of the argument passed to the handler and to manage it
   1505  1.1.1.2.2.2  yamt properly.</p>
   1506  1.1.1.2.2.2  yamt </div>
   1507  1.1.1.2.2.2  yamt 
   1508  1.1.1.2.2.2  yamt <div class="handler">
   1509  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetSkippedEntityHandler">
   1510  1.1.1.2.2.2  yamt void XMLCALL
   1511  1.1.1.2.2.2  yamt XML_SetSkippedEntityHandler(XML_Parser p,
   1512  1.1.1.2.2.2  yamt                             XML_SkippedEntityHandler handler)
   1513  1.1.1.2.2.2  yamt </pre>
   1514  1.1.1.2.2.2  yamt <pre class="signature">
   1515  1.1.1.2.2.2  yamt typedef void
   1516  1.1.1.2.2.2  yamt (XMLCALL *XML_SkippedEntityHandler)(void *userData,
   1517  1.1.1.2.2.2  yamt                                     const XML_Char *entityName,
   1518  1.1.1.2.2.2  yamt                                     int is_parameter_entity);
   1519  1.1.1.2.2.2  yamt </pre>
   1520  1.1.1.2.2.2  yamt <p>Set a skipped entity handler. This is called in two situations:</p>
   1521  1.1.1.2.2.2  yamt <ol>
   1522  1.1.1.2.2.2  yamt    <li>An entity reference is encountered for which no declaration
   1523  1.1.1.2.2.2  yamt        has been read <em>and</em> this is not an error.</li>
   1524  1.1.1.2.2.2  yamt    <li>An internal entity reference is read, but not expanded, because
   1525  1.1.1.2.2.2  yamt        <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a>
   1526  1.1.1.2.2.2  yamt 	   has been called.</li>
   1527  1.1.1.2.2.2  yamt </ol>
   1528  1.1.1.2.2.2  yamt <p>The <code>is_parameter_entity</code> argument will be non-zero for
   1529  1.1.1.2.2.2  yamt a parameter entity and zero for a general entity.</p> <p>Note: skipped
   1530  1.1.1.2.2.2  yamt parameter entities in declarations and skipped general entities in
   1531  1.1.1.2.2.2  yamt attribute values cannot be reported, because the event would be out of
   1532  1.1.1.2.2.2  yamt sync with the reporting of the declarations or attribute values</p>
   1533  1.1.1.2.2.2  yamt </div>
   1534  1.1.1.2.2.2  yamt 
   1535  1.1.1.2.2.2  yamt <div class="handler">
   1536  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetUnknownEncodingHandler">
   1537  1.1.1.2.2.2  yamt void XMLCALL
   1538  1.1.1.2.2.2  yamt XML_SetUnknownEncodingHandler(XML_Parser p,
   1539  1.1.1.2.2.2  yamt                               XML_UnknownEncodingHandler enchandler,
   1540  1.1.1.2.2.2  yamt 			      void *encodingHandlerData)
   1541  1.1.1.2.2.2  yamt </pre>
   1542  1.1.1.2.2.2  yamt <pre class="signature">
   1543  1.1.1.2.2.2  yamt typedef int
   1544  1.1.1.2.2.2  yamt (XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData,
   1545  1.1.1.2.2.2  yamt                                       const XML_Char *name,
   1546  1.1.1.2.2.2  yamt                                       XML_Encoding *info);
   1547  1.1.1.2.2.2  yamt 
   1548  1.1.1.2.2.2  yamt typedef struct {
   1549  1.1.1.2.2.2  yamt   int map[256];
   1550  1.1.1.2.2.2  yamt   void *data;
   1551  1.1.1.2.2.2  yamt   int (XMLCALL *convert)(void *data, const char *s);
   1552  1.1.1.2.2.2  yamt   void (XMLCALL *release)(void *data);
   1553  1.1.1.2.2.2  yamt } XML_Encoding;
   1554  1.1.1.2.2.2  yamt </pre>
   1555  1.1.1.2.2.2  yamt <p>Set a handler to deal with encodings other than the <a
   1556  1.1.1.2.2.2  yamt href="#builtin_encodings">built in set</a>. This should be done before
   1557  1.1.1.2.2.2  yamt <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href=
   1558  1.1.1.2.2.2  yamt "#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the
   1559  1.1.1.2.2.2  yamt given parser.</p> <p>If the handler knows how to deal with an encoding
   1560  1.1.1.2.2.2  yamt with the given name, it should fill in the <code>info</code> data
   1561  1.1.1.2.2.2  yamt structure and return <code>XML_STATUS_OK</code>. Otherwise it
   1562  1.1.1.2.2.2  yamt should return <code>XML_STATUS_ERROR</code>. The handler will be called
   1563  1.1.1.2.2.2  yamt at most once per parsed (external) entity. The optional application
   1564  1.1.1.2.2.2  yamt data pointer <code>encodingHandlerData</code> will be passed back to
   1565  1.1.1.2.2.2  yamt the handler.</p>
   1566  1.1.1.2.2.2  yamt 
   1567  1.1.1.2.2.2  yamt <p>The map array contains information for every possible possible leading
   1568  1.1.1.2.2.2  yamt byte in a byte sequence. If the corresponding value is &gt;= 0, then it's
   1569  1.1.1.2.2.2  yamt a single byte sequence and the byte encodes that Unicode value. If the
   1570  1.1.1.2.2.2  yamt value is -1, then that byte is invalid as the initial byte in a sequence.
   1571  1.1.1.2.2.2  yamt If the value is -n, where n is an integer &gt; 1, then n is the number of
   1572  1.1.1.2.2.2  yamt bytes in the sequence and the actual conversion is accomplished by a
   1573  1.1.1.2.2.2  yamt call to the function pointed at by convert. This function may return -1
   1574  1.1.1.2.2.2  yamt if the sequence itself is invalid. The convert pointer may be null if
   1575  1.1.1.2.2.2  yamt there are only single byte codes. The data parameter passed to the convert
   1576  1.1.1.2.2.2  yamt function is the data pointer from <code>XML_Encoding</code>. The
   1577  1.1.1.2.2.2  yamt string s is <em>NOT</em> nul-terminated and points at the sequence of
   1578  1.1.1.2.2.2  yamt bytes to be converted.</p>
   1579  1.1.1.2.2.2  yamt 
   1580  1.1.1.2.2.2  yamt <p>The function pointed at by <code>release</code> is called by the
   1581  1.1.1.2.2.2  yamt parser when it is finished with the encoding. It may be NULL.</p>
   1582  1.1.1.2.2.2  yamt </div>
   1583  1.1.1.2.2.2  yamt 
   1584  1.1.1.2.2.2  yamt <div class="handler">
   1585  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetStartNamespaceDeclHandler">
   1586  1.1.1.2.2.2  yamt void XMLCALL
   1587  1.1.1.2.2.2  yamt XML_SetStartNamespaceDeclHandler(XML_Parser p,
   1588  1.1.1.2.2.2  yamt 			         XML_StartNamespaceDeclHandler start);
   1589  1.1.1.2.2.2  yamt </pre>
   1590  1.1.1.2.2.2  yamt <pre class="signature">
   1591  1.1.1.2.2.2  yamt typedef void
   1592  1.1.1.2.2.2  yamt (XMLCALL *XML_StartNamespaceDeclHandler)(void *userData,
   1593  1.1.1.2.2.2  yamt                                          const XML_Char *prefix,
   1594  1.1.1.2.2.2  yamt                                          const XML_Char *uri);
   1595  1.1.1.2.2.2  yamt </pre>
   1596  1.1.1.2.2.2  yamt <p>Set a handler to be called when a namespace is declared. Namespace
   1597  1.1.1.2.2.2  yamt declarations occur inside start tags. But the namespace declaration start
   1598  1.1.1.2.2.2  yamt handler is called before the start tag handler for each namespace declared
   1599  1.1.1.2.2.2  yamt in that start tag.</p>
   1600  1.1.1.2.2.2  yamt </div>
   1601  1.1.1.2.2.2  yamt 
   1602  1.1.1.2.2.2  yamt <div class="handler">
   1603  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetEndNamespaceDeclHandler">
   1604  1.1.1.2.2.2  yamt void XMLCALL
   1605  1.1.1.2.2.2  yamt XML_SetEndNamespaceDeclHandler(XML_Parser p,
   1606  1.1.1.2.2.2  yamt 			       XML_EndNamespaceDeclHandler end);
   1607  1.1.1.2.2.2  yamt </pre>
   1608  1.1.1.2.2.2  yamt <pre class="signature">
   1609  1.1.1.2.2.2  yamt typedef void
   1610  1.1.1.2.2.2  yamt (XMLCALL *XML_EndNamespaceDeclHandler)(void *userData,
   1611  1.1.1.2.2.2  yamt                                        const XML_Char *prefix);
   1612  1.1.1.2.2.2  yamt </pre>
   1613  1.1.1.2.2.2  yamt <p>Set a handler to be called when leaving the scope of a namespace
   1614  1.1.1.2.2.2  yamt declaration. This will be called, for each namespace declaration,
   1615  1.1.1.2.2.2  yamt after the handler for the end tag of the element in which the
   1616  1.1.1.2.2.2  yamt namespace was declared.</p>
   1617  1.1.1.2.2.2  yamt </div>
   1618  1.1.1.2.2.2  yamt 
   1619  1.1.1.2.2.2  yamt <div class="handler">
   1620  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetNamespaceDeclHandler">
   1621  1.1.1.2.2.2  yamt void XMLCALL
   1622  1.1.1.2.2.2  yamt XML_SetNamespaceDeclHandler(XML_Parser p,
   1623  1.1.1.2.2.2  yamt                             XML_StartNamespaceDeclHandler start,
   1624  1.1.1.2.2.2  yamt                             XML_EndNamespaceDeclHandler end)
   1625  1.1.1.2.2.2  yamt </pre>
   1626  1.1.1.2.2.2  yamt <p>Sets both namespace declaration handlers with a single call.</p>
   1627  1.1.1.2.2.2  yamt </div>
   1628  1.1.1.2.2.2  yamt 
   1629  1.1.1.2.2.2  yamt <div class="handler">
   1630  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetXmlDeclHandler">
   1631  1.1.1.2.2.2  yamt void XMLCALL
   1632  1.1.1.2.2.2  yamt XML_SetXmlDeclHandler(XML_Parser p,
   1633  1.1.1.2.2.2  yamt 		      XML_XmlDeclHandler xmldecl);
   1634  1.1.1.2.2.2  yamt </pre>
   1635  1.1.1.2.2.2  yamt <pre class="signature">
   1636  1.1.1.2.2.2  yamt typedef void
   1637  1.1.1.2.2.2  yamt (XMLCALL *XML_XmlDeclHandler)(void            *userData,
   1638  1.1.1.2.2.2  yamt                               const XML_Char  *version,
   1639  1.1.1.2.2.2  yamt                               const XML_Char  *encoding,
   1640  1.1.1.2.2.2  yamt                               int             standalone);
   1641  1.1.1.2.2.2  yamt </pre>
   1642  1.1.1.2.2.2  yamt <p>Sets a handler that is called for XML declarations and also for
   1643  1.1.1.2.2.2  yamt text declarations discovered in external entities. The way to
   1644  1.1.1.2.2.2  yamt distinguish is that the <code>version</code> parameter will be NULL
   1645  1.1.1.2.2.2  yamt for text declarations. The <code>encoding</code> parameter may be NULL
   1646  1.1.1.2.2.2  yamt for an XML declaration. The <code>standalone</code> argument will
   1647  1.1.1.2.2.2  yamt contain -1, 0, or 1 indicating respectively that there was no
   1648  1.1.1.2.2.2  yamt standalone parameter in the declaration, that it was given as no, or
   1649  1.1.1.2.2.2  yamt that it was given as yes.</p>
   1650  1.1.1.2.2.2  yamt </div>
   1651  1.1.1.2.2.2  yamt 
   1652  1.1.1.2.2.2  yamt <div class="handler">
   1653  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetStartDoctypeDeclHandler">
   1654  1.1.1.2.2.2  yamt void XMLCALL
   1655  1.1.1.2.2.2  yamt XML_SetStartDoctypeDeclHandler(XML_Parser p,
   1656  1.1.1.2.2.2  yamt 			       XML_StartDoctypeDeclHandler start);
   1657  1.1.1.2.2.2  yamt </pre>
   1658  1.1.1.2.2.2  yamt <pre class="signature">
   1659  1.1.1.2.2.2  yamt typedef void
   1660  1.1.1.2.2.2  yamt (XMLCALL *XML_StartDoctypeDeclHandler)(void           *userData,
   1661  1.1.1.2.2.2  yamt                                        const XML_Char *doctypeName,
   1662  1.1.1.2.2.2  yamt                                        const XML_Char *sysid,
   1663  1.1.1.2.2.2  yamt                                        const XML_Char *pubid,
   1664  1.1.1.2.2.2  yamt                                        int            has_internal_subset);
   1665  1.1.1.2.2.2  yamt </pre>
   1666  1.1.1.2.2.2  yamt <p>Set a handler that is called at the start of a DOCTYPE declaration,
   1667  1.1.1.2.2.2  yamt before any external or internal subset is parsed. Both <code>sysid</code>
   1668  1.1.1.2.2.2  yamt and <code>pubid</code> may be NULL. The <code>has_internal_subset</code>
   1669  1.1.1.2.2.2  yamt will be non-zero if the DOCTYPE declaration has an internal subset.</p>
   1670  1.1.1.2.2.2  yamt </div>
   1671  1.1.1.2.2.2  yamt 
   1672  1.1.1.2.2.2  yamt <div class="handler">
   1673  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetEndDoctypeDeclHandler">
   1674  1.1.1.2.2.2  yamt void XMLCALL
   1675  1.1.1.2.2.2  yamt XML_SetEndDoctypeDeclHandler(XML_Parser p,
   1676  1.1.1.2.2.2  yamt 			     XML_EndDoctypeDeclHandler end);
   1677  1.1.1.2.2.2  yamt </pre>
   1678  1.1.1.2.2.2  yamt <pre class="signature">
   1679  1.1.1.2.2.2  yamt typedef void
   1680  1.1.1.2.2.2  yamt (XMLCALL *XML_EndDoctypeDeclHandler)(void *userData);
   1681  1.1.1.2.2.2  yamt </pre>
   1682  1.1.1.2.2.2  yamt <p>Set a handler that is called at the end of a DOCTYPE declaration,
   1683  1.1.1.2.2.2  yamt after parsing any external subset.</p>
   1684  1.1.1.2.2.2  yamt </div>
   1685  1.1.1.2.2.2  yamt 
   1686  1.1.1.2.2.2  yamt <div class="handler">
   1687  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetDoctypeDeclHandler">
   1688  1.1.1.2.2.2  yamt void XMLCALL
   1689  1.1.1.2.2.2  yamt XML_SetDoctypeDeclHandler(XML_Parser p,
   1690  1.1.1.2.2.2  yamt 			  XML_StartDoctypeDeclHandler start,
   1691  1.1.1.2.2.2  yamt 			  XML_EndDoctypeDeclHandler end);
   1692  1.1.1.2.2.2  yamt </pre>
   1693  1.1.1.2.2.2  yamt <p>Set both doctype handlers with one call.</p>
   1694  1.1.1.2.2.2  yamt </div>
   1695  1.1.1.2.2.2  yamt 
   1696  1.1.1.2.2.2  yamt <div class="handler">
   1697  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetElementDeclHandler">
   1698  1.1.1.2.2.2  yamt void XMLCALL
   1699  1.1.1.2.2.2  yamt XML_SetElementDeclHandler(XML_Parser p,
   1700  1.1.1.2.2.2  yamt 			  XML_ElementDeclHandler eldecl);
   1701  1.1.1.2.2.2  yamt </pre>
   1702  1.1.1.2.2.2  yamt <pre class="signature">
   1703  1.1.1.2.2.2  yamt typedef void
   1704  1.1.1.2.2.2  yamt (XMLCALL *XML_ElementDeclHandler)(void *userData,
   1705  1.1.1.2.2.2  yamt                                   const XML_Char *name,
   1706  1.1.1.2.2.2  yamt                                   XML_Content *model);
   1707  1.1.1.2.2.2  yamt </pre>
   1708  1.1.1.2.2.2  yamt <pre class="signature">
   1709  1.1.1.2.2.2  yamt enum XML_Content_Type {
   1710  1.1.1.2.2.2  yamt   XML_CTYPE_EMPTY = 1,
   1711  1.1.1.2.2.2  yamt   XML_CTYPE_ANY,
   1712  1.1.1.2.2.2  yamt   XML_CTYPE_MIXED,
   1713  1.1.1.2.2.2  yamt   XML_CTYPE_NAME,
   1714  1.1.1.2.2.2  yamt   XML_CTYPE_CHOICE,
   1715  1.1.1.2.2.2  yamt   XML_CTYPE_SEQ
   1716  1.1.1.2.2.2  yamt };
   1717  1.1.1.2.2.2  yamt 
   1718  1.1.1.2.2.2  yamt enum XML_Content_Quant {
   1719  1.1.1.2.2.2  yamt   XML_CQUANT_NONE,
   1720  1.1.1.2.2.2  yamt   XML_CQUANT_OPT,
   1721  1.1.1.2.2.2  yamt   XML_CQUANT_REP,
   1722  1.1.1.2.2.2  yamt   XML_CQUANT_PLUS
   1723  1.1.1.2.2.2  yamt };
   1724  1.1.1.2.2.2  yamt 
   1725  1.1.1.2.2.2  yamt typedef struct XML_cp XML_Content;
   1726  1.1.1.2.2.2  yamt 
   1727  1.1.1.2.2.2  yamt struct XML_cp {
   1728  1.1.1.2.2.2  yamt   enum XML_Content_Type		type;
   1729  1.1.1.2.2.2  yamt   enum XML_Content_Quant	quant;
   1730  1.1.1.2.2.2  yamt   const XML_Char *		name;
   1731  1.1.1.2.2.2  yamt   unsigned int			numchildren;
   1732  1.1.1.2.2.2  yamt   XML_Content *			children;
   1733  1.1.1.2.2.2  yamt };
   1734  1.1.1.2.2.2  yamt </pre>
   1735  1.1.1.2.2.2  yamt <p>Sets a handler for element declarations in a DTD. The handler gets
   1736  1.1.1.2.2.2  yamt called with the name of the element in the declaration and a pointer
   1737  1.1.1.2.2.2  yamt to a structure that contains the element model. It is the
   1738  1.1.1.2.2.2  yamt application's responsibility to free this data structure using
   1739  1.1.1.2.2.2  yamt <code><a href="#XML_FreeContentModel"
   1740  1.1.1.2.2.2  yamt >XML_FreeContentModel</a></code>.</p>
   1741  1.1.1.2.2.2  yamt 
   1742  1.1.1.2.2.2  yamt <p>The <code>model</code> argument is the root of a tree of
   1743  1.1.1.2.2.2  yamt <code>XML_Content</code> nodes. If <code>type</code> equals
   1744  1.1.1.2.2.2  yamt <code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then
   1745  1.1.1.2.2.2  yamt <code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other
   1746  1.1.1.2.2.2  yamt fields will be zero or NULL.  If <code>type</code> is
   1747  1.1.1.2.2.2  yamt <code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be
   1748  1.1.1.2.2.2  yamt <code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and
   1749  1.1.1.2.2.2  yamt <code>numchildren</code> will contain the number of elements that are
   1750  1.1.1.2.2.2  yamt allowed to be mixed in and <code>children</code> points to an array of
   1751  1.1.1.2.2.2  yamt <code>XML_Content</code> structures that will all have type
   1752  1.1.1.2.2.2  yamt XML_CTYPE_NAME with no quantification.  Only the root node can be type
   1753  1.1.1.2.2.2  yamt <code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or
   1754  1.1.1.2.2.2  yamt <code>XML_CTYPE_MIXED</code>.</p>
   1755  1.1.1.2.2.2  yamt 
   1756  1.1.1.2.2.2  yamt <p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field
   1757  1.1.1.2.2.2  yamt points to the name and the <code>numchildren</code> and
   1758  1.1.1.2.2.2  yamt <code>children</code> fields will be zero and NULL. The
   1759  1.1.1.2.2.2  yamt <code>quant</code> field will indicate any quantifiers placed on the
   1760  1.1.1.2.2.2  yamt name.</p>
   1761  1.1.1.2.2.2  yamt 
   1762  1.1.1.2.2.2  yamt <p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code>
   1763  1.1.1.2.2.2  yamt indicate a choice or sequence respectively. The
   1764  1.1.1.2.2.2  yamt <code>numchildren</code> field indicates how many nodes in the choice
   1765  1.1.1.2.2.2  yamt or sequence and <code>children</code> points to the nodes.</p>
   1766  1.1.1.2.2.2  yamt </div>
   1767  1.1.1.2.2.2  yamt 
   1768  1.1.1.2.2.2  yamt <div class="handler">
   1769  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetAttlistDeclHandler">
   1770  1.1.1.2.2.2  yamt void XMLCALL
   1771  1.1.1.2.2.2  yamt XML_SetAttlistDeclHandler(XML_Parser p,
   1772  1.1.1.2.2.2  yamt                           XML_AttlistDeclHandler attdecl);
   1773  1.1.1.2.2.2  yamt </pre>
   1774  1.1.1.2.2.2  yamt <pre class="signature">
   1775  1.1.1.2.2.2  yamt typedef void
   1776  1.1.1.2.2.2  yamt (XMLCALL *XML_AttlistDeclHandler)(void           *userData,
   1777  1.1.1.2.2.2  yamt                                   const XML_Char *elname,
   1778  1.1.1.2.2.2  yamt                                   const XML_Char *attname,
   1779  1.1.1.2.2.2  yamt                                   const XML_Char *att_type,
   1780  1.1.1.2.2.2  yamt                                   const XML_Char *dflt,
   1781  1.1.1.2.2.2  yamt                                   int            isrequired);
   1782  1.1.1.2.2.2  yamt </pre>
   1783  1.1.1.2.2.2  yamt <p>Set a handler for attlist declarations in the DTD. This handler is
   1784  1.1.1.2.2.2  yamt called for <em>each</em> attribute. So a single attlist declaration
   1785  1.1.1.2.2.2  yamt with multiple attributes declared will generate multiple calls to this
   1786  1.1.1.2.2.2  yamt handler. The <code>elname</code> parameter returns the name of the
   1787  1.1.1.2.2.2  yamt element for which the attribute is being declared. The attribute name
   1788  1.1.1.2.2.2  yamt is in the <code>attname</code> parameter. The attribute type is in the
   1789  1.1.1.2.2.2  yamt <code>att_type</code> parameter.  It is the string representing the
   1790  1.1.1.2.2.2  yamt type in the declaration with whitespace removed.</p>
   1791  1.1.1.2.2.2  yamt 
   1792  1.1.1.2.2.2  yamt <p>The <code>dflt</code> parameter holds the default value. It will be
   1793  1.1.1.2.2.2  yamt NULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can
   1794  1.1.1.2.2.2  yamt distinguish these two cases by checking the <code>isrequired</code>
   1795  1.1.1.2.2.2  yamt parameter, which will be true in the case of "#REQUIRED" attributes.
   1796  1.1.1.2.2.2  yamt Attributes which are "#FIXED" will have also have a true
   1797  1.1.1.2.2.2  yamt <code>isrequired</code>, but they will have the non-NULL fixed value
   1798  1.1.1.2.2.2  yamt in the <code>dflt</code> parameter.</p>
   1799  1.1.1.2.2.2  yamt </div>
   1800  1.1.1.2.2.2  yamt 
   1801  1.1.1.2.2.2  yamt <div class="handler">
   1802  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetEntityDeclHandler">
   1803  1.1.1.2.2.2  yamt void XMLCALL
   1804  1.1.1.2.2.2  yamt XML_SetEntityDeclHandler(XML_Parser p,
   1805  1.1.1.2.2.2  yamt 			 XML_EntityDeclHandler handler);
   1806  1.1.1.2.2.2  yamt </pre>
   1807  1.1.1.2.2.2  yamt <pre class="signature">
   1808  1.1.1.2.2.2  yamt typedef void
   1809  1.1.1.2.2.2  yamt (XMLCALL *XML_EntityDeclHandler)(void           *userData,
   1810  1.1.1.2.2.2  yamt                                  const XML_Char *entityName,
   1811  1.1.1.2.2.2  yamt                                  int            is_parameter_entity,
   1812  1.1.1.2.2.2  yamt                                  const XML_Char *value,
   1813  1.1.1.2.2.2  yamt                                  int            value_length, 
   1814  1.1.1.2.2.2  yamt                                  const XML_Char *base,
   1815  1.1.1.2.2.2  yamt                                  const XML_Char *systemId,
   1816  1.1.1.2.2.2  yamt                                  const XML_Char *publicId,
   1817  1.1.1.2.2.2  yamt                                  const XML_Char *notationName);
   1818  1.1.1.2.2.2  yamt </pre>
   1819  1.1.1.2.2.2  yamt <p>Sets a handler that will be called for all entity declarations.
   1820  1.1.1.2.2.2  yamt The <code>is_parameter_entity</code> argument will be non-zero in the
   1821  1.1.1.2.2.2  yamt case of parameter entities and zero otherwise.</p>
   1822  1.1.1.2.2.2  yamt 
   1823  1.1.1.2.2.2  yamt <p>For internal entities (<code>&lt;!ENTITY foo "bar"&gt;</code>),
   1824  1.1.1.2.2.2  yamt <code>value</code> will be non-NULL and <code>systemId</code>,
   1825  1.1.1.2.2.2  yamt <code>publicId</code>, and <code>notationName</code> will all be NULL.
   1826  1.1.1.2.2.2  yamt The value string is <em>not</em> NULL terminated; the length is
   1827  1.1.1.2.2.2  yamt provided in the <code>value_length</code> parameter. Do not use
   1828  1.1.1.2.2.2  yamt <code>value_length</code> to test for internal entities, since it is
   1829  1.1.1.2.2.2  yamt legal to have zero-length values. Instead check for whether or not
   1830  1.1.1.2.2.2  yamt <code>value</code> is NULL.</p> <p>The <code>notationName</code>
   1831  1.1.1.2.2.2  yamt argument will have a non-NULL value only for unparsed entity
   1832  1.1.1.2.2.2  yamt declarations.</p>
   1833  1.1.1.2.2.2  yamt </div>
   1834  1.1.1.2.2.2  yamt 
   1835  1.1.1.2.2.2  yamt <div class="handler">
   1836  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetUnparsedEntityDeclHandler">
   1837  1.1.1.2.2.2  yamt void XMLCALL
   1838  1.1.1.2.2.2  yamt XML_SetUnparsedEntityDeclHandler(XML_Parser p,
   1839  1.1.1.2.2.2  yamt                                  XML_UnparsedEntityDeclHandler h)
   1840  1.1.1.2.2.2  yamt </pre>
   1841  1.1.1.2.2.2  yamt <pre class="signature">
   1842  1.1.1.2.2.2  yamt typedef void
   1843  1.1.1.2.2.2  yamt (XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData,
   1844  1.1.1.2.2.2  yamt                                          const XML_Char *entityName, 
   1845  1.1.1.2.2.2  yamt                                          const XML_Char *base,
   1846  1.1.1.2.2.2  yamt                                          const XML_Char *systemId,
   1847  1.1.1.2.2.2  yamt                                          const XML_Char *publicId,
   1848  1.1.1.2.2.2  yamt                                          const XML_Char *notationName);
   1849  1.1.1.2.2.2  yamt </pre>
   1850  1.1.1.2.2.2  yamt <p>Set a handler that receives declarations of unparsed entities. These
   1851  1.1.1.2.2.2  yamt are entity declarations that have a notation (NDATA) field:</p>
   1852  1.1.1.2.2.2  yamt 
   1853  1.1.1.2.2.2  yamt <div id="eg"><pre>
   1854  1.1.1.2.2.2  yamt &lt;!ENTITY logo SYSTEM "images/logo.gif" NDATA gif&gt;
   1855  1.1.1.2.2.2  yamt </pre></div>
   1856  1.1.1.2.2.2  yamt <p>This handler is obsolete and is provided for backwards
   1857  1.1.1.2.2.2  yamt compatibility.  Use instead <a href= "#XML_SetEntityDeclHandler"
   1858  1.1.1.2.2.2  yamt >XML_SetEntityDeclHandler</a>.</p>
   1859  1.1.1.2.2.2  yamt </div>
   1860  1.1.1.2.2.2  yamt 
   1861  1.1.1.2.2.2  yamt <div class="handler">
   1862  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetNotationDeclHandler">
   1863  1.1.1.2.2.2  yamt void XMLCALL
   1864  1.1.1.2.2.2  yamt XML_SetNotationDeclHandler(XML_Parser p,
   1865  1.1.1.2.2.2  yamt                            XML_NotationDeclHandler h)
   1866  1.1.1.2.2.2  yamt </pre>
   1867  1.1.1.2.2.2  yamt <pre class="signature">
   1868  1.1.1.2.2.2  yamt typedef void
   1869  1.1.1.2.2.2  yamt (XMLCALL *XML_NotationDeclHandler)(void *userData, 
   1870  1.1.1.2.2.2  yamt                                    const XML_Char *notationName,
   1871  1.1.1.2.2.2  yamt                                    const XML_Char *base,
   1872  1.1.1.2.2.2  yamt                                    const XML_Char *systemId,
   1873  1.1.1.2.2.2  yamt                                    const XML_Char *publicId);
   1874  1.1.1.2.2.2  yamt </pre>
   1875  1.1.1.2.2.2  yamt <p>Set a handler that receives notation declarations.</p>
   1876  1.1.1.2.2.2  yamt </div>
   1877  1.1.1.2.2.2  yamt 
   1878  1.1.1.2.2.2  yamt <div class="handler">
   1879  1.1.1.2.2.2  yamt <pre class="setter" id="XML_SetNotStandaloneHandler">
   1880  1.1.1.2.2.2  yamt void XMLCALL
   1881  1.1.1.2.2.2  yamt XML_SetNotStandaloneHandler(XML_Parser p,
   1882  1.1.1.2.2.2  yamt                             XML_NotStandaloneHandler h)
   1883  1.1.1.2.2.2  yamt </pre>
   1884  1.1.1.2.2.2  yamt <pre class="signature">
   1885  1.1.1.2.2.2  yamt typedef int 
   1886  1.1.1.2.2.2  yamt (XMLCALL *XML_NotStandaloneHandler)(void *userData);
   1887  1.1.1.2.2.2  yamt </pre>
   1888  1.1.1.2.2.2  yamt <p>Set a handler that is called if the document is not "standalone".
   1889  1.1.1.2.2.2  yamt This happens when there is an external subset or a reference to a
   1890  1.1.1.2.2.2  yamt parameter entity, but does not have standalone set to "yes" in an XML
   1891  1.1.1.2.2.2  yamt declaration.  If this handler returns <code>XML_STATUS_ERROR</code>,
   1892  1.1.1.2.2.2  yamt then the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code>
   1893  1.1.1.2.2.2  yamt error.</p>
   1894  1.1.1.2.2.2  yamt </div>
   1895  1.1.1.2.2.2  yamt 
   1896  1.1.1.2.2.2  yamt <h3><a name="position">Parse position and error reporting functions</a></h3>
   1897  1.1.1.2.2.2  yamt 
   1898  1.1.1.2.2.2  yamt <p>These are the functions you'll want to call when the parse
   1899  1.1.1.2.2.2  yamt functions return <code>XML_STATUS_ERROR</code> (a parse error has
   1900  1.1.1.2.2.2  yamt occurred), although the position reporting functions are useful outside
   1901  1.1.1.2.2.2  yamt of errors. The position reported is the byte position (in the original
   1902  1.1.1.2.2.2  yamt document or entity encoding) of the first of the sequence of
   1903  1.1.1.2.2.2  yamt characters that generated the current event (or the error that caused
   1904  1.1.1.2.2.2  yamt the parse functions to return <code>XML_STATUS_ERROR</code>.)  The
   1905  1.1.1.2.2.2  yamt exceptions are callbacks trigged by declarations in the document
   1906  1.1.1.2.2.2  yamt prologue, in which case they exact position reported is somewhere in the
   1907  1.1.1.2.2.2  yamt relevant markup, but not necessarily as meaningful as for other
   1908  1.1.1.2.2.2  yamt events.</p>
   1909  1.1.1.2.2.2  yamt 
   1910  1.1.1.2.2.2  yamt <p>The position reporting functions are accurate only outside of the
   1911  1.1.1.2.2.2  yamt DTD.  In other words, they usually return bogus information when
   1912  1.1.1.2.2.2  yamt called from within a DTD declaration handler.</p>
   1913  1.1.1.2.2.2  yamt 
   1914  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetErrorCode">
   1915  1.1.1.2.2.2  yamt enum XML_Error XMLCALL
   1916  1.1.1.2.2.2  yamt XML_GetErrorCode(XML_Parser p);
   1917  1.1.1.2.2.2  yamt </pre>
   1918  1.1.1.2.2.2  yamt <div class="fcndef">
   1919  1.1.1.2.2.2  yamt Return what type of error has occurred.
   1920  1.1.1.2.2.2  yamt </div>
   1921  1.1.1.2.2.2  yamt 
   1922  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ErrorString">
   1923  1.1.1.2.2.2  yamt const XML_LChar * XMLCALL
   1924  1.1.1.2.2.2  yamt XML_ErrorString(enum XML_Error code);
   1925  1.1.1.2.2.2  yamt </pre>
   1926  1.1.1.2.2.2  yamt <div class="fcndef">
   1927  1.1.1.2.2.2  yamt Return a string describing the error corresponding to code.
   1928  1.1.1.2.2.2  yamt The code should be one of the enums that can be returned from
   1929  1.1.1.2.2.2  yamt <code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>.
   1930  1.1.1.2.2.2  yamt </div>
   1931  1.1.1.2.2.2  yamt 
   1932  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetCurrentByteIndex">
   1933  1.1.1.2.2.2  yamt XML_Index XMLCALL
   1934  1.1.1.2.2.2  yamt XML_GetCurrentByteIndex(XML_Parser p);
   1935  1.1.1.2.2.2  yamt </pre>
   1936  1.1.1.2.2.2  yamt <div class="fcndef">
   1937  1.1.1.2.2.2  yamt Return the byte offset of the position.  This always corresponds to
   1938  1.1.1.2.2.2  yamt the values returned by <code><a href= "#XML_GetCurrentLineNumber"
   1939  1.1.1.2.2.2  yamt >XML_GetCurrentLineNumber</a></code> and <code><a href=
   1940  1.1.1.2.2.2  yamt "#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>.
   1941  1.1.1.2.2.2  yamt </div>
   1942  1.1.1.2.2.2  yamt 
   1943  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetCurrentLineNumber">
   1944  1.1.1.2.2.2  yamt XML_Size XMLCALL
   1945  1.1.1.2.2.2  yamt XML_GetCurrentLineNumber(XML_Parser p);
   1946  1.1.1.2.2.2  yamt </pre>
   1947  1.1.1.2.2.2  yamt <div class="fcndef">
   1948  1.1.1.2.2.2  yamt Return the line number of the position.  The first line is reported as
   1949  1.1.1.2.2.2  yamt <code>1</code>.
   1950  1.1.1.2.2.2  yamt </div>
   1951  1.1.1.2.2.2  yamt 
   1952  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetCurrentColumnNumber">
   1953  1.1.1.2.2.2  yamt XML_Size XMLCALL
   1954  1.1.1.2.2.2  yamt XML_GetCurrentColumnNumber(XML_Parser p);
   1955  1.1.1.2.2.2  yamt </pre>
   1956  1.1.1.2.2.2  yamt <div class="fcndef">
   1957  1.1.1.2.2.2  yamt Return the offset, from the beginning of the current line, of
   1958  1.1.1.2.2.2  yamt the position.
   1959  1.1.1.2.2.2  yamt </div>
   1960  1.1.1.2.2.2  yamt 
   1961  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetCurrentByteCount">
   1962  1.1.1.2.2.2  yamt int XMLCALL
   1963  1.1.1.2.2.2  yamt XML_GetCurrentByteCount(XML_Parser p);
   1964  1.1.1.2.2.2  yamt </pre>
   1965  1.1.1.2.2.2  yamt <div class="fcndef">
   1966  1.1.1.2.2.2  yamt Return the number of bytes in the current event. Returns
   1967  1.1.1.2.2.2  yamt <code>0</code> if the event is inside a reference to an internal
   1968  1.1.1.2.2.2  yamt entity and for the end-tag event for empty element tags (the later can
   1969  1.1.1.2.2.2  yamt be used to distinguish empty-element tags from empty elements using
   1970  1.1.1.2.2.2  yamt separate start and end tags).
   1971  1.1.1.2.2.2  yamt </div>
   1972  1.1.1.2.2.2  yamt 
   1973  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetInputContext">
   1974  1.1.1.2.2.2  yamt const char * XMLCALL
   1975  1.1.1.2.2.2  yamt XML_GetInputContext(XML_Parser p,
   1976  1.1.1.2.2.2  yamt                     int *offset,
   1977  1.1.1.2.2.2  yamt                     int *size);
   1978  1.1.1.2.2.2  yamt </pre>
   1979  1.1.1.2.2.2  yamt <div class="fcndef">
   1980  1.1.1.2.2.2  yamt 
   1981  1.1.1.2.2.2  yamt <p>Returns the parser's input buffer, sets the integer pointed at by
   1982  1.1.1.2.2.2  yamt <code>offset</code> to the offset within this buffer of the current
   1983  1.1.1.2.2.2  yamt parse position, and set the integer pointed at by <code>size</code> to
   1984  1.1.1.2.2.2  yamt the size of the returned buffer.</p>
   1985  1.1.1.2.2.2  yamt 
   1986  1.1.1.2.2.2  yamt <p>This should only be called from within a handler during an active
   1987  1.1.1.2.2.2  yamt parse and the returned buffer should only be referred to from within
   1988  1.1.1.2.2.2  yamt the handler that made the call. This input buffer contains the
   1989  1.1.1.2.2.2  yamt untranslated bytes of the input.</p>
   1990  1.1.1.2.2.2  yamt 
   1991  1.1.1.2.2.2  yamt <p>Only a limited amount of context is kept, so if the event
   1992  1.1.1.2.2.2  yamt triggering a call spans over a very large amount of input, the actual
   1993  1.1.1.2.2.2  yamt parse position may be before the beginning of the buffer.</p>
   1994  1.1.1.2.2.2  yamt 
   1995  1.1.1.2.2.2  yamt <p>If <code>XML_CONTEXT_BYTES</code> is not defined, this will always
   1996  1.1.1.2.2.2  yamt return NULL.</p>
   1997  1.1.1.2.2.2  yamt </div>
   1998  1.1.1.2.2.2  yamt 
   1999  1.1.1.2.2.2  yamt <h3><a name="miscellaneous">Miscellaneous functions</a></h3>
   2000  1.1.1.2.2.2  yamt 
   2001  1.1.1.2.2.2  yamt <p>The functions in this section either obtain state information from
   2002  1.1.1.2.2.2  yamt the parser or can be used to dynamicly set parser options.</p>
   2003  1.1.1.2.2.2  yamt 
   2004  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetUserData">
   2005  1.1.1.2.2.2  yamt void XMLCALL
   2006  1.1.1.2.2.2  yamt XML_SetUserData(XML_Parser p,
   2007  1.1.1.2.2.2  yamt                 void *userData);
   2008  1.1.1.2.2.2  yamt </pre>
   2009  1.1.1.2.2.2  yamt <div class="fcndef">
   2010  1.1.1.2.2.2  yamt This sets the user data pointer that gets passed to handlers.  It
   2011  1.1.1.2.2.2  yamt overwrites any previous value for this pointer. Note that the
   2012  1.1.1.2.2.2  yamt application is responsible for freeing the memory associated with
   2013  1.1.1.2.2.2  yamt <code>userData</code> when it is finished with the parser. So if you
   2014  1.1.1.2.2.2  yamt call this when there's already a pointer there, and you haven't freed
   2015  1.1.1.2.2.2  yamt the memory associated with it, then you've probably just leaked
   2016  1.1.1.2.2.2  yamt memory.
   2017  1.1.1.2.2.2  yamt </div>
   2018  1.1.1.2.2.2  yamt 
   2019  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetUserData">
   2020  1.1.1.2.2.2  yamt void * XMLCALL
   2021  1.1.1.2.2.2  yamt XML_GetUserData(XML_Parser p);
   2022  1.1.1.2.2.2  yamt </pre>
   2023  1.1.1.2.2.2  yamt <div class="fcndef">
   2024  1.1.1.2.2.2  yamt This returns the user data pointer that gets passed to handlers.
   2025  1.1.1.2.2.2  yamt It is actually implemented as a macro.
   2026  1.1.1.2.2.2  yamt </div>
   2027  1.1.1.2.2.2  yamt 
   2028  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_UseParserAsHandlerArg">
   2029  1.1.1.2.2.2  yamt void XMLCALL
   2030  1.1.1.2.2.2  yamt XML_UseParserAsHandlerArg(XML_Parser p);
   2031  1.1.1.2.2.2  yamt </pre>
   2032  1.1.1.2.2.2  yamt <div class="fcndef">
   2033  1.1.1.2.2.2  yamt After this is called, handlers receive the parser in their
   2034  1.1.1.2.2.2  yamt <code>userData</code> arguments.  The user data can still be obtained
   2035  1.1.1.2.2.2  yamt using the <code><a href= "#XML_GetUserData"
   2036  1.1.1.2.2.2  yamt >XML_GetUserData</a></code> function.
   2037  1.1.1.2.2.2  yamt </div>
   2038  1.1.1.2.2.2  yamt 
   2039  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetBase">
   2040  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   2041  1.1.1.2.2.2  yamt XML_SetBase(XML_Parser p,
   2042  1.1.1.2.2.2  yamt             const XML_Char *base);
   2043  1.1.1.2.2.2  yamt </pre>
   2044  1.1.1.2.2.2  yamt <div class="fcndef">
   2045  1.1.1.2.2.2  yamt Set the base to be used for resolving relative URIs in system
   2046  1.1.1.2.2.2  yamt identifiers.  The return value is <code>XML_STATUS_ERROR</code> if
   2047  1.1.1.2.2.2  yamt there's no memory to store base, otherwise it's
   2048  1.1.1.2.2.2  yamt <code>XML_STATUS_OK</code>.
   2049  1.1.1.2.2.2  yamt </div>
   2050  1.1.1.2.2.2  yamt 
   2051  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetBase">
   2052  1.1.1.2.2.2  yamt const XML_Char * XMLCALL
   2053  1.1.1.2.2.2  yamt XML_GetBase(XML_Parser p);
   2054  1.1.1.2.2.2  yamt </pre>
   2055  1.1.1.2.2.2  yamt <div class="fcndef">
   2056  1.1.1.2.2.2  yamt Return the base for resolving relative URIs.
   2057  1.1.1.2.2.2  yamt </div>
   2058  1.1.1.2.2.2  yamt 
   2059  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetSpecifiedAttributeCount">
   2060  1.1.1.2.2.2  yamt int XMLCALL
   2061  1.1.1.2.2.2  yamt XML_GetSpecifiedAttributeCount(XML_Parser p);
   2062  1.1.1.2.2.2  yamt </pre>
   2063  1.1.1.2.2.2  yamt <div class="fcndef">
   2064  1.1.1.2.2.2  yamt When attributes are reported to the start handler in the atts vector,
   2065  1.1.1.2.2.2  yamt attributes that were explicitly set in the element occur before any
   2066  1.1.1.2.2.2  yamt attributes that receive their value from default information in an
   2067  1.1.1.2.2.2  yamt ATTLIST declaration. This function returns the number of attributes
   2068  1.1.1.2.2.2  yamt that were explicitly set times two, thus giving the offset in the
   2069  1.1.1.2.2.2  yamt <code>atts</code> array passed to the start tag handler of the first
   2070  1.1.1.2.2.2  yamt attribute set due to defaults. It supplies information for the last
   2071  1.1.1.2.2.2  yamt call to a start handler. If called inside a start handler, then that
   2072  1.1.1.2.2.2  yamt means the current call.
   2073  1.1.1.2.2.2  yamt </div>
   2074  1.1.1.2.2.2  yamt 
   2075  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetIdAttributeIndex">
   2076  1.1.1.2.2.2  yamt int XMLCALL
   2077  1.1.1.2.2.2  yamt XML_GetIdAttributeIndex(XML_Parser p);
   2078  1.1.1.2.2.2  yamt </pre>
   2079  1.1.1.2.2.2  yamt <div class="fcndef">
   2080  1.1.1.2.2.2  yamt Returns the index of the ID attribute passed in the atts array in the
   2081  1.1.1.2.2.2  yamt last call to <code><a href= "#XML_StartElementHandler"
   2082  1.1.1.2.2.2  yamt >XML_StartElementHandler</a></code>, or -1 if there is no ID
   2083  1.1.1.2.2.2  yamt attribute. If called inside a start handler, then that means the
   2084  1.1.1.2.2.2  yamt current call.
   2085  1.1.1.2.2.2  yamt </div>
   2086  1.1.1.2.2.2  yamt 
   2087  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetAttributeInfo">
   2088  1.1.1.2.2.2  yamt const XML_AttrInfo * XMLCALL
   2089  1.1.1.2.2.2  yamt XML_GetAttributeInfo(XML_Parser parser);
   2090  1.1.1.2.2.2  yamt </pre>
   2091  1.1.1.2.2.2  yamt <pre class="signature">
   2092  1.1.1.2.2.2  yamt typedef struct {
   2093  1.1.1.2.2.2  yamt   XML_Index  nameStart;  /* Offset to beginning of the attribute name. */
   2094  1.1.1.2.2.2  yamt   XML_Index  nameEnd;    /* Offset after the attribute name's last byte. */
   2095  1.1.1.2.2.2  yamt   XML_Index  valueStart; /* Offset to beginning of the attribute value. */
   2096  1.1.1.2.2.2  yamt   XML_Index  valueEnd;   /* Offset after the attribute value's last byte. */
   2097  1.1.1.2.2.2  yamt } XML_AttrInfo;
   2098  1.1.1.2.2.2  yamt </pre>
   2099  1.1.1.2.2.2  yamt <div class="fcndef">
   2100  1.1.1.2.2.2  yamt Returns an array of <code>XML_AttrInfo</code> structures for the
   2101  1.1.1.2.2.2  yamt attribute/value pairs passed in the last call to the
   2102  1.1.1.2.2.2  yamt <code>XML_StartElementHandler</code> that were specified
   2103  1.1.1.2.2.2  yamt in the start-tag rather than defaulted. Each attribute/value pair counts
   2104  1.1.1.2.2.2  yamt as 1; thus the number of entries in the array is
   2105  1.1.1.2.2.2  yamt <code>XML_GetSpecifiedAttributeCount(parser) / 2</code>.
   2106  1.1.1.2.2.2  yamt </div>
   2107  1.1.1.2.2.2  yamt 
   2108  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetEncoding">
   2109  1.1.1.2.2.2  yamt enum XML_Status XMLCALL
   2110  1.1.1.2.2.2  yamt XML_SetEncoding(XML_Parser p,
   2111  1.1.1.2.2.2  yamt                 const XML_Char *encoding);
   2112  1.1.1.2.2.2  yamt </pre>
   2113  1.1.1.2.2.2  yamt <div class="fcndef">
   2114  1.1.1.2.2.2  yamt Set the encoding to be used by the parser. It is equivalent to
   2115  1.1.1.2.2.2  yamt passing a non-null encoding argument to the parser creation functions.
   2116  1.1.1.2.2.2  yamt It must not be called after <code><a href= "#XML_Parse"
   2117  1.1.1.2.2.2  yamt >XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer"
   2118  1.1.1.2.2.2  yamt >XML_ParseBuffer</a></code> have been called on the given parser.
   2119  1.1.1.2.2.2  yamt Returns <code>XML_STATUS_OK</code> on success or
   2120  1.1.1.2.2.2  yamt <code>XML_STATUS_ERROR</code> on error.
   2121  1.1.1.2.2.2  yamt </div>
   2122  1.1.1.2.2.2  yamt 
   2123  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetParamEntityParsing">
   2124  1.1.1.2.2.2  yamt int XMLCALL
   2125  1.1.1.2.2.2  yamt XML_SetParamEntityParsing(XML_Parser p,
   2126  1.1.1.2.2.2  yamt                           enum XML_ParamEntityParsing code);
   2127  1.1.1.2.2.2  yamt </pre>
   2128  1.1.1.2.2.2  yamt <div class="fcndef">
   2129  1.1.1.2.2.2  yamt This enables parsing of parameter entities, including the external
   2130  1.1.1.2.2.2  yamt parameter entity that is the external DTD subset, according to
   2131  1.1.1.2.2.2  yamt <code>code</code>.
   2132  1.1.1.2.2.2  yamt The choices for <code>code</code> are:
   2133  1.1.1.2.2.2  yamt <ul>
   2134  1.1.1.2.2.2  yamt <li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li>
   2135  1.1.1.2.2.2  yamt <li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li>
   2136  1.1.1.2.2.2  yamt <li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li>
   2137  1.1.1.2.2.2  yamt </ul>
   2138  1.1.1.2.2.2  yamt <b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after 
   2139  1.1.1.2.2.2  yamt <code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has
   2140  1.1.1.2.2.2  yamt no effect and will always return 0.
   2141  1.1.1.2.2.2  yamt </div>
   2142  1.1.1.2.2.2  yamt 
   2143  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetHashSalt">
   2144  1.1.1.2.2.2  yamt int XMLCALL
   2145  1.1.1.2.2.2  yamt XML_SetHashSalt(XML_Parser p,
   2146  1.1.1.2.2.2  yamt                 unsigned long hash_salt);
   2147  1.1.1.2.2.2  yamt </pre>
   2148  1.1.1.2.2.2  yamt <div class="fcndef">
   2149  1.1.1.2.2.2  yamt Sets the hash salt to use for internal hash calculations.
   2150  1.1.1.2.2.2  yamt Helps in preventing DoS attacks based on predicting hash
   2151  1.1.1.2.2.2  yamt function behavior. In order to have an effect this must be called
   2152  1.1.1.2.2.2  yamt before parsing has started. Returns 1 if successful, 0 when called
   2153  1.1.1.2.2.2  yamt after <code>XML_Parse</code> or <code>XML_ParseBuffer</code>.
   2154  1.1.1.2.2.2  yamt <p><b>Note:</b> This call is optional, as the parser will auto-generate a new
   2155  1.1.1.2.2.2  yamt random salt value if no value has been set at the start of parsing.</p>
   2156  1.1.1.2.2.2  yamt </div>
   2157  1.1.1.2.2.2  yamt 
   2158  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_UseForeignDTD">
   2159  1.1.1.2.2.2  yamt enum XML_Error XMLCALL
   2160  1.1.1.2.2.2  yamt XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD);
   2161  1.1.1.2.2.2  yamt </pre>
   2162  1.1.1.2.2.2  yamt <div class="fcndef">
   2163  1.1.1.2.2.2  yamt <p>This function allows an application to provide an external subset
   2164  1.1.1.2.2.2  yamt for the document type declaration for documents which do not specify
   2165  1.1.1.2.2.2  yamt an external subset of their own.  For documents which specify an
   2166  1.1.1.2.2.2  yamt external subset in their DOCTYPE declaration, the application-provided
   2167  1.1.1.2.2.2  yamt subset will be ignored.  If the document does not contain a DOCTYPE
   2168  1.1.1.2.2.2  yamt declaration at all and <code>useDTD</code> is true, the
   2169  1.1.1.2.2.2  yamt application-provided subset will be parsed, but the
   2170  1.1.1.2.2.2  yamt <code>startDoctypeDeclHandler</code> and
   2171  1.1.1.2.2.2  yamt <code>endDoctypeDeclHandler</code> functions, if set, will not be
   2172  1.1.1.2.2.2  yamt called.  The setting of parameter entity parsing, controlled using
   2173  1.1.1.2.2.2  yamt <code><a href= "#XML_SetParamEntityParsing"
   2174  1.1.1.2.2.2  yamt >XML_SetParamEntityParsing</a></code>, will be honored.</p>
   2175  1.1.1.2.2.2  yamt 
   2176  1.1.1.2.2.2  yamt <p>The application-provided external subset is read by calling the
   2177  1.1.1.2.2.2  yamt external entity reference handler set via <code><a href=
   2178  1.1.1.2.2.2  yamt "#XML_SetExternalEntityRefHandler"
   2179  1.1.1.2.2.2  yamt >XML_SetExternalEntityRefHandler</a></code> with both
   2180  1.1.1.2.2.2  yamt <code>publicId</code> and <code>systemId</code> set to NULL.</p>
   2181  1.1.1.2.2.2  yamt 
   2182  1.1.1.2.2.2  yamt <p>If this function is called after parsing has begun, it returns
   2183  1.1.1.2.2.2  yamt <code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores
   2184  1.1.1.2.2.2  yamt <code>useDTD</code>.  If called when Expat has been compiled without
   2185  1.1.1.2.2.2  yamt DTD support, it returns
   2186  1.1.1.2.2.2  yamt <code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>.  Otherwise, it
   2187  1.1.1.2.2.2  yamt returns <code>XML_ERROR_NONE</code>.</p>
   2188  1.1.1.2.2.2  yamt 
   2189  1.1.1.2.2.2  yamt <p><b>Note:</b> For the purpose of checking WFC: Entity Declared, passing
   2190  1.1.1.2.2.2  yamt <code>useDTD == XML_TRUE</code> will make the parser behave as if
   2191  1.1.1.2.2.2  yamt the document had a DTD with an external subset. This holds true even if
   2192  1.1.1.2.2.2  yamt the external entity reference handler returns without action.</p>
   2193  1.1.1.2.2.2  yamt </div>
   2194  1.1.1.2.2.2  yamt 
   2195  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_SetReturnNSTriplet">
   2196  1.1.1.2.2.2  yamt void XMLCALL
   2197  1.1.1.2.2.2  yamt XML_SetReturnNSTriplet(XML_Parser parser,
   2198  1.1.1.2.2.2  yamt                        int        do_nst);
   2199  1.1.1.2.2.2  yamt </pre>
   2200  1.1.1.2.2.2  yamt <div class="fcndef">
   2201  1.1.1.2.2.2  yamt <p>
   2202  1.1.1.2.2.2  yamt This function only has an effect when using a parser created with
   2203  1.1.1.2.2.2  yamt <code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>,
   2204  1.1.1.2.2.2  yamt i.e. when namespace processing is in effect. The <code>do_nst</code>
   2205  1.1.1.2.2.2  yamt sets whether or not prefixes are returned with names qualified with a
   2206  1.1.1.2.2.2  yamt namespace prefix. If this function is called with <code>do_nst</code>
   2207  1.1.1.2.2.2  yamt non-zero, then afterwards namespace qualified names (that is qualified
   2208  1.1.1.2.2.2  yamt with a prefix as opposed to belonging to a default namespace) are
   2209  1.1.1.2.2.2  yamt returned as a triplet with the three parts separated by the namespace
   2210  1.1.1.2.2.2  yamt separator specified when the parser was created.  The order of
   2211  1.1.1.2.2.2  yamt returned parts is URI, local name, and prefix.</p> <p>If
   2212  1.1.1.2.2.2  yamt <code>do_nst</code> is zero, then namespaces are reported in the
   2213  1.1.1.2.2.2  yamt default manner, URI then local_name separated by the namespace
   2214  1.1.1.2.2.2  yamt separator.</p>
   2215  1.1.1.2.2.2  yamt </div>
   2216  1.1.1.2.2.2  yamt 
   2217  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_DefaultCurrent">
   2218  1.1.1.2.2.2  yamt void XMLCALL
   2219  1.1.1.2.2.2  yamt XML_DefaultCurrent(XML_Parser parser);
   2220  1.1.1.2.2.2  yamt </pre>
   2221  1.1.1.2.2.2  yamt <div class="fcndef">
   2222  1.1.1.2.2.2  yamt This can be called within a handler for a start element, end element,
   2223  1.1.1.2.2.2  yamt processing instruction or character data.  It causes the corresponding
   2224  1.1.1.2.2.2  yamt markup to be passed to the default handler set by <code><a
   2225  1.1.1.2.2.2  yamt href="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or
   2226  1.1.1.2.2.2  yamt <code><a href="#XML_SetDefaultHandlerExpand"
   2227  1.1.1.2.2.2  yamt >XML_SetDefaultHandlerExpand</a></code>.  It does nothing if there is
   2228  1.1.1.2.2.2  yamt not a default handler.
   2229  1.1.1.2.2.2  yamt </div>
   2230  1.1.1.2.2.2  yamt 
   2231  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ExpatVersion">
   2232  1.1.1.2.2.2  yamt XML_LChar * XMLCALL
   2233  1.1.1.2.2.2  yamt XML_ExpatVersion();
   2234  1.1.1.2.2.2  yamt </pre>
   2235  1.1.1.2.2.2  yamt <div class="fcndef">
   2236  1.1.1.2.2.2  yamt Return the library version as a string (e.g. <code>"expat_1.95.1"</code>).
   2237  1.1.1.2.2.2  yamt </div>
   2238  1.1.1.2.2.2  yamt 
   2239  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_ExpatVersionInfo">
   2240  1.1.1.2.2.2  yamt struct XML_Expat_Version XMLCALL
   2241  1.1.1.2.2.2  yamt XML_ExpatVersionInfo();
   2242  1.1.1.2.2.2  yamt </pre>
   2243  1.1.1.2.2.2  yamt <pre class="signature">
   2244  1.1.1.2.2.2  yamt typedef struct {
   2245  1.1.1.2.2.2  yamt   int major;
   2246  1.1.1.2.2.2  yamt   int minor;
   2247  1.1.1.2.2.2  yamt   int micro;
   2248  1.1.1.2.2.2  yamt } XML_Expat_Version;
   2249  1.1.1.2.2.2  yamt </pre>
   2250  1.1.1.2.2.2  yamt <div class="fcndef">
   2251  1.1.1.2.2.2  yamt Return the library version information as a structure.
   2252  1.1.1.2.2.2  yamt Some macros are also defined that support compile-time tests of the
   2253  1.1.1.2.2.2  yamt library version:
   2254  1.1.1.2.2.2  yamt <ul>
   2255  1.1.1.2.2.2  yamt <li><code>XML_MAJOR_VERSION</code></li>
   2256  1.1.1.2.2.2  yamt <li><code>XML_MINOR_VERSION</code></li>
   2257  1.1.1.2.2.2  yamt <li><code>XML_MICRO_VERSION</code></li>
   2258  1.1.1.2.2.2  yamt </ul>
   2259  1.1.1.2.2.2  yamt Testing these constants is currently the best way to determine if
   2260  1.1.1.2.2.2  yamt particular parts of the Expat API are available.
   2261  1.1.1.2.2.2  yamt </div>
   2262  1.1.1.2.2.2  yamt 
   2263  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_GetFeatureList">
   2264  1.1.1.2.2.2  yamt const XML_Feature * XMLCALL
   2265  1.1.1.2.2.2  yamt XML_GetFeatureList();
   2266  1.1.1.2.2.2  yamt </pre>
   2267  1.1.1.2.2.2  yamt <pre class="signature">
   2268  1.1.1.2.2.2  yamt enum XML_FeatureEnum {
   2269  1.1.1.2.2.2  yamt   XML_FEATURE_END = 0,
   2270  1.1.1.2.2.2  yamt   XML_FEATURE_UNICODE,
   2271  1.1.1.2.2.2  yamt   XML_FEATURE_UNICODE_WCHAR_T,
   2272  1.1.1.2.2.2  yamt   XML_FEATURE_DTD,
   2273  1.1.1.2.2.2  yamt   XML_FEATURE_CONTEXT_BYTES,
   2274  1.1.1.2.2.2  yamt   XML_FEATURE_MIN_SIZE,
   2275  1.1.1.2.2.2  yamt   XML_FEATURE_SIZEOF_XML_CHAR,
   2276  1.1.1.2.2.2  yamt   XML_FEATURE_SIZEOF_XML_LCHAR,
   2277  1.1.1.2.2.2  yamt   XML_FEATURE_NS,
   2278  1.1.1.2.2.2  yamt   XML_FEATURE_LARGE_SIZE
   2279  1.1.1.2.2.2  yamt };
   2280  1.1.1.2.2.2  yamt 
   2281  1.1.1.2.2.2  yamt typedef struct {
   2282  1.1.1.2.2.2  yamt   enum XML_FeatureEnum  feature;
   2283  1.1.1.2.2.2  yamt   XML_LChar            *name;
   2284  1.1.1.2.2.2  yamt   long int              value;
   2285  1.1.1.2.2.2  yamt } XML_Feature;
   2286  1.1.1.2.2.2  yamt </pre>
   2287  1.1.1.2.2.2  yamt <div class="fcndef">
   2288  1.1.1.2.2.2  yamt <p>Returns a list of "feature" records, providing details on how
   2289  1.1.1.2.2.2  yamt Expat was configured at compile time.  Most applications should not
   2290  1.1.1.2.2.2  yamt need to worry about this, but this information is otherwise not
   2291  1.1.1.2.2.2  yamt available from Expat.  This function allows code that does need to
   2292  1.1.1.2.2.2  yamt check these features to do so at runtime.</p>
   2293  1.1.1.2.2.2  yamt 
   2294  1.1.1.2.2.2  yamt <p>The return value is an array of <code>XML_Feature</code>,
   2295  1.1.1.2.2.2  yamt terminated by a record with a <code>feature</code> of
   2296  1.1.1.2.2.2  yamt <code>XML_FEATURE_END</code> and <code>name</code> of NULL,
   2297  1.1.1.2.2.2  yamt identifying the feature-test macros Expat was compiled with.  Since an
   2298  1.1.1.2.2.2  yamt application that requires this kind of information needs to determine
   2299  1.1.1.2.2.2  yamt the type of character the <code>name</code> points to, records for the
   2300  1.1.1.2.2.2  yamt <code>XML_FEATURE_SIZEOF_XML_CHAR</code> and
   2301  1.1.1.2.2.2  yamt <code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the
   2302  1.1.1.2.2.2  yamt beginning of the list, followed by <code>XML_FEATURE_UNICODE</code>
   2303  1.1.1.2.2.2  yamt and <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at
   2304  1.1.1.2.2.2  yamt all.</p>
   2305  1.1.1.2.2.2  yamt 
   2306  1.1.1.2.2.2  yamt <p>Some features have an associated value.  If there isn't an
   2307  1.1.1.2.2.2  yamt associated value, the <code>value</code> field is set to 0.  At this
   2308  1.1.1.2.2.2  yamt time, the following features have been defined to have values:</p>
   2309  1.1.1.2.2.2  yamt 
   2310  1.1.1.2.2.2  yamt <dl>
   2311  1.1.1.2.2.2  yamt   <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt>
   2312  1.1.1.2.2.2  yamt   <dd>The number of bytes occupied by one <code>XML_Char</code>
   2313  1.1.1.2.2.2  yamt   character.</dd>
   2314  1.1.1.2.2.2  yamt   <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt>
   2315  1.1.1.2.2.2  yamt   <dd>The number of bytes occupied by one <code>XML_LChar</code>
   2316  1.1.1.2.2.2  yamt   character.</dd>
   2317  1.1.1.2.2.2  yamt   <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt>
   2318  1.1.1.2.2.2  yamt   <dd>The maximum number of characters of context which can be
   2319  1.1.1.2.2.2  yamt   reported by <code><a href= "#XML_GetInputContext"
   2320  1.1.1.2.2.2  yamt   >XML_GetInputContext</a></code>.</dd>
   2321  1.1.1.2.2.2  yamt </dl>
   2322  1.1.1.2.2.2  yamt </div>
   2323  1.1.1.2.2.2  yamt 
   2324  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_FreeContentModel">
   2325  1.1.1.2.2.2  yamt void XMLCALL
   2326  1.1.1.2.2.2  yamt XML_FreeContentModel(XML_Parser parser, XML_Content *model);
   2327  1.1.1.2.2.2  yamt </pre>
   2328  1.1.1.2.2.2  yamt <div class="fcndef">
   2329  1.1.1.2.2.2  yamt Function to deallocate the <code>model</code> argument passed to the
   2330  1.1.1.2.2.2  yamt <code>XML_ElementDeclHandler</code> callback set using <code><a
   2331  1.1.1.2.2.2  yamt href="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>.
   2332  1.1.1.2.2.2  yamt This function should not be used for any other purpose.
   2333  1.1.1.2.2.2  yamt </div>
   2334  1.1.1.2.2.2  yamt 
   2335  1.1.1.2.2.2  yamt <p>The following functions allow external code to share the memory
   2336  1.1.1.2.2.2  yamt allocator an <code>XML_Parser</code> has been configured to use.  This
   2337  1.1.1.2.2.2  yamt is especially useful for third-party libraries that interact with a
   2338  1.1.1.2.2.2  yamt parser object created by application code, or heavily layered
   2339  1.1.1.2.2.2  yamt applications.  This can be essential when using dynamically loaded
   2340  1.1.1.2.2.2  yamt libraries which use different C standard libraries (this can happen on
   2341  1.1.1.2.2.2  yamt Windows, at least).</p>
   2342  1.1.1.2.2.2  yamt 
   2343  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_MemMalloc">
   2344  1.1.1.2.2.2  yamt void * XMLCALL
   2345  1.1.1.2.2.2  yamt XML_MemMalloc(XML_Parser parser, size_t size);
   2346  1.1.1.2.2.2  yamt </pre>
   2347  1.1.1.2.2.2  yamt <div class="fcndef">
   2348  1.1.1.2.2.2  yamt Allocate <code>size</code> bytes of memory using the allocator the
   2349  1.1.1.2.2.2  yamt <code>parser</code> object has been configured to use.  Returns a
   2350  1.1.1.2.2.2  yamt pointer to the memory or NULL on failure.  Memory allocated in this
   2351  1.1.1.2.2.2  yamt way must be freed using <code><a href="#XML_MemFree"
   2352  1.1.1.2.2.2  yamt >XML_MemFree</a></code>.
   2353  1.1.1.2.2.2  yamt </div>
   2354  1.1.1.2.2.2  yamt 
   2355  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_MemRealloc">
   2356  1.1.1.2.2.2  yamt void * XMLCALL
   2357  1.1.1.2.2.2  yamt XML_MemRealloc(XML_Parser parser, void *ptr, size_t size);
   2358  1.1.1.2.2.2  yamt </pre>
   2359  1.1.1.2.2.2  yamt <div class="fcndef">
   2360  1.1.1.2.2.2  yamt Allocate <code>size</code> bytes of memory using the allocator the
   2361  1.1.1.2.2.2  yamt <code>parser</code> object has been configured to use.
   2362  1.1.1.2.2.2  yamt <code>ptr</code> must point to a block of memory allocated by <code><a
   2363  1.1.1.2.2.2  yamt href="#XML_MemMalloc" >XML_MemMalloc</a></code> or
   2364  1.1.1.2.2.2  yamt <code>XML_MemRealloc</code>, or be NULL.  This function tries to
   2365  1.1.1.2.2.2  yamt expand the block pointed to by <code>ptr</code> if possible.  Returns
   2366  1.1.1.2.2.2  yamt a pointer to the memory or NULL on failure.  On success, the original
   2367  1.1.1.2.2.2  yamt block has either been expanded or freed.  On failure, the original
   2368  1.1.1.2.2.2  yamt block has not been freed; the caller is responsible for freeing the
   2369  1.1.1.2.2.2  yamt original block.  Memory allocated in this way must be freed using
   2370  1.1.1.2.2.2  yamt <code><a href="#XML_MemFree"
   2371  1.1.1.2.2.2  yamt >XML_MemFree</a></code>.
   2372  1.1.1.2.2.2  yamt </div>
   2373  1.1.1.2.2.2  yamt 
   2374  1.1.1.2.2.2  yamt <pre class="fcndec" id="XML_MemFree">
   2375  1.1.1.2.2.2  yamt void XMLCALL
   2376  1.1.1.2.2.2  yamt XML_MemFree(XML_Parser parser, void *ptr);
   2377  1.1.1.2.2.2  yamt </pre>
   2378  1.1.1.2.2.2  yamt <div class="fcndef">
   2379  1.1.1.2.2.2  yamt Free a block of memory pointed to by <code>ptr</code>.  The block must
   2380  1.1.1.2.2.2  yamt have been allocated by <code><a href="#XML_MemMalloc"
   2381  1.1.1.2.2.2  yamt >XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be NULL.
   2382  1.1.1.2.2.2  yamt </div>
   2383  1.1.1.2.2.2  yamt 
   2384  1.1.1.2.2.2  yamt <hr />
   2385  1.1.1.2.2.2  yamt <p><a href="http://validator.w3.org/check/referer"><img
   2386  1.1.1.2.2.2  yamt         src="valid-xhtml10.png" alt="Valid XHTML 1.0!"
   2387  1.1.1.2.2.2  yamt         height="31" width="88" class="noborder" /></a></p>
   2388  1.1.1.2.2.2  yamt </div>
   2389  1.1.1.2.2.2  yamt </body>
   2390  1.1.1.2.2.2  yamt </html>
   2391