15bb6a25fSPoul-Henning Kamp<?xml version="1.0" encoding="iso-8859-1"?>
25bb6a25fSPoul-Henning Kamp<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
35bb6a25fSPoul-Henning Kamp                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
45bb6a25fSPoul-Henning Kamp<html>
55bb6a25fSPoul-Henning Kamp<head>
65bb6a25fSPoul-Henning Kamp<!-- Copyright 1999,2000 Clark Cooper <[email protected]>
75bb6a25fSPoul-Henning Kamp     All rights reserved.
85bb6a25fSPoul-Henning Kamp     This is free software. You may distribute or modify according to
95bb6a25fSPoul-Henning Kamp     the terms of the MIT/X License -->
105bb6a25fSPoul-Henning Kamp  <title>Expat XML Parser</title>
115bb6a25fSPoul-Henning Kamp  <meta name="author" content="Clark Cooper, [email protected]" />
125bb6a25fSPoul-Henning Kamp  <meta http-equiv="Content-Style-Type" content="text/css" />
135bb6a25fSPoul-Henning Kamp  <link href="style.css" rel="stylesheet" type="text/css" />
145bb6a25fSPoul-Henning Kamp</head>
155bb6a25fSPoul-Henning Kamp<body>
16*220ed979SColeman Kane  <table cellspacing="0" cellpadding="0" width="100%">
17*220ed979SColeman Kane    <tr>
18*220ed979SColeman Kane      <td class="corner"><img src="expat.png" alt="(Expat logo)" /></td>
19*220ed979SColeman Kane      <td class="banner"><h1>The Expat XML Parser</h1></td>
20*220ed979SColeman Kane    </tr>
21*220ed979SColeman Kane    <tr>
22*220ed979SColeman Kane      <td class="releaseno">Release 2.0.1</td>
23*220ed979SColeman Kane      <td></td>
24*220ed979SColeman Kane    </tr>
25*220ed979SColeman Kane  </table>
26*220ed979SColeman Kane<div class="content">
275bb6a25fSPoul-Henning Kamp
285bb6a25fSPoul-Henning Kamp<p>Expat is a library, written in C, for parsing XML documents. It's
295bb6a25fSPoul-Henning Kampthe underlying XML parser for the open source Mozilla project, Perl's
305bb6a25fSPoul-Henning Kamp<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and
315bb6a25fSPoul-Henning Kampother open-source XML parsers.</p>
325bb6a25fSPoul-Henning Kamp
335bb6a25fSPoul-Henning Kamp<p>This library is the creation of James Clark, who's also given us
345bb6a25fSPoul-Henning Kampgroff (an nroff look-alike), Jade (an implemention of ISO's DSSSL
355bb6a25fSPoul-Henning Kampstylesheet language for SGML), XP (a Java XML parser package), XT (a
365bb6a25fSPoul-Henning KampJava XSL engine).  James was also the technical lead on the XML
375bb6a25fSPoul-Henning KampWorking Group at W3C that produced the XML specification.</p>
385bb6a25fSPoul-Henning Kamp
395bb6a25fSPoul-Henning Kamp<p>This is free software, licensed under the <a
405bb6a25fSPoul-Henning Kamphref="../COPYING">MIT/X Consortium license</a>. You may download it
415bb6a25fSPoul-Henning Kampfrom <a href="http://www.libexpat.org/">the Expat home page</a>.
425bb6a25fSPoul-Henning Kamp</p>
435bb6a25fSPoul-Henning Kamp
44*220ed979SColeman Kane<p>The bulk of this document was originally commissioned as an article
45*220ed979SColeman Kaneby <a href="http://www.xml.com/">XML.com</a>. They graciously allowed
46*220ed979SColeman KaneClark Cooper to retain copyright and to distribute it with Expat.
47*220ed979SColeman KaneThis version has been substantially extended to include documentation
48*220ed979SColeman Kaneon features which have been added since the original article was
49*220ed979SColeman Kanepublished, and additional information on using the original
50*220ed979SColeman Kaneinterface.</p>
515bb6a25fSPoul-Henning Kamp
525bb6a25fSPoul-Henning Kamp<hr />
535bb6a25fSPoul-Henning Kamp<h2>Table of Contents</h2>
545bb6a25fSPoul-Henning Kamp<ul>
555bb6a25fSPoul-Henning Kamp  <li><a href="#overview">Overview</a></li>
565bb6a25fSPoul-Henning Kamp  <li><a href="#building">Building and Installing</a></li>
575bb6a25fSPoul-Henning Kamp  <li><a href="#using">Using Expat</a></li>
585bb6a25fSPoul-Henning Kamp  <li><a href="#reference">Reference</a>
595bb6a25fSPoul-Henning Kamp  <ul>
605bb6a25fSPoul-Henning Kamp    <li><a href="#creation">Parser Creation Functions</a>
615bb6a25fSPoul-Henning Kamp    <ul>
625bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li>
635bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li>
645bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li>
655bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li>
665bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParserFree">XML_ParserFree</a></li>
675bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParserReset">XML_ParserReset</a></li>
685bb6a25fSPoul-Henning Kamp    </ul>
695bb6a25fSPoul-Henning Kamp    </li>
705bb6a25fSPoul-Henning Kamp    <li><a href="#parsing">Parsing Functions</a>
715bb6a25fSPoul-Henning Kamp    <ul>
725bb6a25fSPoul-Henning Kamp      <li><a href="#XML_Parse">XML_Parse</a></li>
735bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li>
745bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li>
75*220ed979SColeman Kane      <li><a href="#XML_StopParser">XML_StopParser</a></li>
76*220ed979SColeman Kane      <li><a href="#XML_ResumeParser">XML_ResumeParser</a></li>
77*220ed979SColeman Kane      <li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li>
785bb6a25fSPoul-Henning Kamp    </ul>
795bb6a25fSPoul-Henning Kamp    </li>
805bb6a25fSPoul-Henning Kamp    <li><a href="#setting">Handler Setting Functions</a>
815bb6a25fSPoul-Henning Kamp    <ul>
825bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li>
835bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li>
845bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li>
855bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li>
865bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li>
875bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li>
885bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li>
895bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li>
905bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li>
915bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li>
925bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li>
935bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li>
94*220ed979SColeman Kane      <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li>
955bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li>
965bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li>
975bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li>
985bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li>
995bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li>
1005bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li>
1015bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li>
1025bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li>
1035bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li>
1045bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li>
1055bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li>
1065bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li>
1075bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li>
1085bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li>
1095bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li>
1105bb6a25fSPoul-Henning Kamp    </ul>
1115bb6a25fSPoul-Henning Kamp    </li>
1125bb6a25fSPoul-Henning Kamp    <li><a href="#position">Parse Position and Error Reporting Functions</a>
1135bb6a25fSPoul-Henning Kamp    <ul>
1145bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li>
1155bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ErrorString">XML_ErrorString</a></li>
1165bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li>
1175bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li>
1185bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li>
1195bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li>
1205bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li>
1215bb6a25fSPoul-Henning Kamp    </ul>
1225bb6a25fSPoul-Henning Kamp    </li>
1235bb6a25fSPoul-Henning Kamp    <li><a href="#miscellaneous">Miscellaneous Functions</a>
1245bb6a25fSPoul-Henning Kamp    <ul>
1255bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetUserData">XML_SetUserData</a></li>
1265bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetUserData">XML_GetUserData</a></li>
1275bb6a25fSPoul-Henning Kamp      <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li>
1285bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetBase">XML_SetBase</a></li>
1295bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetBase">XML_GetBase</a></li>
1305bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li>
1315bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li>
1325bb6a25fSPoul-Henning Kamp      <li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li>
1335bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li>
1345bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li>
1355bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li>
1365bb6a25fSPoul-Henning Kamp      <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li>
1375bb6a25fSPoul-Henning Kamp      <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li>
1385bb6a25fSPoul-Henning Kamp      <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li>
1395bb6a25fSPoul-Henning Kamp      <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li>
140*220ed979SColeman Kane      <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li>
141*220ed979SColeman Kane      <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li>
142*220ed979SColeman Kane      <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li>
143*220ed979SColeman Kane      <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li>
1445bb6a25fSPoul-Henning Kamp      <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li>
1455bb6a25fSPoul-Henning Kamp      <li><a href="#XML_MemFree">XML_MemFree</a></li>
1465bb6a25fSPoul-Henning Kamp    </ul>
1475bb6a25fSPoul-Henning Kamp    </li>
1485bb6a25fSPoul-Henning Kamp  </ul>
1495bb6a25fSPoul-Henning Kamp  </li>
1505bb6a25fSPoul-Henning Kamp</ul>
1515bb6a25fSPoul-Henning Kamp
1525bb6a25fSPoul-Henning Kamp<hr />
1535bb6a25fSPoul-Henning Kamp<h2><a name="overview">Overview</a></h2>
1545bb6a25fSPoul-Henning Kamp
1555bb6a25fSPoul-Henning Kamp<p>Expat is a stream-oriented parser. You register callback (or
1565bb6a25fSPoul-Henning Kamphandler) functions with the parser and then start feeding it the
1575bb6a25fSPoul-Henning Kampdocument.  As the parser recognizes parts of the document, it will
1585bb6a25fSPoul-Henning Kampcall the appropriate handler for that part (if you've registered one.)
1595bb6a25fSPoul-Henning KampThe document is fed to the parser in pieces, so you can start parsing
1605bb6a25fSPoul-Henning Kampbefore you have all the document. This also allows you to parse really
1615bb6a25fSPoul-Henning Kamphuge documents that won't fit into memory.</p>
1625bb6a25fSPoul-Henning Kamp
1635bb6a25fSPoul-Henning Kamp<p>Expat can be intimidating due to the many kinds of handlers and
1645bb6a25fSPoul-Henning Kampoptions you can set. But you only need to learn four functions in
1655bb6a25fSPoul-Henning Kamporder to do 90% of what you'll want to do with it:</p>
1665bb6a25fSPoul-Henning Kamp
1675bb6a25fSPoul-Henning Kamp<dl>
1685bb6a25fSPoul-Henning Kamp
1695bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_ParserCreate"
1705bb6a25fSPoul-Henning Kamp             >XML_ParserCreate</a></code></dt>
1715bb6a25fSPoul-Henning Kamp  <dd>Create a new parser object.</dd>
1725bb6a25fSPoul-Henning Kamp
1735bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_SetElementHandler"
1745bb6a25fSPoul-Henning Kamp             >XML_SetElementHandler</a></code></dt>
1755bb6a25fSPoul-Henning Kamp  <dd>Set handlers for start and end tags.</dd>
1765bb6a25fSPoul-Henning Kamp
1775bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_SetCharacterDataHandler"
1785bb6a25fSPoul-Henning Kamp             >XML_SetCharacterDataHandler</a></code></dt>
1795bb6a25fSPoul-Henning Kamp  <dd>Set handler for text.</dd>
1805bb6a25fSPoul-Henning Kamp
1815bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_Parse"
1825bb6a25fSPoul-Henning Kamp             >XML_Parse</a></code></dt>
1835bb6a25fSPoul-Henning Kamp  <dd>Pass a buffer full of document to the parser</dd>
1845bb6a25fSPoul-Henning Kamp</dl>
1855bb6a25fSPoul-Henning Kamp
1865bb6a25fSPoul-Henning Kamp<p>These functions and others are described in the <a
1875bb6a25fSPoul-Henning Kamphref="#reference">reference</a> part of this document. The reference
1885bb6a25fSPoul-Henning Kampsection also describes in detail the parameters passed to the
1895bb6a25fSPoul-Henning Kampdifferent types of handlers.</p>
1905bb6a25fSPoul-Henning Kamp
1915bb6a25fSPoul-Henning Kamp<p>Let's look at a very simple example program that only uses 3 of the
1925bb6a25fSPoul-Henning Kampabove functions (it doesn't need to set a character handler.) The
1935bb6a25fSPoul-Henning Kampprogram <a href="../examples/outline.c">outline.c</a> prints an
1945bb6a25fSPoul-Henning Kampelement outline, indenting child elements to distinguish them from the
1955bb6a25fSPoul-Henning Kampparent element that contains them. The start handler does all the
1965bb6a25fSPoul-Henning Kampwork.  It prints two indenting spaces for every level of ancestor
1975bb6a25fSPoul-Henning Kampelements, then it prints the element and attribute
1985bb6a25fSPoul-Henning Kampinformation. Finally it increments the global <code>Depth</code>
1995bb6a25fSPoul-Henning Kampvariable.</p>
2005bb6a25fSPoul-Henning Kamp
2015bb6a25fSPoul-Henning Kamp<pre class="eg">
202*220ed979SColeman Kaneint Depth;
2035bb6a25fSPoul-Henning Kamp
2045bb6a25fSPoul-Henning Kampvoid XMLCALL
2055bb6a25fSPoul-Henning Kampstart(void *data, const char *el, const char **attr) {
2065bb6a25fSPoul-Henning Kamp  int i;
2075bb6a25fSPoul-Henning Kamp
2085bb6a25fSPoul-Henning Kamp  for (i = 0; i &lt; Depth; i++)
2095bb6a25fSPoul-Henning Kamp    printf("  ");
2105bb6a25fSPoul-Henning Kamp
2115bb6a25fSPoul-Henning Kamp  printf("%s", el);
2125bb6a25fSPoul-Henning Kamp
2135bb6a25fSPoul-Henning Kamp  for (i = 0; attr[i]; i += 2) {
2145bb6a25fSPoul-Henning Kamp    printf(" %s='%s'", attr[i], attr[i + 1]);
2155bb6a25fSPoul-Henning Kamp  }
2165bb6a25fSPoul-Henning Kamp
2175bb6a25fSPoul-Henning Kamp  printf("\n");
2185bb6a25fSPoul-Henning Kamp  Depth++;
2195bb6a25fSPoul-Henning Kamp}  /* End of start handler */
2205bb6a25fSPoul-Henning Kamp</pre>
2215bb6a25fSPoul-Henning Kamp
2225bb6a25fSPoul-Henning Kamp<p>The end tag simply does the bookkeeping work of decrementing
223*220ed979SColeman Kane<code>Depth</code>.</p>
2245bb6a25fSPoul-Henning Kamp<pre class="eg">
2255bb6a25fSPoul-Henning Kampvoid XMLCALL
2265bb6a25fSPoul-Henning Kampend(void *data, const char *el) {
2275bb6a25fSPoul-Henning Kamp  Depth--;
2285bb6a25fSPoul-Henning Kamp}  /* End of end handler */
229*220ed979SColeman Kane</pre>
230*220ed979SColeman Kane
231*220ed979SColeman Kane<p>Note the <code>XMLCALL</code> annotation used for the callbacks.
232*220ed979SColeman KaneThis is used to ensure that the Expat and the callbacks are using the
233*220ed979SColeman Kanesame calling convention in case the compiler options used for Expat
234*220ed979SColeman Kaneitself and the client code are different.  Expat tries not to care
235*220ed979SColeman Kanewhat the default calling convention is, though it may require that it
236*220ed979SColeman Kanebe compiled with a default convention of "cdecl" on some platforms.
237*220ed979SColeman KaneFor code which uses Expat, however, the calling convention is
238*220ed979SColeman Kanespecified by the <code>XMLCALL</code> annotation on most platforms;
239*220ed979SColeman Kanecallbacks should be defined using this annotation.</p>
240*220ed979SColeman Kane
241*220ed979SColeman Kane<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but
242*220ed979SColeman Kaneexisting working Expat applications don't need to add it (since they
243*220ed979SColeman Kaneare already using the "cdecl" calling convention, or they wouldn't be
244*220ed979SColeman Kaneworking).  The annotation is only needed if the default calling
245*220ed979SColeman Kaneconvention may be something other than "cdecl".  To use the annotation
246*220ed979SColeman Kanesafely with older versions of Expat, you can conditionally define it
247*220ed979SColeman Kane<em>after</em> including Expat's header file:</p>
248*220ed979SColeman Kane
249*220ed979SColeman Kane<pre class="eg">
250*220ed979SColeman Kane#include &lt;expat.h&gt;
251*220ed979SColeman Kane
252*220ed979SColeman Kane#ifndef XMLCALL
253*220ed979SColeman Kane#if defined(_MSC_EXTENSIONS) &amp;&amp; !defined(__BEOS__) &amp;&amp; !defined(__CYGWIN__)
254*220ed979SColeman Kane#define XMLCALL __cdecl
255*220ed979SColeman Kane#elif defined(__GNUC__)
256*220ed979SColeman Kane#define XMLCALL __attribute__((cdecl))
257*220ed979SColeman Kane#else
258*220ed979SColeman Kane#define XMLCALL
259*220ed979SColeman Kane#endif
260*220ed979SColeman Kane#endif
2615bb6a25fSPoul-Henning Kamp</pre>
2625bb6a25fSPoul-Henning Kamp
2635bb6a25fSPoul-Henning Kamp<p>After creating the parser, the main program just has the job of
2645bb6a25fSPoul-Henning Kampshoveling the document to the parser so that it can do its work.</p>
2655bb6a25fSPoul-Henning Kamp
2665bb6a25fSPoul-Henning Kamp<hr />
2675bb6a25fSPoul-Henning Kamp<h2><a name="building">Building and Installing Expat</a></h2>
2685bb6a25fSPoul-Henning Kamp
2695bb6a25fSPoul-Henning Kamp<p>The Expat distribution comes as a compressed (with GNU gzip) tar
2705bb6a25fSPoul-Henning Kampfile.  You may download the latest version from <a href=
2715bb6a25fSPoul-Henning Kamp"http://sourceforge.net/projects/expat/" >Source Forge</a>.  After
2725bb6a25fSPoul-Henning Kampunpacking this, cd into the directory. Then follow either the Win32
2735bb6a25fSPoul-Henning Kampdirections or Unix directions below.</p>
2745bb6a25fSPoul-Henning Kamp
2755bb6a25fSPoul-Henning Kamp<h3>Building under Win32</h3>
2765bb6a25fSPoul-Henning Kamp
2775bb6a25fSPoul-Henning Kamp<p>If you're using the GNU compiler under cygwin, follow the Unix
2785bb6a25fSPoul-Henning Kampdirections in the next section. Otherwise if you have Microsoft's
2795bb6a25fSPoul-Henning KampDeveloper Studio installed, then from Windows Explorer double-click on
2805bb6a25fSPoul-Henning Kamp"expat.dsp" in the lib directory and build and install in the usual
2815bb6a25fSPoul-Henning Kampmanner.</p>
2825bb6a25fSPoul-Henning Kamp
2835bb6a25fSPoul-Henning Kamp<p>Alternatively, you may download the Win32 binary package that
2845bb6a25fSPoul-Henning Kampcontains the "expat.h" include file and a pre-built DLL.</p>
2855bb6a25fSPoul-Henning Kamp
2865bb6a25fSPoul-Henning Kamp<h3>Building under Unix (or GNU)</h3>
2875bb6a25fSPoul-Henning Kamp
2885bb6a25fSPoul-Henning Kamp<p>First you'll need to run the configure shell script in order to
2895bb6a25fSPoul-Henning Kampconfigure the Makefiles and headers for your system.</p>
2905bb6a25fSPoul-Henning Kamp
2915bb6a25fSPoul-Henning Kamp<p>If you're happy with all the defaults that configure picks for you,
2925bb6a25fSPoul-Henning Kampand you have permission on your system to install into /usr/local, you
2935bb6a25fSPoul-Henning Kampcan install Expat with this sequence of commands:</p>
2945bb6a25fSPoul-Henning Kamp
2955bb6a25fSPoul-Henning Kamp<pre class="eg">
2965bb6a25fSPoul-Henning Kamp./configure
2975bb6a25fSPoul-Henning Kampmake
2985bb6a25fSPoul-Henning Kampmake install
2995bb6a25fSPoul-Henning Kamp</pre>
3005bb6a25fSPoul-Henning Kamp
3015bb6a25fSPoul-Henning Kamp<p>There are some options that you can provide to this script, but the
3025bb6a25fSPoul-Henning Kamponly one we'll mention here is the <code>--prefix</code> option. You
3035bb6a25fSPoul-Henning Kampcan find out all the options available by running configure with just
3045bb6a25fSPoul-Henning Kampthe <code>--help</code> option.</p>
3055bb6a25fSPoul-Henning Kamp
3065bb6a25fSPoul-Henning Kamp<p>By default, the configure script sets things up so that the library
3075bb6a25fSPoul-Henning Kampgets installed in <code>/usr/local/lib</code> and the associated
3085bb6a25fSPoul-Henning Kampheader file in <code>/usr/local/include</code>.  But if you were to
3095bb6a25fSPoul-Henning Kampgive the option, <code>--prefix=/home/me/mystuff</code>, then the
3105bb6a25fSPoul-Henning Kamplibrary and header would get installed in
3115bb6a25fSPoul-Henning Kamp<code>/home/me/mystuff/lib</code> and
312*220ed979SColeman Kane<code>/home/me/mystuff/include</code> respectively.</p>
313*220ed979SColeman Kane
314*220ed979SColeman Kane<h3>Configuring Expat Using the Pre-Processor</h3>
315*220ed979SColeman Kane
316*220ed979SColeman Kane<p>Expat's feature set can be configured using a small number of
317*220ed979SColeman Kanepre-processor definitions.  The definition of this symbols does not
318*220ed979SColeman Kaneaffect the set of entry points for Expat, only the behavior of the API
319*220ed979SColeman Kaneand the definition of character types in the case of
320*220ed979SColeman Kane<code>XML_UNICODE_WCHAR_T</code>.  The symbols are:</p>
321*220ed979SColeman Kane
322*220ed979SColeman Kane<dl class="cpp-symbols">
323*220ed979SColeman Kane<dt>XML_DTD</dt>
324*220ed979SColeman Kane<dd>Include support for using and reporting DTD-based content.  If
325*220ed979SColeman Kanethis is defined, default attribute values from an external DTD subset
326*220ed979SColeman Kaneare reported and attribute value normalization occurs based on the
327*220ed979SColeman Kanetype of attributes defined in the external subset.  Without
328*220ed979SColeman Kanethis, Expat has a smaller memory footprint and can be faster, but will
329*220ed979SColeman Kanenot load external entities or process conditional sections.  This does
330*220ed979SColeman Kanenot affect the set of functions available in the API.</dd>
331*220ed979SColeman Kane
332*220ed979SColeman Kane<dt>XML_NS</dt>
333*220ed979SColeman Kane<dd>When defined, support for the <cite><a href=
334*220ed979SColeman Kane"http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite>
335*220ed979SColeman Kanespecification is included.</dd>
336*220ed979SColeman Kane
337*220ed979SColeman Kane<dt>XML_UNICODE</dt>
338*220ed979SColeman Kane<dd>When defined, character data reported to the application is
339*220ed979SColeman Kaneencoded in UTF-16 using wide characters of the type
340*220ed979SColeman Kane<code>XML_Char</code>.  This is implied if
341*220ed979SColeman Kane<code>XML_UNICODE_WCHAR_T</code> is defined.</dd>
342*220ed979SColeman Kane
343*220ed979SColeman Kane<dt>XML_UNICODE_WCHAR_T</dt>
344*220ed979SColeman Kane<dd>If defined, causes the <code>XML_Char</code> character type to be
345*220ed979SColeman Kanedefined using the <code>wchar_t</code> type; otherwise, <code>unsigned
346*220ed979SColeman Kaneshort</code> is used.  Defining this implies
347*220ed979SColeman Kane<code>XML_UNICODE</code>.</dd>
348*220ed979SColeman Kane
349*220ed979SColeman Kane<dt>XML_LARGE_SIZE</dt>
350*220ed979SColeman Kane<dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code>
351*220ed979SColeman Kaneinteger types to be at least 64 bits in size. This is intended to support
352*220ed979SColeman Kaneprocessing of very large input streams, where the return values of
353*220ed979SColeman Kane<code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>,
354*220ed979SColeman Kane<code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and
355*220ed979SColeman Kane<code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>
356*220ed979SColeman Kanecould overflow. It may not be supported by all compilers, and is turned
357*220ed979SColeman Kaneoff by default.</dd>
358*220ed979SColeman Kane
359*220ed979SColeman Kane<dt>XML_CONTEXT_BYTES</dt>
360*220ed979SColeman Kane<dd>The number of input bytes of markup context which the parser will
361*220ed979SColeman Kaneensure are available for reporting via <code><a href=
362*220ed979SColeman Kane"#XML_GetInputContext" >XML_GetInputContext</a></code>.  This is
363*220ed979SColeman Kanenormally set to 1024, and must be set to a positive interger.  If this
364*220ed979SColeman Kaneis not defined, the input context will not be available and <code><a
365*220ed979SColeman Kanehref= "#XML_GetInputContext" >XML_GetInputContext</a></code> will
366*220ed979SColeman Kanealways report NULL.  Without this, Expat has a smaller memory
367*220ed979SColeman Kanefootprint and can be faster.</dd>
368*220ed979SColeman Kane
369*220ed979SColeman Kane<dt>XML_STATIC</dt>
370*220ed979SColeman Kane<dd>On Windows, this should be set if Expat is going to be linked
371*220ed979SColeman Kanestatically with the code that calls it; this is required to get all
372*220ed979SColeman Kanethe right MSVC magic annotations correct.  This is ignored on other
373*220ed979SColeman Kaneplatforms.</dd>
3745bb6a25fSPoul-Henning Kamp
3755bb6a25fSPoul-Henning Kamp<dt>XML_ATTR_INFO</dt>
3765bb6a25fSPoul-Henning Kamp<dd>If defined, makes the the additional function <code><a href=
3775bb6a25fSPoul-Henning Kamp"#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available
3785bb6a25fSPoul-Henning Kampfor reporting attribute byte offsets.</dd>
3795bb6a25fSPoul-Henning Kamp</dl>
3805bb6a25fSPoul-Henning Kamp
3815bb6a25fSPoul-Henning Kamp<hr />
3825bb6a25fSPoul-Henning Kamp<h2><a name="using">Using Expat</a></h2>
3835bb6a25fSPoul-Henning Kamp
3845bb6a25fSPoul-Henning Kamp<h3>Compiling and Linking Against Expat</h3>
3855bb6a25fSPoul-Henning Kamp
3865bb6a25fSPoul-Henning Kamp<p>Unless you installed Expat in a location not expected by your
387*220ed979SColeman Kanecompiler and linker, all you have to do to use Expat in your programs
3885bb6a25fSPoul-Henning Kampis to include the Expat header (<code>#include &lt;expat.h&gt;</code>)
3895bb6a25fSPoul-Henning Kampin your files that make calls to it and to tell the linker that it
3905bb6a25fSPoul-Henning Kampneeds to link against the Expat library.  On Unix systems, this would
3915bb6a25fSPoul-Henning Kampusually be done with the <code>-lexpat</code> argument.  Otherwise,
3925bb6a25fSPoul-Henning Kampyou'll need to tell the compiler where to look for the Expat header
3935bb6a25fSPoul-Henning Kampand the linker where to find the Expat library.  You may also need to
3945bb6a25fSPoul-Henning Kamptake steps to tell the operating system where to find this library at
3955bb6a25fSPoul-Henning Kamprun time.</p>
3965bb6a25fSPoul-Henning Kamp
3975bb6a25fSPoul-Henning Kamp<p>On a Unix-based system, here's what a Makefile might look like when
3985bb6a25fSPoul-Henning KampExpat is installed in a standard location:</p>
3995bb6a25fSPoul-Henning Kamp
4005bb6a25fSPoul-Henning Kamp<pre class="eg">
4015bb6a25fSPoul-Henning KampCC=cc
4025bb6a25fSPoul-Henning KampLDFLAGS=
4035bb6a25fSPoul-Henning KampLIBS= -lexpat
4045bb6a25fSPoul-Henning Kampxmlapp: xmlapp.o
4055bb6a25fSPoul-Henning Kamp        $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
4065bb6a25fSPoul-Henning Kamp</pre>
4075bb6a25fSPoul-Henning Kamp
4085bb6a25fSPoul-Henning Kamp<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then
4095bb6a25fSPoul-Henning Kampthe Makefile would look like this:</p>
4105bb6a25fSPoul-Henning Kamp
4115bb6a25fSPoul-Henning Kamp<pre class="eg">
4125bb6a25fSPoul-Henning KampCC=cc
4135bb6a25fSPoul-Henning KampCFLAGS= -I/home/me/mystuff/include
4145bb6a25fSPoul-Henning KampLDFLAGS=
4155bb6a25fSPoul-Henning KampLIBS= -L/home/me/mystuff/lib -lexpat
4165bb6a25fSPoul-Henning Kampxmlapp: xmlapp.o
4175bb6a25fSPoul-Henning Kamp        $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
4185bb6a25fSPoul-Henning Kamp</pre>
4195bb6a25fSPoul-Henning Kamp
4205bb6a25fSPoul-Henning Kamp<p>You'd also have to set the environment variable
4215bb6a25fSPoul-Henning Kamp<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or
4225bb6a25fSPoul-Henning Kampto <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if
4235bb6a25fSPoul-Henning KampLD_LIBRARY_PATH already has some directories in it) in order to run
4245bb6a25fSPoul-Henning Kampyour application.</p>
4255bb6a25fSPoul-Henning Kamp
4265bb6a25fSPoul-Henning Kamp<h3>Expat Basics</h3>
4275bb6a25fSPoul-Henning Kamp
4285bb6a25fSPoul-Henning Kamp<p>As we saw in the example in the overview, the first step in parsing
4295bb6a25fSPoul-Henning Kampan XML document with Expat is to create a parser object. There are <a
4305bb6a25fSPoul-Henning Kamphref="#creation">three functions</a> in the Expat API for creating a
4315bb6a25fSPoul-Henning Kampparser object.  However, only two of these (<code><a href=
432*220ed979SColeman Kane"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href=
4335bb6a25fSPoul-Henning Kamp"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for
4345bb6a25fSPoul-Henning Kampconstructing a parser for a top-level document.  The object returned
4355bb6a25fSPoul-Henning Kampby these functions is an opaque pointer (i.e. "expat.h" declares it as
4365bb6a25fSPoul-Henning Kampvoid *) to data with further internal structure. In order to free the
4375bb6a25fSPoul-Henning Kampmemory associated with this object you must call <code><a href=
4385bb6a25fSPoul-Henning Kamp"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have
4395bb6a25fSPoul-Henning Kampprovided any <a href="#userdata">user data</a> that gets stored in the
4405bb6a25fSPoul-Henning Kampparser, then your application is responsible for freeing it prior to
4415bb6a25fSPoul-Henning Kampcalling <code>XML_ParserFree</code>.</p>
4425bb6a25fSPoul-Henning Kamp
4435bb6a25fSPoul-Henning Kamp<p>The objects returned by the parser creation functions are good for
4445bb6a25fSPoul-Henning Kampparsing only one XML document or external parsed entity. If your
4455bb6a25fSPoul-Henning Kampapplication needs to parse many XML documents, then it needs to create
4465bb6a25fSPoul-Henning Kampa parser object for each one. The best way to deal with this is to
4475bb6a25fSPoul-Henning Kampcreate a higher level object that contains all the default
4485bb6a25fSPoul-Henning Kampinitialization you want for your parser objects.</p>
4495bb6a25fSPoul-Henning Kamp
4505bb6a25fSPoul-Henning Kamp<p>Walking through a document hierarchy with a stream oriented parser
4515bb6a25fSPoul-Henning Kampwill require a good stack mechanism in order to keep track of current
4525bb6a25fSPoul-Henning Kampcontext.  For instance, to answer the simple question, "What element
4535bb6a25fSPoul-Henning Kampdoes this text belong to?" requires a stack, since the parser may have
4545bb6a25fSPoul-Henning Kampdescended into other elements that are children of the current one and
4555bb6a25fSPoul-Henning Kamphas encountered this text on the way out.</p>
4565bb6a25fSPoul-Henning Kamp
4575bb6a25fSPoul-Henning Kamp<p>The things you're likely to want to keep on a stack are the
4585bb6a25fSPoul-Henning Kampcurrently opened element and it's attributes. You push this
4595bb6a25fSPoul-Henning Kampinformation onto the stack in the start handler and you pop it off in
4605bb6a25fSPoul-Henning Kampthe end handler.</p>
4615bb6a25fSPoul-Henning Kamp
4625bb6a25fSPoul-Henning Kamp<p>For some tasks, it is sufficient to just keep information on what
4635bb6a25fSPoul-Henning Kampthe depth of the stack is (or would be if you had one.) The outline
4645bb6a25fSPoul-Henning Kampprogram shown above presents one example. Another such task would be
4655bb6a25fSPoul-Henning Kampskipping over a complete element. When you see the start tag for the
4665bb6a25fSPoul-Henning Kampelement you want to skip, you set a skip flag and record the depth at
4675bb6a25fSPoul-Henning Kampwhich the element started.  When the end tag handler encounters the
4685bb6a25fSPoul-Henning Kampsame depth, the skipped element has ended and the flag may be
4695bb6a25fSPoul-Henning Kampcleared. If you follow the convention that the root element starts at
4705bb6a25fSPoul-Henning Kamp1, then you can use the same variable for skip flag and skip
4715bb6a25fSPoul-Henning Kampdepth.</p>
4725bb6a25fSPoul-Henning Kamp
4735bb6a25fSPoul-Henning Kamp<pre class="eg">
474*220ed979SColeman Kanevoid
4755bb6a25fSPoul-Henning Kampinit_info(Parseinfo *info) {
4765bb6a25fSPoul-Henning Kamp  info->skip = 0;
4775bb6a25fSPoul-Henning Kamp  info->depth = 1;
4785bb6a25fSPoul-Henning Kamp  /* Other initializations here */
4795bb6a25fSPoul-Henning Kamp}  /* End of init_info */
4805bb6a25fSPoul-Henning Kamp
4815bb6a25fSPoul-Henning Kampvoid XMLCALL
4825bb6a25fSPoul-Henning Kamprawstart(void *data, const char *el, const char **attr) {
4835bb6a25fSPoul-Henning Kamp  Parseinfo *inf = (Parseinfo *) data;
4845bb6a25fSPoul-Henning Kamp
4855bb6a25fSPoul-Henning Kamp  if (! inf->skip) {
4865bb6a25fSPoul-Henning Kamp    if (should_skip(inf, el, attr)) {
4875bb6a25fSPoul-Henning Kamp      inf->skip = inf->depth;
4885bb6a25fSPoul-Henning Kamp    }
489*220ed979SColeman Kane    else
4905bb6a25fSPoul-Henning Kamp      start(inf, el, attr);     /* This does rest of start handling */
4915bb6a25fSPoul-Henning Kamp  }
4925bb6a25fSPoul-Henning Kamp
4935bb6a25fSPoul-Henning Kamp  inf->depth++;
4945bb6a25fSPoul-Henning Kamp}  /* End of rawstart */
4955bb6a25fSPoul-Henning Kamp
4965bb6a25fSPoul-Henning Kampvoid XMLCALL
4975bb6a25fSPoul-Henning Kamprawend(void *data, const char *el) {
4985bb6a25fSPoul-Henning Kamp  Parseinfo *inf = (Parseinfo *) data;
4995bb6a25fSPoul-Henning Kamp
5005bb6a25fSPoul-Henning Kamp  inf->depth--;
5015bb6a25fSPoul-Henning Kamp
5025bb6a25fSPoul-Henning Kamp  if (! inf->skip)
5035bb6a25fSPoul-Henning Kamp    end(inf, el);              /* This does rest of end handling */
5045bb6a25fSPoul-Henning Kamp
5055bb6a25fSPoul-Henning Kamp  if (inf->skip == inf->depth)
5065bb6a25fSPoul-Henning Kamp    inf->skip = 0;
5075bb6a25fSPoul-Henning Kamp}  /* End rawend */
5085bb6a25fSPoul-Henning Kamp</pre>
5095bb6a25fSPoul-Henning Kamp
5105bb6a25fSPoul-Henning Kamp<p>Notice in the above example the difference in how depth is
5115bb6a25fSPoul-Henning Kampmanipulated in the start and end handlers. The end tag handler should
5125bb6a25fSPoul-Henning Kampbe the mirror image of the start tag handler. This is necessary to
5135bb6a25fSPoul-Henning Kampproperly model containment. Since, in the start tag handler, we
5145bb6a25fSPoul-Henning Kampincremented depth <em>after</em> the main body of start tag code, then
5155bb6a25fSPoul-Henning Kampin the end handler, we need to manipulate it <em>before</em> the main
5165bb6a25fSPoul-Henning Kampbody.  If we'd decided to increment it first thing in the start
5175bb6a25fSPoul-Henning Kamphandler, then we'd have had to decrement it last thing in the end
5185bb6a25fSPoul-Henning Kamphandler.</p>
519*220ed979SColeman Kane
520*220ed979SColeman Kane<h3 id="userdata">Communicating between handlers</h3>
521*220ed979SColeman Kane
522*220ed979SColeman Kane<p>In order to be able to pass information between different handlers
523*220ed979SColeman Kanewithout using globals, you'll need to define a data structure to hold
524*220ed979SColeman Kanethe shared variables. You can then tell Expat (with the <code><a href=
525*220ed979SColeman Kane"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a
526*220ed979SColeman Kanepointer to this structure to the handlers.  This is the first
527*220ed979SColeman Kaneargument received by most handlers.  In the <a href="#reference"
528*220ed979SColeman Kane>reference section</a>, an argument to a callback function is named
529*220ed979SColeman Kane<code>userData</code> and have type <code>void *</code> if the user
530*220ed979SColeman Kanedata is passed; it will have the type <code>XML_Parser</code> if the
531*220ed979SColeman Kaneparser itself is passed.  When the parser is passed, the user data may
532*220ed979SColeman Kanebe retrieved using <code><a href="#XML_GetUserData"
533*220ed979SColeman Kane>XML_GetUserData</a></code>.</p>
534*220ed979SColeman Kane
535*220ed979SColeman Kane<p>One common case where multiple calls to a single handler may need
536*220ed979SColeman Kaneto communicate using an application data structure is the case when
537*220ed979SColeman Kanecontent passed to the character data handler (set by <code><a href=
538*220ed979SColeman Kane"#XML_SetCharacterDataHandler"
539*220ed979SColeman Kane>XML_SetCharacterDataHandler</a></code>) needs to be accumulated.  A
540*220ed979SColeman Kanecommon first-time mistake with any of the event-oriented interfaces to
541*220ed979SColeman Kanean XML parser is to expect all the text contained in an element to be
542*220ed979SColeman Kanereported by a single call to the character data handler.  Expat, like
543*220ed979SColeman Kanemany other XML parsers, reports such data as a sequence of calls;
5445bb6a25fSPoul-Henning Kampthere's no way to know when the end of the sequence is reached until a
5455bb6a25fSPoul-Henning Kampdifferent callback is made.  A buffer referenced by the user data
5465bb6a25fSPoul-Henning Kampstructure proves both an effective and convenient place to accumulate
5475bb6a25fSPoul-Henning Kampcharacter data.</p>
5485bb6a25fSPoul-Henning Kamp
5495bb6a25fSPoul-Henning Kamp<!-- XXX example needed here -->
5505bb6a25fSPoul-Henning Kamp
5515bb6a25fSPoul-Henning Kamp
5525bb6a25fSPoul-Henning Kamp<h3>XML Version</h3>
5535bb6a25fSPoul-Henning Kamp
5545bb6a25fSPoul-Henning Kamp<p>Expat is an XML 1.0 parser, and as such never complains based on
5555bb6a25fSPoul-Henning Kampthe value of the <code>version</code> pseudo-attribute in the XML
5565bb6a25fSPoul-Henning Kampdeclaration, if present.</p>
5575bb6a25fSPoul-Henning Kamp
5585bb6a25fSPoul-Henning Kamp<p>If an application needs to check the version number (to support
5595bb6a25fSPoul-Henning Kampalternate processing), it should use the <code><a href=
5605bb6a25fSPoul-Henning Kamp"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to
5615bb6a25fSPoul-Henning Kampset a handler that uses the information in the XML declaration to
562*220ed979SColeman Kanedetermine what to do.  This example shows how to check that only a
5635bb6a25fSPoul-Henning Kampversion number of <code>"1.0"</code> is accepted:</p>
5645bb6a25fSPoul-Henning Kamp
5655bb6a25fSPoul-Henning Kamp<pre class="eg">
5665bb6a25fSPoul-Henning Kampstatic int wrong_version;
5675bb6a25fSPoul-Henning Kampstatic XML_Parser parser;
5685bb6a25fSPoul-Henning Kamp
5695bb6a25fSPoul-Henning Kampstatic void XMLCALL
5705bb6a25fSPoul-Henning Kampxmldecl_handler(void            *userData,
5715bb6a25fSPoul-Henning Kamp                const XML_Char  *version,
5725bb6a25fSPoul-Henning Kamp                const XML_Char  *encoding,
5735bb6a25fSPoul-Henning Kamp                int              standalone)
5745bb6a25fSPoul-Henning Kamp{
5755bb6a25fSPoul-Henning Kamp  static const XML_Char Version_1_0[] = {'1', '.', '0', 0};
5765bb6a25fSPoul-Henning Kamp
5775bb6a25fSPoul-Henning Kamp  int i;
5785bb6a25fSPoul-Henning Kamp
5795bb6a25fSPoul-Henning Kamp  for (i = 0; i &lt; (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) {
5805bb6a25fSPoul-Henning Kamp    if (version[i] != Version_1_0[i]) {
5815bb6a25fSPoul-Henning Kamp      wrong_version = 1;
5825bb6a25fSPoul-Henning Kamp      /* also clear all other handlers: */
5835bb6a25fSPoul-Henning Kamp      XML_SetCharacterDataHandler(parser, NULL);
5845bb6a25fSPoul-Henning Kamp      ...
5855bb6a25fSPoul-Henning Kamp      return;
5865bb6a25fSPoul-Henning Kamp    }
5875bb6a25fSPoul-Henning Kamp  }
5885bb6a25fSPoul-Henning Kamp  ...
5895bb6a25fSPoul-Henning Kamp}
5905bb6a25fSPoul-Henning Kamp</pre>
5915bb6a25fSPoul-Henning Kamp
5925bb6a25fSPoul-Henning Kamp<h3>Namespace Processing</h3>
5935bb6a25fSPoul-Henning Kamp
5945bb6a25fSPoul-Henning Kamp<p>When the parser is created using the <code><a href=
5955bb6a25fSPoul-Henning Kamp"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat
5965bb6a25fSPoul-Henning Kampperforms namespace processing. Under namespace processing, Expat
5975bb6a25fSPoul-Henning Kampconsumes <code>xmlns</code> and <code>xmlns:...</code> attributes,
5985bb6a25fSPoul-Henning Kampwhich declare namespaces for the scope of the element in which they
5995bb6a25fSPoul-Henning Kampoccur. This means that your start handler will not see these
6005bb6a25fSPoul-Henning Kampattributes.  Your application can still be informed of these
6015bb6a25fSPoul-Henning Kampdeclarations by setting namespace declaration handlers with <a href=
6025bb6a25fSPoul-Henning Kamp"#XML_SetNamespaceDeclHandler"
6035bb6a25fSPoul-Henning Kamp><code>XML_SetNamespaceDeclHandler</code></a>.</p>
604*220ed979SColeman Kane
605*220ed979SColeman Kane<p>Element type and attribute names that belong to a given namespace
6065bb6a25fSPoul-Henning Kampare passed to the appropriate handler in expanded form. By default
6075bb6a25fSPoul-Henning Kampthis expanded form is a concatenation of the namespace URI, the
6085bb6a25fSPoul-Henning Kampseparator character (which is the 2nd argument to <code><a href=
609*220ed979SColeman Kane"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local
6105bb6a25fSPoul-Henning Kampname (i.e. the part after the colon). Names with undeclared prefixes
6115bb6a25fSPoul-Henning Kampare not well-formed when namespace processing is enabled, and will
6125bb6a25fSPoul-Henning Kamptrigger an error. Unprefixed attribute names are never expanded,
6135bb6a25fSPoul-Henning Kampand unprefixed element names are only expanded when they are in the
6145bb6a25fSPoul-Henning Kampscope of a default namespace.</p>
6155bb6a25fSPoul-Henning Kamp
6165bb6a25fSPoul-Henning Kamp<p>However if <code><a href= "#XML_SetReturnNSTriplet"
6175bb6a25fSPoul-Henning Kamp>XML_SetReturnNSTriplet</a></code> has been called with a non-zero
6185bb6a25fSPoul-Henning Kamp<code>do_nst</code> parameter, then the expanded form for names with
619*220ed979SColeman Kanean explicit prefix is a concatenation of: URI, separator, local name,
6205bb6a25fSPoul-Henning Kampseparator, prefix.</p>
6215bb6a25fSPoul-Henning Kamp
6225bb6a25fSPoul-Henning Kamp<p>You can set handlers for the start of a namespace declaration and
6235bb6a25fSPoul-Henning Kampfor the end of a scope of a declaration with the <code><a href=
6245bb6a25fSPoul-Henning Kamp"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code>
6255bb6a25fSPoul-Henning Kampfunction.  The StartNamespaceDeclHandler is called prior to the start
6265bb6a25fSPoul-Henning Kamptag handler and the EndNamespaceDeclHandler is called after the
6275bb6a25fSPoul-Henning Kampcorresponding end tag that ends the namespace's scope.  The namespace
6285bb6a25fSPoul-Henning Kampstart handler gets passed the prefix and URI for the namespace.  For a
6295bb6a25fSPoul-Henning Kampdefault namespace declaration (xmlns='...'), the prefix will be null.
6305bb6a25fSPoul-Henning KampThe URI will be null for the case where the default namespace is being
6315bb6a25fSPoul-Henning Kampunset.  The namespace end handler just gets the prefix for the closing
6325bb6a25fSPoul-Henning Kampscope.</p>
6335bb6a25fSPoul-Henning Kamp
6345bb6a25fSPoul-Henning Kamp<p>These handlers are called for each declaration. So if, for
6355bb6a25fSPoul-Henning Kampinstance, a start tag had three namespace declarations, then the
6365bb6a25fSPoul-Henning KampStartNamespaceDeclHandler would be called three times before the start
6375bb6a25fSPoul-Henning Kamptag handler is called, once for each declaration.</p>
6385bb6a25fSPoul-Henning Kamp
6395bb6a25fSPoul-Henning Kamp<h3>Character Encodings</h3>
6405bb6a25fSPoul-Henning Kamp
6415bb6a25fSPoul-Henning Kamp<p>While XML is based on Unicode, and every XML processor is required
6425bb6a25fSPoul-Henning Kampto recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode),
6435bb6a25fSPoul-Henning Kampother encodings may be declared in XML documents or entities. For the
6445bb6a25fSPoul-Henning Kampmain document, an XML declaration may contain an encoding
6455bb6a25fSPoul-Henning Kampdeclaration:</p>
6465bb6a25fSPoul-Henning Kamp<pre>
6475bb6a25fSPoul-Henning Kamp&lt;?xml version="1.0" encoding="ISO-8859-2"?&gt;
6485bb6a25fSPoul-Henning Kamp</pre>
6495bb6a25fSPoul-Henning Kamp
6505bb6a25fSPoul-Henning Kamp<p>External parsed entities may begin with a text declaration, which
6515bb6a25fSPoul-Henning Kamplooks like an XML declaration with just an encoding declaration:</p>
6525bb6a25fSPoul-Henning Kamp<pre>
6535bb6a25fSPoul-Henning Kamp&lt;?xml encoding="Big5"?&gt;
6545bb6a25fSPoul-Henning Kamp</pre>
6555bb6a25fSPoul-Henning Kamp
6565bb6a25fSPoul-Henning Kamp<p>With Expat, you may also specify an encoding at the time of
6575bb6a25fSPoul-Henning Kampcreating a parser. This is useful when the encoding information may
6585bb6a25fSPoul-Henning Kampcome from a source outside the document itself (like a higher level
6595bb6a25fSPoul-Henning Kampprotocol.)</p>
6605bb6a25fSPoul-Henning Kamp
6615bb6a25fSPoul-Henning Kamp<p><a name="builtin_encodings"></a>There are four built-in encodings
6625bb6a25fSPoul-Henning Kampin Expat:</p>
6635bb6a25fSPoul-Henning Kamp<ul>
6645bb6a25fSPoul-Henning Kamp<li>UTF-8</li>
6655bb6a25fSPoul-Henning Kamp<li>UTF-16</li>
6665bb6a25fSPoul-Henning Kamp<li>ISO-8859-1</li>
667*220ed979SColeman Kane<li>US-ASCII</li>
668*220ed979SColeman Kane</ul>
669*220ed979SColeman Kane
670*220ed979SColeman Kane<p>Anything else discovered in an encoding declaration or in the
671*220ed979SColeman Kaneprotocol encoding specified in the parser constructor, triggers a call
672*220ed979SColeman Kaneto the <code>UnknownEncodingHandler</code>. This handler gets passed
6735bb6a25fSPoul-Henning Kampthe encoding name and a pointer to an <code>XML_Encoding</code> data
6745bb6a25fSPoul-Henning Kampstructure. Your handler must fill in this structure and return
6755bb6a25fSPoul-Henning Kamp<code>XML_STATUS_OK</code> if it knows how to deal with the
6765bb6a25fSPoul-Henning Kampencoding. Otherwise the handler should return
6775bb6a25fSPoul-Henning Kamp<code>XML_STATUS_ERROR</code>.  The handler also gets passed a pointer
6785bb6a25fSPoul-Henning Kampto an optional application data structure that you may indicate when
6795bb6a25fSPoul-Henning Kampyou set the handler.</p>
6805bb6a25fSPoul-Henning Kamp
6815bb6a25fSPoul-Henning Kamp<p>Expat places restrictions on character encodings that it can
6825bb6a25fSPoul-Henning Kampsupport by filling in the <code>XML_Encoding</code> structure.
6835bb6a25fSPoul-Henning Kampinclude file:</p>
6845bb6a25fSPoul-Henning Kamp<ol>
6855bb6a25fSPoul-Henning Kamp<li>Every ASCII character that can appear in a well-formed XML document
6865bb6a25fSPoul-Henning Kampmust be represented by a single byte, and that byte must correspond to
6875bb6a25fSPoul-Henning Kampit's ASCII encoding (except for the characters $@\^'{}~)</li>
6885bb6a25fSPoul-Henning Kamp<li>Characters must be encoded in 4 bytes or less.</li>
6895bb6a25fSPoul-Henning Kamp<li>All characters encoded must have Unicode scalar values less than or
6905bb6a25fSPoul-Henning Kampequal to 65535 (0xFFFF)<em>This does not apply to the built-in support
6915bb6a25fSPoul-Henning Kampfor UTF-16 and UTF-8</em></li>
6925bb6a25fSPoul-Henning Kamp<li>No character may be encoded by more that one distinct sequence of
6935bb6a25fSPoul-Henning Kampbytes</li>
6945bb6a25fSPoul-Henning Kamp</ol>
6955bb6a25fSPoul-Henning Kamp
6965bb6a25fSPoul-Henning Kamp<p><code>XML_Encoding</code> contains an array of integers that
6975bb6a25fSPoul-Henning Kampcorrespond to the 1st byte of an encoding sequence. If the value in
6985bb6a25fSPoul-Henning Kampthe array for a byte is zero or positive, then the byte is a single
6995bb6a25fSPoul-Henning Kampbyte encoding that encodes the Unicode scalar value contained in the
7005bb6a25fSPoul-Henning Kamparray. A -1 in this array indicates a malformed byte. If the value is
7015bb6a25fSPoul-Henning Kamp-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte
7025bb6a25fSPoul-Henning Kampsequence respectively. Multi-byte sequences are sent to the convert
7035bb6a25fSPoul-Henning Kampfunction pointed at in the <code>XML_Encoding</code> structure. This
7045bb6a25fSPoul-Henning Kampfunction should return the Unicode scalar value for the sequence or -1
7055bb6a25fSPoul-Henning Kampif the sequence is malformed.</p>
7065bb6a25fSPoul-Henning Kamp
7075bb6a25fSPoul-Henning Kamp<p>One pitfall that novice Expat users are likely to fall into is that
7085bb6a25fSPoul-Henning Kampalthough Expat may accept input in various encodings, the strings that
7095bb6a25fSPoul-Henning Kampit passes to the handlers are always encoded in UTF-8 or UTF-16
7105bb6a25fSPoul-Henning Kamp(depending on how Expat was compiled). Your application is responsible
7115bb6a25fSPoul-Henning Kampfor any translation of these strings into other encodings.</p>
7125bb6a25fSPoul-Henning Kamp
7135bb6a25fSPoul-Henning Kamp<h3>Handling External Entity References</h3>
7145bb6a25fSPoul-Henning Kamp
7155bb6a25fSPoul-Henning Kamp<p>Expat does not read or parse external entities directly. Note that
7165bb6a25fSPoul-Henning Kampany external DTD is a special case of an external entity.  If you've
7175bb6a25fSPoul-Henning Kampset no <code>ExternalEntityRefHandler</code>, then external entity
7185bb6a25fSPoul-Henning Kampreferences are silently ignored. Otherwise, it calls your handler with
7195bb6a25fSPoul-Henning Kampthe information needed to read and parse the external entity.</p>
7205bb6a25fSPoul-Henning Kamp
7215bb6a25fSPoul-Henning Kamp<p>Your handler isn't actually responsible for parsing the entity, but
7225bb6a25fSPoul-Henning Kampit is responsible for creating a subsidiary parser with <code><a href=
7235bb6a25fSPoul-Henning Kamp"#XML_ExternalEntityParserCreate"
7245bb6a25fSPoul-Henning Kamp>XML_ExternalEntityParserCreate</a></code> that will do the job. This
7255bb6a25fSPoul-Henning Kampreturns an instance of <code>XML_Parser</code> that has handlers and
7265bb6a25fSPoul-Henning Kampother data structures initialized from the parent parser. You may then
7275bb6a25fSPoul-Henning Kampuse <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a
7285bb6a25fSPoul-Henning Kamphref= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this
7295bb6a25fSPoul-Henning Kampparser.  Since external entities my refer to other external entities,
7305bb6a25fSPoul-Henning Kampyour handler should be prepared to be called recursively.</p>
7315bb6a25fSPoul-Henning Kamp
7325bb6a25fSPoul-Henning Kamp<h3>Parsing DTDs</h3>
7335bb6a25fSPoul-Henning Kamp
7345bb6a25fSPoul-Henning Kamp<p>In order to parse parameter entities, before starting the parse,
7355bb6a25fSPoul-Henning Kampyou must call <code><a href= "#XML_SetParamEntityParsing"
7365bb6a25fSPoul-Henning Kamp>XML_SetParamEntityParsing</a></code> with one of the following
7375bb6a25fSPoul-Henning Kamparguments:</p>
7385bb6a25fSPoul-Henning Kamp<dl>
7395bb6a25fSPoul-Henning Kamp<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt>
7405bb6a25fSPoul-Henning Kamp<dd>Don't parse parameter entities or the external subset</dd>
7415bb6a25fSPoul-Henning Kamp<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt>
7425bb6a25fSPoul-Henning Kamp<dd>Parse parameter entites and the external subset unless
7435bb6a25fSPoul-Henning Kamp<code>standalone</code> was set to "yes" in the XML declaration.</dd>
744*220ed979SColeman Kane<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt>
745*220ed979SColeman Kane<dd>Always parse parameter entities and the external subset</dd>
746*220ed979SColeman Kane</dl>
747*220ed979SColeman Kane
748*220ed979SColeman Kane<p>In order to read an external DTD, you also have to set an external
749*220ed979SColeman Kaneentity reference handler as described above.</p>
750*220ed979SColeman Kane
751*220ed979SColeman Kane<h3 id="stop-resume">Temporarily Stopping Parsing</h3>
752*220ed979SColeman Kane
753*220ed979SColeman Kane<p>Expat 1.95.8 introduces a new feature: its now possible to stop
754*220ed979SColeman Kaneparsing temporarily from within a handler function, even if more data
755*220ed979SColeman Kanehas already been passed into the parser.  Applications for this
756*220ed979SColeman Kaneinclude</p>
757*220ed979SColeman Kane
758*220ed979SColeman Kane<ul>
759*220ed979SColeman Kane  <li>Supporting the <a href= "http://www.w3.org/TR/xinclude/"
760*220ed979SColeman Kane  >XInclude</a> specification.</li>
761*220ed979SColeman Kane
762*220ed979SColeman Kane  <li>Delaying further processing until additional information is
763*220ed979SColeman Kane  available from some other source.</li>
764*220ed979SColeman Kane
765*220ed979SColeman Kane  <li>Adjusting processor load as task priorities shift within an
766*220ed979SColeman Kane  application.</li>
767*220ed979SColeman Kane
768*220ed979SColeman Kane  <li>Stopping parsing completely (simply free or reset the parser
769*220ed979SColeman Kane  instead of resuming in the outer parsing loop).  This can be useful
770*220ed979SColeman Kane  if a application-domain error is found in the XML being parsed or if
771*220ed979SColeman Kane  the result of the parse is determined not to be useful after
772*220ed979SColeman Kane  all.</li>
773*220ed979SColeman Kane</ul>
774*220ed979SColeman Kane
775*220ed979SColeman Kane<p>To take advantage of this feature, the main parsing loop of an
776*220ed979SColeman Kaneapplication needs to support this specifically.  It cannot be
777*220ed979SColeman Kanesupported with a parsing loop compatible with Expat 1.95.7 or
778*220ed979SColeman Kaneearlier (though existing loops will continue to work without
779*220ed979SColeman Kanesupporting the stop/resume feature).</p>
780*220ed979SColeman Kane
781*220ed979SColeman Kane<p>An application that uses this feature for a single parser will have
782*220ed979SColeman Kanethe rough structure (in pseudo-code):</p>
783*220ed979SColeman Kane
784*220ed979SColeman Kane<pre class="pseudocode">
785*220ed979SColeman Kanefd = open_input()
786*220ed979SColeman Kanep = create_parser()
787*220ed979SColeman Kane
788*220ed979SColeman Kaneif parse_xml(p, fd) {
789*220ed979SColeman Kane  /* suspended */
790*220ed979SColeman Kane
791*220ed979SColeman Kane  int suspended = 1;
792*220ed979SColeman Kane
793*220ed979SColeman Kane  while (suspended) {
794*220ed979SColeman Kane    do_something_else()
795*220ed979SColeman Kane    if ready_to_resume() {
796*220ed979SColeman Kane      suspended = continue_parsing(p, fd);
797*220ed979SColeman Kane    }
798*220ed979SColeman Kane  }
799*220ed979SColeman Kane}
800*220ed979SColeman Kane</pre>
801*220ed979SColeman Kane
802*220ed979SColeman Kane<p>An application that may resume any of several parsers based on
803*220ed979SColeman Kaneinput (either from the XML being parsed or some other source) will
804*220ed979SColeman Kanecertainly have more interesting control structures.</p>
805*220ed979SColeman Kane
806*220ed979SColeman Kane<p>This C function could be used for the <code>parse_xml</code>
807*220ed979SColeman Kanefunction mentioned in the pseudo-code above:</p>
808*220ed979SColeman Kane
809*220ed979SColeman Kane<pre class="eg">
810*220ed979SColeman Kane#define BUFF_SIZE 10240
811*220ed979SColeman Kane
812*220ed979SColeman Kane/* Parse a document from the open file descriptor 'fd' until the parse
813*220ed979SColeman Kane   is complete (the document has been completely parsed, or there's
814*220ed979SColeman Kane   been an error), or the parse is stopped.  Return non-zero when
815*220ed979SColeman Kane   the parse is merely suspended.
816*220ed979SColeman Kane*/
817*220ed979SColeman Kaneint
818*220ed979SColeman Kaneparse_xml(XML_Parser p, int fd)
819*220ed979SColeman Kane{
820*220ed979SColeman Kane  for (;;) {
821*220ed979SColeman Kane    int last_chunk;
822*220ed979SColeman Kane    int bytes_read;
823*220ed979SColeman Kane    enum XML_Status status;
824*220ed979SColeman Kane
825*220ed979SColeman Kane    void *buff = XML_GetBuffer(p, BUFF_SIZE);
826*220ed979SColeman Kane    if (buff == NULL) {
827*220ed979SColeman Kane      /* handle error... */
828*220ed979SColeman Kane      return 0;
829*220ed979SColeman Kane    }
830*220ed979SColeman Kane    bytes_read = read(fd, buff, BUFF_SIZE);
831*220ed979SColeman Kane    if (bytes_read &lt; 0) {
832*220ed979SColeman Kane      /* handle error... */
833*220ed979SColeman Kane      return 0;
834*220ed979SColeman Kane    }
835*220ed979SColeman Kane    status = XML_ParseBuffer(p, bytes_read, bytes_read == 0);
836*220ed979SColeman Kane    switch (status) {
837*220ed979SColeman Kane      case XML_STATUS_ERROR:
838*220ed979SColeman Kane        /* handle error... */
839*220ed979SColeman Kane        return 0;
840*220ed979SColeman Kane      case XML_STATUS_SUSPENDED:
841*220ed979SColeman Kane        return 1;
842*220ed979SColeman Kane    }
843*220ed979SColeman Kane    if (bytes_read == 0)
844*220ed979SColeman Kane      return 0;
845*220ed979SColeman Kane  }
846*220ed979SColeman Kane}
847*220ed979SColeman Kane</pre>
848*220ed979SColeman Kane
849*220ed979SColeman Kane<p>The corresponding <code>continue_parsing</code> function is
850*220ed979SColeman Kanesomewhat simpler, since it only need deal with the return code from
851*220ed979SColeman Kane<code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can
852*220ed979SColeman Kanedelegate the input handling to the <code>parse_xml</code>
853*220ed979SColeman Kanefunction:</p>
854*220ed979SColeman Kane
855*220ed979SColeman Kane<pre class="eg">
856*220ed979SColeman Kane/* Continue parsing a document which had been suspended.  The 'p' and
857*220ed979SColeman Kane   'fd' arguments are the same as passed to parse_xml().  Return
858*220ed979SColeman Kane   non-zero when the parse is suspended.
859*220ed979SColeman Kane*/
860*220ed979SColeman Kaneint
861*220ed979SColeman Kanecontinue_parsing(XML_Parser p, int fd)
862*220ed979SColeman Kane{
863*220ed979SColeman Kane  enum XML_Status status = XML_ResumeParser(p);
864*220ed979SColeman Kane  switch (status) {
865*220ed979SColeman Kane    case XML_STATUS_ERROR:
866*220ed979SColeman Kane      /* handle error... */
867*220ed979SColeman Kane      return 0;
868*220ed979SColeman Kane    case XML_ERROR_NOT_SUSPENDED:
869*220ed979SColeman Kane      /* handle error... */
870*220ed979SColeman Kane      return 0;.
871*220ed979SColeman Kane    case XML_STATUS_SUSPENDED:
872*220ed979SColeman Kane      return 1;
873*220ed979SColeman Kane  }
874*220ed979SColeman Kane  return parse_xml(p, fd);
875*220ed979SColeman Kane}
876*220ed979SColeman Kane</pre>
877*220ed979SColeman Kane
878*220ed979SColeman Kane<p>Now that we've seen what a mess the top-level parsing loop can
879*220ed979SColeman Kanebecome, what have we gained?  Very simply, we can now use the <code><a
880*220ed979SColeman Kanehref= "#XML_StopParser" >XML_StopParser</a></code> function to stop
881*220ed979SColeman Kaneparsing, without having to go to great lengths to avoid additional
882*220ed979SColeman Kaneprocessing that we're expecting to ignore.  As a bonus, we get to stop
883*220ed979SColeman Kaneparsing <em>temporarily</em>, and come back to it when we're
884*220ed979SColeman Kaneready.</p>
885*220ed979SColeman Kane
886*220ed979SColeman Kane<p>To stop parsing from a handler function, use the <code><a href=
8875bb6a25fSPoul-Henning Kamp"#XML_StopParser" >XML_StopParser</a></code> function.  This function
8885bb6a25fSPoul-Henning Kamptakes two arguments; the parser being stopped and a flag indicating
8895bb6a25fSPoul-Henning Kampwhether the parse can be resumed in the future.</p>
8905bb6a25fSPoul-Henning Kamp
8915bb6a25fSPoul-Henning Kamp<!-- XXX really need more here -->
8925bb6a25fSPoul-Henning Kamp
8935bb6a25fSPoul-Henning Kamp
8945bb6a25fSPoul-Henning Kamp<hr />
895*220ed979SColeman Kane<!-- ================================================================ -->
8965bb6a25fSPoul-Henning Kamp
8975bb6a25fSPoul-Henning Kamp<h2><a name="reference">Expat Reference</a></h2>
8985bb6a25fSPoul-Henning Kamp
8995bb6a25fSPoul-Henning Kamp<h3><a name="creation">Parser Creation</a></h3>
9005bb6a25fSPoul-Henning Kamp
9015bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserCreate">
9025bb6a25fSPoul-Henning KampXML_Parser XMLCALL
9035bb6a25fSPoul-Henning KampXML_ParserCreate(const XML_Char *encoding);
9045bb6a25fSPoul-Henning Kamp</pre>
9055bb6a25fSPoul-Henning Kamp<div class="fcndef">
9065bb6a25fSPoul-Henning KampConstruct a new parser. If encoding is non-null, it specifies a
9075bb6a25fSPoul-Henning Kampcharacter encoding to use for the document. This overrides the document
9085bb6a25fSPoul-Henning Kampencoding declaration. There are four built-in encodings:
9095bb6a25fSPoul-Henning Kamp<ul>
9105bb6a25fSPoul-Henning Kamp<li>US-ASCII</li>
9115bb6a25fSPoul-Henning Kamp<li>UTF-8</li>
912*220ed979SColeman Kane<li>UTF-16</li>
9135bb6a25fSPoul-Henning Kamp<li>ISO-8859-1</li>
9145bb6a25fSPoul-Henning Kamp</ul>
9155bb6a25fSPoul-Henning KampAny other value will invoke a call to the UnknownEncodingHandler.
9165bb6a25fSPoul-Henning Kamp</div>
9175bb6a25fSPoul-Henning Kamp
9185bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserCreateNS">
9195bb6a25fSPoul-Henning KampXML_Parser XMLCALL
9205bb6a25fSPoul-Henning KampXML_ParserCreateNS(const XML_Char *encoding,
921*220ed979SColeman Kane                   XML_Char sep);
922*220ed979SColeman Kane</pre>
923*220ed979SColeman Kane<div class="fcndef">
924*220ed979SColeman KaneConstructs a new parser that has namespace processing in effect. Namespace
925*220ed979SColeman Kaneexpanded element names and attribute names are returned as a concatenation
9265bb6a25fSPoul-Henning Kampof the namespace URI, <em>sep</em>, and the local part of the name. This
9275bb6a25fSPoul-Henning Kampmeans that you should pick a character for <em>sep</em> that can't be part
928*220ed979SColeman Kaneof an URI. Since Expat does not check namespace URIs for conformance, the
9295bb6a25fSPoul-Henning Kamponly safe choice for a namespace separator is a character that is illegal
9305bb6a25fSPoul-Henning Kampin XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and
9315bb6a25fSPoul-Henning Kamp<code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when
9325bb6a25fSPoul-Henning Kamp<em>sep</em> is the null character <code>'\0'</code>: the namespace URI and
9335bb6a25fSPoul-Henning Kampthe local part will be concatenated without any separator - this is intended
9345bb6a25fSPoul-Henning Kampto support RDF processors. It is a programming error to use the null separator
935*220ed979SColeman Kanewith <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div>
936*220ed979SColeman Kane
937*220ed979SColeman Kane<pre class="fcndec" id="XML_ParserCreate_MM">
9385bb6a25fSPoul-Henning KampXML_Parser XMLCALL
9395bb6a25fSPoul-Henning KampXML_ParserCreate_MM(const XML_Char *encoding,
9405bb6a25fSPoul-Henning Kamp                    const XML_Memory_Handling_Suite *ms,
9415bb6a25fSPoul-Henning Kamp		    const XML_Char *sep);
9425bb6a25fSPoul-Henning Kamp</pre>
9435bb6a25fSPoul-Henning Kamp<pre class="signature">
9445bb6a25fSPoul-Henning Kamptypedef struct {
9455bb6a25fSPoul-Henning Kamp  void *(XMLCALL *malloc_fcn)(size_t size);
9465bb6a25fSPoul-Henning Kamp  void *(XMLCALL *realloc_fcn)(void *ptr, size_t size);
9475bb6a25fSPoul-Henning Kamp  void (XMLCALL *free_fcn)(void *ptr);
9485bb6a25fSPoul-Henning Kamp} XML_Memory_Handling_Suite;
9495bb6a25fSPoul-Henning Kamp</pre>
950*220ed979SColeman Kane<div class="fcndef">
9515bb6a25fSPoul-Henning Kamp<p>Construct a new parser using the suite of memory handling functions
9525bb6a25fSPoul-Henning Kampspecified in <code>ms</code>. If <code>ms</code> is NULL, then use the
9535bb6a25fSPoul-Henning Kampstandard set of memory management functions. If <code>sep</code> is
9545bb6a25fSPoul-Henning Kampnon NULL, then namespace processing is enabled in the created parser
9555bb6a25fSPoul-Henning Kampand the character pointed at by sep is used as the separator between
9565bb6a25fSPoul-Henning Kampthe namespace URI and the local part of the name.</p>
9575bb6a25fSPoul-Henning Kamp</div>
9585bb6a25fSPoul-Henning Kamp
9595bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExternalEntityParserCreate">
9605bb6a25fSPoul-Henning KampXML_Parser XMLCALL
9615bb6a25fSPoul-Henning KampXML_ExternalEntityParserCreate(XML_Parser p,
9625bb6a25fSPoul-Henning Kamp                               const XML_Char *context,
9635bb6a25fSPoul-Henning Kamp                               const XML_Char *encoding);
9645bb6a25fSPoul-Henning Kamp</pre>
9655bb6a25fSPoul-Henning Kamp<div class="fcndef">
966*220ed979SColeman KaneConstruct a new <code>XML_Parser</code> object for parsing an external
9675bb6a25fSPoul-Henning Kampgeneral entity. Context is the context argument passed in a call to a
9685bb6a25fSPoul-Henning KampExternalEntityRefHandler. Other state information such as handlers,
9695bb6a25fSPoul-Henning Kampuser data, namespace processing is inherited from the parser passed as
9705bb6a25fSPoul-Henning Kampthe 1st argument. So you shouldn't need to call any of the behavior
9715bb6a25fSPoul-Henning Kampchanging functions on this parser (unless you want it to act
9725bb6a25fSPoul-Henning Kampdifferently than the parent parser).
9735bb6a25fSPoul-Henning Kamp</div>
9745bb6a25fSPoul-Henning Kamp
975*220ed979SColeman Kane<pre class="fcndec" id="XML_ParserFree">
976*220ed979SColeman Kanevoid XMLCALL
977*220ed979SColeman KaneXML_ParserFree(XML_Parser p);
9785bb6a25fSPoul-Henning Kamp</pre>
9795bb6a25fSPoul-Henning Kamp<div class="fcndef">
9805bb6a25fSPoul-Henning KampFree memory used by the parser. Your application is responsible for
9815bb6a25fSPoul-Henning Kampfreeing any memory associated with <a href="#userdata">user data</a>.
982*220ed979SColeman Kane</div>
983*220ed979SColeman Kane
984*220ed979SColeman Kane<pre class="fcndec" id="XML_ParserReset">
985*220ed979SColeman KaneXML_Bool XMLCALL
9865bb6a25fSPoul-Henning KampXML_ParserReset(XML_Parser p,
9875bb6a25fSPoul-Henning Kamp                const XML_Char *encoding);
9885bb6a25fSPoul-Henning Kamp</pre>
9895bb6a25fSPoul-Henning Kamp<div class="fcndef">
9905bb6a25fSPoul-Henning KampClean up the memory structures maintained by the parser so that it may
9915bb6a25fSPoul-Henning Kampbe used again.  After this has been called, <code>parser</code> is
9925bb6a25fSPoul-Henning Kampready to start parsing a new document.  All handlers are cleared from
9935bb6a25fSPoul-Henning Kampthe parser, except for the unknownEncodingHandler.  The parser's external
9945bb6a25fSPoul-Henning Kampstate is re-initialized except for the values of ns and ns_triplets.
995*220ed979SColeman KaneThis function may not be used on a parser created using <code><a href=
996*220ed979SColeman Kane"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a
997*220ed979SColeman Kane></code>; it will return <code>XML_FALSE</code> in that case.  Returns
998*220ed979SColeman Kane<code>XML_TRUE</code> on success.  Your application is responsible for
999*220ed979SColeman Kanedealing with any memory associated with <a href="#userdata">user data</a>.
1000*220ed979SColeman Kane</div>
1001*220ed979SColeman Kane
1002*220ed979SColeman Kane<h3><a name="parsing">Parsing</a></h3>
10035bb6a25fSPoul-Henning Kamp
10045bb6a25fSPoul-Henning Kamp<p>To state the obvious: the three parsing functions <code><a href=
1005*220ed979SColeman Kane"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer">
1006*220ed979SColeman KaneXML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer">
1007*220ed979SColeman KaneXML_GetBuffer</a></code> must not be called from within a handler
1008*220ed979SColeman Kaneunless they operate on a separate parser instance, that is, one that
1009*220ed979SColeman Kanedid not call the handler. For example, it is OK to call the parsing
1010*220ed979SColeman Kanefunctions from within an <code>XML_ExternalEntityRefHandler</code>,
1011*220ed979SColeman Kaneif they apply to the parser created by
1012*220ed979SColeman Kane<code><a href= "#XML_ExternalEntityParserCreate"
10135bb6a25fSPoul-Henning Kamp>XML_ExternalEntityParserCreate</a></code>.</p>
1014*220ed979SColeman Kane
10155bb6a25fSPoul-Henning Kamp<p>Note: the <code>len</code> argument passed to these functions
10165bb6a25fSPoul-Henning Kampshould be considerably less than the maximum value for an integer,
10175bb6a25fSPoul-Henning Kampas it could create an integer overflow situation if the added
10185bb6a25fSPoul-Henning Kamplengths of a buffer and the unprocessed portion of the previous buffer
10195bb6a25fSPoul-Henning Kampexceed the maximum integer value. Input data at the end of a buffer
10205bb6a25fSPoul-Henning Kampwill remain unprocessed if it is part of an XML token for which the
10215bb6a25fSPoul-Henning Kampend is not part of that buffer.</p>
10225bb6a25fSPoul-Henning Kamp
10235bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_Parse">
10245bb6a25fSPoul-Henning Kampenum XML_Status XMLCALL
10255bb6a25fSPoul-Henning KampXML_Parse(XML_Parser p,
10265bb6a25fSPoul-Henning Kamp          const char *s,
10275bb6a25fSPoul-Henning Kamp          int len,
10285bb6a25fSPoul-Henning Kamp          int isFinal);
10295bb6a25fSPoul-Henning Kamp</pre>
10305bb6a25fSPoul-Henning Kamp<pre class="signature">
10315bb6a25fSPoul-Henning Kampenum XML_Status {
10325bb6a25fSPoul-Henning Kamp  XML_STATUS_ERROR = 0,
10335bb6a25fSPoul-Henning Kamp  XML_STATUS_OK = 1
10345bb6a25fSPoul-Henning Kamp};
10355bb6a25fSPoul-Henning Kamp</pre>
10365bb6a25fSPoul-Henning Kamp<div class="fcndef">
10375bb6a25fSPoul-Henning KampParse some more of the document. The string <code>s</code> is a buffer
10385bb6a25fSPoul-Henning Kampcontaining part (or perhaps all) of the document. The number of bytes of s
10395bb6a25fSPoul-Henning Kampthat are part of the document is indicated by <code>len</code>. This means
10405bb6a25fSPoul-Henning Kampthat <code>s</code> doesn't have to be null terminated. It also means that
1041*220ed979SColeman Kaneif <code>len</code> is larger than the number of bytes in the block of
10425bb6a25fSPoul-Henning Kampmemory that <code>s</code> points at, then a memory fault is likely. The
10435bb6a25fSPoul-Henning Kamp<code>isFinal</code> parameter informs the parser that this is the last
10445bb6a25fSPoul-Henning Kamppiece of the document. Frequently, the last piece is empty (i.e.
10455bb6a25fSPoul-Henning Kamp<code>len</code> is zero.)
10465bb6a25fSPoul-Henning KampIf a parse error occurred, it returns <code>XML_STATUS_ERROR</code>.
10475bb6a25fSPoul-Henning KampOtherwise it returns <code>XML_STATUS_OK</code> value.
10485bb6a25fSPoul-Henning Kamp</div>
10495bb6a25fSPoul-Henning Kamp
10505bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParseBuffer">
10515bb6a25fSPoul-Henning Kampenum XML_Status XMLCALL
10525bb6a25fSPoul-Henning KampXML_ParseBuffer(XML_Parser p,
10535bb6a25fSPoul-Henning Kamp                int len,
10545bb6a25fSPoul-Henning Kamp                int isFinal);
1055*220ed979SColeman Kane</pre>
10565bb6a25fSPoul-Henning Kamp<div class="fcndef">
10575bb6a25fSPoul-Henning KampThis is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>,
10585bb6a25fSPoul-Henning Kampexcept in this case Expat provides the buffer.  By obtaining the
10595bb6a25fSPoul-Henning Kampbuffer from Expat with the <code><a href= "#XML_GetBuffer"
10605bb6a25fSPoul-Henning Kamp>XML_GetBuffer</a></code> function, the application can avoid double
10615bb6a25fSPoul-Henning Kampcopying of the input.
10625bb6a25fSPoul-Henning Kamp</div>
10635bb6a25fSPoul-Henning Kamp
10645bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetBuffer">
10655bb6a25fSPoul-Henning Kampvoid * XMLCALL
10665bb6a25fSPoul-Henning KampXML_GetBuffer(XML_Parser p,
10675bb6a25fSPoul-Henning Kamp              int len);
10685bb6a25fSPoul-Henning Kamp</pre>
10695bb6a25fSPoul-Henning Kamp<div class="fcndef">
10705bb6a25fSPoul-Henning KampObtain a buffer of size <code>len</code> to read a piece of the document
10715bb6a25fSPoul-Henning Kampinto. A NULL value is returned if Expat can't allocate enough memory for
10725bb6a25fSPoul-Henning Kampthis buffer. This has to be called prior to every call to
10735bb6a25fSPoul-Henning Kamp<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A
10745bb6a25fSPoul-Henning Kamptypical use would look like this:
10755bb6a25fSPoul-Henning Kamp
10765bb6a25fSPoul-Henning Kamp<pre class="eg">
10775bb6a25fSPoul-Henning Kampfor (;;) {
10785bb6a25fSPoul-Henning Kamp  int bytes_read;
10795bb6a25fSPoul-Henning Kamp  void *buff = XML_GetBuffer(p, BUFF_SIZE);
10805bb6a25fSPoul-Henning Kamp  if (buff == NULL) {
10815bb6a25fSPoul-Henning Kamp    /* handle error */
10825bb6a25fSPoul-Henning Kamp  }
10835bb6a25fSPoul-Henning Kamp
10845bb6a25fSPoul-Henning Kamp  bytes_read = read(docfd, buff, BUFF_SIZE);
10855bb6a25fSPoul-Henning Kamp  if (bytes_read &lt; 0) {
10865bb6a25fSPoul-Henning Kamp    /* handle error */
10875bb6a25fSPoul-Henning Kamp  }
10885bb6a25fSPoul-Henning Kamp
1089*220ed979SColeman Kane  if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) {
1090*220ed979SColeman Kane    /* handle parse error */
1091*220ed979SColeman Kane  }
1092*220ed979SColeman Kane
1093*220ed979SColeman Kane  if (bytes_read == 0)
1094*220ed979SColeman Kane    break;
1095*220ed979SColeman Kane}
1096*220ed979SColeman Kane</pre>
1097*220ed979SColeman Kane</div>
1098*220ed979SColeman Kane
1099*220ed979SColeman Kane<pre class="fcndec" id="XML_StopParser">
1100*220ed979SColeman Kaneenum XML_Status XMLCALL
1101*220ed979SColeman KaneXML_StopParser(XML_Parser p,
1102*220ed979SColeman Kane               XML_Bool resumable);
1103*220ed979SColeman Kane</pre>
1104*220ed979SColeman Kane<div class="fcndef">
1105*220ed979SColeman Kane
1106*220ed979SColeman Kane<p>Stops parsing, causing <code><a href= "#XML_Parse"
1107*220ed979SColeman Kane>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer"
1108*220ed979SColeman Kane>XML_ParseBuffer</a></code> to return.  Must be called from within a
1109*220ed979SColeman Kanecall-back handler, except when aborting (when <code>resumable</code>
1110*220ed979SColeman Kaneis <code>XML_FALSE</code>) an already suspended parser.  Some
1111*220ed979SColeman Kanecall-backs may still follow because they would otherwise get
1112*220ed979SColeman Kanelost, including
1113*220ed979SColeman Kane<ul>
1114*220ed979SColeman Kane  <li> the end element handler for empty elements when stopped in the
1115*220ed979SColeman Kane       start element handler,</li>
1116*220ed979SColeman Kane  <li> the end namespace declaration handler when stopped in the end
1117*220ed979SColeman Kane       element handler,</li>
1118*220ed979SColeman Kane  <li> the character data handler when stopped in the character data handler
1119*220ed979SColeman Kane       while making multiple call-backs on a contiguous chunk of characters,</li>
1120*220ed979SColeman Kane</ul>
1121*220ed979SColeman Kaneand possibly others.</p>
1122*220ed979SColeman Kane
1123*220ed979SColeman Kane<p>This can be called from most handlers, including DTD related
1124*220ed979SColeman Kanecall-backs, except when parsing an external parameter entity and
1125*220ed979SColeman Kane<code>resumable</code> is <code>XML_TRUE</code>.  Returns
1126*220ed979SColeman Kane<code>XML_STATUS_OK</code> when successful,
1127*220ed979SColeman Kane<code>XML_STATUS_ERROR</code> otherwise.  The possible error codes
1128*220ed979SColeman Kaneare:</p>
1129*220ed979SColeman Kane<dl>
1130*220ed979SColeman Kane  <dt><code>XML_ERROR_SUSPENDED</code></dt>
1131*220ed979SColeman Kane  <dd>when suspending an already suspended parser.</dd>
1132*220ed979SColeman Kane  <dt><code>XML_ERROR_FINISHED</code></dt>
1133*220ed979SColeman Kane  <dd>when the parser has already finished.</dd>
1134*220ed979SColeman Kane  <dt><code>XML_ERROR_SUSPEND_PE</code></dt>
1135*220ed979SColeman Kane  <dd>when suspending while parsing an external PE.</dd>
1136*220ed979SColeman Kane</dl>
1137*220ed979SColeman Kane
1138*220ed979SColeman Kane<p>Since the stop/resume feature requires application support in the
1139*220ed979SColeman Kaneouter parsing loop, it is an error to call this function for a parser
1140*220ed979SColeman Kanenot being handled appropriately; see <a href= "#stop-resume"
1141*220ed979SColeman Kane>Temporarily Stopping Parsing</a> for more information.</p>
1142*220ed979SColeman Kane
1143*220ed979SColeman Kane<p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing
1144*220ed979SColeman Kaneis <em>suspended</em>, that is, <code><a href= "#XML_Parse"
1145*220ed979SColeman Kane>XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer"
1146*220ed979SColeman Kane>XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>.
1147*220ed979SColeman KaneOtherwise, parsing is <em>aborted</em>, that is, <code><a href=
1148*220ed979SColeman Kane"#XML_Parse" >XML_Parse</a></code> and <code><a href=
1149*220ed979SColeman Kane"#XML_ParseBuffer" >XML_ParseBuffer</a></code> return
1150*220ed979SColeman Kane<code>XML_STATUS_ERROR</code> with error code
1151*220ed979SColeman Kane<code>XML_ERROR_ABORTED</code>.</p>
1152*220ed979SColeman Kane
1153*220ed979SColeman Kane<p><strong>Note:</strong>
1154*220ed979SColeman KaneThis will be applied to the current parser instance only, that is, if
1155*220ed979SColeman Kanethere is a parent parser then it will continue parsing when the
1156*220ed979SColeman Kaneexternal entity reference handler returns.  It is up to the
1157*220ed979SColeman Kaneimplementation of that handler to call <code><a href=
1158*220ed979SColeman Kane"#XML_StopParser" >XML_StopParser</a></code> on the parent parser
1159*220ed979SColeman Kane(recursively), if one wants to stop parsing altogether.</p>
1160*220ed979SColeman Kane
1161*220ed979SColeman Kane<p>When suspended, parsing can be resumed by calling <code><a href=
1162*220ed979SColeman Kane"#XML_ResumeParser" >XML_ResumeParser</a></code>.</p>
1163*220ed979SColeman Kane
1164*220ed979SColeman Kane<p>New in Expat 1.95.8.</p>
1165*220ed979SColeman Kane</div>
1166*220ed979SColeman Kane
1167*220ed979SColeman Kane<pre class="fcndec" id="XML_ResumeParser">
1168*220ed979SColeman Kaneenum XML_Status XMLCALL
1169*220ed979SColeman KaneXML_ResumeParser(XML_Parser p);
1170*220ed979SColeman Kane</pre>
1171*220ed979SColeman Kane<div class="fcndef">
1172*220ed979SColeman Kane<p>Resumes parsing after it has been suspended with <code><a href=
1173*220ed979SColeman Kane"#XML_StopParser" >XML_StopParser</a></code>.  Must not be called from
1174*220ed979SColeman Kanewithin a handler call-back.  Returns same status codes as <code><a
1175*220ed979SColeman Kanehref= "#XML_Parse">XML_Parse</a></code> or <code><a href=
1176*220ed979SColeman Kane"#XML_ParseBuffer" >XML_ParseBuffer</a></code>.  An additional error
1177*220ed979SColeman Kanecode, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the
1178*220ed979SColeman Kaneparser was not currently suspended.</p>
1179*220ed979SColeman Kane
1180*220ed979SColeman Kane<p><strong>Note:</strong>
1181*220ed979SColeman KaneThis must be called on the most deeply nested child parser instance
1182*220ed979SColeman Kanefirst, and on its parent parser only after the child parser has
1183*220ed979SColeman Kanefinished, to be applied recursively until the document entity's parser
1184*220ed979SColeman Kaneis restarted.  That is, the parent parser will not resume by itself
1185*220ed979SColeman Kaneand it is up to the application to call <code><a href=
1186*220ed979SColeman Kane"#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the
1187*220ed979SColeman Kaneappropriate moment.</p>
1188*220ed979SColeman Kane
1189*220ed979SColeman Kane<p>New in Expat 1.95.8.</p>
1190*220ed979SColeman Kane</div>
1191*220ed979SColeman Kane
1192*220ed979SColeman Kane<pre class="fcndec" id="XML_GetParsingStatus">
1193*220ed979SColeman Kanevoid XMLCALL
1194*220ed979SColeman KaneXML_GetParsingStatus(XML_Parser p,
1195*220ed979SColeman Kane                     XML_ParsingStatus *status);
1196*220ed979SColeman Kane</pre>
1197*220ed979SColeman Kane<pre class="signature">
1198*220ed979SColeman Kaneenum XML_Parsing {
1199*220ed979SColeman Kane  XML_INITIALIZED,
1200*220ed979SColeman Kane  XML_PARSING,
1201*220ed979SColeman Kane  XML_FINISHED,
1202*220ed979SColeman Kane  XML_SUSPENDED
1203*220ed979SColeman Kane};
1204*220ed979SColeman Kane
1205*220ed979SColeman Kanetypedef struct {
1206*220ed979SColeman Kane  enum XML_Parsing parsing;
1207*220ed979SColeman Kane  XML_Bool finalBuffer;
1208*220ed979SColeman Kane} XML_ParsingStatus;
1209*220ed979SColeman Kane</pre>
12105bb6a25fSPoul-Henning Kamp<div class="fcndef">
12115bb6a25fSPoul-Henning Kamp<p>Returns status of parser with respect to being initialized,
12125bb6a25fSPoul-Henning Kampparsing, finished, or suspended, and whether the final buffer is being
12135bb6a25fSPoul-Henning Kampprocessed.  The <code>status</code> parameter <em>must not</em> be
12145bb6a25fSPoul-Henning KampNULL.</p>
12155bb6a25fSPoul-Henning Kamp
12165bb6a25fSPoul-Henning Kamp<p>New in Expat 1.95.8.</p>
12175bb6a25fSPoul-Henning Kamp</div>
12185bb6a25fSPoul-Henning Kamp
12195bb6a25fSPoul-Henning Kamp
12205bb6a25fSPoul-Henning Kamp<h3><a name="setting">Handler Setting</a></h3>
12215bb6a25fSPoul-Henning Kamp
12225bb6a25fSPoul-Henning Kamp<p>Although handlers are typically set prior to parsing and left alone, an
12235bb6a25fSPoul-Henning Kampapplication may choose to set or change the handler for a parsing event
1224*220ed979SColeman Kanewhile the parse is in progress. For instance, your application may choose
1225*220ed979SColeman Kaneto ignore all text not descended from a <code>para</code> element. One
1226*220ed979SColeman Kaneway it could do this is to set the character handler when a para start tag
1227*220ed979SColeman Kaneis seen, and unset it for the corresponding end tag.</p>
1228*220ed979SColeman Kane
12295bb6a25fSPoul-Henning Kamp<p>A handler may be <em>unset</em> by providing a NULL pointer to the
12305bb6a25fSPoul-Henning Kampappropriate handler setter. None of the handler setting functions have
12315bb6a25fSPoul-Henning Kampa return value.</p>
1232*220ed979SColeman Kane
12335bb6a25fSPoul-Henning Kamp<p>Your handlers will be receiving strings in arrays of type
12345bb6a25fSPoul-Henning Kamp<code>XML_Char</code>. This type is conditionally defined in expat.h as
12355bb6a25fSPoul-Henning Kampeither <code>char</code>, <code>wchar_t</code> or <code>unsigned short</code>.
12365bb6a25fSPoul-Henning KampThe former implies UTF-8 encoding, the latter two imply UTF-16 encoding.
12375bb6a25fSPoul-Henning KampNote that you'll receive them in this form independent of the original
1238*220ed979SColeman Kaneencoding of the document.</p>
12395bb6a25fSPoul-Henning Kamp
12405bb6a25fSPoul-Henning Kamp<div class="handler">
12415bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartElementHandler">
12425bb6a25fSPoul-Henning Kampvoid XMLCALL
12435bb6a25fSPoul-Henning KampXML_SetStartElementHandler(XML_Parser p,
12445bb6a25fSPoul-Henning Kamp                           XML_StartElementHandler start);
12455bb6a25fSPoul-Henning Kamp</pre>
12465bb6a25fSPoul-Henning Kamp<pre class="signature">
12475bb6a25fSPoul-Henning Kamptypedef void
12485bb6a25fSPoul-Henning Kamp(XMLCALL *XML_StartElementHandler)(void *userData,
12495bb6a25fSPoul-Henning Kamp                                   const XML_Char *name,
12505bb6a25fSPoul-Henning Kamp                                   const XML_Char **atts);
12515bb6a25fSPoul-Henning Kamp</pre>
12525bb6a25fSPoul-Henning Kamp<p>Set handler for start (and empty) tags. Attributes are passed to the start
1253*220ed979SColeman Kanehandler as a pointer to a vector of char pointers. Each attribute seen in
12545bb6a25fSPoul-Henning Kampa start (or empty) tag occupies 2 consecutive places in this vector: the
12555bb6a25fSPoul-Henning Kampattribute name followed by the attribute value. These pairs are terminated
12565bb6a25fSPoul-Henning Kampby a null pointer.</p>
12575bb6a25fSPoul-Henning Kamp<p>Note that an empty tag generates a call to both start and end handlers
12585bb6a25fSPoul-Henning Kamp(in that order).</p>
1259*220ed979SColeman Kane</div>
12605bb6a25fSPoul-Henning Kamp
12615bb6a25fSPoul-Henning Kamp<div class="handler">
12625bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndElementHandler">
12635bb6a25fSPoul-Henning Kampvoid XMLCALL
12645bb6a25fSPoul-Henning KampXML_SetEndElementHandler(XML_Parser p,
12655bb6a25fSPoul-Henning Kamp                         XML_EndElementHandler);
12665bb6a25fSPoul-Henning Kamp</pre>
12675bb6a25fSPoul-Henning Kamp<pre class="signature">
1268*220ed979SColeman Kanetypedef void
12695bb6a25fSPoul-Henning Kamp(XMLCALL *XML_EndElementHandler)(void *userData,
12705bb6a25fSPoul-Henning Kamp                                 const XML_Char *name);
12715bb6a25fSPoul-Henning Kamp</pre>
12725bb6a25fSPoul-Henning Kamp<p>Set handler for end (and empty) tags. As noted above, an empty tag
12735bb6a25fSPoul-Henning Kampgenerates a call to both start and end handlers.</p>
12745bb6a25fSPoul-Henning Kamp</div>
12755bb6a25fSPoul-Henning Kamp
12765bb6a25fSPoul-Henning Kamp<div class="handler">
12775bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetElementHandler">
1278*220ed979SColeman Kanevoid XMLCALL
12795bb6a25fSPoul-Henning KampXML_SetElementHandler(XML_Parser p,
12805bb6a25fSPoul-Henning Kamp                      XML_StartElementHandler start,
12815bb6a25fSPoul-Henning Kamp                      XML_EndElementHandler end);
12825bb6a25fSPoul-Henning Kamp</pre>
12835bb6a25fSPoul-Henning Kamp<p>Set handlers for start and end tags with one call.</p>
1284*220ed979SColeman Kane</div>
12855bb6a25fSPoul-Henning Kamp
12865bb6a25fSPoul-Henning Kamp<div class="handler">
12875bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCharacterDataHandler">
12885bb6a25fSPoul-Henning Kampvoid XMLCALL
12895bb6a25fSPoul-Henning KampXML_SetCharacterDataHandler(XML_Parser p,
12905bb6a25fSPoul-Henning Kamp                            XML_CharacterDataHandler charhndl)
12915bb6a25fSPoul-Henning Kamp</pre>
12925bb6a25fSPoul-Henning Kamp<pre class="signature">
1293*220ed979SColeman Kanetypedef void
1294*220ed979SColeman Kane(XMLCALL *XML_CharacterDataHandler)(void *userData,
1295*220ed979SColeman Kane                                    const XML_Char *s,
1296*220ed979SColeman Kane                                    int len);
12975bb6a25fSPoul-Henning Kamp</pre>
12985bb6a25fSPoul-Henning Kamp<p>Set a text handler. The string your handler receives
12995bb6a25fSPoul-Henning Kampis <em>NOT nul-terminated</em>. You have to use the length argument
13005bb6a25fSPoul-Henning Kampto deal with the end of the string. A single block of contiguous text
1301*220ed979SColeman Kanefree of markup may still result in a sequence of calls to this handler.
13025bb6a25fSPoul-Henning KampIn other words, if you're searching for a pattern in the text, it may
13035bb6a25fSPoul-Henning Kampbe split across calls to this handler. Note: Setting this handler to NULL
13045bb6a25fSPoul-Henning Kampmay <em>NOT immediately</em> terminate call-backs if the parser is currently
13055bb6a25fSPoul-Henning Kampprocessing such a single block of contiguous markup-free text, as the parser
13065bb6a25fSPoul-Henning Kampwill continue calling back until the end of the block is reached.</p>
1307*220ed979SColeman Kane</div>
13085bb6a25fSPoul-Henning Kamp
13095bb6a25fSPoul-Henning Kamp<div class="handler">
13105bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetProcessingInstructionHandler">
13115bb6a25fSPoul-Henning Kampvoid XMLCALL
13125bb6a25fSPoul-Henning KampXML_SetProcessingInstructionHandler(XML_Parser p,
13135bb6a25fSPoul-Henning Kamp                                    XML_ProcessingInstructionHandler proc)
13145bb6a25fSPoul-Henning Kamp</pre>
13155bb6a25fSPoul-Henning Kamp<pre class="signature">
13165bb6a25fSPoul-Henning Kamptypedef void
13175bb6a25fSPoul-Henning Kamp(XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
13185bb6a25fSPoul-Henning Kamp                                            const XML_Char *target,
1319*220ed979SColeman Kane                                            const XML_Char *data);
13205bb6a25fSPoul-Henning Kamp
13215bb6a25fSPoul-Henning Kamp</pre>
13225bb6a25fSPoul-Henning Kamp<p>Set a handler for processing instructions. The target is the first word
13235bb6a25fSPoul-Henning Kampin the processing instruction. The data is the rest of the characters in
13245bb6a25fSPoul-Henning Kampit after skipping all whitespace after the initial word.</p>
1325*220ed979SColeman Kane</div>
13265bb6a25fSPoul-Henning Kamp
13275bb6a25fSPoul-Henning Kamp<div class="handler">
13285bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCommentHandler">
13295bb6a25fSPoul-Henning Kampvoid XMLCALL
13305bb6a25fSPoul-Henning KampXML_SetCommentHandler(XML_Parser p,
13315bb6a25fSPoul-Henning Kamp                      XML_CommentHandler cmnt)
13325bb6a25fSPoul-Henning Kamp</pre>
13335bb6a25fSPoul-Henning Kamp<pre class="signature">
1334*220ed979SColeman Kanetypedef void
13355bb6a25fSPoul-Henning Kamp(XMLCALL *XML_CommentHandler)(void *userData,
13365bb6a25fSPoul-Henning Kamp                              const XML_Char *data);
13375bb6a25fSPoul-Henning Kamp</pre>
13385bb6a25fSPoul-Henning Kamp<p>Set a handler for comments. The data is all text inside the comment
13395bb6a25fSPoul-Henning Kampdelimiters.</p>
1340*220ed979SColeman Kane</div>
13415bb6a25fSPoul-Henning Kamp
13425bb6a25fSPoul-Henning Kamp<div class="handler">
13435bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartCdataSectionHandler">
13445bb6a25fSPoul-Henning Kampvoid XMLCALL
13455bb6a25fSPoul-Henning KampXML_SetStartCdataSectionHandler(XML_Parser p,
13465bb6a25fSPoul-Henning Kamp                                XML_StartCdataSectionHandler start);
1347*220ed979SColeman Kane</pre>
13485bb6a25fSPoul-Henning Kamp<pre class="signature">
13495bb6a25fSPoul-Henning Kamptypedef void
13505bb6a25fSPoul-Henning Kamp(XMLCALL *XML_StartCdataSectionHandler)(void *userData);
13515bb6a25fSPoul-Henning Kamp</pre>
13525bb6a25fSPoul-Henning Kamp<p>Set a handler that gets called at the beginning of a CDATA section.</p>
1353*220ed979SColeman Kane</div>
13545bb6a25fSPoul-Henning Kamp
13555bb6a25fSPoul-Henning Kamp<div class="handler">
13565bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndCdataSectionHandler">
13575bb6a25fSPoul-Henning Kampvoid XMLCALL
13585bb6a25fSPoul-Henning KampXML_SetEndCdataSectionHandler(XML_Parser p,
13595bb6a25fSPoul-Henning Kamp                              XML_EndCdataSectionHandler end);
1360*220ed979SColeman Kane</pre>
13615bb6a25fSPoul-Henning Kamp<pre class="signature">
13625bb6a25fSPoul-Henning Kamptypedef void
13635bb6a25fSPoul-Henning Kamp(XMLCALL *XML_EndCdataSectionHandler)(void *userData);
13645bb6a25fSPoul-Henning Kamp</pre>
13655bb6a25fSPoul-Henning Kamp<p>Set a handler that gets called at the end of a CDATA section.</p>
13665bb6a25fSPoul-Henning Kamp</div>
13675bb6a25fSPoul-Henning Kamp
13685bb6a25fSPoul-Henning Kamp<div class="handler">
13695bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCdataSectionHandler">
1370*220ed979SColeman Kanevoid XMLCALL
13715bb6a25fSPoul-Henning KampXML_SetCdataSectionHandler(XML_Parser p,
13725bb6a25fSPoul-Henning Kamp                           XML_StartCdataSectionHandler start,
13735bb6a25fSPoul-Henning Kamp                           XML_EndCdataSectionHandler end)
13745bb6a25fSPoul-Henning Kamp</pre>
13755bb6a25fSPoul-Henning Kamp<p>Sets both CDATA section handlers with one call.</p>
1376*220ed979SColeman Kane</div>
13775bb6a25fSPoul-Henning Kamp
13785bb6a25fSPoul-Henning Kamp<div class="handler">
13795bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDefaultHandler">
13805bb6a25fSPoul-Henning Kampvoid XMLCALL
13815bb6a25fSPoul-Henning KampXML_SetDefaultHandler(XML_Parser p,
13825bb6a25fSPoul-Henning Kamp                      XML_DefaultHandler hndl)
13835bb6a25fSPoul-Henning Kamp</pre>
13845bb6a25fSPoul-Henning Kamp<pre class="signature">
13855bb6a25fSPoul-Henning Kamptypedef void
13865bb6a25fSPoul-Henning Kamp(XMLCALL *XML_DefaultHandler)(void *userData,
13875bb6a25fSPoul-Henning Kamp                              const XML_Char *s,
13885bb6a25fSPoul-Henning Kamp                              int len);
13895bb6a25fSPoul-Henning Kamp</pre>
13905bb6a25fSPoul-Henning Kamp
13915bb6a25fSPoul-Henning Kamp<p>Sets a handler for any characters in the document which wouldn't
13925bb6a25fSPoul-Henning Kampotherwise be handled. This includes both data for which no handlers
13935bb6a25fSPoul-Henning Kampcan be set (like some kinds of DTD declarations) and data which could
13945bb6a25fSPoul-Henning Kampbe reported but which currently has no handler set.  The characters
13955bb6a25fSPoul-Henning Kampare passed exactly as they were present in the XML document except
13965bb6a25fSPoul-Henning Kampthat they will be encoded in UTF-8 or UTF-16. Line boundaries are not
13975bb6a25fSPoul-Henning Kampnormalized. Note that a byte order mark character is not passed to the
13985bb6a25fSPoul-Henning Kampdefault handler. There are no guarantees about how characters are
13995bb6a25fSPoul-Henning Kampdivided between calls to the default handler: for example, a comment
14005bb6a25fSPoul-Henning Kampmight be split between multiple calls.  Setting the handler with
1401*220ed979SColeman Kanethis call has the side effect of turning off expansion of references
14025bb6a25fSPoul-Henning Kampto internally defined general entities. Instead these references are
14035bb6a25fSPoul-Henning Kamppassed to the default handler.</p>
14045bb6a25fSPoul-Henning Kamp
14055bb6a25fSPoul-Henning Kamp<p>See also <code><a
14065bb6a25fSPoul-Henning Kamphref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p>
1407*220ed979SColeman Kane</div>
14085bb6a25fSPoul-Henning Kamp
14095bb6a25fSPoul-Henning Kamp<div class="handler">
14105bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDefaultHandlerExpand">
14115bb6a25fSPoul-Henning Kampvoid XMLCALL
14125bb6a25fSPoul-Henning KampXML_SetDefaultHandlerExpand(XML_Parser p,
14135bb6a25fSPoul-Henning Kamp                            XML_DefaultHandler hndl)
14145bb6a25fSPoul-Henning Kamp</pre>
14155bb6a25fSPoul-Henning Kamp<pre class="signature">
14165bb6a25fSPoul-Henning Kamptypedef void
14175bb6a25fSPoul-Henning Kamp(XMLCALL *XML_DefaultHandler)(void *userData,
14185bb6a25fSPoul-Henning Kamp                              const XML_Char *s,
14195bb6a25fSPoul-Henning Kamp                              int len);
14205bb6a25fSPoul-Henning Kamp</pre>
1421*220ed979SColeman Kane<p>This sets a default handler, but doesn't inhibit the expansion of
14225bb6a25fSPoul-Henning Kampinternal entity references.  The entity reference will not be passed
14235bb6a25fSPoul-Henning Kampto the default handler.</p>
14245bb6a25fSPoul-Henning Kamp
14255bb6a25fSPoul-Henning Kamp<p>See also <code><a
14265bb6a25fSPoul-Henning Kamphref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p>
1427*220ed979SColeman Kane</div>
14285bb6a25fSPoul-Henning Kamp
14295bb6a25fSPoul-Henning Kamp<div class="handler">
14305bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetExternalEntityRefHandler">
14315bb6a25fSPoul-Henning Kampvoid XMLCALL
14325bb6a25fSPoul-Henning KampXML_SetExternalEntityRefHandler(XML_Parser p,
14335bb6a25fSPoul-Henning Kamp                                XML_ExternalEntityRefHandler hndl)
14345bb6a25fSPoul-Henning Kamp</pre>
14355bb6a25fSPoul-Henning Kamp<pre class="signature">
14365bb6a25fSPoul-Henning Kamptypedef int
14375bb6a25fSPoul-Henning Kamp(XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p,
1438*220ed979SColeman Kane                                        const XML_Char *context,
1439*220ed979SColeman Kane                                        const XML_Char *base,
1440*220ed979SColeman Kane                                        const XML_Char *systemId,
1441*220ed979SColeman Kane                                        const XML_Char *publicId);
1442*220ed979SColeman Kane</pre>
1443*220ed979SColeman Kane<p>Set an external entity reference handler. This handler is also
1444*220ed979SColeman Kanecalled for processing an external DTD subset if parameter entity parsing
1445*220ed979SColeman Kaneis in effect. (See <a href="#XML_SetParamEntityParsing">
14465bb6a25fSPoul-Henning Kamp<code>XML_SetParamEntityParsing</code></a>.)</p>
1447*220ed979SColeman Kane
1448*220ed979SColeman Kane<p>The <code>context</code> parameter specifies the parsing context in
1449*220ed979SColeman Kanethe format expected by the <code>context</code> argument to <code><a
1450*220ed979SColeman Kanehref="#XML_ExternalEntityParserCreate"
1451*220ed979SColeman Kane>XML_ExternalEntityParserCreate</a></code>.  <code>code</code> is
1452*220ed979SColeman Kanevalid only until the handler returns, so if the referenced entity is
14535bb6a25fSPoul-Henning Kampto be parsed later, it must be copied.  <code>context</code> is NULL
1454*220ed979SColeman Kaneonly when the entity is a parameter entity, which is how one can
1455*220ed979SColeman Kanedifferentiate between general and parameter entities.</p>
1456*220ed979SColeman Kane
1457*220ed979SColeman Kane<p>The <code>base</code> parameter is the base to use for relative
1458*220ed979SColeman Kanesystem identifiers.  It is set by <code><a
1459*220ed979SColeman Kanehref="#XML_SetBase">XML_SetBase</a></code> and may be NULL. The
1460*220ed979SColeman Kane<code>publicId</code> parameter is the public id given in the entity
14615bb6a25fSPoul-Henning Kampdeclaration and may be NULL.  <code>systemId</code> is the system
1462*220ed979SColeman Kaneidentifier specified in the entity declaration and is never NULL.</p>
1463*220ed979SColeman Kane
1464*220ed979SColeman Kane<p>There are a couple of ways in which this handler differs from
1465*220ed979SColeman Kaneothers.  First, this handler returns a status indicator (an
1466*220ed979SColeman Kaneinteger). <code>XML_STATUS_OK</code> should be returned for successful
1467*220ed979SColeman Kanehandling of the external entity reference.  Returning
14685bb6a25fSPoul-Henning Kamp<code>XML_STATUS_ERROR</code> indicates failure, and causes the
14695bb6a25fSPoul-Henning Kampcalling parser to return an
14705bb6a25fSPoul-Henning Kamp<code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p>
14715bb6a25fSPoul-Henning Kamp
14725bb6a25fSPoul-Henning Kamp<p>Second, instead of having the user data as its first argument, it
1473*220ed979SColeman Kanereceives the parser that encountered the entity reference. This, along
1474*220ed979SColeman Kanewith the context parameter, may be used as arguments to a call to
1475*220ed979SColeman Kane<code><a href= "#XML_ExternalEntityParserCreate"
1476*220ed979SColeman Kane>XML_ExternalEntityParserCreate</a></code>.  Using the returned
1477*220ed979SColeman Kaneparser, the body of the external entity can be recursively parsed.</p>
1478*220ed979SColeman Kane
1479*220ed979SColeman Kane<p>Since this handler may be called recursively, it should not be saving
1480*220ed979SColeman Kaneinformation into global or static variables.</p>
1481*220ed979SColeman Kane</div>
1482*220ed979SColeman Kane
1483*220ed979SColeman Kane<pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg">
1484*220ed979SColeman Kanevoid XMLCALL
1485*220ed979SColeman KaneXML_SetExternalEntityRefHandlerArg(XML_Parser p,
1486*220ed979SColeman Kane                                   void *arg)
1487*220ed979SColeman Kane</pre>
1488*220ed979SColeman Kane<div class="fcndef">
1489*220ed979SColeman Kane<p>Set the argument passed to the ExternalEntityRefHandler.  If
1490*220ed979SColeman Kane<code>arg</code> is not NULL, it is the new value passed to the
1491*220ed979SColeman Kanehandler set using <code><a href="#XML_SetExternalEntityRefHandler"
1492*220ed979SColeman Kane>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is
1493*220ed979SColeman KaneNULL, the argument passed to the handler function will be the parser
1494*220ed979SColeman Kaneobject itself.</p>
1495*220ed979SColeman Kane
1496*220ed979SColeman Kane<p><strong>Note:</strong>
1497*220ed979SColeman KaneThe type of <code>arg</code> and the type of the first argument to the
14985bb6a25fSPoul-Henning KampExternalEntityRefHandler do not match.  This function takes a
14995bb6a25fSPoul-Henning Kamp<code>void *</code> to be passed to the handler, while the handler
1500*220ed979SColeman Kaneaccepts an <code>XML_Parser</code>.  This is a historical accident,
15015bb6a25fSPoul-Henning Kampbut will not be corrected before Expat 2.0 (at the earliest) to avoid
15025bb6a25fSPoul-Henning Kampcausing compiler warnings for code that's known to work with this
15035bb6a25fSPoul-Henning KampAPI.  It is the responsibility of the application code to know the
15045bb6a25fSPoul-Henning Kampactual type of the argument passed to the handler and to manage it
15055bb6a25fSPoul-Henning Kampproperly.</p>
1506*220ed979SColeman Kane</div>
15075bb6a25fSPoul-Henning Kamp
15085bb6a25fSPoul-Henning Kamp<div class="handler">
15095bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetSkippedEntityHandler">
15105bb6a25fSPoul-Henning Kampvoid XMLCALL
15115bb6a25fSPoul-Henning KampXML_SetSkippedEntityHandler(XML_Parser p,
15125bb6a25fSPoul-Henning Kamp                            XML_SkippedEntityHandler handler)
15135bb6a25fSPoul-Henning Kamp</pre>
15145bb6a25fSPoul-Henning Kamp<pre class="signature">
15155bb6a25fSPoul-Henning Kamptypedef void
15165bb6a25fSPoul-Henning Kamp(XMLCALL *XML_SkippedEntityHandler)(void *userData,
15175bb6a25fSPoul-Henning Kamp                                    const XML_Char *entityName,
15185bb6a25fSPoul-Henning Kamp                                    int is_parameter_entity);
15195bb6a25fSPoul-Henning Kamp</pre>
15205bb6a25fSPoul-Henning Kamp<p>Set a skipped entity handler. This is called in two situations:</p>
15215bb6a25fSPoul-Henning Kamp<ol>
15225bb6a25fSPoul-Henning Kamp   <li>An entity reference is encountered for which no declaration
15235bb6a25fSPoul-Henning Kamp       has been read <em>and</em> this is not an error.</li>
15245bb6a25fSPoul-Henning Kamp   <li>An internal entity reference is read, but not expanded, because
15255bb6a25fSPoul-Henning Kamp       <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a>
15265bb6a25fSPoul-Henning Kamp	   has been called.</li>
1527*220ed979SColeman Kane</ol>
15285bb6a25fSPoul-Henning Kamp<p>The <code>is_parameter_entity</code> argument will be non-zero for
15295bb6a25fSPoul-Henning Kampa parameter entity and zero for a general entity.</p> <p>Note: skipped
15305bb6a25fSPoul-Henning Kampparameter entities in declarations and skipped general entities in
15315bb6a25fSPoul-Henning Kampattribute values cannot be reported, because the event would be out of
15325bb6a25fSPoul-Henning Kampsync with the reporting of the declarations or attribute values</p>
15335bb6a25fSPoul-Henning Kamp</div>
1534*220ed979SColeman Kane
15355bb6a25fSPoul-Henning Kamp<div class="handler">
15365bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetUnknownEncodingHandler">
15375bb6a25fSPoul-Henning Kampvoid XMLCALL
15385bb6a25fSPoul-Henning KampXML_SetUnknownEncodingHandler(XML_Parser p,
15395bb6a25fSPoul-Henning Kamp                              XML_UnknownEncodingHandler enchandler,
15405bb6a25fSPoul-Henning Kamp			      void *encodingHandlerData)
1541*220ed979SColeman Kane</pre>
1542*220ed979SColeman Kane<pre class="signature">
15435bb6a25fSPoul-Henning Kamptypedef int
15445bb6a25fSPoul-Henning Kamp(XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData,
1545*220ed979SColeman Kane                                      const XML_Char *name,
1546*220ed979SColeman Kane                                      XML_Encoding *info);
15475bb6a25fSPoul-Henning Kamp
15485bb6a25fSPoul-Henning Kamptypedef struct {
1549*220ed979SColeman Kane  int map[256];
1550*220ed979SColeman Kane  void *data;
1551*220ed979SColeman Kane  int (XMLCALL *convert)(void *data, const char *s);
1552*220ed979SColeman Kane  void (XMLCALL *release)(void *data);
1553*220ed979SColeman Kane} XML_Encoding;
1554*220ed979SColeman Kane</pre>
1555*220ed979SColeman Kane<p>Set a handler to deal with encodings other than the <a
15565bb6a25fSPoul-Henning Kamphref="#builtin_encodings">built in set</a>. This should be done before
15575bb6a25fSPoul-Henning Kamp<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href=
15585bb6a25fSPoul-Henning Kamp"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the
15595bb6a25fSPoul-Henning Kampgiven parser.</p> <p>If the handler knows how to deal with an encoding
15605bb6a25fSPoul-Henning Kampwith the given name, it should fill in the <code>info</code> data
15615bb6a25fSPoul-Henning Kampstructure and return <code>XML_STATUS_OK</code>. Otherwise it
15625bb6a25fSPoul-Henning Kampshould return <code>XML_STATUS_ERROR</code>. The handler will be called
15635bb6a25fSPoul-Henning Kampat most once per parsed (external) entity. The optional application
15645bb6a25fSPoul-Henning Kampdata pointer <code>encodingHandlerData</code> will be passed back to
15655bb6a25fSPoul-Henning Kampthe handler.</p>
15665bb6a25fSPoul-Henning Kamp
15675bb6a25fSPoul-Henning Kamp<p>The map array contains information for every possible possible leading
15685bb6a25fSPoul-Henning Kampbyte in a byte sequence. If the corresponding value is &gt;= 0, then it's
15695bb6a25fSPoul-Henning Kampa single byte sequence and the byte encodes that Unicode value. If the
15705bb6a25fSPoul-Henning Kampvalue is -1, then that byte is invalid as the initial byte in a sequence.
15715bb6a25fSPoul-Henning KampIf the value is -n, where n is an integer &gt; 1, then n is the number of
15725bb6a25fSPoul-Henning Kampbytes in the sequence and the actual conversion is accomplished by a
15735bb6a25fSPoul-Henning Kampcall to the function pointed at by convert. This function may return -1
15745bb6a25fSPoul-Henning Kampif the sequence itself is invalid. The convert pointer may be null if
15755bb6a25fSPoul-Henning Kampthere are only single byte codes. The data parameter passed to the convert
1576*220ed979SColeman Kanefunction is the data pointer from <code>XML_Encoding</code>. The
15775bb6a25fSPoul-Henning Kampstring s is <em>NOT</em> nul-terminated and points at the sequence of
15785bb6a25fSPoul-Henning Kampbytes to be converted.</p>
15795bb6a25fSPoul-Henning Kamp
15805bb6a25fSPoul-Henning Kamp<p>The function pointed at by <code>release</code> is called by the
15815bb6a25fSPoul-Henning Kampparser when it is finished with the encoding. It may be NULL.</p>
1582*220ed979SColeman Kane</div>
15835bb6a25fSPoul-Henning Kamp
15845bb6a25fSPoul-Henning Kamp<div class="handler">
15855bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartNamespaceDeclHandler">
15865bb6a25fSPoul-Henning Kampvoid XMLCALL
15875bb6a25fSPoul-Henning KampXML_SetStartNamespaceDeclHandler(XML_Parser p,
15885bb6a25fSPoul-Henning Kamp			         XML_StartNamespaceDeclHandler start);
15895bb6a25fSPoul-Henning Kamp</pre>
15905bb6a25fSPoul-Henning Kamp<pre class="signature">
15915bb6a25fSPoul-Henning Kamptypedef void
15925bb6a25fSPoul-Henning Kamp(XMLCALL *XML_StartNamespaceDeclHandler)(void *userData,
15935bb6a25fSPoul-Henning Kamp                                         const XML_Char *prefix,
1594*220ed979SColeman Kane                                         const XML_Char *uri);
15955bb6a25fSPoul-Henning Kamp</pre>
15965bb6a25fSPoul-Henning Kamp<p>Set a handler to be called when a namespace is declared. Namespace
15975bb6a25fSPoul-Henning Kampdeclarations occur inside start tags. But the namespace declaration start
15985bb6a25fSPoul-Henning Kamphandler is called before the start tag handler for each namespace declared
15995bb6a25fSPoul-Henning Kampin that start tag.</p>
1600*220ed979SColeman Kane</div>
16015bb6a25fSPoul-Henning Kamp
16025bb6a25fSPoul-Henning Kamp<div class="handler">
16035bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndNamespaceDeclHandler">
16045bb6a25fSPoul-Henning Kampvoid XMLCALL
16055bb6a25fSPoul-Henning KampXML_SetEndNamespaceDeclHandler(XML_Parser p,
16065bb6a25fSPoul-Henning Kamp			       XML_EndNamespaceDeclHandler end);
16075bb6a25fSPoul-Henning Kamp</pre>
16085bb6a25fSPoul-Henning Kamp<pre class="signature">
16095bb6a25fSPoul-Henning Kamptypedef void
16105bb6a25fSPoul-Henning Kamp(XMLCALL *XML_EndNamespaceDeclHandler)(void *userData,
1611*220ed979SColeman Kane                                       const XML_Char *prefix);
16125bb6a25fSPoul-Henning Kamp</pre>
16135bb6a25fSPoul-Henning Kamp<p>Set a handler to be called when leaving the scope of a namespace
16145bb6a25fSPoul-Henning Kampdeclaration. This will be called, for each namespace declaration,
16155bb6a25fSPoul-Henning Kampafter the handler for the end tag of the element in which the
1616*220ed979SColeman Kanenamespace was declared.</p>
16175bb6a25fSPoul-Henning Kamp</div>
16185bb6a25fSPoul-Henning Kamp
16195bb6a25fSPoul-Henning Kamp<div class="handler">
16205bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNamespaceDeclHandler">
1621*220ed979SColeman Kanevoid XMLCALL
16225bb6a25fSPoul-Henning KampXML_SetNamespaceDeclHandler(XML_Parser p,
16235bb6a25fSPoul-Henning Kamp                            XML_StartNamespaceDeclHandler start,
16245bb6a25fSPoul-Henning Kamp                            XML_EndNamespaceDeclHandler end)
16255bb6a25fSPoul-Henning Kamp</pre>
16265bb6a25fSPoul-Henning Kamp<p>Sets both namespace declaration handlers with a single call.</p>
1627*220ed979SColeman Kane</div>
16285bb6a25fSPoul-Henning Kamp
16295bb6a25fSPoul-Henning Kamp<div class="handler">
16305bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetXmlDeclHandler">
16315bb6a25fSPoul-Henning Kampvoid XMLCALL
16325bb6a25fSPoul-Henning KampXML_SetXmlDeclHandler(XML_Parser p,
16335bb6a25fSPoul-Henning Kamp		      XML_XmlDeclHandler xmldecl);
16345bb6a25fSPoul-Henning Kamp</pre>
16355bb6a25fSPoul-Henning Kamp<pre class="signature">
16365bb6a25fSPoul-Henning Kamptypedef void
16375bb6a25fSPoul-Henning Kamp(XMLCALL *XML_XmlDeclHandler)(void            *userData,
16385bb6a25fSPoul-Henning Kamp                              const XML_Char  *version,
16395bb6a25fSPoul-Henning Kamp                              const XML_Char  *encoding,
16405bb6a25fSPoul-Henning Kamp                              int             standalone);
16415bb6a25fSPoul-Henning Kamp</pre>
16425bb6a25fSPoul-Henning Kamp<p>Sets a handler that is called for XML declarations and also for
16435bb6a25fSPoul-Henning Kamptext declarations discovered in external entities. The way to
1644*220ed979SColeman Kanedistinguish is that the <code>version</code> parameter will be NULL
16455bb6a25fSPoul-Henning Kampfor text declarations. The <code>encoding</code> parameter may be NULL
16465bb6a25fSPoul-Henning Kampfor an XML declaration. The <code>standalone</code> argument will
16475bb6a25fSPoul-Henning Kampcontain -1, 0, or 1 indicating respectively that there was no
16485bb6a25fSPoul-Henning Kampstandalone parameter in the declaration, that it was given as no, or
16495bb6a25fSPoul-Henning Kampthat it was given as yes.</p>
1650*220ed979SColeman Kane</div>
16515bb6a25fSPoul-Henning Kamp
16525bb6a25fSPoul-Henning Kamp<div class="handler">
16535bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartDoctypeDeclHandler">
16545bb6a25fSPoul-Henning Kampvoid XMLCALL
16555bb6a25fSPoul-Henning KampXML_SetStartDoctypeDeclHandler(XML_Parser p,
16565bb6a25fSPoul-Henning Kamp			       XML_StartDoctypeDeclHandler start);
16575bb6a25fSPoul-Henning Kamp</pre>
16585bb6a25fSPoul-Henning Kamp<pre class="signature">
16595bb6a25fSPoul-Henning Kamptypedef void
16605bb6a25fSPoul-Henning Kamp(XMLCALL *XML_StartDoctypeDeclHandler)(void           *userData,
16615bb6a25fSPoul-Henning Kamp                                       const XML_Char *doctypeName,
16625bb6a25fSPoul-Henning Kamp                                       const XML_Char *sysid,
16635bb6a25fSPoul-Henning Kamp                                       const XML_Char *pubid,
1664*220ed979SColeman Kane                                       int            has_internal_subset);
16655bb6a25fSPoul-Henning Kamp</pre>
16665bb6a25fSPoul-Henning Kamp<p>Set a handler that is called at the start of a DOCTYPE declaration,
16675bb6a25fSPoul-Henning Kampbefore any external or internal subset is parsed. Both <code>sysid</code>
16685bb6a25fSPoul-Henning Kampand <code>pubid</code> may be NULL. The <code>has_internal_subset</code>
16695bb6a25fSPoul-Henning Kampwill be non-zero if the DOCTYPE declaration has an internal subset.</p>
1670*220ed979SColeman Kane</div>
16715bb6a25fSPoul-Henning Kamp
16725bb6a25fSPoul-Henning Kamp<div class="handler">
16735bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndDoctypeDeclHandler">
16745bb6a25fSPoul-Henning Kampvoid XMLCALL
16755bb6a25fSPoul-Henning KampXML_SetEndDoctypeDeclHandler(XML_Parser p,
16765bb6a25fSPoul-Henning Kamp			     XML_EndDoctypeDeclHandler end);
16775bb6a25fSPoul-Henning Kamp</pre>
1678*220ed979SColeman Kane<pre class="signature">
16795bb6a25fSPoul-Henning Kamptypedef void
16805bb6a25fSPoul-Henning Kamp(XMLCALL *XML_EndDoctypeDeclHandler)(void *userData);
16815bb6a25fSPoul-Henning Kamp</pre>
16825bb6a25fSPoul-Henning Kamp<p>Set a handler that is called at the end of a DOCTYPE declaration,
16835bb6a25fSPoul-Henning Kampafter parsing any external subset.</p>
16845bb6a25fSPoul-Henning Kamp</div>
16855bb6a25fSPoul-Henning Kamp
16865bb6a25fSPoul-Henning Kamp<div class="handler">
16875bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDoctypeDeclHandler">
1688*220ed979SColeman Kanevoid XMLCALL
16895bb6a25fSPoul-Henning KampXML_SetDoctypeDeclHandler(XML_Parser p,
16905bb6a25fSPoul-Henning Kamp			  XML_StartDoctypeDeclHandler start,
16915bb6a25fSPoul-Henning Kamp			  XML_EndDoctypeDeclHandler end);
16925bb6a25fSPoul-Henning Kamp</pre>
16935bb6a25fSPoul-Henning Kamp<p>Set both doctype handlers with one call.</p>
1694*220ed979SColeman Kane</div>
16955bb6a25fSPoul-Henning Kamp
16965bb6a25fSPoul-Henning Kamp<div class="handler">
16975bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetElementDeclHandler">
16985bb6a25fSPoul-Henning Kampvoid XMLCALL
16995bb6a25fSPoul-Henning KampXML_SetElementDeclHandler(XML_Parser p,
17005bb6a25fSPoul-Henning Kamp			  XML_ElementDeclHandler eldecl);
17015bb6a25fSPoul-Henning Kamp</pre>
17025bb6a25fSPoul-Henning Kamp<pre class="signature">
17035bb6a25fSPoul-Henning Kamptypedef void
17045bb6a25fSPoul-Henning Kamp(XMLCALL *XML_ElementDeclHandler)(void *userData,
17055bb6a25fSPoul-Henning Kamp                                  const XML_Char *name,
17065bb6a25fSPoul-Henning Kamp                                  XML_Content *model);
17075bb6a25fSPoul-Henning Kamp</pre>
17085bb6a25fSPoul-Henning Kamp<pre class="signature">
17095bb6a25fSPoul-Henning Kampenum XML_Content_Type {
17105bb6a25fSPoul-Henning Kamp  XML_CTYPE_EMPTY = 1,
17115bb6a25fSPoul-Henning Kamp  XML_CTYPE_ANY,
17125bb6a25fSPoul-Henning Kamp  XML_CTYPE_MIXED,
17135bb6a25fSPoul-Henning Kamp  XML_CTYPE_NAME,
17145bb6a25fSPoul-Henning Kamp  XML_CTYPE_CHOICE,
17155bb6a25fSPoul-Henning Kamp  XML_CTYPE_SEQ
17165bb6a25fSPoul-Henning Kamp};
17175bb6a25fSPoul-Henning Kamp
17185bb6a25fSPoul-Henning Kampenum XML_Content_Quant {
17195bb6a25fSPoul-Henning Kamp  XML_CQUANT_NONE,
17205bb6a25fSPoul-Henning Kamp  XML_CQUANT_OPT,
17215bb6a25fSPoul-Henning Kamp  XML_CQUANT_REP,
17225bb6a25fSPoul-Henning Kamp  XML_CQUANT_PLUS
17235bb6a25fSPoul-Henning Kamp};
17245bb6a25fSPoul-Henning Kamp
17255bb6a25fSPoul-Henning Kamptypedef struct XML_cp XML_Content;
17265bb6a25fSPoul-Henning Kamp
17275bb6a25fSPoul-Henning Kampstruct XML_cp {
1728*220ed979SColeman Kane  enum XML_Content_Type		type;
1729*220ed979SColeman Kane  enum XML_Content_Quant	quant;
1730*220ed979SColeman Kane  const XML_Char *		name;
17315bb6a25fSPoul-Henning Kamp  unsigned int			numchildren;
17325bb6a25fSPoul-Henning Kamp  XML_Content *			children;
17335bb6a25fSPoul-Henning Kamp};
17345bb6a25fSPoul-Henning Kamp</pre>
17355bb6a25fSPoul-Henning Kamp<p>Sets a handler for element declarations in a DTD. The handler gets
17365bb6a25fSPoul-Henning Kampcalled with the name of the element in the declaration and a pointer
17375bb6a25fSPoul-Henning Kampto a structure that contains the element model. It is the
17385bb6a25fSPoul-Henning Kampapplication's responsibility to free this data structure using
17395bb6a25fSPoul-Henning Kamp<code><a href="#XML_FreeContentModel"
17405bb6a25fSPoul-Henning Kamp>XML_FreeContentModel</a></code>.</p>
17415bb6a25fSPoul-Henning Kamp
17425bb6a25fSPoul-Henning Kamp<p>The <code>model</code> argument is the root of a tree of
17435bb6a25fSPoul-Henning Kamp<code>XML_Content</code> nodes. If <code>type</code> equals
17445bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then
17455bb6a25fSPoul-Henning Kamp<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other
17465bb6a25fSPoul-Henning Kampfields will be zero or NULL.  If <code>type</code> is
17475bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be
17485bb6a25fSPoul-Henning Kamp<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and
17495bb6a25fSPoul-Henning Kamp<code>numchildren</code> will contain the number of elements that are
17505bb6a25fSPoul-Henning Kampallowed to be mixed in and <code>children</code> points to an array of
17515bb6a25fSPoul-Henning Kamp<code>XML_Content</code> structures that will all have type
17525bb6a25fSPoul-Henning KampXML_CTYPE_NAME with no quantification.  Only the root node can be type
17535bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or
17545bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_MIXED</code>.</p>
17555bb6a25fSPoul-Henning Kamp
17565bb6a25fSPoul-Henning Kamp<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field
17575bb6a25fSPoul-Henning Kamppoints to the name and the <code>numchildren</code> and
17585bb6a25fSPoul-Henning Kamp<code>children</code> fields will be zero and NULL. The
17595bb6a25fSPoul-Henning Kamp<code>quant</code> field will indicate any quantifiers placed on the
1760*220ed979SColeman Kanename.</p>
17615bb6a25fSPoul-Henning Kamp
17625bb6a25fSPoul-Henning Kamp<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code>
17635bb6a25fSPoul-Henning Kampindicate a choice or sequence respectively. The
17645bb6a25fSPoul-Henning Kamp<code>numchildren</code> field indicates how many nodes in the choice
17655bb6a25fSPoul-Henning Kampor sequence and <code>children</code> points to the nodes.</p>
1766*220ed979SColeman Kane</div>
17675bb6a25fSPoul-Henning Kamp
17685bb6a25fSPoul-Henning Kamp<div class="handler">
17695bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetAttlistDeclHandler">
17705bb6a25fSPoul-Henning Kampvoid XMLCALL
17715bb6a25fSPoul-Henning KampXML_SetAttlistDeclHandler(XML_Parser p,
17725bb6a25fSPoul-Henning Kamp                          XML_AttlistDeclHandler attdecl);
17735bb6a25fSPoul-Henning Kamp</pre>
17745bb6a25fSPoul-Henning Kamp<pre class="signature">
17755bb6a25fSPoul-Henning Kamptypedef void
17765bb6a25fSPoul-Henning Kamp(XMLCALL *XML_AttlistDeclHandler)(void           *userData,
17775bb6a25fSPoul-Henning Kamp                                  const XML_Char *elname,
17785bb6a25fSPoul-Henning Kamp                                  const XML_Char *attname,
17795bb6a25fSPoul-Henning Kamp                                  const XML_Char *att_type,
17805bb6a25fSPoul-Henning Kamp                                  const XML_Char *dflt,
17815bb6a25fSPoul-Henning Kamp                                  int            isrequired);
17825bb6a25fSPoul-Henning Kamp</pre>
17835bb6a25fSPoul-Henning Kamp<p>Set a handler for attlist declarations in the DTD. This handler is
17845bb6a25fSPoul-Henning Kampcalled for <em>each</em> attribute. So a single attlist declaration
17855bb6a25fSPoul-Henning Kampwith multiple attributes declared will generate multiple calls to this
17865bb6a25fSPoul-Henning Kamphandler. The <code>elname</code> parameter returns the name of the
17875bb6a25fSPoul-Henning Kampelement for which the attribute is being declared. The attribute name
17885bb6a25fSPoul-Henning Kampis in the <code>attname</code> parameter. The attribute type is in the
17895bb6a25fSPoul-Henning Kamp<code>att_type</code> parameter.  It is the string representing the
17905bb6a25fSPoul-Henning Kamptype in the declaration with whitespace removed.</p>
17915bb6a25fSPoul-Henning Kamp
17925bb6a25fSPoul-Henning Kamp<p>The <code>dflt</code> parameter holds the default value. It will be
1793*220ed979SColeman KaneNULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can
17945bb6a25fSPoul-Henning Kampdistinguish these two cases by checking the <code>isrequired</code>
17955bb6a25fSPoul-Henning Kampparameter, which will be true in the case of "#REQUIRED" attributes.
17965bb6a25fSPoul-Henning KampAttributes which are "#FIXED" will have also have a true
17975bb6a25fSPoul-Henning Kamp<code>isrequired</code>, but they will have the non-NULL fixed value
17985bb6a25fSPoul-Henning Kampin the <code>dflt</code> parameter.</p>
1799*220ed979SColeman Kane</div>
18005bb6a25fSPoul-Henning Kamp
18015bb6a25fSPoul-Henning Kamp<div class="handler">
18025bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEntityDeclHandler">
18035bb6a25fSPoul-Henning Kampvoid XMLCALL
18045bb6a25fSPoul-Henning KampXML_SetEntityDeclHandler(XML_Parser p,
18055bb6a25fSPoul-Henning Kamp			 XML_EntityDeclHandler handler);
18065bb6a25fSPoul-Henning Kamp</pre>
18075bb6a25fSPoul-Henning Kamp<pre class="signature">
18085bb6a25fSPoul-Henning Kamptypedef void
18095bb6a25fSPoul-Henning Kamp(XMLCALL *XML_EntityDeclHandler)(void           *userData,
18105bb6a25fSPoul-Henning Kamp                                 const XML_Char *entityName,
18115bb6a25fSPoul-Henning Kamp                                 int            is_parameter_entity,
18125bb6a25fSPoul-Henning Kamp                                 const XML_Char *value,
18135bb6a25fSPoul-Henning Kamp                                 int            value_length,
18145bb6a25fSPoul-Henning Kamp                                 const XML_Char *base,
18155bb6a25fSPoul-Henning Kamp                                 const XML_Char *systemId,
18165bb6a25fSPoul-Henning Kamp                                 const XML_Char *publicId,
18175bb6a25fSPoul-Henning Kamp                                 const XML_Char *notationName);
18185bb6a25fSPoul-Henning Kamp</pre>
18195bb6a25fSPoul-Henning Kamp<p>Sets a handler that will be called for all entity declarations.
18205bb6a25fSPoul-Henning KampThe <code>is_parameter_entity</code> argument will be non-zero in the
18215bb6a25fSPoul-Henning Kampcase of parameter entities and zero otherwise.</p>
18225bb6a25fSPoul-Henning Kamp
18235bb6a25fSPoul-Henning Kamp<p>For internal entities (<code>&lt;!ENTITY foo "bar"&gt;</code>),
18245bb6a25fSPoul-Henning Kamp<code>value</code> will be non-NULL and <code>systemId</code>,
18255bb6a25fSPoul-Henning Kamp<code>publicId</code>, and <code>notationName</code> will all be NULL.
18265bb6a25fSPoul-Henning KampThe value string is <em>not</em> NULL terminated; the length is
1827*220ed979SColeman Kaneprovided in the <code>value_length</code> parameter. Do not use
18285bb6a25fSPoul-Henning Kamp<code>value_length</code> to test for internal entities, since it is
18295bb6a25fSPoul-Henning Kamplegal to have zero-length values. Instead check for whether or not
18305bb6a25fSPoul-Henning Kamp<code>value</code> is NULL.</p> <p>The <code>notationName</code>
18315bb6a25fSPoul-Henning Kampargument will have a non-NULL value only for unparsed entity
18325bb6a25fSPoul-Henning Kampdeclarations.</p>
1833*220ed979SColeman Kane</div>
18345bb6a25fSPoul-Henning Kamp
18355bb6a25fSPoul-Henning Kamp<div class="handler">
18365bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetUnparsedEntityDeclHandler">
18375bb6a25fSPoul-Henning Kampvoid XMLCALL
18385bb6a25fSPoul-Henning KampXML_SetUnparsedEntityDeclHandler(XML_Parser p,
18395bb6a25fSPoul-Henning Kamp                                 XML_UnparsedEntityDeclHandler h)
18405bb6a25fSPoul-Henning Kamp</pre>
18415bb6a25fSPoul-Henning Kamp<pre class="signature">
18425bb6a25fSPoul-Henning Kamptypedef void
18435bb6a25fSPoul-Henning Kamp(XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData,
18445bb6a25fSPoul-Henning Kamp                                         const XML_Char *entityName,
18455bb6a25fSPoul-Henning Kamp                                         const XML_Char *base,
18465bb6a25fSPoul-Henning Kamp                                         const XML_Char *systemId,
18475bb6a25fSPoul-Henning Kamp                                         const XML_Char *publicId,
18485bb6a25fSPoul-Henning Kamp                                         const XML_Char *notationName);
18495bb6a25fSPoul-Henning Kamp</pre>
18505bb6a25fSPoul-Henning Kamp<p>Set a handler that receives declarations of unparsed entities. These
18515bb6a25fSPoul-Henning Kampare entity declarations that have a notation (NDATA) field:</p>
18525bb6a25fSPoul-Henning Kamp
1853*220ed979SColeman Kane<div id="eg"><pre>
18545bb6a25fSPoul-Henning Kamp&lt;!ENTITY logo SYSTEM "images/logo.gif" NDATA gif&gt;
18555bb6a25fSPoul-Henning Kamp</pre></div>
18565bb6a25fSPoul-Henning Kamp<p>This handler is obsolete and is provided for backwards
18575bb6a25fSPoul-Henning Kampcompatibility.  Use instead <a href= "#XML_SetEntityDeclHandler"
18585bb6a25fSPoul-Henning Kamp>XML_SetEntityDeclHandler</a>.</p>
1859*220ed979SColeman Kane</div>
18605bb6a25fSPoul-Henning Kamp
18615bb6a25fSPoul-Henning Kamp<div class="handler">
18625bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNotationDeclHandler">
18635bb6a25fSPoul-Henning Kampvoid XMLCALL
18645bb6a25fSPoul-Henning KampXML_SetNotationDeclHandler(XML_Parser p,
18655bb6a25fSPoul-Henning Kamp                           XML_NotationDeclHandler h)
18665bb6a25fSPoul-Henning Kamp</pre>
18675bb6a25fSPoul-Henning Kamp<pre class="signature">
18685bb6a25fSPoul-Henning Kamptypedef void
18695bb6a25fSPoul-Henning Kamp(XMLCALL *XML_NotationDeclHandler)(void *userData,
1870*220ed979SColeman Kane                                   const XML_Char *notationName,
18715bb6a25fSPoul-Henning Kamp                                   const XML_Char *base,
18725bb6a25fSPoul-Henning Kamp                                   const XML_Char *systemId,
18735bb6a25fSPoul-Henning Kamp                                   const XML_Char *publicId);
18745bb6a25fSPoul-Henning Kamp</pre>
18755bb6a25fSPoul-Henning Kamp<p>Set a handler that receives notation declarations.</p>
1876*220ed979SColeman Kane</div>
18775bb6a25fSPoul-Henning Kamp
18785bb6a25fSPoul-Henning Kamp<div class="handler">
18795bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNotStandaloneHandler">
18805bb6a25fSPoul-Henning Kampvoid XMLCALL
1881*220ed979SColeman KaneXML_SetNotStandaloneHandler(XML_Parser p,
1882*220ed979SColeman Kane                            XML_NotStandaloneHandler h)
1883*220ed979SColeman Kane</pre>
18845bb6a25fSPoul-Henning Kamp<pre class="signature">
18855bb6a25fSPoul-Henning Kamptypedef int
18865bb6a25fSPoul-Henning Kamp(XMLCALL *XML_NotStandaloneHandler)(void *userData);
18875bb6a25fSPoul-Henning Kamp</pre>
18885bb6a25fSPoul-Henning Kamp<p>Set a handler that is called if the document is not "standalone".
1889*220ed979SColeman KaneThis happens when there is an external subset or a reference to a
1890*220ed979SColeman Kaneparameter entity, but does not have standalone set to "yes" in an XML
1891*220ed979SColeman Kanedeclaration.  If this handler returns <code>XML_STATUS_ERROR</code>,
1892*220ed979SColeman Kanethen the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code>
1893*220ed979SColeman Kaneerror.</p>
1894*220ed979SColeman Kane</div>
1895*220ed979SColeman Kane
1896*220ed979SColeman Kane<h3><a name="position">Parse position and error reporting functions</a></h3>
1897*220ed979SColeman Kane
1898*220ed979SColeman Kane<p>These are the functions you'll want to call when the parse
18995bb6a25fSPoul-Henning Kampfunctions return <code>XML_STATUS_ERROR</code> (a parse error has
19005bb6a25fSPoul-Henning Kampoccurred), although the position reporting functions are useful outside
19015bb6a25fSPoul-Henning Kampof errors. The position reported is the byte position (in the original
19025bb6a25fSPoul-Henning Kampdocument or entity encoding) of the first of the sequence of
19035bb6a25fSPoul-Henning Kampcharacters that generated the current event (or the error that caused
19045bb6a25fSPoul-Henning Kampthe parse functions to return <code>XML_STATUS_ERROR</code>.)  The
1905*220ed979SColeman Kaneexceptions are callbacks trigged by declarations in the document
19065bb6a25fSPoul-Henning Kampprologue, in which case they exact position reported is somewhere in the
19075bb6a25fSPoul-Henning Kamprelevant markup, but not necessarily as meaningful as for other
19085bb6a25fSPoul-Henning Kampevents.</p>
19095bb6a25fSPoul-Henning Kamp
19105bb6a25fSPoul-Henning Kamp<p>The position reporting functions are accurate only outside of the
19115bb6a25fSPoul-Henning KampDTD.  In other words, they usually return bogus information when
19125bb6a25fSPoul-Henning Kampcalled from within a DTD declaration handler.</p>
1913*220ed979SColeman Kane
1914*220ed979SColeman Kane<pre class="fcndec" id="XML_GetErrorCode">
19155bb6a25fSPoul-Henning Kampenum XML_Error XMLCALL
19165bb6a25fSPoul-Henning KampXML_GetErrorCode(XML_Parser p);
19175bb6a25fSPoul-Henning Kamp</pre>
19185bb6a25fSPoul-Henning Kamp<div class="fcndef">
19195bb6a25fSPoul-Henning KampReturn what type of error has occurred.
19205bb6a25fSPoul-Henning Kamp</div>
19215bb6a25fSPoul-Henning Kamp
19225bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ErrorString">
1923*220ed979SColeman Kaneconst XML_LChar * XMLCALL
19245bb6a25fSPoul-Henning KampXML_ErrorString(enum XML_Error code);
19255bb6a25fSPoul-Henning Kamp</pre>
19265bb6a25fSPoul-Henning Kamp<div class="fcndef">
1927*220ed979SColeman KaneReturn a string describing the error corresponding to code.
1928*220ed979SColeman KaneThe code should be one of the enums that can be returned from
1929*220ed979SColeman Kane<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>.
1930*220ed979SColeman Kane</div>
19315bb6a25fSPoul-Henning Kamp
19325bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentByteIndex">
19335bb6a25fSPoul-Henning KampXML_Index XMLCALL
1934*220ed979SColeman KaneXML_GetCurrentByteIndex(XML_Parser p);
19355bb6a25fSPoul-Henning Kamp</pre>
19365bb6a25fSPoul-Henning Kamp<div class="fcndef">
19375bb6a25fSPoul-Henning KampReturn the byte offset of the position.  This always corresponds to
1938*220ed979SColeman Kanethe values returned by <code><a href= "#XML_GetCurrentLineNumber"
1939*220ed979SColeman Kane>XML_GetCurrentLineNumber</a></code> and <code><a href=
19405bb6a25fSPoul-Henning Kamp"#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>.
19415bb6a25fSPoul-Henning Kamp</div>
19425bb6a25fSPoul-Henning Kamp
1943*220ed979SColeman Kane<pre class="fcndec" id="XML_GetCurrentLineNumber">
19445bb6a25fSPoul-Henning KampXML_Size XMLCALL
19455bb6a25fSPoul-Henning KampXML_GetCurrentLineNumber(XML_Parser p);
19465bb6a25fSPoul-Henning Kamp</pre>
19475bb6a25fSPoul-Henning Kamp<div class="fcndef">
19485bb6a25fSPoul-Henning KampReturn the line number of the position.  The first line is reported as
19495bb6a25fSPoul-Henning Kamp<code>1</code>.
19505bb6a25fSPoul-Henning Kamp</div>
19515bb6a25fSPoul-Henning Kamp
1952*220ed979SColeman Kane<pre class="fcndec" id="XML_GetCurrentColumnNumber">
19535bb6a25fSPoul-Henning KampXML_Size XMLCALL
19545bb6a25fSPoul-Henning KampXML_GetCurrentColumnNumber(XML_Parser p);
19555bb6a25fSPoul-Henning Kamp</pre>
19565bb6a25fSPoul-Henning Kamp<div class="fcndef">
19575bb6a25fSPoul-Henning KampReturn the offset, from the beginning of the current line, of
19585bb6a25fSPoul-Henning Kampthe position.
19595bb6a25fSPoul-Henning Kamp</div>
19605bb6a25fSPoul-Henning Kamp
19615bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentByteCount">
19625bb6a25fSPoul-Henning Kampint XMLCALL
19635bb6a25fSPoul-Henning KampXML_GetCurrentByteCount(XML_Parser p);
1964*220ed979SColeman Kane</pre>
19655bb6a25fSPoul-Henning Kamp<div class="fcndef">
19665bb6a25fSPoul-Henning KampReturn the number of bytes in the current event. Returns
19675bb6a25fSPoul-Henning Kamp<code>0</code> if the event is inside a reference to an internal
19685bb6a25fSPoul-Henning Kampentity and for the end-tag event for empty element tags (the later can
19695bb6a25fSPoul-Henning Kampbe used to distinguish empty-element tags from empty elements using
19705bb6a25fSPoul-Henning Kampseparate start and end tags).
19715bb6a25fSPoul-Henning Kamp</div>
19725bb6a25fSPoul-Henning Kamp
19735bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetInputContext">
19745bb6a25fSPoul-Henning Kampconst char * XMLCALL
19755bb6a25fSPoul-Henning KampXML_GetInputContext(XML_Parser p,
19765bb6a25fSPoul-Henning Kamp                    int *offset,
19775bb6a25fSPoul-Henning Kamp                    int *size);
19785bb6a25fSPoul-Henning Kamp</pre>
19795bb6a25fSPoul-Henning Kamp<div class="fcndef">
19805bb6a25fSPoul-Henning Kamp
19815bb6a25fSPoul-Henning Kamp<p>Returns the parser's input buffer, sets the integer pointed at by
19825bb6a25fSPoul-Henning Kamp<code>offset</code> to the offset within this buffer of the current
19835bb6a25fSPoul-Henning Kampparse position, and set the integer pointed at by <code>size</code> to
1984*220ed979SColeman Kanethe size of the returned buffer.</p>
1985*220ed979SColeman Kane
1986*220ed979SColeman Kane<p>This should only be called from within a handler during an active
19875bb6a25fSPoul-Henning Kampparse and the returned buffer should only be referred to from within
19885bb6a25fSPoul-Henning Kampthe handler that made the call. This input buffer contains the
19895bb6a25fSPoul-Henning Kampuntranslated bytes of the input.</p>
19905bb6a25fSPoul-Henning Kamp
19915bb6a25fSPoul-Henning Kamp<p>Only a limited amount of context is kept, so if the event
19925bb6a25fSPoul-Henning Kamptriggering a call spans over a very large amount of input, the actual
19935bb6a25fSPoul-Henning Kampparse position may be before the beginning of the buffer.</p>
19945bb6a25fSPoul-Henning Kamp
1995*220ed979SColeman Kane<p>If <code>XML_CONTEXT_BYTES</code> is not defined, this will always
19965bb6a25fSPoul-Henning Kampreturn NULL.</p>
19975bb6a25fSPoul-Henning Kamp</div>
19985bb6a25fSPoul-Henning Kamp
19995bb6a25fSPoul-Henning Kamp<h3><a name="miscellaneous">Miscellaneous functions</a></h3>
20005bb6a25fSPoul-Henning Kamp
20015bb6a25fSPoul-Henning Kamp<p>The functions in this section either obtain state information from
20025bb6a25fSPoul-Henning Kampthe parser or can be used to dynamicly set parser options.</p>
20035bb6a25fSPoul-Henning Kamp
20045bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetUserData">
20055bb6a25fSPoul-Henning Kampvoid XMLCALL
20065bb6a25fSPoul-Henning KampXML_SetUserData(XML_Parser p,
20075bb6a25fSPoul-Henning Kamp                void *userData);
20085bb6a25fSPoul-Henning Kamp</pre>
20095bb6a25fSPoul-Henning Kamp<div class="fcndef">
2010*220ed979SColeman KaneThis sets the user data pointer that gets passed to handlers.  It
20115bb6a25fSPoul-Henning Kampoverwrites any previous value for this pointer. Note that the
20125bb6a25fSPoul-Henning Kampapplication is responsible for freeing the memory associated with
20135bb6a25fSPoul-Henning Kamp<code>userData</code> when it is finished with the parser. So if you
20145bb6a25fSPoul-Henning Kampcall this when there's already a pointer there, and you haven't freed
20155bb6a25fSPoul-Henning Kampthe memory associated with it, then you've probably just leaked
20165bb6a25fSPoul-Henning Kampmemory.
20175bb6a25fSPoul-Henning Kamp</div>
20185bb6a25fSPoul-Henning Kamp
2019*220ed979SColeman Kane<pre class="fcndec" id="XML_GetUserData">
20205bb6a25fSPoul-Henning Kampvoid * XMLCALL
20215bb6a25fSPoul-Henning KampXML_GetUserData(XML_Parser p);
20225bb6a25fSPoul-Henning Kamp</pre>
2023*220ed979SColeman Kane<div class="fcndef">
2024*220ed979SColeman KaneThis returns the user data pointer that gets passed to handlers.
2025*220ed979SColeman KaneIt is actually implemented as a macro.
2026*220ed979SColeman Kane</div>
20275bb6a25fSPoul-Henning Kamp
20285bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_UseParserAsHandlerArg">
20295bb6a25fSPoul-Henning Kampvoid XMLCALL
2030*220ed979SColeman KaneXML_UseParserAsHandlerArg(XML_Parser p);
20315bb6a25fSPoul-Henning Kamp</pre>
20325bb6a25fSPoul-Henning Kamp<div class="fcndef">
20335bb6a25fSPoul-Henning KampAfter this is called, handlers receive the parser in their
20345bb6a25fSPoul-Henning Kamp<code>userData</code> arguments.  The user data can still be obtained
20355bb6a25fSPoul-Henning Kampusing the <code><a href= "#XML_GetUserData"
2036*220ed979SColeman Kane>XML_GetUserData</a></code> function.
2037*220ed979SColeman Kane</div>
2038*220ed979SColeman Kane
20395bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetBase">
20405bb6a25fSPoul-Henning Kampenum XML_Status XMLCALL
20415bb6a25fSPoul-Henning KampXML_SetBase(XML_Parser p,
2042*220ed979SColeman Kane            const XML_Char *base);
20435bb6a25fSPoul-Henning Kamp</pre>
20445bb6a25fSPoul-Henning Kamp<div class="fcndef">
20455bb6a25fSPoul-Henning KampSet the base to be used for resolving relative URIs in system
20465bb6a25fSPoul-Henning Kampidentifiers.  The return value is <code>XML_STATUS_ERROR</code> if
20475bb6a25fSPoul-Henning Kampthere's no memory to store base, otherwise it's
20485bb6a25fSPoul-Henning Kamp<code>XML_STATUS_OK</code>.
20495bb6a25fSPoul-Henning Kamp</div>
2050*220ed979SColeman Kane
20515bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetBase">
20525bb6a25fSPoul-Henning Kampconst XML_Char * XMLCALL
20535bb6a25fSPoul-Henning KampXML_GetBase(XML_Parser p);
20545bb6a25fSPoul-Henning Kamp</pre>
20555bb6a25fSPoul-Henning Kamp<div class="fcndef">
20565bb6a25fSPoul-Henning KampReturn the base for resolving relative URIs.
20575bb6a25fSPoul-Henning Kamp</div>
20585bb6a25fSPoul-Henning Kamp
20595bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetSpecifiedAttributeCount">
20605bb6a25fSPoul-Henning Kampint XMLCALL
20615bb6a25fSPoul-Henning KampXML_GetSpecifiedAttributeCount(XML_Parser p);
20625bb6a25fSPoul-Henning Kamp</pre>
20635bb6a25fSPoul-Henning Kamp<div class="fcndef">
20645bb6a25fSPoul-Henning KampWhen attributes are reported to the start handler in the atts vector,
20655bb6a25fSPoul-Henning Kampattributes that were explicitly set in the element occur before any
2066*220ed979SColeman Kaneattributes that receive their value from default information in an
20675bb6a25fSPoul-Henning KampATTLIST declaration. This function returns the number of attributes
20685bb6a25fSPoul-Henning Kampthat were explicitly set times two, thus giving the offset in the
20695bb6a25fSPoul-Henning Kamp<code>atts</code> array passed to the start tag handler of the first
20705bb6a25fSPoul-Henning Kampattribute set due to defaults. It supplies information for the last
20715bb6a25fSPoul-Henning Kampcall to a start handler. If called inside a start handler, then that
20725bb6a25fSPoul-Henning Kampmeans the current call.
20735bb6a25fSPoul-Henning Kamp</div>
20745bb6a25fSPoul-Henning Kamp
20755bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetIdAttributeIndex">
20765bb6a25fSPoul-Henning Kampint XMLCALL
20775bb6a25fSPoul-Henning KampXML_GetIdAttributeIndex(XML_Parser p);
2078*220ed979SColeman Kane</pre>
20795bb6a25fSPoul-Henning Kamp<div class="fcndef">
20805bb6a25fSPoul-Henning KampReturns the index of the ID attribute passed in the atts array in the
20815bb6a25fSPoul-Henning Kamplast call to <code><a href= "#XML_StartElementHandler"
20825bb6a25fSPoul-Henning Kamp>XML_StartElementHandler</a></code>, or -1 if there is no ID
20835bb6a25fSPoul-Henning Kampattribute. If called inside a start handler, then that means the
20845bb6a25fSPoul-Henning Kampcurrent call.
20855bb6a25fSPoul-Henning Kamp</div>
20865bb6a25fSPoul-Henning Kamp
20875bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetAttributeInfo">
2088*220ed979SColeman Kaneconst XML_AttrInfo * XMLCALL
2089*220ed979SColeman KaneXML_GetAttributeInfo(XML_Parser parser);
20905bb6a25fSPoul-Henning Kamp</pre>
20915bb6a25fSPoul-Henning Kamp<pre class="signature">
20925bb6a25fSPoul-Henning Kamptypedef struct {
2093*220ed979SColeman Kane  XML_Index  nameStart;  /* Offset to beginning of the attribute name. */
20945bb6a25fSPoul-Henning Kamp  XML_Index  nameEnd;    /* Offset after the attribute name's last byte. */
20955bb6a25fSPoul-Henning Kamp  XML_Index  valueStart; /* Offset to beginning of the attribute value. */
20965bb6a25fSPoul-Henning Kamp  XML_Index  valueEnd;   /* Offset after the attribute value's last byte. */
20975bb6a25fSPoul-Henning Kamp} XML_AttrInfo;
20985bb6a25fSPoul-Henning Kamp</pre>
20995bb6a25fSPoul-Henning Kamp<div class="fcndef">
21005bb6a25fSPoul-Henning KampReturns an array of <code>XML_AttrInfo</code> structures for the
21015bb6a25fSPoul-Henning Kampattribute/value pairs passed in the last call to the
21025bb6a25fSPoul-Henning Kamp<code>XML_StartElementHandler</code> that were specified
21035bb6a25fSPoul-Henning Kampin the start-tag rather than defaulted. Each attribute/value pair counts
21045bb6a25fSPoul-Henning Kampas 1; thus the number of entries in the array is
21055bb6a25fSPoul-Henning Kamp<code>XML_GetSpecifiedAttributeCount(parser) / 2</code>.
21065bb6a25fSPoul-Henning Kamp</div>
21075bb6a25fSPoul-Henning Kamp
21085bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetEncoding">
21095bb6a25fSPoul-Henning Kampenum XML_Status XMLCALL
2110*220ed979SColeman KaneXML_SetEncoding(XML_Parser p,
21115bb6a25fSPoul-Henning Kamp                const XML_Char *encoding);
21125bb6a25fSPoul-Henning Kamp</pre>
21135bb6a25fSPoul-Henning Kamp<div class="fcndef">
21145bb6a25fSPoul-Henning KampSet the encoding to be used by the parser. It is equivalent to
21155bb6a25fSPoul-Henning Kamppassing a non-null encoding argument to the parser creation functions.
21165bb6a25fSPoul-Henning KampIt must not be called after <code><a href= "#XML_Parse"
21175bb6a25fSPoul-Henning Kamp>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer"
21185bb6a25fSPoul-Henning Kamp>XML_ParseBuffer</a></code> have been called on the given parser.
21195bb6a25fSPoul-Henning KampReturns <code>XML_STATUS_OK</code> on success or
21205bb6a25fSPoul-Henning Kamp<code>XML_STATUS_ERROR</code> on error.
21215bb6a25fSPoul-Henning Kamp</div>
21225bb6a25fSPoul-Henning Kamp
21235bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetParamEntityParsing">
21245bb6a25fSPoul-Henning Kampint XMLCALL
21255bb6a25fSPoul-Henning KampXML_SetParamEntityParsing(XML_Parser p,
21265bb6a25fSPoul-Henning Kamp                          enum XML_ParamEntityParsing code);
21275bb6a25fSPoul-Henning Kamp</pre>
21285bb6a25fSPoul-Henning Kamp<div class="fcndef">
21295bb6a25fSPoul-Henning KampThis enables parsing of parameter entities, including the external
21305bb6a25fSPoul-Henning Kampparameter entity that is the external DTD subset, according to
21315bb6a25fSPoul-Henning Kamp<code>code</code>.
21325bb6a25fSPoul-Henning KampThe choices for <code>code</code> are:
21335bb6a25fSPoul-Henning Kamp<ul>
21345bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li>
21355bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li>
21365bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li>
21375bb6a25fSPoul-Henning Kamp</ul>
21385bb6a25fSPoul-Henning Kamp<b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after
2139*220ed979SColeman Kane<code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has
2140*220ed979SColeman Kaneno effect and will always return 0.
2141*220ed979SColeman Kane</div>
2142*220ed979SColeman Kane
2143*220ed979SColeman Kane<pre class="fcndec" id="XML_SetHashSalt">
21445bb6a25fSPoul-Henning Kampint XMLCALL
21455bb6a25fSPoul-Henning KampXML_SetHashSalt(XML_Parser p,
21465bb6a25fSPoul-Henning Kamp                unsigned long hash_salt);
2147*220ed979SColeman Kane</pre>
21485bb6a25fSPoul-Henning Kamp<div class="fcndef">
21495bb6a25fSPoul-Henning KampSets the hash salt to use for internal hash calculations.
21505bb6a25fSPoul-Henning KampHelps in preventing DoS attacks based on predicting hash
21515bb6a25fSPoul-Henning Kampfunction behavior. In order to have an effect this must be called
21525bb6a25fSPoul-Henning Kampbefore parsing has started. Returns 1 if successful, 0 when called
21535bb6a25fSPoul-Henning Kampafter <code>XML_Parse</code> or <code>XML_ParseBuffer</code>.
21545bb6a25fSPoul-Henning Kamp<p><b>Note:</b>This call is optional, as the parser will auto-generate
21555bb6a25fSPoul-Henning Kampa new random salt value if no value has been set at the start of parsing.
21565bb6a25fSPoul-Henning Kamp<p><b>Note:</b>One should not call <code>XML_SetHashSalt</code> with a
21575bb6a25fSPoul-Henning Kamphash salt value of 0, as this value is used as sentinel value to indicate
21585bb6a25fSPoul-Henning Kampthat <code>XML_SetHashSalt</code> has <b>not</b> been called. Consequently
21595bb6a25fSPoul-Henning Kampsuch a call will have no effect, even if it returns 1.</p>
21605bb6a25fSPoul-Henning Kamp</div>
21615bb6a25fSPoul-Henning Kamp
21625bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_UseForeignDTD">
21635bb6a25fSPoul-Henning Kampenum XML_Error XMLCALL
21645bb6a25fSPoul-Henning KampXML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD);
21655bb6a25fSPoul-Henning Kamp</pre>
21665bb6a25fSPoul-Henning Kamp<div class="fcndef">
21675bb6a25fSPoul-Henning Kamp<p>This function allows an application to provide an external subset
21685bb6a25fSPoul-Henning Kampfor the document type declaration for documents which do not specify
2169*220ed979SColeman Kanean external subset of their own.  For documents which specify an
21705bb6a25fSPoul-Henning Kampexternal subset in their DOCTYPE declaration, the application-provided
21715bb6a25fSPoul-Henning Kampsubset will be ignored.  If the document does not contain a DOCTYPE
21725bb6a25fSPoul-Henning Kampdeclaration at all and <code>useDTD</code> is true, the
21735bb6a25fSPoul-Henning Kampapplication-provided subset will be parsed, but the
21745bb6a25fSPoul-Henning Kamp<code>startDoctypeDeclHandler</code> and
21755bb6a25fSPoul-Henning Kamp<code>endDoctypeDeclHandler</code> functions, if set, will not be
21765bb6a25fSPoul-Henning Kampcalled.  The setting of parameter entity parsing, controlled using
21775bb6a25fSPoul-Henning Kamp<code><a href= "#XML_SetParamEntityParsing"
21785bb6a25fSPoul-Henning Kamp>XML_SetParamEntityParsing</a></code>, will be honored.</p>
21795bb6a25fSPoul-Henning Kamp
21805bb6a25fSPoul-Henning Kamp<p>The application-provided external subset is read by calling the
21815bb6a25fSPoul-Henning Kampexternal entity reference handler set via <code><a href=
21825bb6a25fSPoul-Henning Kamp"#XML_SetExternalEntityRefHandler"
2183*220ed979SColeman Kane>XML_SetExternalEntityRefHandler</a></code> with both
21845bb6a25fSPoul-Henning Kamp<code>publicId</code> and <code>systemId</code> set to NULL.</p>
21855bb6a25fSPoul-Henning Kamp
21865bb6a25fSPoul-Henning Kamp<p>If this function is called after parsing has begun, it returns
21875bb6a25fSPoul-Henning Kamp<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores
21885bb6a25fSPoul-Henning Kamp<code>useDTD</code>.  If called when Expat has been compiled without
21895bb6a25fSPoul-Henning KampDTD support, it returns
21905bb6a25fSPoul-Henning Kamp<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>.  Otherwise, it
2191*220ed979SColeman Kanereturns <code>XML_ERROR_NONE</code>.</p>
21925bb6a25fSPoul-Henning Kamp
21935bb6a25fSPoul-Henning Kamp<p><b>Note:</b> For the purpose of checking WFC: Entity Declared, passing
21945bb6a25fSPoul-Henning Kamp<code>useDTD == XML_TRUE</code> will make the parser behave as if
21955bb6a25fSPoul-Henning Kampthe document had a DTD with an external subset. This holds true even if
21965bb6a25fSPoul-Henning Kampthe external entity reference handler returns without action.</p>
21975bb6a25fSPoul-Henning Kamp</div>
21985bb6a25fSPoul-Henning Kamp
21995bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetReturnNSTriplet">
22005bb6a25fSPoul-Henning Kampvoid XMLCALL
22015bb6a25fSPoul-Henning KampXML_SetReturnNSTriplet(XML_Parser parser,
22025bb6a25fSPoul-Henning Kamp                       int        do_nst);
22035bb6a25fSPoul-Henning Kamp</pre>
22045bb6a25fSPoul-Henning Kamp<div class="fcndef">
22055bb6a25fSPoul-Henning Kamp<p>
22065bb6a25fSPoul-Henning KampThis function only has an effect when using a parser created with
22075bb6a25fSPoul-Henning Kamp<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>,
22085bb6a25fSPoul-Henning Kampi.e. when namespace processing is in effect. The <code>do_nst</code>
22095bb6a25fSPoul-Henning Kampsets whether or not prefixes are returned with names qualified with a
22105bb6a25fSPoul-Henning Kampnamespace prefix. If this function is called with <code>do_nst</code>
22115bb6a25fSPoul-Henning Kampnon-zero, then afterwards namespace qualified names (that is qualified
22125bb6a25fSPoul-Henning Kampwith a prefix as opposed to belonging to a default namespace) are
22135bb6a25fSPoul-Henning Kampreturned as a triplet with the three parts separated by the namespace
22145bb6a25fSPoul-Henning Kampseparator specified when the parser was created.  The order of
2215*220ed979SColeman Kanereturned parts is URI, local name, and prefix.</p> <p>If
22165bb6a25fSPoul-Henning Kamp<code>do_nst</code> is zero, then namespaces are reported in the
22175bb6a25fSPoul-Henning Kampdefault manner, URI then local_name separated by the namespace
22185bb6a25fSPoul-Henning Kampseparator.</p>
22195bb6a25fSPoul-Henning Kamp</div>
22205bb6a25fSPoul-Henning Kamp
22215bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_DefaultCurrent">
22225bb6a25fSPoul-Henning Kampvoid XMLCALL
22235bb6a25fSPoul-Henning KampXML_DefaultCurrent(XML_Parser parser);
22245bb6a25fSPoul-Henning Kamp</pre>
22255bb6a25fSPoul-Henning Kamp<div class="fcndef">
22265bb6a25fSPoul-Henning KampThis can be called within a handler for a start element, end element,
2227*220ed979SColeman Kaneprocessing instruction or character data.  It causes the corresponding
2228*220ed979SColeman Kanemarkup to be passed to the default handler set by <code><a
2229*220ed979SColeman Kanehref="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or
22305bb6a25fSPoul-Henning Kamp<code><a href="#XML_SetDefaultHandlerExpand"
22315bb6a25fSPoul-Henning Kamp>XML_SetDefaultHandlerExpand</a></code>.  It does nothing if there is
22325bb6a25fSPoul-Henning Kampnot a default handler.
22335bb6a25fSPoul-Henning Kamp</div>
22345bb6a25fSPoul-Henning Kamp
22355bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExpatVersion">
22365bb6a25fSPoul-Henning KampXML_LChar * XMLCALL
22375bb6a25fSPoul-Henning KampXML_ExpatVersion();
22385bb6a25fSPoul-Henning Kamp</pre>
22395bb6a25fSPoul-Henning Kamp<div class="fcndef">
22405bb6a25fSPoul-Henning KampReturn the library version as a string (e.g. <code>"expat_1.95.1"</code>).
22415bb6a25fSPoul-Henning Kamp</div>
22425bb6a25fSPoul-Henning Kamp
22435bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExpatVersionInfo">
22445bb6a25fSPoul-Henning Kampstruct XML_Expat_Version XMLCALL
22455bb6a25fSPoul-Henning KampXML_ExpatVersionInfo();
22465bb6a25fSPoul-Henning Kamp</pre>
22475bb6a25fSPoul-Henning Kamp<pre class="signature">
22485bb6a25fSPoul-Henning Kamptypedef struct {
22495bb6a25fSPoul-Henning Kamp  int major;
22505bb6a25fSPoul-Henning Kamp  int minor;
22515bb6a25fSPoul-Henning Kamp  int micro;
22525bb6a25fSPoul-Henning Kamp} XML_Expat_Version;
22535bb6a25fSPoul-Henning Kamp</pre>
22545bb6a25fSPoul-Henning Kamp<div class="fcndef">
22555bb6a25fSPoul-Henning KampReturn the library version information as a structure.
22565bb6a25fSPoul-Henning KampSome macros are also defined that support compile-time tests of the
22575bb6a25fSPoul-Henning Kamplibrary version:
22585bb6a25fSPoul-Henning Kamp<ul>
22595bb6a25fSPoul-Henning Kamp<li><code>XML_MAJOR_VERSION</code></li>
22605bb6a25fSPoul-Henning Kamp<li><code>XML_MINOR_VERSION</code></li>
22615bb6a25fSPoul-Henning Kamp<li><code>XML_MICRO_VERSION</code></li>
22625bb6a25fSPoul-Henning Kamp</ul>
22635bb6a25fSPoul-Henning KampTesting these constants is currently the best way to determine if
22645bb6a25fSPoul-Henning Kampparticular parts of the Expat API are available.
22655bb6a25fSPoul-Henning Kamp</div>
22665bb6a25fSPoul-Henning Kamp
22675bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetFeatureList">
22685bb6a25fSPoul-Henning Kampconst XML_Feature * XMLCALL
22695bb6a25fSPoul-Henning KampXML_GetFeatureList();
22705bb6a25fSPoul-Henning Kamp</pre>
22715bb6a25fSPoul-Henning Kamp<pre class="signature">
22725bb6a25fSPoul-Henning Kampenum XML_FeatureEnum {
22735bb6a25fSPoul-Henning Kamp  XML_FEATURE_END = 0,
22745bb6a25fSPoul-Henning Kamp  XML_FEATURE_UNICODE,
2275*220ed979SColeman Kane  XML_FEATURE_UNICODE_WCHAR_T,
2276*220ed979SColeman Kane  XML_FEATURE_DTD,
2277*220ed979SColeman Kane  XML_FEATURE_CONTEXT_BYTES,
2278*220ed979SColeman Kane  XML_FEATURE_MIN_SIZE,
2279*220ed979SColeman Kane  XML_FEATURE_SIZEOF_XML_CHAR,
2280*220ed979SColeman Kane  XML_FEATURE_SIZEOF_XML_LCHAR,
2281*220ed979SColeman Kane  XML_FEATURE_NS,
2282*220ed979SColeman Kane  XML_FEATURE_LARGE_SIZE
2283*220ed979SColeman Kane};
2284*220ed979SColeman Kane
2285*220ed979SColeman Kanetypedef struct {
2286*220ed979SColeman Kane  enum XML_FeatureEnum  feature;
2287*220ed979SColeman Kane  XML_LChar            *name;
2288*220ed979SColeman Kane  long int              value;
2289*220ed979SColeman Kane} XML_Feature;
2290*220ed979SColeman Kane</pre>
2291*220ed979SColeman Kane<div class="fcndef">
2292*220ed979SColeman Kane<p>Returns a list of "feature" records, providing details on how
2293*220ed979SColeman KaneExpat was configured at compile time.  Most applications should not
2294*220ed979SColeman Kaneneed to worry about this, but this information is otherwise not
2295*220ed979SColeman Kaneavailable from Expat.  This function allows code that does need to
2296*220ed979SColeman Kanecheck these features to do so at runtime.</p>
2297*220ed979SColeman Kane
2298*220ed979SColeman Kane<p>The return value is an array of <code>XML_Feature</code>,
2299*220ed979SColeman Kaneterminated by a record with a <code>feature</code> of
2300*220ed979SColeman Kane<code>XML_FEATURE_END</code> and <code>name</code> of NULL,
2301*220ed979SColeman Kaneidentifying the feature-test macros Expat was compiled with.  Since an
2302*220ed979SColeman Kaneapplication that requires this kind of information needs to determine
2303*220ed979SColeman Kanethe type of character the <code>name</code> points to, records for the
2304*220ed979SColeman Kane<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and
2305*220ed979SColeman Kane<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the
2306*220ed979SColeman Kanebeginning of the list, followed by <code>XML_FEATURE_UNICODE</code>
2307*220ed979SColeman Kaneand <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at
2308*220ed979SColeman Kaneall.</p>
2309*220ed979SColeman Kane
2310*220ed979SColeman Kane<p>Some features have an associated value.  If there isn't an
2311*220ed979SColeman Kaneassociated value, the <code>value</code> field is set to 0.  At this
2312*220ed979SColeman Kanetime, the following features have been defined to have values:</p>
2313*220ed979SColeman Kane
2314*220ed979SColeman Kane<dl>
2315*220ed979SColeman Kane  <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt>
2316*220ed979SColeman Kane  <dd>The number of bytes occupied by one <code>XML_Char</code>
2317*220ed979SColeman Kane  character.</dd>
2318*220ed979SColeman Kane  <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt>
2319*220ed979SColeman Kane  <dd>The number of bytes occupied by one <code>XML_LChar</code>
2320*220ed979SColeman Kane  character.</dd>
2321*220ed979SColeman Kane  <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt>
2322*220ed979SColeman Kane  <dd>The maximum number of characters of context which can be
2323*220ed979SColeman Kane  reported by <code><a href= "#XML_GetInputContext"
2324*220ed979SColeman Kane  >XML_GetInputContext</a></code>.</dd>
2325*220ed979SColeman Kane</dl>
2326*220ed979SColeman Kane</div>
2327*220ed979SColeman Kane
2328*220ed979SColeman Kane<pre class="fcndec" id="XML_FreeContentModel">
2329*220ed979SColeman Kanevoid XMLCALL
2330*220ed979SColeman KaneXML_FreeContentModel(XML_Parser parser, XML_Content *model);
2331*220ed979SColeman Kane</pre>
2332*220ed979SColeman Kane<div class="fcndef">
2333*220ed979SColeman KaneFunction to deallocate the <code>model</code> argument passed to the
2334*220ed979SColeman Kane<code>XML_ElementDeclHandler</code> callback set using <code><a
23355bb6a25fSPoul-Henning Kamphref="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>.
23365bb6a25fSPoul-Henning KampThis function should not be used for any other purpose.
23375bb6a25fSPoul-Henning Kamp</div>
23385bb6a25fSPoul-Henning Kamp
2339*220ed979SColeman Kane<p>The following functions allow external code to share the memory
23405bb6a25fSPoul-Henning Kampallocator an <code>XML_Parser</code> has been configured to use.  This
23415bb6a25fSPoul-Henning Kampis especially useful for third-party libraries that interact with a
2342parser object created by application code, or heavily layered
2343applications.  This can be essential when using dynamically loaded
2344libraries which use different C standard libraries (this can happen on
2345Windows, at least).</p>
2346
2347<pre class="fcndec" id="XML_MemMalloc">
2348void * XMLCALL
2349XML_MemMalloc(XML_Parser parser, size_t size);
2350</pre>
2351<div class="fcndef">
2352Allocate <code>size</code> bytes of memory using the allocator the
2353<code>parser</code> object has been configured to use.  Returns a
2354pointer to the memory or NULL on failure.  Memory allocated in this
2355way must be freed using <code><a href="#XML_MemFree"
2356>XML_MemFree</a></code>.
2357</div>
2358
2359<pre class="fcndec" id="XML_MemRealloc">
2360void * XMLCALL
2361XML_MemRealloc(XML_Parser parser, void *ptr, size_t size);
2362</pre>
2363<div class="fcndef">
2364Allocate <code>size</code> bytes of memory using the allocator the
2365<code>parser</code> object has been configured to use.
2366<code>ptr</code> must point to a block of memory allocated by <code><a
2367href="#XML_MemMalloc" >XML_MemMalloc</a></code> or
2368<code>XML_MemRealloc</code>, or be NULL.  This function tries to
2369expand the block pointed to by <code>ptr</code> if possible.  Returns
2370a pointer to the memory or NULL on failure.  On success, the original
2371block has either been expanded or freed.  On failure, the original
2372block has not been freed; the caller is responsible for freeing the
2373original block.  Memory allocated in this way must be freed using
2374<code><a href="#XML_MemFree"
2375>XML_MemFree</a></code>.
2376</div>
2377
2378<pre class="fcndec" id="XML_MemFree">
2379void XMLCALL
2380XML_MemFree(XML_Parser parser, void *ptr);
2381</pre>
2382<div class="fcndef">
2383Free a block of memory pointed to by <code>ptr</code>.  The block must
2384have been allocated by <code><a href="#XML_MemMalloc"
2385>XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be NULL.
2386</div>
2387
2388<hr />
2389<p><a href="http://validator.w3.org/check/referer"><img
2390        src="valid-xhtml10.png" alt="Valid XHTML 1.0!"
2391        height="31" width="88" class="noborder" /></a></p>
2392</div>
2393</body>
2394</html>
2395