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