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 <coopercc@netheaven.com> 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, coopercc@netheaven.com" /> 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> 165bb6a25fSPoul-Henning Kamp<h1>Expat XML Parser</h1> 175bb6a25fSPoul-Henning Kamp 185bb6a25fSPoul-Henning Kamp<p>Expat is a library, written in C, for parsing XML documents. It's 195bb6a25fSPoul-Henning Kampthe underlying XML parser for the open source Mozilla project, Perl's 205bb6a25fSPoul-Henning Kamp<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and 215bb6a25fSPoul-Henning Kampother open-source XML parsers.</p> 225bb6a25fSPoul-Henning Kamp 235bb6a25fSPoul-Henning Kamp<p>This library is the creation of James Clark, who's also given us 245bb6a25fSPoul-Henning Kampgroff (an nroff look-alike), Jade (an implemention of ISO's DSSSL 255bb6a25fSPoul-Henning Kampstylesheet language for SGML), XP (a Java XML parser package), XT (a 265bb6a25fSPoul-Henning KampJava XSL engine). James was also the technical lead on the XML 275bb6a25fSPoul-Henning KampWorking Group at W3C that produced the XML specification.</p> 285bb6a25fSPoul-Henning Kamp 295bb6a25fSPoul-Henning Kamp<p>This is free software, licensed under the <a 305bb6a25fSPoul-Henning Kamphref="../COPYING">MIT/X Consortium license</a>. You may download it 315bb6a25fSPoul-Henning Kampfrom <a href="http://www.libexpat.org/">the Expat home page</a>. 325bb6a25fSPoul-Henning Kamp</p> 335bb6a25fSPoul-Henning Kamp 345bb6a25fSPoul-Henning Kamp<p>The bulk of this document was originally commissioned as an article by 355bb6a25fSPoul-Henning Kamp<a href="http://www.xml.com/">XML.com</a>. They graciously allowed 365bb6a25fSPoul-Henning KampClark Cooper to retain copyright and to distribute it with Expat.</p> 375bb6a25fSPoul-Henning Kamp 385bb6a25fSPoul-Henning Kamp<hr /> 395bb6a25fSPoul-Henning Kamp<h2>Table of Contents</h2> 405bb6a25fSPoul-Henning Kamp<ul> 415bb6a25fSPoul-Henning Kamp <li><a href="#overview">Overview</a></li> 425bb6a25fSPoul-Henning Kamp <li><a href="#building">Building and Installing</a></li> 435bb6a25fSPoul-Henning Kamp <li><a href="#using">Using Expat</a></li> 445bb6a25fSPoul-Henning Kamp <li><a href="#reference">Reference</a> 455bb6a25fSPoul-Henning Kamp <ul> 465bb6a25fSPoul-Henning Kamp <li><a href="#creation">Parser Creation Functions</a> 475bb6a25fSPoul-Henning Kamp <ul> 485bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li> 495bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li> 505bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li> 515bb6a25fSPoul-Henning Kamp <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li> 525bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParserFree">XML_ParserFree</a></li> 535bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParserReset">XML_ParserReset</a></li> 545bb6a25fSPoul-Henning Kamp </ul> 555bb6a25fSPoul-Henning Kamp </li> 565bb6a25fSPoul-Henning Kamp <li><a href="#parsing">Parsing Functions</a> 575bb6a25fSPoul-Henning Kamp <ul> 585bb6a25fSPoul-Henning Kamp <li><a href="#XML_Parse">XML_Parse</a></li> 595bb6a25fSPoul-Henning Kamp <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li> 605bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li> 615bb6a25fSPoul-Henning Kamp </ul> 625bb6a25fSPoul-Henning Kamp </li> 635bb6a25fSPoul-Henning Kamp <li><a href="#setting">Handler Setting Functions</a> 645bb6a25fSPoul-Henning Kamp <ul> 655bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li> 665bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li> 675bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li> 685bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li> 695bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li> 705bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li> 715bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li> 725bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li> 735bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li> 745bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li> 755bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li> 765bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li> 775bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li> 785bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li> 795bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li> 805bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li> 815bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li> 825bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li> 835bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li> 845bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li> 855bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li> 865bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li> 875bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li> 885bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li> 895bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li> 905bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li> 915bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li> 925bb6a25fSPoul-Henning Kamp </ul> 935bb6a25fSPoul-Henning Kamp </li> 945bb6a25fSPoul-Henning Kamp <li><a href="#position">Parse Position and Error Reporting Functions</a> 955bb6a25fSPoul-Henning Kamp <ul> 965bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li> 975bb6a25fSPoul-Henning Kamp <li><a href="#XML_ErrorString">XML_ErrorString</a></li> 985bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li> 995bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li> 1005bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li> 1015bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li> 1025bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li> 1035bb6a25fSPoul-Henning Kamp </ul> 1045bb6a25fSPoul-Henning Kamp </li> 1055bb6a25fSPoul-Henning Kamp <li><a href="#miscellaneous">Miscellaneous Functions</a> 1065bb6a25fSPoul-Henning Kamp <ul> 1075bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetUserData">XML_SetUserData</a></li> 1085bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetUserData">XML_GetUserData</a></li> 1095bb6a25fSPoul-Henning Kamp <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li> 1105bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetBase">XML_SetBase</a></li> 1115bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetBase">XML_GetBase</a></li> 1125bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li> 1135bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li> 1145bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li> 1155bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li> 1165bb6a25fSPoul-Henning Kamp <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li> 1175bb6a25fSPoul-Henning Kamp <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li> 1185bb6a25fSPoul-Henning Kamp <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li> 1195bb6a25fSPoul-Henning Kamp <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li> 1205bb6a25fSPoul-Henning Kamp <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li> 1215bb6a25fSPoul-Henning Kamp <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li> 1225bb6a25fSPoul-Henning Kamp </ul> 1235bb6a25fSPoul-Henning Kamp </li> 1245bb6a25fSPoul-Henning Kamp </ul> 1255bb6a25fSPoul-Henning Kamp </li> 1265bb6a25fSPoul-Henning Kamp</ul> 1275bb6a25fSPoul-Henning Kamp 1285bb6a25fSPoul-Henning Kamp<hr /> 1295bb6a25fSPoul-Henning Kamp<h2><a name="overview">Overview</a></h2> 1305bb6a25fSPoul-Henning Kamp 1315bb6a25fSPoul-Henning Kamp<p>Expat is a stream-oriented parser. You register callback (or 1325bb6a25fSPoul-Henning Kamphandler) functions with the parser and then start feeding it the 1335bb6a25fSPoul-Henning Kampdocument. As the parser recognizes parts of the document, it will 1345bb6a25fSPoul-Henning Kampcall the appropriate handler for that part (if you've registered one.) 1355bb6a25fSPoul-Henning KampThe document is fed to the parser in pieces, so you can start parsing 1365bb6a25fSPoul-Henning Kampbefore you have all the document. This also allows you to parse really 1375bb6a25fSPoul-Henning Kamphuge documents that won't fit into memory.</p> 1385bb6a25fSPoul-Henning Kamp 1395bb6a25fSPoul-Henning Kamp<p>Expat can be intimidating due to the many kinds of handlers and 1405bb6a25fSPoul-Henning Kampoptions you can set. But you only need to learn four functions in 1415bb6a25fSPoul-Henning Kamporder to do 90% of what you'll want to do with it:</p> 1425bb6a25fSPoul-Henning Kamp 1435bb6a25fSPoul-Henning Kamp<dl> 1445bb6a25fSPoul-Henning Kamp 1455bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_ParserCreate" 1465bb6a25fSPoul-Henning Kamp >XML_ParserCreate</a></code></dt> 1475bb6a25fSPoul-Henning Kamp <dd>Create a new parser object.</dd> 1485bb6a25fSPoul-Henning Kamp 1495bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_SetElementHandler" 1505bb6a25fSPoul-Henning Kamp >XML_SetElementHandler</a></code></dt> 1515bb6a25fSPoul-Henning Kamp <dd>Set handlers for start and end tags.</dd> 1525bb6a25fSPoul-Henning Kamp 1535bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_SetCharacterDataHandler" 1545bb6a25fSPoul-Henning Kamp >XML_SetCharacterDataHandler</a></code></dt> 1555bb6a25fSPoul-Henning Kamp <dd>Set handler for text.</dd> 1565bb6a25fSPoul-Henning Kamp 1575bb6a25fSPoul-Henning Kamp<dt><code><a href= "#XML_Parse" 1585bb6a25fSPoul-Henning Kamp >XML_Parse</a></code></dt> 1595bb6a25fSPoul-Henning Kamp <dd>Pass a buffer full of document to the parser</dd> 1605bb6a25fSPoul-Henning Kamp</dl> 1615bb6a25fSPoul-Henning Kamp 1625bb6a25fSPoul-Henning Kamp<p>These functions and others are described in the <a 1635bb6a25fSPoul-Henning Kamphref="#reference">reference</a> part of this document. The reference 1645bb6a25fSPoul-Henning Kampsection also describes in detail the parameters passed to the 1655bb6a25fSPoul-Henning Kampdifferent types of handlers.</p> 1665bb6a25fSPoul-Henning Kamp 1675bb6a25fSPoul-Henning Kamp<p>Let's look at a very simple example program that only uses 3 of the 1685bb6a25fSPoul-Henning Kampabove functions (it doesn't need to set a character handler.) The 1695bb6a25fSPoul-Henning Kampprogram <a href="../examples/outline.c">outline.c</a> prints an 1705bb6a25fSPoul-Henning Kampelement outline, indenting child elements to distinguish them from the 1715bb6a25fSPoul-Henning Kampparent element that contains them. The start handler does all the 1725bb6a25fSPoul-Henning Kampwork. It prints two indenting spaces for every level of ancestor 1735bb6a25fSPoul-Henning Kampelements, then it prints the element and attribute 1745bb6a25fSPoul-Henning Kampinformation. Finally it increments the global <code>Depth</code> 1755bb6a25fSPoul-Henning Kampvariable.</p> 1765bb6a25fSPoul-Henning Kamp 1775bb6a25fSPoul-Henning Kamp<pre class="eg"> 1785bb6a25fSPoul-Henning Kampint Depth; 1795bb6a25fSPoul-Henning Kamp 1805bb6a25fSPoul-Henning Kampvoid 1815bb6a25fSPoul-Henning Kampstart(void *data, const char *el, const char **attr) { 1825bb6a25fSPoul-Henning Kamp int i; 1835bb6a25fSPoul-Henning Kamp 1845bb6a25fSPoul-Henning Kamp for (i = 0; i < Depth; i++) 1855bb6a25fSPoul-Henning Kamp printf(" "); 1865bb6a25fSPoul-Henning Kamp 1875bb6a25fSPoul-Henning Kamp printf("%s", el); 1885bb6a25fSPoul-Henning Kamp 1895bb6a25fSPoul-Henning Kamp for (i = 0; attr[i]; i += 2) { 1905bb6a25fSPoul-Henning Kamp printf(" %s='%s'", attr[i], attr[i + 1]); 1915bb6a25fSPoul-Henning Kamp } 1925bb6a25fSPoul-Henning Kamp 1935bb6a25fSPoul-Henning Kamp printf("\n"); 1945bb6a25fSPoul-Henning Kamp Depth++; 1955bb6a25fSPoul-Henning Kamp} /* End of start handler */ 1965bb6a25fSPoul-Henning Kamp</pre> 1975bb6a25fSPoul-Henning Kamp 1985bb6a25fSPoul-Henning Kamp<p>The end tag simply does the bookkeeping work of decrementing 1995bb6a25fSPoul-Henning Kamp<code>Depth</code>.</p> 2005bb6a25fSPoul-Henning Kamp<pre class="eg"> 2015bb6a25fSPoul-Henning Kampvoid 2025bb6a25fSPoul-Henning Kampend(void *data, const char *el) { 2035bb6a25fSPoul-Henning Kamp Depth--; 2045bb6a25fSPoul-Henning Kamp} /* End of end handler */ 2055bb6a25fSPoul-Henning Kamp</pre> 2065bb6a25fSPoul-Henning Kamp 2075bb6a25fSPoul-Henning Kamp<p>After creating the parser, the main program just has the job of 2085bb6a25fSPoul-Henning Kampshoveling the document to the parser so that it can do its work.</p> 2095bb6a25fSPoul-Henning Kamp 2105bb6a25fSPoul-Henning Kamp<hr /> 2115bb6a25fSPoul-Henning Kamp<h2><a name="building">Building and Installing Expat</a></h2> 2125bb6a25fSPoul-Henning Kamp 2135bb6a25fSPoul-Henning Kamp<p>The Expat distribution comes as a compressed (with GNU gzip) tar 2145bb6a25fSPoul-Henning Kampfile. You may download the latest version from <a href= 2155bb6a25fSPoul-Henning Kamp"http://sourceforge.net/projects/expat/" >Source Forge</a>. After 2165bb6a25fSPoul-Henning Kampunpacking this, cd into the directory. Then follow either the Win32 2175bb6a25fSPoul-Henning Kampdirections or Unix directions below.</p> 2185bb6a25fSPoul-Henning Kamp 2195bb6a25fSPoul-Henning Kamp<h3>Building under Win32</h3> 2205bb6a25fSPoul-Henning Kamp 2215bb6a25fSPoul-Henning Kamp<p>If you're using the GNU compiler under cygwin, follow the Unix 2225bb6a25fSPoul-Henning Kampdirections in the next section. Otherwise if you have Microsoft's 2235bb6a25fSPoul-Henning KampDeveloper Studio installed, then from Windows Explorer double-click on 2245bb6a25fSPoul-Henning Kamp"expat.dsp" in the lib directory and build and install in the usual 2255bb6a25fSPoul-Henning Kampmanner.</p> 2265bb6a25fSPoul-Henning Kamp 2275bb6a25fSPoul-Henning Kamp<p>Alternatively, you may download the Win32 binary package that 2285bb6a25fSPoul-Henning Kampcontains the "expat.h" include file and a pre-built DLL.</p> 2295bb6a25fSPoul-Henning Kamp 2305bb6a25fSPoul-Henning Kamp<h3>Building under Unix (or GNU)</h3> 2315bb6a25fSPoul-Henning Kamp 2325bb6a25fSPoul-Henning Kamp<p>First you'll need to run the configure shell script in order to 2335bb6a25fSPoul-Henning Kampconfigure the Makefiles and headers for your system.</p> 2345bb6a25fSPoul-Henning Kamp 2355bb6a25fSPoul-Henning Kamp<p>If you're happy with all the defaults that configure picks for you, 2365bb6a25fSPoul-Henning Kampand you have permission on your system to install into /usr/local, you 2375bb6a25fSPoul-Henning Kampcan install Expat with this sequence of commands:</p> 2385bb6a25fSPoul-Henning Kamp 2395bb6a25fSPoul-Henning Kamp<pre class="eg"> 2405bb6a25fSPoul-Henning Kamp ./configure 2415bb6a25fSPoul-Henning Kamp make 2425bb6a25fSPoul-Henning Kamp make install 2435bb6a25fSPoul-Henning Kamp</pre> 2445bb6a25fSPoul-Henning Kamp 2455bb6a25fSPoul-Henning Kamp<p>There are some options that you can provide to this script, but the 2465bb6a25fSPoul-Henning Kamponly one we'll mention here is the <code>--prefix</code> option. You 2475bb6a25fSPoul-Henning Kampcan find out all the options available by running configure with just 2485bb6a25fSPoul-Henning Kampthe <code>--help</code> option.</p> 2495bb6a25fSPoul-Henning Kamp 2505bb6a25fSPoul-Henning Kamp<p>By default, the configure script sets things up so that the library 2515bb6a25fSPoul-Henning Kampgets installed in <code>/usr/local/lib</code> and the associated 2525bb6a25fSPoul-Henning Kampheader file in <code>/usr/local/include</code>. But if you were to 2535bb6a25fSPoul-Henning Kampgive the option, <code>--prefix=/home/me/mystuff</code>, then the 2545bb6a25fSPoul-Henning Kamplibrary and header would get installed in 2555bb6a25fSPoul-Henning Kamp<code>/home/me/mystuff/lib</code> and 2565bb6a25fSPoul-Henning Kamp<code>/home/me/mystuff/include</code> respectively.</p> 2575bb6a25fSPoul-Henning Kamp 2585bb6a25fSPoul-Henning Kamp<hr /> 2595bb6a25fSPoul-Henning Kamp<h2><a name="using">Using Expat</a></h2> 2605bb6a25fSPoul-Henning Kamp 2615bb6a25fSPoul-Henning Kamp<h3>Compiling and Linking Against Expat</h3> 2625bb6a25fSPoul-Henning Kamp 2635bb6a25fSPoul-Henning Kamp<p>Unless you installed Expat in a location not expected by your 2645bb6a25fSPoul-Henning Kampcompiler and linker, all you have to do to use Expat in your programs 2655bb6a25fSPoul-Henning Kampis to include the Expat header (<code>#include <expat.h></code>) 2665bb6a25fSPoul-Henning Kampin your files that make calls to it and to tell the linker that it 2675bb6a25fSPoul-Henning Kampneeds to link against the Expat library. On Unix systems, this would 2685bb6a25fSPoul-Henning Kampusually be done with the <code>-lexpat</code> argument. Otherwise, 2695bb6a25fSPoul-Henning Kampyou'll need to tell the compiler where to look for the Expat header 2705bb6a25fSPoul-Henning Kampand the linker where to find the Expat library. You may also need to 2715bb6a25fSPoul-Henning Kamptake steps to tell the operating system where to find this libary at 2725bb6a25fSPoul-Henning Kamprun time.</p> 2735bb6a25fSPoul-Henning Kamp 2745bb6a25fSPoul-Henning Kamp<p>On a Unix-based system, here's what a Makefile might look like when 2755bb6a25fSPoul-Henning KampExpat is installed in a standard location:</p> 2765bb6a25fSPoul-Henning Kamp 2775bb6a25fSPoul-Henning Kamp<pre class="eg"> 2785bb6a25fSPoul-Henning KampCC=cc 2795bb6a25fSPoul-Henning KampLDFLAGS= 2805bb6a25fSPoul-Henning KampLIBS= -lexpat 2815bb6a25fSPoul-Henning Kampxmlapp: xmlapp.o 2825bb6a25fSPoul-Henning Kamp $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 2835bb6a25fSPoul-Henning Kamp</pre> 2845bb6a25fSPoul-Henning Kamp 2855bb6a25fSPoul-Henning Kamp<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then 2865bb6a25fSPoul-Henning Kampthe Makefile would look like this:</p> 2875bb6a25fSPoul-Henning Kamp 2885bb6a25fSPoul-Henning Kamp<pre class="eg"> 2895bb6a25fSPoul-Henning KampCC=cc 2905bb6a25fSPoul-Henning KampCFLAGS= -I/home/me/mystuff/include 2915bb6a25fSPoul-Henning KampLDFLAGS= 2925bb6a25fSPoul-Henning KampLIBS= -L/home/me/mystuff/lib -lexpat 2935bb6a25fSPoul-Henning Kampxmlapp: xmlapp.o 2945bb6a25fSPoul-Henning Kamp $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 2955bb6a25fSPoul-Henning Kamp</pre> 2965bb6a25fSPoul-Henning Kamp 2975bb6a25fSPoul-Henning Kamp<p>You'd also have to set the environment variable 2985bb6a25fSPoul-Henning Kamp<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or 2995bb6a25fSPoul-Henning Kampto <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if 3005bb6a25fSPoul-Henning KampLD_LIBRARY_PATH already has some directories in it) in order to run 3015bb6a25fSPoul-Henning Kampyour application.</p> 3025bb6a25fSPoul-Henning Kamp 3035bb6a25fSPoul-Henning Kamp<h3>Expat Basics</h3> 3045bb6a25fSPoul-Henning Kamp 3055bb6a25fSPoul-Henning Kamp<p>As we saw in the example in the overview, the first step in parsing 3065bb6a25fSPoul-Henning Kampan XML document with Expat is to create a parser object. There are <a 3075bb6a25fSPoul-Henning Kamphref="#creation">three functions</a> in the Expat API for creating a 3085bb6a25fSPoul-Henning Kampparser object. However, only two of these (<code><a href= 3095bb6a25fSPoul-Henning Kamp"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href= 3105bb6a25fSPoul-Henning Kamp"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for 3115bb6a25fSPoul-Henning Kampconstructing a parser for a top-level document. The object returned 3125bb6a25fSPoul-Henning Kampby these functions is an opaque pointer (i.e. "expat.h" declares it as 3135bb6a25fSPoul-Henning Kampvoid *) to data with further internal structure. In order to free the 3145bb6a25fSPoul-Henning Kampmemory associated with this object you must call <code><a href= 3155bb6a25fSPoul-Henning Kamp"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have 3165bb6a25fSPoul-Henning Kampprovided any <a href="userdata">user data</a> that gets stored in the 3175bb6a25fSPoul-Henning Kampparser, then your application is responsible for freeing it prior to 3185bb6a25fSPoul-Henning Kampcalling <code>XML_ParserFree</code>.</p> 3195bb6a25fSPoul-Henning Kamp 3205bb6a25fSPoul-Henning Kamp<p>The objects returned by the parser creation functions are good for 3215bb6a25fSPoul-Henning Kampparsing only one XML document or external parsed entity. If your 3225bb6a25fSPoul-Henning Kampapplication needs to parse many XML documents, then it needs to create 3235bb6a25fSPoul-Henning Kampa parser object for each one. The best way to deal with this is to 3245bb6a25fSPoul-Henning Kampcreate a higher level object that contains all the default 3255bb6a25fSPoul-Henning Kampinitialization you want for your parser objects.</p> 3265bb6a25fSPoul-Henning Kamp 3275bb6a25fSPoul-Henning Kamp<p>Walking through a document hierarchy with a stream oriented parser 3285bb6a25fSPoul-Henning Kampwill require a good stack mechanism in order to keep track of current 3295bb6a25fSPoul-Henning Kampcontext. For instance, to answer the simple question, "What element 3305bb6a25fSPoul-Henning Kampdoes this text belong to?" requires a stack, since the parser may have 3315bb6a25fSPoul-Henning Kampdescended into other elements that are children of the current one and 3325bb6a25fSPoul-Henning Kamphas encountered this text on the way out.</p> 3335bb6a25fSPoul-Henning Kamp 3345bb6a25fSPoul-Henning Kamp<p>The things you're likely to want to keep on a stack are the 3355bb6a25fSPoul-Henning Kampcurrently opened element and it's attributes. You push this 3365bb6a25fSPoul-Henning Kampinformation onto the stack in the start handler and you pop it off in 3375bb6a25fSPoul-Henning Kampthe end handler.</p> 3385bb6a25fSPoul-Henning Kamp 3395bb6a25fSPoul-Henning Kamp<p>For some tasks, it is sufficient to just keep information on what 3405bb6a25fSPoul-Henning Kampthe depth of the stack is (or would be if you had one.) The outline 3415bb6a25fSPoul-Henning Kampprogram shown above presents one example. Another such task would be 3425bb6a25fSPoul-Henning Kampskipping over a complete element. When you see the start tag for the 3435bb6a25fSPoul-Henning Kampelement you want to skip, you set a skip flag and record the depth at 3445bb6a25fSPoul-Henning Kampwhich the element started. When the end tag handler encounters the 3455bb6a25fSPoul-Henning Kampsame depth, the skipped element has ended and the flag may be 3465bb6a25fSPoul-Henning Kampcleared. If you follow the convention that the root element starts at 3475bb6a25fSPoul-Henning Kamp1, then you can use the same variable for skip flag and skip 3485bb6a25fSPoul-Henning Kampdepth.</p> 3495bb6a25fSPoul-Henning Kamp 3505bb6a25fSPoul-Henning Kamp<pre class="eg"> 3515bb6a25fSPoul-Henning Kampvoid 3525bb6a25fSPoul-Henning Kampinit_info(Parseinfo *info) { 3535bb6a25fSPoul-Henning Kamp info->skip = 0; 3545bb6a25fSPoul-Henning Kamp info->depth = 1; 3555bb6a25fSPoul-Henning Kamp /* Other initializations here */ 3565bb6a25fSPoul-Henning Kamp} /* End of init_info */ 3575bb6a25fSPoul-Henning Kamp 3585bb6a25fSPoul-Henning Kampvoid 3595bb6a25fSPoul-Henning Kamprawstart(void *data, const char *el, const char **attr) { 3605bb6a25fSPoul-Henning Kamp Parseinfo *inf = (Parseinfo *) data; 3615bb6a25fSPoul-Henning Kamp 3625bb6a25fSPoul-Henning Kamp if (! inf->skip) { 3635bb6a25fSPoul-Henning Kamp if (should_skip(inf, el, attr)) { 3645bb6a25fSPoul-Henning Kamp inf->skip = inf->depth; 3655bb6a25fSPoul-Henning Kamp } 3665bb6a25fSPoul-Henning Kamp else 3675bb6a25fSPoul-Henning Kamp start(inf, el, attr); /* This does rest of start handling */ 3685bb6a25fSPoul-Henning Kamp } 3695bb6a25fSPoul-Henning Kamp 3705bb6a25fSPoul-Henning Kamp inf->depth++; 3715bb6a25fSPoul-Henning Kamp} /* End of rawstart */ 3725bb6a25fSPoul-Henning Kamp 3735bb6a25fSPoul-Henning Kampvoid 3745bb6a25fSPoul-Henning Kamprawend(void *data, const char *el) { 3755bb6a25fSPoul-Henning Kamp Parseinfo *inf = (Parseinfo *) data; 3765bb6a25fSPoul-Henning Kamp 3775bb6a25fSPoul-Henning Kamp inf->depth--; 3785bb6a25fSPoul-Henning Kamp 3795bb6a25fSPoul-Henning Kamp if (! inf->skip) 3805bb6a25fSPoul-Henning Kamp end(inf, el); /* This does rest of end handling */ 3815bb6a25fSPoul-Henning Kamp 3825bb6a25fSPoul-Henning Kamp if (inf->skip == inf->depth) 3835bb6a25fSPoul-Henning Kamp inf->skip = 0; 3845bb6a25fSPoul-Henning Kamp} /* End rawend */ 3855bb6a25fSPoul-Henning Kamp</pre> 3865bb6a25fSPoul-Henning Kamp 3875bb6a25fSPoul-Henning Kamp<p>Notice in the above example the difference in how depth is 3885bb6a25fSPoul-Henning Kampmanipulated in the start and end handlers. The end tag handler should 3895bb6a25fSPoul-Henning Kampbe the mirror image of the start tag handler. This is necessary to 3905bb6a25fSPoul-Henning Kampproperly model containment. Since, in the start tag handler, we 3915bb6a25fSPoul-Henning Kampincremented depth <em>after</em> the main body of start tag code, then 3925bb6a25fSPoul-Henning Kampin the end handler, we need to manipulate it <em>before</em> the main 3935bb6a25fSPoul-Henning Kampbody. If we'd decided to increment it first thing in the start 3945bb6a25fSPoul-Henning Kamphandler, then we'd have had to decrement it last thing in the end 3955bb6a25fSPoul-Henning Kamphandler.</p> 3965bb6a25fSPoul-Henning Kamp 3975bb6a25fSPoul-Henning Kamp<h3 id="userdata">Communicating between handlers</h3> 3985bb6a25fSPoul-Henning Kamp 3995bb6a25fSPoul-Henning Kamp<p>In order to be able to pass information between different handlers 4005bb6a25fSPoul-Henning Kampwithout using globals, you'll need to define a data structure to hold 4015bb6a25fSPoul-Henning Kampthe shared variables. You can then tell Expat (with the <code><a href= 4025bb6a25fSPoul-Henning Kamp"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a 4035bb6a25fSPoul-Henning Kamppointer to this structure to the handlers. This is typically the first 4045bb6a25fSPoul-Henning Kampargument received by most handlers.</p> 4055bb6a25fSPoul-Henning Kamp 4065bb6a25fSPoul-Henning Kamp<h3>XML Version</h3> 4075bb6a25fSPoul-Henning Kamp 4085bb6a25fSPoul-Henning Kamp<p>Expat is an XML 1.0 parser, and as such never complains based on 4095bb6a25fSPoul-Henning Kampthe value of the <code>version</code> pseudo-attribute in the XML 4105bb6a25fSPoul-Henning Kampdeclaration, if present.</p> 4115bb6a25fSPoul-Henning Kamp 4125bb6a25fSPoul-Henning Kamp<p>If an application needs to check the version number (to support 4135bb6a25fSPoul-Henning Kampalternate processing), it should use the <code><a href= 4145bb6a25fSPoul-Henning Kamp"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to 4155bb6a25fSPoul-Henning Kampset a handler that uses the information in the XML declaration to 4165bb6a25fSPoul-Henning Kampdetermine what to do. This example shows how to check that only a 4175bb6a25fSPoul-Henning Kampversion number of <code>"1.0"</code> is accepted:</p> 4185bb6a25fSPoul-Henning Kamp 4195bb6a25fSPoul-Henning Kamp<pre class="eg"> 4205bb6a25fSPoul-Henning Kampstatic int wrong_version; 4215bb6a25fSPoul-Henning Kampstatic XML_Parser parser; 4225bb6a25fSPoul-Henning Kamp 4235bb6a25fSPoul-Henning Kampstatic void 4245bb6a25fSPoul-Henning Kampxmldecl_handler(void *userData, 4255bb6a25fSPoul-Henning Kamp const XML_Char *version, 4265bb6a25fSPoul-Henning Kamp const XML_Char *encoding, 4275bb6a25fSPoul-Henning Kamp int standalone) 4285bb6a25fSPoul-Henning Kamp{ 4295bb6a25fSPoul-Henning Kamp static const XML_Char Version_1_0[] = {'1', '.', '0', 0}; 4305bb6a25fSPoul-Henning Kamp 4315bb6a25fSPoul-Henning Kamp int i; 4325bb6a25fSPoul-Henning Kamp 4335bb6a25fSPoul-Henning Kamp for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) { 4345bb6a25fSPoul-Henning Kamp if (version[i] != Version_1_0[i]) { 4355bb6a25fSPoul-Henning Kamp wrong_version = 1; 4365bb6a25fSPoul-Henning Kamp /* also clear all other handlers: */ 4375bb6a25fSPoul-Henning Kamp XML_SetCharacterDataHandler(parser, NULL); 4385bb6a25fSPoul-Henning Kamp ... 4395bb6a25fSPoul-Henning Kamp return; 4405bb6a25fSPoul-Henning Kamp } 4415bb6a25fSPoul-Henning Kamp } 4425bb6a25fSPoul-Henning Kamp ... 4435bb6a25fSPoul-Henning Kamp} 4445bb6a25fSPoul-Henning Kamp</pre> 4455bb6a25fSPoul-Henning Kamp 4465bb6a25fSPoul-Henning Kamp<h3>Namespace Processing</h3> 4475bb6a25fSPoul-Henning Kamp 4485bb6a25fSPoul-Henning Kamp<p>When the parser is created using the <code><a href= 4495bb6a25fSPoul-Henning Kamp"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat 4505bb6a25fSPoul-Henning Kampperforms namespace processing. Under namespace processing, Expat 4515bb6a25fSPoul-Henning Kampconsumes <code>xmlns</code> and <code>xmlns:...</code> attributes, 4525bb6a25fSPoul-Henning Kampwhich declare namespaces for the scope of the element in which they 4535bb6a25fSPoul-Henning Kampoccur. This means that your start handler will not see these 4545bb6a25fSPoul-Henning Kampattributes. Your application can still be informed of these 4555bb6a25fSPoul-Henning Kampdeclarations by setting namespace declaration handlers with <a href= 4565bb6a25fSPoul-Henning Kamp"#XML_SetNamespaceDeclHandler" 4575bb6a25fSPoul-Henning Kamp><code>XML_SetNamespaceDeclHandler</code></a>.</p> 4585bb6a25fSPoul-Henning Kamp 4595bb6a25fSPoul-Henning Kamp<p>Element type and attribute names that belong to a given namespace 4605bb6a25fSPoul-Henning Kampare passed to the appropriate handler in expanded form. By default 4615bb6a25fSPoul-Henning Kampthis expanded form is a concatenation of the namespace URI, the 4625bb6a25fSPoul-Henning Kampseparator character (which is the 2nd argument to <code><a href= 4635bb6a25fSPoul-Henning Kamp"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local 4645bb6a25fSPoul-Henning Kampname (i.e. the part after the colon). Names with undeclared prefixes 4655bb6a25fSPoul-Henning Kampare passed through to the handlers unchanged, with the prefix and 4665bb6a25fSPoul-Henning Kampcolon still attached. Unprefixed attribute names are never expanded, 4675bb6a25fSPoul-Henning Kampand unprefixed element names are only expanded when they are in the 4685bb6a25fSPoul-Henning Kampscope of a default namespace.</p> 4695bb6a25fSPoul-Henning Kamp 4705bb6a25fSPoul-Henning Kamp<p>However if <code><a href= "XML_SetReturnNSTriplet" 4715bb6a25fSPoul-Henning Kamp>XML_SetReturnNSTriplet</a></code> has been called with a non-zero 4725bb6a25fSPoul-Henning Kamp<code>do_nst</code> parameter, then the expanded form for names with 4735bb6a25fSPoul-Henning Kampan explicit prefix is a concatenation of: URI, separator, local name, 4745bb6a25fSPoul-Henning Kampseparator, prefix.</p> 4755bb6a25fSPoul-Henning Kamp 4765bb6a25fSPoul-Henning Kamp<p>You can set handlers for the start of a namespace declaration and 4775bb6a25fSPoul-Henning Kampfor the end of a scope of a declaration with the <code><a href= 4785bb6a25fSPoul-Henning Kamp"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code> 4795bb6a25fSPoul-Henning Kampfunction. The StartNamespaceDeclHandler is called prior to the start 4805bb6a25fSPoul-Henning Kamptag handler and the EndNamespaceDeclHandler is called before the 4815bb6a25fSPoul-Henning Kampcorresponding end tag that ends the namespace's scope. The namespace 4825bb6a25fSPoul-Henning Kampstart handler gets passed the prefix and URI for the namespace. For a 4835bb6a25fSPoul-Henning Kampdefault namespace declaration (xmlns='...'), the prefix will be null. 4845bb6a25fSPoul-Henning KampThe URI will be null for the case where the default namespace is being 4855bb6a25fSPoul-Henning Kampunset. The namespace end handler just gets the prefix for the closing 4865bb6a25fSPoul-Henning Kampscope.</p> 4875bb6a25fSPoul-Henning Kamp 4885bb6a25fSPoul-Henning Kamp<p>These handlers are called for each declaration. So if, for 4895bb6a25fSPoul-Henning Kampinstance, a start tag had three namespace declarations, then the 4905bb6a25fSPoul-Henning KampStartNamespaceDeclHandler would be called three times before the start 4915bb6a25fSPoul-Henning Kamptag handler is called, once for each declaration.</p> 4925bb6a25fSPoul-Henning Kamp 4935bb6a25fSPoul-Henning Kamp<h3>Character Encodings</h3> 4945bb6a25fSPoul-Henning Kamp 4955bb6a25fSPoul-Henning Kamp<p>While XML is based on Unicode, and every XML processor is required 4965bb6a25fSPoul-Henning Kampto recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), 4975bb6a25fSPoul-Henning Kampother encodings may be declared in XML documents or entities. For the 4985bb6a25fSPoul-Henning Kampmain document, an XML declaration may contain an encoding 4995bb6a25fSPoul-Henning Kampdeclaration:</p> 5005bb6a25fSPoul-Henning Kamp<pre> 5015bb6a25fSPoul-Henning Kamp<?xml version="1.0" encoding="ISO-8859-2"?> 5025bb6a25fSPoul-Henning Kamp</pre> 5035bb6a25fSPoul-Henning Kamp 5045bb6a25fSPoul-Henning Kamp<p>External parsed entities may begin with a text declaration, which 5055bb6a25fSPoul-Henning Kamplooks like an XML declaration with just an encoding declaration:</p> 5065bb6a25fSPoul-Henning Kamp<pre> 5075bb6a25fSPoul-Henning Kamp<?xml encoding="Big5"?> 5085bb6a25fSPoul-Henning Kamp</pre> 5095bb6a25fSPoul-Henning Kamp 5105bb6a25fSPoul-Henning Kamp<p>With Expat, you may also specify an encoding at the time of 5115bb6a25fSPoul-Henning Kampcreating a parser. This is useful when the encoding information may 5125bb6a25fSPoul-Henning Kampcome from a source outside the document itself (like a higher level 5135bb6a25fSPoul-Henning Kampprotocol.)</p> 5145bb6a25fSPoul-Henning Kamp 5155bb6a25fSPoul-Henning Kamp<p><a name="builtin_encodings"></a>There are four built-in encodings 5165bb6a25fSPoul-Henning Kampin Expat:</p> 5175bb6a25fSPoul-Henning Kamp<ul> 5185bb6a25fSPoul-Henning Kamp<li>UTF-8</li> 5195bb6a25fSPoul-Henning Kamp<li>UTF-16</li> 5205bb6a25fSPoul-Henning Kamp<li>ISO-8859-1</li> 5215bb6a25fSPoul-Henning Kamp<li>US-ASCII</li> 5225bb6a25fSPoul-Henning Kamp</ul> 5235bb6a25fSPoul-Henning Kamp 5245bb6a25fSPoul-Henning Kamp<p>Anything else discovered in an encoding declaration or in the 5255bb6a25fSPoul-Henning Kampprotocol encoding specified in the parser constructor, triggers a call 5265bb6a25fSPoul-Henning Kampto the <code>UnknownEncodingHandler</code>. This handler gets passed 5275bb6a25fSPoul-Henning Kampthe encoding name and a pointer to an <code>XML_Encoding</code> data 5285bb6a25fSPoul-Henning Kampstructure. Your handler must fill in this structure and return 1 if it 5295bb6a25fSPoul-Henning Kampknows how to deal with the encoding. Otherwise the handler should 5305bb6a25fSPoul-Henning Kampreturn 0. The handler also gets passed a pointer to an optional 5315bb6a25fSPoul-Henning Kampapplication data structure that you may indicate when you set the 5325bb6a25fSPoul-Henning Kamphandler.</p> 5335bb6a25fSPoul-Henning Kamp 5345bb6a25fSPoul-Henning Kamp<p>Expat places restrictions on character encodings that it can 5355bb6a25fSPoul-Henning Kampsupport by filling in the <code>XML_Encoding</code> structure. 5365bb6a25fSPoul-Henning Kampinclude file:</p> 5375bb6a25fSPoul-Henning Kamp<ol> 5385bb6a25fSPoul-Henning Kamp<li>Every ASCII character that can appear in a well-formed XML document 5395bb6a25fSPoul-Henning Kampmust be represented by a single byte, and that byte must correspond to 5405bb6a25fSPoul-Henning Kampit's ASCII encoding (except for the characters $@\^'{}~)</li> 5415bb6a25fSPoul-Henning Kamp<li>Characters must be encoded in 4 bytes or less.</li> 5425bb6a25fSPoul-Henning Kamp<li>All characters encoded must have Unicode scalar values less than or 5435bb6a25fSPoul-Henning Kampequal to 65535 (0xFFFF)<em>This does not apply to the built-in support 5445bb6a25fSPoul-Henning Kampfor UTF-16 and UTF-8</em></li> 5455bb6a25fSPoul-Henning Kamp<li>No character may be encoded by more that one distinct sequence of 5465bb6a25fSPoul-Henning Kampbytes</li> 5475bb6a25fSPoul-Henning Kamp</ol> 5485bb6a25fSPoul-Henning Kamp 5495bb6a25fSPoul-Henning Kamp<p><code>XML_Encoding</code> contains an array of integers that 5505bb6a25fSPoul-Henning Kampcorrespond to the 1st byte of an encoding sequence. If the value in 5515bb6a25fSPoul-Henning Kampthe array for a byte is zero or positive, then the byte is a single 5525bb6a25fSPoul-Henning Kampbyte encoding that encodes the Unicode scalar value contained in the 5535bb6a25fSPoul-Henning Kamparray. A -1 in this array indicates a malformed byte. If the value is 5545bb6a25fSPoul-Henning Kamp-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte 5555bb6a25fSPoul-Henning Kampsequence respectively. Multi-byte sequences are sent to the convert 5565bb6a25fSPoul-Henning Kampfunction pointed at in the <code>XML_Encoding</code> structure. This 5575bb6a25fSPoul-Henning Kampfunction should return the Unicode scalar value for the sequence or -1 5585bb6a25fSPoul-Henning Kampif the sequence is malformed.</p> 5595bb6a25fSPoul-Henning Kamp 5605bb6a25fSPoul-Henning Kamp<p>One pitfall that novice Expat users are likely to fall into is that 5615bb6a25fSPoul-Henning Kampalthough Expat may accept input in various encodings, the strings that 5625bb6a25fSPoul-Henning Kampit passes to the handlers are always encoded in UTF-8 or UTF-16 5635bb6a25fSPoul-Henning Kamp(depending on how Expat was compiled). Your application is responsible 5645bb6a25fSPoul-Henning Kampfor any translation of these strings into other encodings.</p> 5655bb6a25fSPoul-Henning Kamp 5665bb6a25fSPoul-Henning Kamp<h3>Handling External Entity References</h3> 5675bb6a25fSPoul-Henning Kamp 5685bb6a25fSPoul-Henning Kamp<p>Expat does not read or parse external entities directly. Note that 5695bb6a25fSPoul-Henning Kampany external DTD is a special case of an external entity. If you've 5705bb6a25fSPoul-Henning Kampset no <code>ExternalEntityRefHandler</code>, then external entity 5715bb6a25fSPoul-Henning Kampreferences are silently ignored. Otherwise, it calls your handler with 5725bb6a25fSPoul-Henning Kampthe information needed to read and parse the external entity.</p> 5735bb6a25fSPoul-Henning Kamp 5745bb6a25fSPoul-Henning Kamp<p>Your handler isn't actually responsible for parsing the entity, but 5755bb6a25fSPoul-Henning Kampit is responsible for creating a subsidiary parser with <code><a href= 5765bb6a25fSPoul-Henning Kamp"#XML_ExternalEntityParserCreate" 5775bb6a25fSPoul-Henning Kamp>XML_ExternalEntityParserCreate</a></code> that will do the job. This 5785bb6a25fSPoul-Henning Kampreturns an instance of <code>XML_Parser</code> that has handlers and 5795bb6a25fSPoul-Henning Kampother data structures initialized from the parent parser. You may then 5805bb6a25fSPoul-Henning Kampuse <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a 5815bb6a25fSPoul-Henning Kamphref= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this 5825bb6a25fSPoul-Henning Kampparser. Since external entities my refer to other external entities, 5835bb6a25fSPoul-Henning Kampyour handler should be prepared to be called recursively.</p> 5845bb6a25fSPoul-Henning Kamp 5855bb6a25fSPoul-Henning Kamp<h3>Parsing DTDs</h3> 5865bb6a25fSPoul-Henning Kamp 5875bb6a25fSPoul-Henning Kamp<p>In order to parse parameter entities, before starting the parse, 5885bb6a25fSPoul-Henning Kampyou must call <code><a href= "#XML_SetParamEntityParsing" 5895bb6a25fSPoul-Henning Kamp>XML_SetParamEntityParsing</a></code> with one of the following 5905bb6a25fSPoul-Henning Kamparguments:</p> 5915bb6a25fSPoul-Henning Kamp<dl> 5925bb6a25fSPoul-Henning Kamp<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt> 5935bb6a25fSPoul-Henning Kamp<dd>Don't parse parameter entities or the external subset</dd> 5945bb6a25fSPoul-Henning Kamp<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt> 5955bb6a25fSPoul-Henning Kamp<dd>Parse parameter entites and the external subset unless 5965bb6a25fSPoul-Henning Kamp<code>standalone</code> was set to "yes" in the XML declaration.</dd> 5975bb6a25fSPoul-Henning Kamp<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt> 5985bb6a25fSPoul-Henning Kamp<dd>Always parse parameter entities and the external subset</dd> 5995bb6a25fSPoul-Henning Kamp</dl> 6005bb6a25fSPoul-Henning Kamp 6015bb6a25fSPoul-Henning Kamp<p>In order to read an external DTD, you also have to set an external 6025bb6a25fSPoul-Henning Kampentity reference handler as described above.</p> 6035bb6a25fSPoul-Henning Kamp 6045bb6a25fSPoul-Henning Kamp<hr /> 6055bb6a25fSPoul-Henning Kamp<!-- ================================================================ --> 6065bb6a25fSPoul-Henning Kamp 6075bb6a25fSPoul-Henning Kamp<h2><a name="reference">Expat Reference</a></h2> 6085bb6a25fSPoul-Henning Kamp 6095bb6a25fSPoul-Henning Kamp<h3><a name="creation">Parser Creation</a></h3> 6105bb6a25fSPoul-Henning Kamp 6115bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserCreate"> 6125bb6a25fSPoul-Henning KampXML_Parser 6135bb6a25fSPoul-Henning KampXML_ParserCreate(const XML_Char *encoding); 6145bb6a25fSPoul-Henning Kamp</pre> 6155bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6165bb6a25fSPoul-Henning KampConstruct a new parser. If encoding is non-null, it specifies a 6175bb6a25fSPoul-Henning Kampcharacter encoding to use for the document. This overrides the document 6185bb6a25fSPoul-Henning Kampencoding declaration. There are four built-in encodings: 6195bb6a25fSPoul-Henning Kamp<ul> 6205bb6a25fSPoul-Henning Kamp<li>US-ASCII</li> 6215bb6a25fSPoul-Henning Kamp<li>UTF-8</li> 6225bb6a25fSPoul-Henning Kamp<li>UTF-16</li> 6235bb6a25fSPoul-Henning Kamp<li>ISO-8859-1</li> 6245bb6a25fSPoul-Henning Kamp</ul> 6255bb6a25fSPoul-Henning KampAny other value will invoke a call to the UnknownEncodingHandler. 6265bb6a25fSPoul-Henning Kamp</div> 6275bb6a25fSPoul-Henning Kamp 6285bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserCreateNS"> 6295bb6a25fSPoul-Henning KampXML_Parser 6305bb6a25fSPoul-Henning KampXML_ParserCreateNS(const XML_Char *encoding, 6315bb6a25fSPoul-Henning Kamp XML_Char sep); 6325bb6a25fSPoul-Henning Kamp</pre> 6335bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6345bb6a25fSPoul-Henning KampConstructs a new parser that has namespace processing in effect. Namespace 6355bb6a25fSPoul-Henning Kampexpanded element names and attribute names are returned as a concatenation 6365bb6a25fSPoul-Henning Kampof the namespace URI, <em>sep</em>, and the local part of the name. This 6375bb6a25fSPoul-Henning Kampmeans that you should pick a character for <em>sep</em> that can't be 6385bb6a25fSPoul-Henning Kamppart of a legal URI.</div> 6395bb6a25fSPoul-Henning Kamp 6405bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserCreate_MM"> 6415bb6a25fSPoul-Henning KampXML_Parser 6425bb6a25fSPoul-Henning KampXML_ParserCreate_MM(const XML_Char *encoding, 6435bb6a25fSPoul-Henning Kamp const XML_Memory_Handling_Suite *ms, 6445bb6a25fSPoul-Henning Kamp const XML_Char *sep); 6455bb6a25fSPoul-Henning Kamp</pre> 6465bb6a25fSPoul-Henning Kamp<pre class="signature"> 6475bb6a25fSPoul-Henning Kamptypedef struct { 6485bb6a25fSPoul-Henning Kamp void *(*malloc_fcn)(size_t size); 6495bb6a25fSPoul-Henning Kamp void *(*realloc_fcn)(void *ptr, size_t size); 6505bb6a25fSPoul-Henning Kamp void (*free_fcn)(void *ptr); 6515bb6a25fSPoul-Henning Kamp} XML_Memory_Handling_Suite; 6525bb6a25fSPoul-Henning Kamp</pre> 6535bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6545bb6a25fSPoul-Henning Kamp<p>Construct a new parser using the suite of memory handling functions 6555bb6a25fSPoul-Henning Kampspecified in <code>ms</code>. If <code>ms</code> is NULL, then use the 6565bb6a25fSPoul-Henning Kampstandard set of memory management functions. If <code>sep</code> is 6575bb6a25fSPoul-Henning Kampnon NULL, then namespace processing is enabled in the created parser 6585bb6a25fSPoul-Henning Kampand the character pointed at by sep is used as the separator between 6595bb6a25fSPoul-Henning Kampthe namespace URI and the local part of the name.</p> 6605bb6a25fSPoul-Henning Kamp</div> 6615bb6a25fSPoul-Henning Kamp 6625bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExternalEntityParserCreate"> 6635bb6a25fSPoul-Henning KampXML_Parser 6645bb6a25fSPoul-Henning KampXML_ExternalEntityParserCreate(XML_Parser p, 6655bb6a25fSPoul-Henning Kamp const XML_Char *context, 6665bb6a25fSPoul-Henning Kamp const XML_Char *encoding); 6675bb6a25fSPoul-Henning Kamp</pre> 6685bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6695bb6a25fSPoul-Henning KampConstruct a new <code>XML_Parser</code> object for parsing an external 6705bb6a25fSPoul-Henning Kampgeneral entity. Context is the context argument passed in a call to a 6715bb6a25fSPoul-Henning KampExternalEntityRefHandler. Other state information such as handlers, 6725bb6a25fSPoul-Henning Kampuser data, namespace processing is inherited from the parser passed as 6735bb6a25fSPoul-Henning Kampthe 1st argument. So you shouldn't need to call any of the behavior 6745bb6a25fSPoul-Henning Kampchanging functions on this parser (unless you want it to act 6755bb6a25fSPoul-Henning Kampdifferently than the parent parser). 6765bb6a25fSPoul-Henning Kamp</div> 6775bb6a25fSPoul-Henning Kamp 6785bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserFree"> 6795bb6a25fSPoul-Henning Kampvoid 6805bb6a25fSPoul-Henning KampXML_ParserFree(XML_Parser p); 6815bb6a25fSPoul-Henning Kamp</pre> 6825bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6835bb6a25fSPoul-Henning KampFree memory used by the parser. Your application is responsible for 6845bb6a25fSPoul-Henning Kampfreeing any memory associated with <a href="#userdata">user data</a>. 6855bb6a25fSPoul-Henning Kamp</div> 6865bb6a25fSPoul-Henning Kamp 6875bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParserReset"> 6885bb6a25fSPoul-Henning KampXML_Bool 6895bb6a25fSPoul-Henning KampXML_ParserReset(XML_Parser p); 6905bb6a25fSPoul-Henning Kamp</pre> 6915bb6a25fSPoul-Henning Kamp<div class="fcndef"> 6925bb6a25fSPoul-Henning KampClean up the memory structures maintained by the parser so that it may 6935bb6a25fSPoul-Henning Kampbe used again. After this has been called, <code>parser</code> is 6945bb6a25fSPoul-Henning Kampready to start parsing a new document. This function may not be used 6955bb6a25fSPoul-Henning Kampon a parser created using <code><a href= 6965bb6a25fSPoul-Henning Kamp"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a 6975bb6a25fSPoul-Henning Kamp></code>; it will return <code>XML_FALSE</code> in that case. Returns 6985bb6a25fSPoul-Henning Kamp<code>XML_TRUE</code> on success. Your application is responsible for 6995bb6a25fSPoul-Henning Kampdealing with any memory associated with <a href="#userdata">user data</a>. 7005bb6a25fSPoul-Henning Kamp</div> 7015bb6a25fSPoul-Henning Kamp 7025bb6a25fSPoul-Henning Kamp<h3><a name="parsing">Parsing</a></h3> 7035bb6a25fSPoul-Henning Kamp 7045bb6a25fSPoul-Henning Kamp<p>To state the obvious: the three parsing functions <code><a href= 7055bb6a25fSPoul-Henning Kamp"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer" 7065bb6a25fSPoul-Henning Kamp>XML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer" 7075bb6a25fSPoul-Henning Kamp>>XML_GetBuffer</a></code> must not be 7085bb6a25fSPoul-Henning Kampcalled from within a handler unless they operate on a separate parser 7095bb6a25fSPoul-Henning Kampinstance, that is, one that did not call the handler. For example, it 7105bb6a25fSPoul-Henning Kampis OK to call the parsing functions from within an 7115bb6a25fSPoul-Henning Kamp<code>XML_ExternalEntityRefHandler</code>, if they apply to the parser 7125bb6a25fSPoul-Henning Kampcreated by <code><a href= "#XML_ExternalEntityParserCreate" 7135bb6a25fSPoul-Henning Kamp>XML_ExternalEntityParserCreate</a></code>.</p> 7145bb6a25fSPoul-Henning Kamp 7155bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_Parse"> 7165bb6a25fSPoul-Henning KampXML_Status 7175bb6a25fSPoul-Henning KampXML_Parse(XML_Parser p, 7185bb6a25fSPoul-Henning Kamp const char *s, 7195bb6a25fSPoul-Henning Kamp int len, 7205bb6a25fSPoul-Henning Kamp int isFinal); 7215bb6a25fSPoul-Henning Kamp</pre> 7225bb6a25fSPoul-Henning Kamp<pre class="signature"> 7235bb6a25fSPoul-Henning Kampenum XML_Status { 7245bb6a25fSPoul-Henning Kamp XML_STATUS_ERROR = 0, 7255bb6a25fSPoul-Henning Kamp XML_STATUS_OK = 1 7265bb6a25fSPoul-Henning Kamp}; 7275bb6a25fSPoul-Henning Kamp</pre> 7285bb6a25fSPoul-Henning Kamp<div class="fcndef"> 7295bb6a25fSPoul-Henning KampParse some more of the document. The string <code>s</code> is a buffer 7305bb6a25fSPoul-Henning Kampcontaining part (or perhaps all) of the document. The number of bytes of s 7315bb6a25fSPoul-Henning Kampthat are part of the document is indicated by <code>len</code>. This means 7325bb6a25fSPoul-Henning Kampthat <code>s</code> doesn't have to be null terminated. It also means that 7335bb6a25fSPoul-Henning Kampif <code>len</code> is larger than the number of bytes in the block of 7345bb6a25fSPoul-Henning Kampmemory that <code>s</code> points at, then a memory fault is likely. The 7355bb6a25fSPoul-Henning Kamp<code>isFinal</code> parameter informs the parser that this is the last 7365bb6a25fSPoul-Henning Kamppiece of the document. Frequently, the last piece is empty (i.e. 7375bb6a25fSPoul-Henning Kamp<code>len</code> is zero.) 7385bb6a25fSPoul-Henning KampIf a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. 7395bb6a25fSPoul-Henning KampOtherwise it returns <code>XML_STATUS_OK</code> value. 7405bb6a25fSPoul-Henning Kamp</div> 7415bb6a25fSPoul-Henning Kamp 7425bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ParseBuffer"> 7435bb6a25fSPoul-Henning KampXML_Status 7445bb6a25fSPoul-Henning KampXML_ParseBuffer(XML_Parser p, 7455bb6a25fSPoul-Henning Kamp int len, 7465bb6a25fSPoul-Henning Kamp int isFinal); 7475bb6a25fSPoul-Henning Kamp</pre> 7485bb6a25fSPoul-Henning Kamp<div class="fcndef"> 7495bb6a25fSPoul-Henning KampThis is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>, 7505bb6a25fSPoul-Henning Kampexcept in this case Expat provides the buffer. By obtaining the 7515bb6a25fSPoul-Henning Kampbuffer from Expat with the <code><a href= "#XML_GetBuffer" 7525bb6a25fSPoul-Henning Kamp>XML_GetBuffer</a></code> function, the application can avoid double 7535bb6a25fSPoul-Henning Kampcopying of the input. 7545bb6a25fSPoul-Henning Kamp</div> 7555bb6a25fSPoul-Henning Kamp 7565bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetBuffer"> 7575bb6a25fSPoul-Henning Kampvoid * 7585bb6a25fSPoul-Henning KampXML_GetBuffer(XML_Parser p, 7595bb6a25fSPoul-Henning Kamp int len); 7605bb6a25fSPoul-Henning Kamp</pre> 7615bb6a25fSPoul-Henning Kamp<div class="fcndef"> 7625bb6a25fSPoul-Henning KampObtain a buffer of size <code>len</code> to read a piece of the document 7635bb6a25fSPoul-Henning Kampinto. A NULL value is returned if Expat can't allocate enough memory for 7645bb6a25fSPoul-Henning Kampthis buffer. This has to be called prior to every call to 7655bb6a25fSPoul-Henning Kamp<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A 7665bb6a25fSPoul-Henning Kamptypical use would look like this: 7675bb6a25fSPoul-Henning Kamp 7685bb6a25fSPoul-Henning Kamp<pre class="eg"> 7695bb6a25fSPoul-Henning Kampfor (;;) { 7705bb6a25fSPoul-Henning Kamp int bytes_read; 7715bb6a25fSPoul-Henning Kamp void *buff = XML_GetBuffer(p, BUFF_SIZE); 7725bb6a25fSPoul-Henning Kamp if (buff == NULL) { 7735bb6a25fSPoul-Henning Kamp /* handle error */ 7745bb6a25fSPoul-Henning Kamp } 7755bb6a25fSPoul-Henning Kamp 7765bb6a25fSPoul-Henning Kamp bytes_read = read(docfd, buff, BUFF_SIZE); 7775bb6a25fSPoul-Henning Kamp if (bytes_read < 0) { 7785bb6a25fSPoul-Henning Kamp /* handle error */ 7795bb6a25fSPoul-Henning Kamp } 7805bb6a25fSPoul-Henning Kamp 7815bb6a25fSPoul-Henning Kamp if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) { 7825bb6a25fSPoul-Henning Kamp /* handle parse error */ 7835bb6a25fSPoul-Henning Kamp } 7845bb6a25fSPoul-Henning Kamp 7855bb6a25fSPoul-Henning Kamp if (bytes_read == 0) 7865bb6a25fSPoul-Henning Kamp break; 7875bb6a25fSPoul-Henning Kamp} 7885bb6a25fSPoul-Henning Kamp</pre> 7895bb6a25fSPoul-Henning Kamp</div> 7905bb6a25fSPoul-Henning Kamp 7915bb6a25fSPoul-Henning Kamp<h3><a name="setting">Handler Setting</a></h3> 7925bb6a25fSPoul-Henning Kamp 7935bb6a25fSPoul-Henning Kamp<p>Although handlers are typically set prior to parsing and left alone, an 7945bb6a25fSPoul-Henning Kampapplication may choose to set or change the handler for a parsing event 7955bb6a25fSPoul-Henning Kampwhile the parse is in progress. For instance, your application may choose 7965bb6a25fSPoul-Henning Kampto ignore all text not descended from a <code>para</code> element. One 7975bb6a25fSPoul-Henning Kampway it could do this is to set the character handler when a para start tag 7985bb6a25fSPoul-Henning Kampis seen, and unset it for the corresponding end tag.</p> 7995bb6a25fSPoul-Henning Kamp 8005bb6a25fSPoul-Henning Kamp<p>A handler may be <em>unset</em> by providing a NULL pointer to the 8015bb6a25fSPoul-Henning Kampappropriate handler setter. None of the handler setting functions have 8025bb6a25fSPoul-Henning Kampa return value.</p> 8035bb6a25fSPoul-Henning Kamp 8045bb6a25fSPoul-Henning Kamp<p>Your handlers will be receiving strings in arrays of type 8055bb6a25fSPoul-Henning Kamp<code>XML_Char</code>. This type is defined in expat.h as <code>char 8065bb6a25fSPoul-Henning Kamp*</code> and contains bytes encoding UTF-8. Note that you'll receive 8075bb6a25fSPoul-Henning Kampthem in this form independent of the original encoding of the 8085bb6a25fSPoul-Henning Kampdocument.</p> 8095bb6a25fSPoul-Henning Kamp 8105bb6a25fSPoul-Henning Kamp<div class="handler"> 8115bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartElementHandler"> 8125bb6a25fSPoul-Henning KampXML_SetStartElementHandler(XML_Parser p, 8135bb6a25fSPoul-Henning Kamp XML_StartElementHandler start); 8145bb6a25fSPoul-Henning Kamp</pre> 8155bb6a25fSPoul-Henning Kamp<pre class="signature"> 8165bb6a25fSPoul-Henning Kamptypedef void 8175bb6a25fSPoul-Henning Kamp(*XML_StartElementHandler)(void *userData, 8185bb6a25fSPoul-Henning Kamp const XML_Char *name, 8195bb6a25fSPoul-Henning Kamp const XML_Char **atts); 8205bb6a25fSPoul-Henning Kamp</pre> 8215bb6a25fSPoul-Henning Kamp<p>Set handler for start (and empty) tags. Attributes are passed to the start 8225bb6a25fSPoul-Henning Kamphandler as a pointer to a vector of char pointers. Each attribute seen in 8235bb6a25fSPoul-Henning Kampa start (or empty) tag occupies 2 consecutive places in this vector: the 8245bb6a25fSPoul-Henning Kampattribute name followed by the attribute value. These pairs are terminated 8255bb6a25fSPoul-Henning Kampby a null pointer.</p> 8265bb6a25fSPoul-Henning Kamp<p>Note that an empty tag generates a call to both start and end handlers 8275bb6a25fSPoul-Henning Kamp(in that order).</p> 8285bb6a25fSPoul-Henning Kamp</div> 8295bb6a25fSPoul-Henning Kamp 8305bb6a25fSPoul-Henning Kamp<div class="handler"> 8315bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndElementHandler"> 8325bb6a25fSPoul-Henning KampXML_SetEndElementHandler(XML_Parser p, 8335bb6a25fSPoul-Henning Kamp XML_EndElementHandler); 8345bb6a25fSPoul-Henning Kamp</pre> 8355bb6a25fSPoul-Henning Kamp<pre class="signature"> 8365bb6a25fSPoul-Henning Kamptypedef void 8375bb6a25fSPoul-Henning Kamp(*XML_EndElementHandler)(void *userData, 8385bb6a25fSPoul-Henning Kamp const XML_Char *name); 8395bb6a25fSPoul-Henning Kamp</pre> 8405bb6a25fSPoul-Henning Kamp<p>Set handler for end (and empty) tags. As noted above, an empty tag 8415bb6a25fSPoul-Henning Kampgenerates a call to both start and end handlers.</p> 8425bb6a25fSPoul-Henning Kamp</div> 8435bb6a25fSPoul-Henning Kamp 8445bb6a25fSPoul-Henning Kamp<div class="handler"> 8455bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetElementHandler"> 8465bb6a25fSPoul-Henning KampXML_SetElementHandler(XML_Parser p, 8475bb6a25fSPoul-Henning Kamp XML_StartElementHandler start, 8485bb6a25fSPoul-Henning Kamp XML_EndElementHandler end); 8495bb6a25fSPoul-Henning Kamp</pre> 8505bb6a25fSPoul-Henning Kamp<p>Set handlers for start and end tags with one call.</p> 8515bb6a25fSPoul-Henning Kamp</div> 8525bb6a25fSPoul-Henning Kamp 8535bb6a25fSPoul-Henning Kamp<div class="handler"> 8545bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCharacterDataHandler"> 8555bb6a25fSPoul-Henning KampXML_SetCharacterDataHandler(XML_Parser p, 8565bb6a25fSPoul-Henning Kamp XML_CharacterDataHandler charhndl) 8575bb6a25fSPoul-Henning Kamp</pre> 8585bb6a25fSPoul-Henning Kamp<pre class="signature"> 8595bb6a25fSPoul-Henning Kamptypedef void 8605bb6a25fSPoul-Henning Kamp(*XML_CharacterDataHandler)(void *userData, 8615bb6a25fSPoul-Henning Kamp const XML_Char *s, 8625bb6a25fSPoul-Henning Kamp int len); 8635bb6a25fSPoul-Henning Kamp</pre> 8645bb6a25fSPoul-Henning Kamp<p>Set a text handler. The string your handler receives 8655bb6a25fSPoul-Henning Kampis <em>NOT nul-terminated</em>. You have to use the length argument 8665bb6a25fSPoul-Henning Kampto deal with the end of the string. A single block of contiguous text 8675bb6a25fSPoul-Henning Kampfree of markup may still result in a sequence of calls to this handler. 8685bb6a25fSPoul-Henning KampIn other words, if you're searching for a pattern in the text, it may 8695bb6a25fSPoul-Henning Kampbe split across calls to this handler.</p> 8705bb6a25fSPoul-Henning Kamp</div> 8715bb6a25fSPoul-Henning Kamp 8725bb6a25fSPoul-Henning Kamp<div class="handler"> 8735bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetProcessingInstructionHandler"> 8745bb6a25fSPoul-Henning KampXML_SetProcessingInstructionHandler(XML_Parser p, 8755bb6a25fSPoul-Henning Kamp XML_ProcessingInstructionHandler proc) 8765bb6a25fSPoul-Henning Kamp</pre> 8775bb6a25fSPoul-Henning Kamp<pre class="signature"> 8785bb6a25fSPoul-Henning Kamptypedef void 8795bb6a25fSPoul-Henning Kamp(*XML_ProcessingInstructionHandler)(void *userData, 8805bb6a25fSPoul-Henning Kamp const XML_Char *target, 8815bb6a25fSPoul-Henning Kamp const XML_Char *data); 8825bb6a25fSPoul-Henning Kamp 8835bb6a25fSPoul-Henning Kamp</pre> 8845bb6a25fSPoul-Henning Kamp<p>Set a handler for processing instructions. The target is the first word 8855bb6a25fSPoul-Henning Kampin the processing instruction. The data is the rest of the characters in 8865bb6a25fSPoul-Henning Kampit after skipping all whitespace after the initial word.</p> 8875bb6a25fSPoul-Henning Kamp</div> 8885bb6a25fSPoul-Henning Kamp 8895bb6a25fSPoul-Henning Kamp<div class="handler"> 8905bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCommentHandler"> 8915bb6a25fSPoul-Henning KampXML_SetCommentHandler(XML_Parser p, 8925bb6a25fSPoul-Henning Kamp XML_CommentHandler cmnt) 8935bb6a25fSPoul-Henning Kamp</pre> 8945bb6a25fSPoul-Henning Kamp<pre class="signature"> 8955bb6a25fSPoul-Henning Kamptypedef void 8965bb6a25fSPoul-Henning Kamp(*XML_CommentHandler)(void *userData, 8975bb6a25fSPoul-Henning Kamp const XML_Char *data); 8985bb6a25fSPoul-Henning Kamp</pre> 8995bb6a25fSPoul-Henning Kamp<p>Set a handler for comments. The data is all text inside the comment 9005bb6a25fSPoul-Henning Kampdelimiters.</p> 9015bb6a25fSPoul-Henning Kamp</div> 9025bb6a25fSPoul-Henning Kamp 9035bb6a25fSPoul-Henning Kamp<div class="handler"> 9045bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartCdataSectionHandler"> 9055bb6a25fSPoul-Henning KampXML_SetStartCdataSectionHandler(XML_Parser p, 9065bb6a25fSPoul-Henning Kamp XML_StartCdataSectionHandler start); 9075bb6a25fSPoul-Henning Kamp</pre> 9085bb6a25fSPoul-Henning Kamp<pre class="signature"> 9095bb6a25fSPoul-Henning Kamptypedef void 9105bb6a25fSPoul-Henning Kamp(*XML_StartCdataSectionHandler)(void *userData); 9115bb6a25fSPoul-Henning Kamp</pre> 9125bb6a25fSPoul-Henning Kamp<p>Set a handler that gets called at the beginning of a CDATA section.</p> 9135bb6a25fSPoul-Henning Kamp</div> 9145bb6a25fSPoul-Henning Kamp 9155bb6a25fSPoul-Henning Kamp<div class="handler"> 9165bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndCdataSectionHandler"> 9175bb6a25fSPoul-Henning KampXML_SetEndCdataSectionHandler(XML_Parser p, 9185bb6a25fSPoul-Henning Kamp XML_EndCdataSectionHandler end); 9195bb6a25fSPoul-Henning Kamp</pre> 9205bb6a25fSPoul-Henning Kamp<pre class="signature"> 9215bb6a25fSPoul-Henning Kamptypedef void 9225bb6a25fSPoul-Henning Kamp(*XML_EndCdataSectionHandler)(void *userData); 9235bb6a25fSPoul-Henning Kamp</pre> 9245bb6a25fSPoul-Henning Kamp<p>Set a handler that gets called at the end of a CDATA section.</p> 9255bb6a25fSPoul-Henning Kamp</div> 9265bb6a25fSPoul-Henning Kamp 9275bb6a25fSPoul-Henning Kamp<div class="handler"> 9285bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetCdataSectionHandler"> 9295bb6a25fSPoul-Henning KampXML_SetCdataSectionHandler(XML_Parser p, 9305bb6a25fSPoul-Henning Kamp XML_StartCdataSectionHandler start, 9315bb6a25fSPoul-Henning Kamp XML_EndCdataSectionHandler end) 9325bb6a25fSPoul-Henning Kamp</pre> 9335bb6a25fSPoul-Henning Kamp<p>Sets both CDATA section handlers with one call.</p> 9345bb6a25fSPoul-Henning Kamp</div> 9355bb6a25fSPoul-Henning Kamp 9365bb6a25fSPoul-Henning Kamp<div class="handler"> 9375bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDefaultHandler"> 9385bb6a25fSPoul-Henning KampXML_SetDefaultHandler(XML_Parser p, 9395bb6a25fSPoul-Henning Kamp XML_DefaultHandler hndl) 9405bb6a25fSPoul-Henning Kamp</pre> 9415bb6a25fSPoul-Henning Kamp<pre class="signature"> 9425bb6a25fSPoul-Henning Kamptypedef void 9435bb6a25fSPoul-Henning Kamp(*XML_DefaultHandler)(void *userData, 9445bb6a25fSPoul-Henning Kamp const XML_Char *s, 9455bb6a25fSPoul-Henning Kamp int len); 9465bb6a25fSPoul-Henning Kamp</pre> 9475bb6a25fSPoul-Henning Kamp 9485bb6a25fSPoul-Henning Kamp<p>Sets a handler for any characters in the document which wouldn't 9495bb6a25fSPoul-Henning Kampotherwise be handled. This includes both data for which no handlers 9505bb6a25fSPoul-Henning Kampcan be set (like some kinds of DTD declarations) and data which could 9515bb6a25fSPoul-Henning Kampbe reported but which currently has no handler set. The characters 9525bb6a25fSPoul-Henning Kampare passed exactly as they were present in the XML document except 9535bb6a25fSPoul-Henning Kampthat they will be encoded in UTF-8 or UTF-16. Line boundaries are not 9545bb6a25fSPoul-Henning Kampnormalized. Note that a byte order mark character is not passed to the 9555bb6a25fSPoul-Henning Kampdefault handler. There are no guarantees about how characters are 9565bb6a25fSPoul-Henning Kampdivided between calls to the default handler: for example, a comment 9575bb6a25fSPoul-Henning Kampmight be split between multiple calls. Setting the handler with 9585bb6a25fSPoul-Henning Kampthis call has the side effect of turning off expansion of references 9595bb6a25fSPoul-Henning Kampto internally defined general entities. Instead these references are 9605bb6a25fSPoul-Henning Kamppassed to the default handler.</p> 9615bb6a25fSPoul-Henning Kamp 9625bb6a25fSPoul-Henning Kamp<p>See also <code><a 9635bb6a25fSPoul-Henning Kamphref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 9645bb6a25fSPoul-Henning Kamp</div> 9655bb6a25fSPoul-Henning Kamp 9665bb6a25fSPoul-Henning Kamp<div class="handler"> 9675bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDefaultHandlerExpand"> 9685bb6a25fSPoul-Henning KampXML_SetDefaultHandlerExpand(XML_Parser p, 9695bb6a25fSPoul-Henning Kamp XML_DefaultHandler hndl) 9705bb6a25fSPoul-Henning Kamp</pre> 9715bb6a25fSPoul-Henning Kamp<pre class="signature"> 9725bb6a25fSPoul-Henning Kamptypedef void 9735bb6a25fSPoul-Henning Kamp(*XML_DefaultHandler)(void *userData, 9745bb6a25fSPoul-Henning Kamp const XML_Char *s, 9755bb6a25fSPoul-Henning Kamp int len); 9765bb6a25fSPoul-Henning Kamp</pre> 9775bb6a25fSPoul-Henning Kamp<p>This sets a default handler, but doesn't inhibit the expansion of 9785bb6a25fSPoul-Henning Kampinternal entity references. The entity reference will not be passed 9795bb6a25fSPoul-Henning Kampto the default handler.</p> 9805bb6a25fSPoul-Henning Kamp 9815bb6a25fSPoul-Henning Kamp<p>See also <code><a 9825bb6a25fSPoul-Henning Kamphref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 9835bb6a25fSPoul-Henning Kamp</div> 9845bb6a25fSPoul-Henning Kamp 9855bb6a25fSPoul-Henning Kamp<div class="handler"> 9865bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetExternalEntityRefHandler"> 9875bb6a25fSPoul-Henning KampXML_SetExternalEntityRefHandler(XML_Parser p, 9885bb6a25fSPoul-Henning Kamp XML_ExternalEntityRefHandler hndl) 9895bb6a25fSPoul-Henning Kamp</pre> 9905bb6a25fSPoul-Henning Kamp<pre class="signature"> 9915bb6a25fSPoul-Henning Kamptypedef int 9925bb6a25fSPoul-Henning Kamp(*XML_ExternalEntityRefHandler)(XML_Parser p, 9935bb6a25fSPoul-Henning Kamp const XML_Char *context, 9945bb6a25fSPoul-Henning Kamp const XML_Char *base, 9955bb6a25fSPoul-Henning Kamp const XML_Char *systemId, 9965bb6a25fSPoul-Henning Kamp const XML_Char *publicId); 9975bb6a25fSPoul-Henning Kamp</pre> 9985bb6a25fSPoul-Henning Kamp<p>Set an external entity reference handler. This handler is also 9995bb6a25fSPoul-Henning Kampcalled for processing an external DTD subset if parameter entity parsing 10005bb6a25fSPoul-Henning Kampis in effect. (See <a href="#XML_SetParamEntityParsing"> 10015bb6a25fSPoul-Henning Kamp<code>XML_SetParamEntityParsing</code></a>.)</p> 10025bb6a25fSPoul-Henning Kamp 10035bb6a25fSPoul-Henning Kamp 10045bb6a25fSPoul-Henning Kamp<p>The base parameter is the base to use for relative system identifiers. 10055bb6a25fSPoul-Henning KampIt is set by <a href="#XML_SetBase">XML_SetBase</a> and may be null. The 10065bb6a25fSPoul-Henning Kamppublic id parameter is the public id given in the entity declaration and 10075bb6a25fSPoul-Henning Kampmay be null. The system id is the system identifier specified in the entity 10085bb6a25fSPoul-Henning Kampdeclaration and is never null.</p> 10095bb6a25fSPoul-Henning Kamp 10105bb6a25fSPoul-Henning Kamp<p>There are a couple of ways in which this handler differs from others. 10115bb6a25fSPoul-Henning KampFirst, this handler returns an integer. A non-zero value should be returned 10125bb6a25fSPoul-Henning Kampfor successful handling of the external entity reference. Returning a zero 10135bb6a25fSPoul-Henning Kampindicates failure, and causes the calling parser to return 10145bb6a25fSPoul-Henning Kampan <code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p> 10155bb6a25fSPoul-Henning Kamp 10165bb6a25fSPoul-Henning Kamp<p>Second, instead of having userData as its first argument, it receives the 10175bb6a25fSPoul-Henning Kampparser that encountered the entity reference. This, along with the context 10185bb6a25fSPoul-Henning Kampparameter, may be used as arguments to a call to 10195bb6a25fSPoul-Henning Kamp<a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a>. 10205bb6a25fSPoul-Henning KampUsing the returned parser, the body of the external entity can be recursively 10215bb6a25fSPoul-Henning Kampparsed.</p> 10225bb6a25fSPoul-Henning Kamp 10235bb6a25fSPoul-Henning Kamp<p>Since this handler may be called recursively, it should not be saving 10245bb6a25fSPoul-Henning Kampinformation into global or static variables.</p> 10255bb6a25fSPoul-Henning Kamp</div> 10265bb6a25fSPoul-Henning Kamp 10275bb6a25fSPoul-Henning Kamp<div class="handler"> 10285bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetSkippedEntityHandler"> 10295bb6a25fSPoul-Henning KampXML_SetSkippedEntityHandler(XML_Parser p, 10305bb6a25fSPoul-Henning Kamp XML_SkippedEntityHandler handler) 10315bb6a25fSPoul-Henning Kamp</pre> 10325bb6a25fSPoul-Henning Kamp<pre class="signature"> 10335bb6a25fSPoul-Henning Kamptypedef void 10345bb6a25fSPoul-Henning Kamp(*XML_SkippedEntityHandler)(void *userData, 10355bb6a25fSPoul-Henning Kamp const XML_Char *entityName, 10365bb6a25fSPoul-Henning Kamp int is_parameter_entity); 10375bb6a25fSPoul-Henning Kamp</pre> 10385bb6a25fSPoul-Henning Kamp<p>Set a skipped entity handler. This is called in two situations:</p> 10395bb6a25fSPoul-Henning Kamp<ol> 10405bb6a25fSPoul-Henning Kamp <li>An entity reference is encountered for which no declaration 10415bb6a25fSPoul-Henning Kamp has been read <em>and</em> this is not an error.</li> 10425bb6a25fSPoul-Henning Kamp <li>An internal entity reference is read, but not expanded, because 10435bb6a25fSPoul-Henning Kamp <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> 10445bb6a25fSPoul-Henning Kamp has been called.</li> 10455bb6a25fSPoul-Henning Kamp</ol> 10465bb6a25fSPoul-Henning Kamp<p>The <code>is_parameter_entity</code> argument will be non-zero for 10475bb6a25fSPoul-Henning Kampa parameter entity and zero for a general entity.</p> <p>Note: skipped 10485bb6a25fSPoul-Henning Kampparameter entities in declarations and skipped general entities in 10495bb6a25fSPoul-Henning Kampattribute values cannot be reported, because the event would be out of 10505bb6a25fSPoul-Henning Kampsync with the reporting of the declarations or attribute values</p> 10515bb6a25fSPoul-Henning Kamp</div> 10525bb6a25fSPoul-Henning Kamp 10535bb6a25fSPoul-Henning Kamp<div class="handler"> 10545bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetUnknownEncodingHandler"> 10555bb6a25fSPoul-Henning KampXML_SetUnknownEncodingHandler(XML_Parser p, 10565bb6a25fSPoul-Henning Kamp XML_UnknownEncodingHandler enchandler, 10575bb6a25fSPoul-Henning Kamp void *encodingHandlerData) 10585bb6a25fSPoul-Henning Kamp</pre> 10595bb6a25fSPoul-Henning Kamp<pre class="signature"> 10605bb6a25fSPoul-Henning Kamptypedef int 10615bb6a25fSPoul-Henning Kamp(*XML_UnknownEncodingHandler)(void *encodingHandlerData, 10625bb6a25fSPoul-Henning Kamp const XML_Char *name, 10635bb6a25fSPoul-Henning Kamp XML_Encoding *info); 10645bb6a25fSPoul-Henning Kamp 10655bb6a25fSPoul-Henning Kamptypedef struct { 10665bb6a25fSPoul-Henning Kamp int map[256]; 10675bb6a25fSPoul-Henning Kamp void *data; 10685bb6a25fSPoul-Henning Kamp int (*convert)(void *data, const char *s); 10695bb6a25fSPoul-Henning Kamp void (*release)(void *data); 10705bb6a25fSPoul-Henning Kamp} XML_Encoding; 10715bb6a25fSPoul-Henning Kamp</pre> 10725bb6a25fSPoul-Henning Kamp<p>Set a handler to deal with encodings other than the 10735bb6a25fSPoul-Henning Kamp<a href="#builtin_encodings">built in set</a>. This should be done before 10745bb6a25fSPoul-Henning Kamp<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href= 10755bb6a25fSPoul-Henning Kamp"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the 10765bb6a25fSPoul-Henning Kampgiven parser.</p> 10775bb6a25fSPoul-Henning Kamp<p>If the handler knows how to deal with an encoding with the given 10785bb6a25fSPoul-Henning Kampname, it should fill in the <code>info</code> data structure and return 10795bb6a25fSPoul-Henning Kamp1. Otherwise it should return 0. The handler will be called at most 10805bb6a25fSPoul-Henning Kamponce per parsed (external) entity. The optional application data 10815bb6a25fSPoul-Henning Kamppointer <code>encodingHandlerData</code> will be passed back to the 10825bb6a25fSPoul-Henning Kamphandler.</p> 10835bb6a25fSPoul-Henning Kamp 10845bb6a25fSPoul-Henning Kamp<p>The map array contains information for every possible possible leading 10855bb6a25fSPoul-Henning Kampbyte in a byte sequence. If the corresponding value is >= 0, then it's 10865bb6a25fSPoul-Henning Kampa single byte sequence and the byte encodes that Unicode value. If the 10875bb6a25fSPoul-Henning Kampvalue is -1, then that byte is invalid as the initial byte in a sequence. 10885bb6a25fSPoul-Henning KampIf the value is -n, where n is an integer > 1, then n is the number of 10895bb6a25fSPoul-Henning Kampbytes in the sequence and the actual conversion is accomplished by a 10905bb6a25fSPoul-Henning Kampcall to the function pointed at by convert. This function may return -1 10915bb6a25fSPoul-Henning Kampif the sequence itself is invalid. The convert pointer may be null if 10925bb6a25fSPoul-Henning Kampthere are only single byte codes. The data parameter passed to the convert 10935bb6a25fSPoul-Henning Kampfunction is the data pointer from <code>XML_Encoding</code>. The 10945bb6a25fSPoul-Henning Kampstring s is <em>NOT</em> nul-terminated and points at the sequence of 10955bb6a25fSPoul-Henning Kampbytes to be converted.</p> 10965bb6a25fSPoul-Henning Kamp 10975bb6a25fSPoul-Henning Kamp<p>The function pointed at by <code>release</code> is called by the 10985bb6a25fSPoul-Henning Kampparser when it is finished with the encoding. It may be NULL.</p> 10995bb6a25fSPoul-Henning Kamp</div> 11005bb6a25fSPoul-Henning Kamp 11015bb6a25fSPoul-Henning Kamp<div class="handler"> 11025bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartNamespaceDeclHandler"> 11035bb6a25fSPoul-Henning KampXML_SetStartNamespaceDeclHandler(XML_Parser p, 11045bb6a25fSPoul-Henning Kamp XML_StartNamespaceDeclHandler start); 11055bb6a25fSPoul-Henning Kamp</pre> 11065bb6a25fSPoul-Henning Kamp<pre class="signature"> 11075bb6a25fSPoul-Henning Kamptypedef void 11085bb6a25fSPoul-Henning Kamp(*XML_StartNamespaceDeclHandler)(void *userData, 11095bb6a25fSPoul-Henning Kamp const XML_Char *prefix, 11105bb6a25fSPoul-Henning Kamp const XML_Char *uri); 11115bb6a25fSPoul-Henning Kamp</pre> 11125bb6a25fSPoul-Henning Kamp<p>Set a handler to be called when a namespace is declared. Namespace 11135bb6a25fSPoul-Henning Kampdeclarations occur inside start tags. But the namespace declaration start 11145bb6a25fSPoul-Henning Kamphandler is called before the start tag handler for each namespace declared 11155bb6a25fSPoul-Henning Kampin that start tag.</p> 11165bb6a25fSPoul-Henning Kamp</div> 11175bb6a25fSPoul-Henning Kamp 11185bb6a25fSPoul-Henning Kamp<div class="handler"> 11195bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndNamespaceDeclHandler"> 11205bb6a25fSPoul-Henning KampXML_SetEndNamespaceDeclHandler(XML_Parser p, 11215bb6a25fSPoul-Henning Kamp XML_EndNamespaceDeclHandler end); 11225bb6a25fSPoul-Henning Kamp</pre> 11235bb6a25fSPoul-Henning Kamp<pre class="signature"> 11245bb6a25fSPoul-Henning Kamptypedef void 11255bb6a25fSPoul-Henning Kamp(*XML_EndNamespaceDeclHandler)(void *userData, 11265bb6a25fSPoul-Henning Kamp const XML_Char *prefix); 11275bb6a25fSPoul-Henning Kamp</pre> 11285bb6a25fSPoul-Henning Kamp<p>Set a handler to be called when leaving the scope of a namespace 11295bb6a25fSPoul-Henning Kampdeclaration. This will be called, for each namespace declaration, 11305bb6a25fSPoul-Henning Kampafter the handler for the end tag of the element in which the 11315bb6a25fSPoul-Henning Kampnamespace was declared.</p> 11325bb6a25fSPoul-Henning Kamp</div> 11335bb6a25fSPoul-Henning Kamp 11345bb6a25fSPoul-Henning Kamp<div class="handler"> 11355bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNamespaceDeclHandler"> 11365bb6a25fSPoul-Henning KampXML_SetNamespaceDeclHandler(XML_Parser p, 11375bb6a25fSPoul-Henning Kamp XML_StartNamespaceDeclHandler start, 11385bb6a25fSPoul-Henning Kamp XML_EndNamespaceDeclHandler end) 11395bb6a25fSPoul-Henning Kamp</pre> 11405bb6a25fSPoul-Henning Kamp<p>Sets both namespace declaration handlers with a single call</p> 11415bb6a25fSPoul-Henning Kamp</div> 11425bb6a25fSPoul-Henning Kamp 11435bb6a25fSPoul-Henning Kamp<div class="handler"> 11445bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetXmlDeclHandler"> 11455bb6a25fSPoul-Henning KampXML_SetXmlDeclHandler(XML_Parser p, 11465bb6a25fSPoul-Henning Kamp XML_XmlDeclHandler xmldecl); 11475bb6a25fSPoul-Henning Kamp</pre> 11485bb6a25fSPoul-Henning Kamp<pre class="signature"> 11495bb6a25fSPoul-Henning Kamptypedef void 11505bb6a25fSPoul-Henning Kamp(*XML_XmlDeclHandler) (void *userData, 11515bb6a25fSPoul-Henning Kamp const XML_Char *version, 11525bb6a25fSPoul-Henning Kamp const XML_Char *encoding, 11535bb6a25fSPoul-Henning Kamp int standalone); 11545bb6a25fSPoul-Henning Kamp</pre> 11555bb6a25fSPoul-Henning Kamp<p>Sets a handler that is called for XML declarations and also for 11565bb6a25fSPoul-Henning Kamptext declarations discovered in external entities. The way to 11575bb6a25fSPoul-Henning Kampdistinguish is that the <code>version</code> parameter will be NULL 11585bb6a25fSPoul-Henning Kampfor text declarations. The <code>encoding</code> parameter may be NULL 11595bb6a25fSPoul-Henning Kampfor an XML declaration. The <code>standalone</code> argument will 11605bb6a25fSPoul-Henning Kampcontain -1, 0, or 1 indicating respectively that there was no 11615bb6a25fSPoul-Henning Kampstandalone parameter in the declaration, that it was given as no, or 11625bb6a25fSPoul-Henning Kampthat it was given as yes.</p> 11635bb6a25fSPoul-Henning Kamp</div> 11645bb6a25fSPoul-Henning Kamp 11655bb6a25fSPoul-Henning Kamp<div class="handler"> 11665bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetStartDoctypeDeclHandler"> 11675bb6a25fSPoul-Henning KampXML_SetStartDoctypeDeclHandler(XML_Parser p, 11685bb6a25fSPoul-Henning Kamp XML_StartDoctypeDeclHandler start); 11695bb6a25fSPoul-Henning Kamp</pre> 11705bb6a25fSPoul-Henning Kamp<pre class="signature"> 11715bb6a25fSPoul-Henning Kamptypedef void 11725bb6a25fSPoul-Henning Kamp(*XML_StartDoctypeDeclHandler)(void *userData, 11735bb6a25fSPoul-Henning Kamp const XML_Char *doctypeName, 11745bb6a25fSPoul-Henning Kamp const XML_Char *sysid, 11755bb6a25fSPoul-Henning Kamp const XML_Char *pubid, 11765bb6a25fSPoul-Henning Kamp int has_internal_subset); 11775bb6a25fSPoul-Henning Kamp</pre> 11785bb6a25fSPoul-Henning Kamp<p>Set a handler that is called at the start of a DOCTYPE declaration, 11795bb6a25fSPoul-Henning Kampbefore any external or internal subset is parsed. Both <code>sysid</code> 11805bb6a25fSPoul-Henning Kampand <code>pubid</code> may be NULL. The <code>has_internal_subset</code> 11815bb6a25fSPoul-Henning Kampwill be non-zero if the DOCTYPE declaration has an internal subset.</p> 11825bb6a25fSPoul-Henning Kamp</div> 11835bb6a25fSPoul-Henning Kamp 11845bb6a25fSPoul-Henning Kamp<div class="handler"> 11855bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEndDoctypeDeclHandler"> 11865bb6a25fSPoul-Henning KampXML_SetEndDoctypeDeclHandler(XML_Parser p, 11875bb6a25fSPoul-Henning Kamp XML_EndDoctypeDeclHandler end); 11885bb6a25fSPoul-Henning Kamp</pre> 11895bb6a25fSPoul-Henning Kamp<pre class="signature"> 11905bb6a25fSPoul-Henning Kamptypedef void 11915bb6a25fSPoul-Henning Kamp(*XML_EndDoctypeDeclHandler)(void *userData); 11925bb6a25fSPoul-Henning Kamp</pre> 11935bb6a25fSPoul-Henning Kamp<p>Set a handler that is called at the end of a DOCTYPE declaration, 11945bb6a25fSPoul-Henning Kampafter parsing any external subset.</p> 11955bb6a25fSPoul-Henning Kamp</div> 11965bb6a25fSPoul-Henning Kamp 11975bb6a25fSPoul-Henning Kamp<div class="handler"> 11985bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetDoctypeDeclHandler"> 11995bb6a25fSPoul-Henning KampXML_SetDoctypeDeclHandler(XML_Parser p, 12005bb6a25fSPoul-Henning Kamp XML_StartDoctypeDeclHandler start, 12015bb6a25fSPoul-Henning Kamp XML_EndDoctypeDeclHandler end); 12025bb6a25fSPoul-Henning Kamp</pre> 12035bb6a25fSPoul-Henning Kamp<p>Set both doctype handlers with one call.</p> 12045bb6a25fSPoul-Henning Kamp</div> 12055bb6a25fSPoul-Henning Kamp 12065bb6a25fSPoul-Henning Kamp<div class="handler"> 12075bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetElementDeclHandler"> 12085bb6a25fSPoul-Henning KampXML_SetElementDeclHandler(XML_Parser p, 12095bb6a25fSPoul-Henning Kamp XML_ElementDeclHandler eldecl); 12105bb6a25fSPoul-Henning Kamp</pre> 12115bb6a25fSPoul-Henning Kamp<pre class="signature"> 12125bb6a25fSPoul-Henning Kamptypedef void 12135bb6a25fSPoul-Henning Kamp(*XML_ElementDeclHandler)(void *userData, 12145bb6a25fSPoul-Henning Kamp const XML_Char *name, 12155bb6a25fSPoul-Henning Kamp XML_Content *model); 12165bb6a25fSPoul-Henning Kamp</pre> 12175bb6a25fSPoul-Henning Kamp<pre class="signature"> 12185bb6a25fSPoul-Henning Kampenum XML_Content_Type { 12195bb6a25fSPoul-Henning Kamp XML_CTYPE_EMPTY = 1, 12205bb6a25fSPoul-Henning Kamp XML_CTYPE_ANY, 12215bb6a25fSPoul-Henning Kamp XML_CTYPE_MIXED, 12225bb6a25fSPoul-Henning Kamp XML_CTYPE_NAME, 12235bb6a25fSPoul-Henning Kamp XML_CTYPE_CHOICE, 12245bb6a25fSPoul-Henning Kamp XML_CTYPE_SEQ 12255bb6a25fSPoul-Henning Kamp}; 12265bb6a25fSPoul-Henning Kamp 12275bb6a25fSPoul-Henning Kampenum XML_Content_Quant { 12285bb6a25fSPoul-Henning Kamp XML_CQUANT_NONE, 12295bb6a25fSPoul-Henning Kamp XML_CQUANT_OPT, 12305bb6a25fSPoul-Henning Kamp XML_CQUANT_REP, 12315bb6a25fSPoul-Henning Kamp XML_CQUANT_PLUS 12325bb6a25fSPoul-Henning Kamp}; 12335bb6a25fSPoul-Henning Kamp 12345bb6a25fSPoul-Henning Kamptypedef struct XML_cp XML_Content; 12355bb6a25fSPoul-Henning Kamp 12365bb6a25fSPoul-Henning Kampstruct XML_cp { 12375bb6a25fSPoul-Henning Kamp enum XML_Content_Type type; 12385bb6a25fSPoul-Henning Kamp enum XML_Content_Quant quant; 12395bb6a25fSPoul-Henning Kamp const XML_Char * name; 12405bb6a25fSPoul-Henning Kamp unsigned int numchildren; 12415bb6a25fSPoul-Henning Kamp XML_Content * children; 12425bb6a25fSPoul-Henning Kamp}; 12435bb6a25fSPoul-Henning Kamp</pre> 12445bb6a25fSPoul-Henning Kamp<p>Sets a handler for element declarations in a DTD. The handler gets 12455bb6a25fSPoul-Henning Kampcalled with the name of the element in the declaration and a pointer 12465bb6a25fSPoul-Henning Kampto a structure that contains the element model. It is the 12475bb6a25fSPoul-Henning Kampapplication's responsibility to free this data structure.</p> 12485bb6a25fSPoul-Henning Kamp 12495bb6a25fSPoul-Henning Kamp<p>The <code>model</code> argument is the root of a tree of 12505bb6a25fSPoul-Henning Kamp<code>XML_Content</code> nodes. If <code>type</code> equals 12515bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then 12525bb6a25fSPoul-Henning Kamp<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other 12535bb6a25fSPoul-Henning Kampfields will be zero or NULL. If <code>type</code> is 12545bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be 12555bb6a25fSPoul-Henning Kamp<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and 12565bb6a25fSPoul-Henning Kamp<code>numchildren</code> will contain the number of elements that are 12575bb6a25fSPoul-Henning Kampallowed to be mixed in and <code>children</code> points to an array of 12585bb6a25fSPoul-Henning Kamp<code>XML_Content</code> structures that will all have type 12595bb6a25fSPoul-Henning KampXML_CTYPE_NAME with no quantification. Only the root node can be type 12605bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or 12615bb6a25fSPoul-Henning Kamp<code>XML_CTYPE_MIXED</code>.</p> 12625bb6a25fSPoul-Henning Kamp 12635bb6a25fSPoul-Henning Kamp<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field 12645bb6a25fSPoul-Henning Kamppoints to the name and the <code>numchildren</code> and 12655bb6a25fSPoul-Henning Kamp<code>children</code> fields will be zero and NULL. The 12665bb6a25fSPoul-Henning Kamp<code>quant</code> field will indicate any quantifiers placed on the 12675bb6a25fSPoul-Henning Kampname.</p> 12685bb6a25fSPoul-Henning Kamp 12695bb6a25fSPoul-Henning Kamp<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> 12705bb6a25fSPoul-Henning Kampindicate a choice or sequence respectively. The 12715bb6a25fSPoul-Henning Kamp<code>numchildren</code> field indicates how many nodes in the choice 12725bb6a25fSPoul-Henning Kampor sequence and <code>children</code> points to the nodes.</p> 12735bb6a25fSPoul-Henning Kamp</div> 12745bb6a25fSPoul-Henning Kamp 12755bb6a25fSPoul-Henning Kamp<div class="handler"> 12765bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetAttlistDeclHandler"> 12775bb6a25fSPoul-Henning KampXML_SetAttlistDeclHandler(XML_Parser p, 12785bb6a25fSPoul-Henning Kamp XML_AttlistDeclHandler attdecl); 12795bb6a25fSPoul-Henning Kamp</pre> 12805bb6a25fSPoul-Henning Kamp<pre class="signature"> 12815bb6a25fSPoul-Henning Kamptypedef void 12825bb6a25fSPoul-Henning Kamp(*XML_AttlistDeclHandler) (void *userData, 12835bb6a25fSPoul-Henning Kamp const XML_Char *elname, 12845bb6a25fSPoul-Henning Kamp const XML_Char *attname, 12855bb6a25fSPoul-Henning Kamp const XML_Char *att_type, 12865bb6a25fSPoul-Henning Kamp const XML_Char *dflt, 12875bb6a25fSPoul-Henning Kamp int isrequired); 12885bb6a25fSPoul-Henning Kamp</pre> 12895bb6a25fSPoul-Henning Kamp<p>Set a handler for attlist declarations in the DTD. This handler is 12905bb6a25fSPoul-Henning Kampcalled for <em>each</em> attribute. So a single attlist declaration 12915bb6a25fSPoul-Henning Kampwith multiple attributes declared will generate multiple calls to this 12925bb6a25fSPoul-Henning Kamphandler. The <code>elname</code> parameter returns the name of the 12935bb6a25fSPoul-Henning Kampelement for which the attribute is being declared. The attribute name 12945bb6a25fSPoul-Henning Kampis in the <code>attname</code> parameter. The attribute type is in the 12955bb6a25fSPoul-Henning Kamp<code>att_type</code> parameter. It is the string representing the 12965bb6a25fSPoul-Henning Kamptype in the declaration with whitespace removed.</p> 12975bb6a25fSPoul-Henning Kamp 12985bb6a25fSPoul-Henning Kamp<p>The <code>dflt</code> parameter holds the default value. It will be 12995bb6a25fSPoul-Henning KampNULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can 13005bb6a25fSPoul-Henning Kampdistinguish these two cases by checking the <code>isrequired</code> 13015bb6a25fSPoul-Henning Kampparameter, which will be true in the case of "#REQUIRED" attributes. 13025bb6a25fSPoul-Henning KampAttributes which are "#FIXED" will have also have a true 13035bb6a25fSPoul-Henning Kamp<code>isrequired</code>, but they will have the non-NULL fixed value 13045bb6a25fSPoul-Henning Kampin the <code>dflt</code> parameter.</p> 13055bb6a25fSPoul-Henning Kamp</div> 13065bb6a25fSPoul-Henning Kamp 13075bb6a25fSPoul-Henning Kamp<div class="handler"> 13085bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetEntityDeclHandler"> 13095bb6a25fSPoul-Henning KampXML_SetEntityDeclHandler(XML_Parser p, 13105bb6a25fSPoul-Henning Kamp XML_EntityDeclHandler handler); 13115bb6a25fSPoul-Henning Kamp</pre> 13125bb6a25fSPoul-Henning Kamp<pre class="signature"> 13135bb6a25fSPoul-Henning Kamptypedef void 13145bb6a25fSPoul-Henning Kamp(*XML_EntityDeclHandler) (void *userData, 13155bb6a25fSPoul-Henning Kamp const XML_Char *entityName, 13165bb6a25fSPoul-Henning Kamp int is_parameter_entity, 13175bb6a25fSPoul-Henning Kamp const XML_Char *value, 13185bb6a25fSPoul-Henning Kamp int value_length, 13195bb6a25fSPoul-Henning Kamp const XML_Char *base, 13205bb6a25fSPoul-Henning Kamp const XML_Char *systemId, 13215bb6a25fSPoul-Henning Kamp const XML_Char *publicId, 13225bb6a25fSPoul-Henning Kamp const XML_Char *notationName); 13235bb6a25fSPoul-Henning Kamp</pre> 13245bb6a25fSPoul-Henning Kamp<p>Sets a handler that will be called for all entity declarations. 13255bb6a25fSPoul-Henning KampThe <code>is_parameter_entity</code> argument will be non-zero in the 13265bb6a25fSPoul-Henning Kampcase of parameter entities and zero otherwise.</p> 13275bb6a25fSPoul-Henning Kamp 13285bb6a25fSPoul-Henning Kamp<p>For internal entities (<code><!ENTITY foo "bar"></code>), 13295bb6a25fSPoul-Henning Kamp<code>value</code> will be non-NULL and <code>systemId</code>, 13305bb6a25fSPoul-Henning Kamp<code>publicId</code>, and <code>notationName</code> will all be NULL. 13315bb6a25fSPoul-Henning KampThe value string is <em>not</em> NULL terminated; the length is 13325bb6a25fSPoul-Henning Kampprovided in the <code>value_length</code> parameter. Do not use 13335bb6a25fSPoul-Henning Kamp<code>value_length</code> to test for internal entities, since it is 13345bb6a25fSPoul-Henning Kamplegal to have zero-length values. Instead check for whether or not 13355bb6a25fSPoul-Henning Kamp<code>value</code> is NULL.</p> <p>The <code>notationName</code> 13365bb6a25fSPoul-Henning Kampargument will have a non-NULL value only for unparsed entity 13375bb6a25fSPoul-Henning Kampdeclarations.</p> 13385bb6a25fSPoul-Henning Kamp</div> 13395bb6a25fSPoul-Henning Kamp 13405bb6a25fSPoul-Henning Kamp<div class="handler"> 13415bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetUnparsedEntityDeclHandler"> 13425bb6a25fSPoul-Henning KampXML_SetUnparsedEntityDeclHandler(XML_Parser p, 13435bb6a25fSPoul-Henning Kamp XML_UnparsedEntityDeclHandler h) 13445bb6a25fSPoul-Henning Kamp</pre> 13455bb6a25fSPoul-Henning Kamp<pre class="signature"> 13465bb6a25fSPoul-Henning Kamptypedef void 13475bb6a25fSPoul-Henning Kamp(*XML_UnparsedEntityDeclHandler)(void *userData, 13485bb6a25fSPoul-Henning Kamp const XML_Char *entityName, 13495bb6a25fSPoul-Henning Kamp const XML_Char *base, 13505bb6a25fSPoul-Henning Kamp const XML_Char *systemId, 13515bb6a25fSPoul-Henning Kamp const XML_Char *publicId, 13525bb6a25fSPoul-Henning Kamp const XML_Char *notationName); 13535bb6a25fSPoul-Henning Kamp</pre> 13545bb6a25fSPoul-Henning Kamp<p>Set a handler that receives declarations of unparsed entities. These 13555bb6a25fSPoul-Henning Kampare entity declarations that have a notation (NDATA) field:</p> 13565bb6a25fSPoul-Henning Kamp 13575bb6a25fSPoul-Henning Kamp<div id="eg"><pre> 13585bb6a25fSPoul-Henning Kamp<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif> 13595bb6a25fSPoul-Henning Kamp</pre></div> 13605bb6a25fSPoul-Henning Kamp<p>This handler is obsolete and is provided for backwards 13615bb6a25fSPoul-Henning Kampcompatibility. Use instead <a href= "#XML_SetEntityDeclHandler" 13625bb6a25fSPoul-Henning Kamp>XML_SetEntityDeclHandler</a>.</p> 13635bb6a25fSPoul-Henning Kamp</div> 13645bb6a25fSPoul-Henning Kamp 13655bb6a25fSPoul-Henning Kamp<div class="handler"> 13665bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNotationDeclHandler"> 13675bb6a25fSPoul-Henning KampXML_SetNotationDeclHandler(XML_Parser p, 13685bb6a25fSPoul-Henning Kamp XML_NotationDeclHandler h) 13695bb6a25fSPoul-Henning Kamp</pre> 13705bb6a25fSPoul-Henning Kamp<pre class="signature"> 13715bb6a25fSPoul-Henning Kamptypedef void 13725bb6a25fSPoul-Henning Kamp(*XML_NotationDeclHandler)(void *userData, 13735bb6a25fSPoul-Henning Kamp const XML_Char *notationName, 13745bb6a25fSPoul-Henning Kamp const XML_Char *base, 13755bb6a25fSPoul-Henning Kamp const XML_Char *systemId, 13765bb6a25fSPoul-Henning Kamp const XML_Char *publicId); 13775bb6a25fSPoul-Henning Kamp</pre> 13785bb6a25fSPoul-Henning Kamp<p>Set a handler that receives notation declarations.</p> 13795bb6a25fSPoul-Henning Kamp</div> 13805bb6a25fSPoul-Henning Kamp 13815bb6a25fSPoul-Henning Kamp<div class="handler"> 13825bb6a25fSPoul-Henning Kamp<pre class="setter" id="XML_SetNotStandaloneHandler"> 13835bb6a25fSPoul-Henning KampXML_SetNotStandaloneHandler(XML_Parser p, 13845bb6a25fSPoul-Henning Kamp XML_NotStandaloneHandler h) 13855bb6a25fSPoul-Henning Kamp</pre> 13865bb6a25fSPoul-Henning Kamp<pre class="signature"> 13875bb6a25fSPoul-Henning Kamptypedef int 13885bb6a25fSPoul-Henning Kamp(*XML_NotStandaloneHandler)(void *userData); 13895bb6a25fSPoul-Henning Kamp</pre> 13905bb6a25fSPoul-Henning Kamp<p>Set a handler that is called if the document is not "standalone". 13915bb6a25fSPoul-Henning KampThis happens when there is an external subset or a reference to a 13925bb6a25fSPoul-Henning Kampparameter entity, but does not have standalone set to "yes" in an XML 13935bb6a25fSPoul-Henning Kampdeclaration. If this handler returns 0, then the parser will throw an 13945bb6a25fSPoul-Henning Kamp<code>XML_ERROR_NOT_STANDALONE</code> error.</p> 13955bb6a25fSPoul-Henning Kamp</div> 13965bb6a25fSPoul-Henning Kamp 13975bb6a25fSPoul-Henning Kamp<h3><a name="position">Parse position and error reporting functions</a></h3> 13985bb6a25fSPoul-Henning Kamp 13995bb6a25fSPoul-Henning Kamp<p>These are the functions you'll want to call when the parse 14005bb6a25fSPoul-Henning Kampfunctions return 0 (i.e. a parse error has ocurred), although the 14015bb6a25fSPoul-Henning Kampposition reporting functions are useful outside of errors. The 14025bb6a25fSPoul-Henning Kampposition reported is the byte position (in the original document or 14035bb6a25fSPoul-Henning Kampentity encoding) of the first of the sequence of characters that 14045bb6a25fSPoul-Henning Kampgenerated the current event (or the error that caused the parse 14055bb6a25fSPoul-Henning Kampfunctions to return 0.)</p> 14065bb6a25fSPoul-Henning Kamp 14075bb6a25fSPoul-Henning Kamp<p>The position reporting functions are accurate only outside of the 14085bb6a25fSPoul-Henning KampDTD. In other words, they usually return bogus information when 14095bb6a25fSPoul-Henning Kampcalled from within a DTD declaration handler.</p> 14105bb6a25fSPoul-Henning Kamp 14115bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetErrorCode"> 14125bb6a25fSPoul-Henning Kampenum XML_Error 14135bb6a25fSPoul-Henning KampXML_GetErrorCode(XML_Parser p); 14145bb6a25fSPoul-Henning Kamp</pre> 14155bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14165bb6a25fSPoul-Henning KampReturn what type of error has occurred. 14175bb6a25fSPoul-Henning Kamp</div> 14185bb6a25fSPoul-Henning Kamp 14195bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ErrorString"> 14205bb6a25fSPoul-Henning Kampconst XML_LChar * 14215bb6a25fSPoul-Henning KampXML_ErrorString(int code); 14225bb6a25fSPoul-Henning Kamp</pre> 14235bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14245bb6a25fSPoul-Henning KampReturn a string describing the error corresponding to code. 14255bb6a25fSPoul-Henning KampThe code should be one of the enums that can be returned from 14265bb6a25fSPoul-Henning Kamp<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>. 14275bb6a25fSPoul-Henning Kamp</div> 14285bb6a25fSPoul-Henning Kamp 14295bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentByteIndex"> 14305bb6a25fSPoul-Henning Kamplong 14315bb6a25fSPoul-Henning KampXML_GetCurrentByteIndex(XML_Parser p); 14325bb6a25fSPoul-Henning Kamp</pre> 14335bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14345bb6a25fSPoul-Henning KampReturn the byte offset of the position. 14355bb6a25fSPoul-Henning Kamp</div> 14365bb6a25fSPoul-Henning Kamp 14375bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentLineNumber"> 14385bb6a25fSPoul-Henning Kampint 14395bb6a25fSPoul-Henning KampXML_GetCurrentLineNumber(XML_Parser p); 14405bb6a25fSPoul-Henning Kamp</pre> 14415bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14425bb6a25fSPoul-Henning KampReturn the line number of the position. 14435bb6a25fSPoul-Henning Kamp</div> 14445bb6a25fSPoul-Henning Kamp 14455bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentColumnNumber"> 14465bb6a25fSPoul-Henning Kampint 14475bb6a25fSPoul-Henning KampXML_GetCurrentColumnNumber(XML_Parser p); 14485bb6a25fSPoul-Henning Kamp</pre> 14495bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14505bb6a25fSPoul-Henning KampReturn the offset, from the beginning of the current line, of 14515bb6a25fSPoul-Henning Kampthe position. 14525bb6a25fSPoul-Henning Kamp</div> 14535bb6a25fSPoul-Henning Kamp 14545bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetCurrentByteCount"> 14555bb6a25fSPoul-Henning Kampint 14565bb6a25fSPoul-Henning KampXML_GetCurrentByteCount(XML_Parser p); 14575bb6a25fSPoul-Henning Kamp</pre> 14585bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14595bb6a25fSPoul-Henning KampReturn the number of bytes in the current event. Returns 14605bb6a25fSPoul-Henning Kamp<code>0</code> if the event is inside a reference to an internal 14615bb6a25fSPoul-Henning Kampentity and for the end-tag event for empty element tags (the later can 14625bb6a25fSPoul-Henning Kampbe used to distinguish empty-element tags from empty elements using 14635bb6a25fSPoul-Henning Kampseparate start and end tags). 14645bb6a25fSPoul-Henning Kamp</div> 14655bb6a25fSPoul-Henning Kamp 14665bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetInputContext"> 14675bb6a25fSPoul-Henning Kampconst char * 14685bb6a25fSPoul-Henning KampXML_GetInputContext(XML_Parser p, 14695bb6a25fSPoul-Henning Kamp int *offset, 14705bb6a25fSPoul-Henning Kamp int *size); 14715bb6a25fSPoul-Henning Kamp</pre> 14725bb6a25fSPoul-Henning Kamp<div class="fcndef"> 14735bb6a25fSPoul-Henning Kamp 14745bb6a25fSPoul-Henning Kamp<p>Returns the parser's input buffer, sets the integer pointed at by 14755bb6a25fSPoul-Henning Kamp<code>offset</code> to the offset within this buffer of the current 14765bb6a25fSPoul-Henning Kampparse position, and set the integer pointed at by <code>size</code> to 14775bb6a25fSPoul-Henning Kampthe size of the returned buffer.</p> 14785bb6a25fSPoul-Henning Kamp 14795bb6a25fSPoul-Henning Kamp<p>This should only be called from within a handler during an active 14805bb6a25fSPoul-Henning Kampparse and the returned buffer should only be referred to from within 14815bb6a25fSPoul-Henning Kampthe handler that made the call. This input buffer contains the 14825bb6a25fSPoul-Henning Kampuntranslated bytes of the input.</p> 14835bb6a25fSPoul-Henning Kamp 14845bb6a25fSPoul-Henning Kamp<p>Only a limited amount of context is kept, so if the event 14855bb6a25fSPoul-Henning Kamptriggering a call spans over a very large amount of input, the actual 14865bb6a25fSPoul-Henning Kampparse position may be before the beginning of the buffer.</p> 14875bb6a25fSPoul-Henning Kamp</div> 14885bb6a25fSPoul-Henning Kamp 14895bb6a25fSPoul-Henning Kamp<h3><a name="miscellaneous">Miscellaneous functions</a></h3> 14905bb6a25fSPoul-Henning Kamp 14915bb6a25fSPoul-Henning Kamp<p>The functions in this section either obtain state information from 14925bb6a25fSPoul-Henning Kampthe parser or can be used to dynamicly set parser options.</p> 14935bb6a25fSPoul-Henning Kamp 14945bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetUserData"> 14955bb6a25fSPoul-Henning Kampvoid 14965bb6a25fSPoul-Henning KampXML_SetUserData(XML_Parser p, 14975bb6a25fSPoul-Henning Kamp void *userData); 14985bb6a25fSPoul-Henning Kamp</pre> 14995bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15005bb6a25fSPoul-Henning KampThis sets the user data pointer that gets passed to handlers. It 15015bb6a25fSPoul-Henning Kampoverwrites any previous value for this pointer. Note that the 15025bb6a25fSPoul-Henning Kampapplication is responsible for freeing the memory associated with 15035bb6a25fSPoul-Henning Kamp<code>userData</code> when it is finished with the parser. So if you 15045bb6a25fSPoul-Henning Kampcall this when there's already a pointer there, and you haven't freed 15055bb6a25fSPoul-Henning Kampthe memory associated with it, then you've probably just leaked 15065bb6a25fSPoul-Henning Kampmemory. 15075bb6a25fSPoul-Henning Kamp</div> 15085bb6a25fSPoul-Henning Kamp 15095bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetUserData"> 15105bb6a25fSPoul-Henning Kampvoid * 15115bb6a25fSPoul-Henning KampXML_GetUserData(XML_Parser p); 15125bb6a25fSPoul-Henning Kamp</pre> 15135bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15145bb6a25fSPoul-Henning KampThis returns the user data pointer that gets passed to handlers. 15155bb6a25fSPoul-Henning KampIt is actually implemented as a macro. 15165bb6a25fSPoul-Henning Kamp</div> 15175bb6a25fSPoul-Henning Kamp 15185bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_UseParserAsHandlerArg"> 15195bb6a25fSPoul-Henning Kampvoid 15205bb6a25fSPoul-Henning KampXML_UseParserAsHandlerArg(XML_Parser p); 15215bb6a25fSPoul-Henning Kamp</pre> 15225bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15235bb6a25fSPoul-Henning KampAfter this is called, handlers receive the parser in the userData 15245bb6a25fSPoul-Henning Kampargument. The userData information can still be obtained using the 15255bb6a25fSPoul-Henning Kamp<code><a href= "#XML_GetUserData" >XML_GetUserData</a></code> 15265bb6a25fSPoul-Henning Kampfunction. 15275bb6a25fSPoul-Henning Kamp</div> 15285bb6a25fSPoul-Henning Kamp 15295bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetBase"> 15305bb6a25fSPoul-Henning Kampint 15315bb6a25fSPoul-Henning KampXML_SetBase(XML_Parser p, 15325bb6a25fSPoul-Henning Kamp const XML_Char *base); 15335bb6a25fSPoul-Henning Kamp</pre> 15345bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15355bb6a25fSPoul-Henning KampSet the base to be used for resolving relative URIs in system 15365bb6a25fSPoul-Henning Kampidentifiers. The return value is 0 if there's no memory to store 15375bb6a25fSPoul-Henning Kampbase, otherwise it's non-zero. 15385bb6a25fSPoul-Henning Kamp</div> 15395bb6a25fSPoul-Henning Kamp 15405bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetBase"> 15415bb6a25fSPoul-Henning Kampconst XML_Char * 15425bb6a25fSPoul-Henning KampXML_GetBase(XML_Parser p); 15435bb6a25fSPoul-Henning Kamp</pre> 15445bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15455bb6a25fSPoul-Henning KampReturn the base for resolving relative URIs. 15465bb6a25fSPoul-Henning Kamp</div> 15475bb6a25fSPoul-Henning Kamp 15485bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetSpecifiedAttributeCount"> 15495bb6a25fSPoul-Henning Kampint 15505bb6a25fSPoul-Henning KampXML_GetSpecifiedAttributeCount(XML_Parser p); 15515bb6a25fSPoul-Henning Kamp</pre> 15525bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15535bb6a25fSPoul-Henning KampWhen attributes are reported to the start handler in the atts vector, 15545bb6a25fSPoul-Henning Kampattributes that were explicitly set in the element occur before any 15555bb6a25fSPoul-Henning Kampattributes that receive their value from default information in an 15565bb6a25fSPoul-Henning KampATTLIST declaration. This function returns the number of attributes 15575bb6a25fSPoul-Henning Kampthat were explicitly set times two, thus giving the offset in the 15585bb6a25fSPoul-Henning Kamp<code>atts</code> array passed to the start tag handler of the first 15595bb6a25fSPoul-Henning Kampattribute set due to defaults. It supplies information for the last 15605bb6a25fSPoul-Henning Kampcall to a start handler. If called inside a start handler, then that 15615bb6a25fSPoul-Henning Kampmeans the current call. 15625bb6a25fSPoul-Henning Kamp</div> 15635bb6a25fSPoul-Henning Kamp 15645bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetIdAttributeIndex"> 15655bb6a25fSPoul-Henning Kampint 15665bb6a25fSPoul-Henning KampXML_GetIdAttributeIndex(XML_Parser p); 15675bb6a25fSPoul-Henning Kamp</pre> 15685bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15695bb6a25fSPoul-Henning KampReturns the index of the ID attribute passed in the atts array in the 15705bb6a25fSPoul-Henning Kamplast call to <code><a href= "#XML_StartElementHandler" 15715bb6a25fSPoul-Henning Kamp>XML_StartElementHandler</a></code>, or -1 if there is no ID 15725bb6a25fSPoul-Henning Kampattribute. If called inside a start handler, then that means the 15735bb6a25fSPoul-Henning Kampcurrent call. 15745bb6a25fSPoul-Henning Kamp</div> 15755bb6a25fSPoul-Henning Kamp 15765bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetEncoding"> 15775bb6a25fSPoul-Henning Kampint 15785bb6a25fSPoul-Henning KampXML_SetEncoding(XML_Parser p, 15795bb6a25fSPoul-Henning Kamp const XML_Char *encoding); 15805bb6a25fSPoul-Henning Kamp</pre> 15815bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15825bb6a25fSPoul-Henning KampSet the encoding to be used by the parser. It is equivalent to 15835bb6a25fSPoul-Henning Kamppassing a non-null encoding argument to the parser creation functions. 15845bb6a25fSPoul-Henning KampIt must not be called after <code><a href= "#XML_Parse" 15855bb6a25fSPoul-Henning Kamp>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 15865bb6a25fSPoul-Henning Kamp>XML_ParseBuffer</a></code> have been called on the given parser. 15875bb6a25fSPoul-Henning Kamp</div> 15885bb6a25fSPoul-Henning Kamp 15895bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetParamEntityParsing"> 15905bb6a25fSPoul-Henning Kampint 15915bb6a25fSPoul-Henning KampXML_SetParamEntityParsing(XML_Parser p, 15925bb6a25fSPoul-Henning Kamp enum XML_ParamEntityParsing code); 15935bb6a25fSPoul-Henning Kamp</pre> 15945bb6a25fSPoul-Henning Kamp<div class="fcndef"> 15955bb6a25fSPoul-Henning KampThis enables parsing of parameter entities, including the external 15965bb6a25fSPoul-Henning Kampparameter entity that is the external DTD subset, according to 15975bb6a25fSPoul-Henning Kamp<code>code</code>. 15985bb6a25fSPoul-Henning KampThe choices for <code>code</code> are: 15995bb6a25fSPoul-Henning Kamp<ul> 16005bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li> 16015bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li> 16025bb6a25fSPoul-Henning Kamp<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li> 16035bb6a25fSPoul-Henning Kamp</ul> 16045bb6a25fSPoul-Henning Kamp</div> 16055bb6a25fSPoul-Henning Kamp 16065bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_UseForeignDTD"> 16075bb6a25fSPoul-Henning Kampenum XML_Error 16085bb6a25fSPoul-Henning KampXML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); 16095bb6a25fSPoul-Henning Kamp</pre> 16105bb6a25fSPoul-Henning Kamp<div class="fcndef"> 16115bb6a25fSPoul-Henning Kamp<p>This function allows an application to provide an external subset 16125bb6a25fSPoul-Henning Kampfor the document type declaration for documents which do not specify 16135bb6a25fSPoul-Henning Kampan external subset of their own. For documents which specify an 16145bb6a25fSPoul-Henning Kampexternal subset in their DOCTYPE declaration, the application-provided 16155bb6a25fSPoul-Henning Kampsubset will be ignored. If the document does not contain a DOCTYPE 16165bb6a25fSPoul-Henning Kampdeclaration at all and <code>useDTD</code> is true, the 16175bb6a25fSPoul-Henning Kampapplication-provided subset will be parsed, but the 16185bb6a25fSPoul-Henning Kamp<code>startDoctypeDeclHandler</code> and 16195bb6a25fSPoul-Henning Kamp<code>endDoctypeDeclHandler</code> functions, if set, will not be 16205bb6a25fSPoul-Henning Kampcalled. The setting of parameter entity parsing, controlled using 16215bb6a25fSPoul-Henning Kamp<code><a href= "#XML_SetParamEntityParsing" 16225bb6a25fSPoul-Henning Kamp>XML_SetParamEntityParsing</a></code>, will be honored.</p> 16235bb6a25fSPoul-Henning Kamp 16245bb6a25fSPoul-Henning Kamp<p>The application-provided external subset is read by calling the 16255bb6a25fSPoul-Henning Kampexternal entity reference handler set via <code><a href= 16265bb6a25fSPoul-Henning Kamp"#XML_SetExternalEntityRefHandler" 16275bb6a25fSPoul-Henning Kamp>XML_SetExternalEntityRefHandler</a></code> with both 16285bb6a25fSPoul-Henning Kamp<code>publicId</code> and <code>systemId</code> set to NULL.</p> 16295bb6a25fSPoul-Henning Kamp 16305bb6a25fSPoul-Henning Kamp<p>If this function is called after parsing has begun, it returns 16315bb6a25fSPoul-Henning Kamp<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores 16325bb6a25fSPoul-Henning Kamp<code>useDTD</code>. If called when Expat has been compiled without 16335bb6a25fSPoul-Henning KampDTD support, it returns 16345bb6a25fSPoul-Henning Kamp<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise, it 16355bb6a25fSPoul-Henning Kampreturns <code>XML_ERROR_NONE</code>.</p> 16365bb6a25fSPoul-Henning Kamp</div> 16375bb6a25fSPoul-Henning Kamp 16385bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_SetReturnNSTriplet"> 16395bb6a25fSPoul-Henning Kampvoid 16405bb6a25fSPoul-Henning KampXML_SetReturnNSTriplet(XML_Parser parser, 16415bb6a25fSPoul-Henning Kamp int do_nst); 16425bb6a25fSPoul-Henning Kamp</pre> 16435bb6a25fSPoul-Henning Kamp<div class="fcndef"> 16445bb6a25fSPoul-Henning Kamp<p> 16455bb6a25fSPoul-Henning KampThis function only has an effect when using a parser created with 16465bb6a25fSPoul-Henning Kamp<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, 16475bb6a25fSPoul-Henning Kampi.e. when namespace processing is in effect. The <code>do_nst</code> 16485bb6a25fSPoul-Henning Kampsets whether or not prefixes are returned with names qualified with a 16495bb6a25fSPoul-Henning Kampnamespace prefix. If this function is called with <code>do_nst</code> 16505bb6a25fSPoul-Henning Kampnon-zero, then afterwards namespace qualified names (that is qualified 16515bb6a25fSPoul-Henning Kampwith a prefix as opposed to belonging to a default namespace) are 16525bb6a25fSPoul-Henning Kampreturned as a triplet with the three parts separated by the namespace 16535bb6a25fSPoul-Henning Kampseparator specified when the parser was created. The order of 16545bb6a25fSPoul-Henning Kampreturned parts is URI, local name, and prefix.</p> <p>If 16555bb6a25fSPoul-Henning Kamp<code>do_nst</code> is zero, then namespaces are reported in the 16565bb6a25fSPoul-Henning Kampdefault manner, URI then local_name separated by the namespace 16575bb6a25fSPoul-Henning Kampseparator.</p> 16585bb6a25fSPoul-Henning Kamp</div> 16595bb6a25fSPoul-Henning Kamp 16605bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_DefaultCurrent"> 16615bb6a25fSPoul-Henning Kampvoid 16625bb6a25fSPoul-Henning KampXML_DefaultCurrent(XML_Parser parser); 16635bb6a25fSPoul-Henning Kamp</pre> 16645bb6a25fSPoul-Henning Kamp<div class="fcndef"> 16655bb6a25fSPoul-Henning KampThis can be called within a handler for a start element, end element, 16665bb6a25fSPoul-Henning Kampprocessing instruction or character data. It causes the corresponding 16675bb6a25fSPoul-Henning Kampmarkup to be passed to the default handler set by <code><a 16685bb6a25fSPoul-Henning Kamphref="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or 16695bb6a25fSPoul-Henning Kamp<code><a href="#XML_SetDefaultHandlerExpand" 16705bb6a25fSPoul-Henning Kamp>XML_SetDefaultHandlerExpand</a></code>. It does nothing if there is 16715bb6a25fSPoul-Henning Kampnot a default handler. 16725bb6a25fSPoul-Henning Kamp</div> 16735bb6a25fSPoul-Henning Kamp 16745bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExpatVersion"> 16755bb6a25fSPoul-Henning KampXML_LChar * 16765bb6a25fSPoul-Henning KampXML_ExpatVersion(); 16775bb6a25fSPoul-Henning Kamp</pre> 16785bb6a25fSPoul-Henning Kamp<div class="fcndef"> 16795bb6a25fSPoul-Henning KampReturn the library version as a string (e.g. <code>"expat_1.95.1"</code>). 16805bb6a25fSPoul-Henning Kamp</div> 16815bb6a25fSPoul-Henning Kamp 16825bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_ExpatVersionInfo"> 16835bb6a25fSPoul-Henning Kampstruct XML_Expat_Version 16845bb6a25fSPoul-Henning KampXML_ExpatVersionInfo(); 16855bb6a25fSPoul-Henning Kamp</pre> 16865bb6a25fSPoul-Henning Kamp<pre class="signature"> 16875bb6a25fSPoul-Henning Kamptypedef struct { 16885bb6a25fSPoul-Henning Kamp int major; 16895bb6a25fSPoul-Henning Kamp int minor; 16905bb6a25fSPoul-Henning Kamp int micro; 16915bb6a25fSPoul-Henning Kamp} XML_Expat_Version; 16925bb6a25fSPoul-Henning Kamp</pre> 16935bb6a25fSPoul-Henning Kamp<div class="fcndef"> 16945bb6a25fSPoul-Henning KampReturn the library version information as a structure. 16955bb6a25fSPoul-Henning KampSome macros are also defined that support compile-time tests of the 16965bb6a25fSPoul-Henning Kamplibrary version: 16975bb6a25fSPoul-Henning Kamp<ul> 16985bb6a25fSPoul-Henning Kamp<li><code>XML_MAJOR_VERSION</code></li> 16995bb6a25fSPoul-Henning Kamp<li><code>XML_MINOR_VERSION</code></li> 17005bb6a25fSPoul-Henning Kamp<li><code>XML_MICRO_VERSION</code></li> 17015bb6a25fSPoul-Henning Kamp</ul> 17025bb6a25fSPoul-Henning KampTesting these constants is currently the best way to determine if 17035bb6a25fSPoul-Henning Kampparticular parts of the Expat API are available. 17045bb6a25fSPoul-Henning Kamp</div> 17055bb6a25fSPoul-Henning Kamp 17065bb6a25fSPoul-Henning Kamp<pre class="fcndec" id="XML_GetFeatureList"> 17075bb6a25fSPoul-Henning Kampconst XML_Feature * 17085bb6a25fSPoul-Henning KampXML_GetFeatureList(); 17095bb6a25fSPoul-Henning Kamp</pre> 17105bb6a25fSPoul-Henning Kamp<pre class="signature"> 17115bb6a25fSPoul-Henning Kampenum XML_FeatureEnum { 17125bb6a25fSPoul-Henning Kamp XML_FEATURE_END = 0, 17135bb6a25fSPoul-Henning Kamp XML_FEATURE_UNICODE, 17145bb6a25fSPoul-Henning Kamp XML_FEATURE_UNICODE_WCHAR_T, 17155bb6a25fSPoul-Henning Kamp XML_FEATURE_DTD, 17165bb6a25fSPoul-Henning Kamp XML_FEATURE_CONTEXT_BYTES, 17175bb6a25fSPoul-Henning Kamp XML_FEATURE_MIN_SIZE, 17185bb6a25fSPoul-Henning Kamp XML_FEATURE_SIZEOF_XML_CHAR, 17195bb6a25fSPoul-Henning Kamp XML_FEATURE_SIZEOF_XML_LCHAR 17205bb6a25fSPoul-Henning Kamp}; 17215bb6a25fSPoul-Henning Kamp 17225bb6a25fSPoul-Henning Kamptypedef struct { 17235bb6a25fSPoul-Henning Kamp enum XML_FeatureEnum feature; 17245bb6a25fSPoul-Henning Kamp XML_LChar *name; 17255bb6a25fSPoul-Henning Kamp long int value; 17265bb6a25fSPoul-Henning Kamp} XML_Feature; 17275bb6a25fSPoul-Henning Kamp</pre> 17285bb6a25fSPoul-Henning Kamp<div class="fcndef"> 17295bb6a25fSPoul-Henning Kamp<p>Returns a list of "feature" records, providing details on how 17305bb6a25fSPoul-Henning KampExpat was configured at compile time. Most applications should not 17315bb6a25fSPoul-Henning Kampneed to worry about this, but this information is otherwise not 17325bb6a25fSPoul-Henning Kampavailable from Expat. This function allows code that does need to 17335bb6a25fSPoul-Henning Kampcheck these features to do so at runtime.</p> 17345bb6a25fSPoul-Henning Kamp 17355bb6a25fSPoul-Henning Kamp<p>The return value is an array of <code>XML_Feature</code>, 17365bb6a25fSPoul-Henning Kampterminated by a record with a <code>feature</code> of 17375bb6a25fSPoul-Henning Kamp<code>XML_FEATURE_END</code> and <code>name</code> of NULL, 17385bb6a25fSPoul-Henning Kampidentifying the feature-test macros Expat was compiled with. Since an 17395bb6a25fSPoul-Henning Kampapplication that requires this kind of information needs to determine 17405bb6a25fSPoul-Henning Kampthe type of character the <code>name</code> points to, records for the 17415bb6a25fSPoul-Henning Kamp<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and 17425bb6a25fSPoul-Henning Kamp<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the 17435bb6a25fSPoul-Henning Kampbeginning of the list, followed by <code>XML_FEATURE_UNICODE</code> 17445bb6a25fSPoul-Henning Kampand <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at 17455bb6a25fSPoul-Henning Kampall.</p> 17465bb6a25fSPoul-Henning Kamp 17475bb6a25fSPoul-Henning Kamp<p>Some features have an associated value. If there isn't an 17485bb6a25fSPoul-Henning Kampassociated value, the <code>value</code> field is set to 0. At this 17495bb6a25fSPoul-Henning Kamptime, the following features have been defined to have values:</p> 17505bb6a25fSPoul-Henning Kamp 17515bb6a25fSPoul-Henning Kamp<dl> 17525bb6a25fSPoul-Henning Kamp <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt> 17535bb6a25fSPoul-Henning Kamp <dd>The number of bytes occupied by one <code>XML_Char</code> 17545bb6a25fSPoul-Henning Kamp character.</dd> 17555bb6a25fSPoul-Henning Kamp <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt> 17565bb6a25fSPoul-Henning Kamp <dd>The number of bytes occupied by one <code>XML_LChar</code> 17575bb6a25fSPoul-Henning Kamp character.</dd> 17585bb6a25fSPoul-Henning Kamp <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt> 17595bb6a25fSPoul-Henning Kamp <dd>The maximum number of characters of context which can be 17605bb6a25fSPoul-Henning Kamp reported by <code><a href= "#XML_GetInputContext" 17615bb6a25fSPoul-Henning Kamp >XML_GetInputContext</a></code>.</dd> 17625bb6a25fSPoul-Henning Kamp</dl> 17635bb6a25fSPoul-Henning Kamp</div> 17645bb6a25fSPoul-Henning Kamp 17655bb6a25fSPoul-Henning Kamp<hr /> 17665bb6a25fSPoul-Henning Kamp<p><a href="http://validator.w3.org/check/referer"><img 17675bb6a25fSPoul-Henning Kamp src="valid-xhtml10.png" alt="Valid XHTML 1.0!" 17685bb6a25fSPoul-Henning Kamp height="31" width="88" class="noborder" /></a></p> 17695bb6a25fSPoul-Henning Kamp</body> 17705bb6a25fSPoul-Henning Kamp</html> 1771
