contrib/expat/doc/reference.html

   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@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@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>