11a3ddf8cSespie<?xml version="1.0" encoding="iso-8859-1"?> 21a3ddf8cSespie<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 31a3ddf8cSespie "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 41a3ddf8cSespie<html> 51a3ddf8cSespie<head> 608819b41Sbluhm<!-- 708819b41Sbluhm __ __ _ 808819b41Sbluhm ___\ \/ /_ __ __ _| |_ 908819b41Sbluhm / _ \\ /| '_ \ / _` | __| 1008819b41Sbluhm | __// \| |_) | (_| | |_ 1108819b41Sbluhm \___/_/\_\ .__/ \__,_|\__| 1208819b41Sbluhm |_| XML parser 1308819b41Sbluhm 1408819b41Sbluhm Copyright (c) 2000 Clark Cooper <coopercc@users.sourceforge.net> 1508819b41Sbluhm Copyright (c) 2000-2004 Fred L. Drake, Jr. <fdrake@users.sourceforge.net> 1608819b41Sbluhm Copyright (c) 2002-2012 Karl Waclawek <karl@waclawek.net> 17bd8f1dc3Sbluhm Copyright (c) 2017-2024 Sebastian Pipping <sebastian@pipping.org> 1808819b41Sbluhm Copyright (c) 2017 Jakub Wilk <jwilk@jwilk.net> 1908819b41Sbluhm Copyright (c) 2021 Tomas Korbar <tkorbar@redhat.com> 202c19dcf8Sbluhm Copyright (c) 2021 Nicolas Cavallari <nicolas.cavallari@green-communications.fr> 21680fbc60Sbluhm Copyright (c) 2022 Thijs Schreijer <thijs@thijsschreijer.nl> 22bd8f1dc3Sbluhm Copyright (c) 2023 Hanno Böck <hanno@gentoo.org> 23bd8f1dc3Sbluhm Copyright (c) 2023 Sony Corporation / Snild Dolkow <snild@sony.com> 2408819b41Sbluhm Licensed under the MIT license: 2508819b41Sbluhm 2608819b41Sbluhm Permission is hereby granted, free of charge, to any person obtaining 2708819b41Sbluhm a copy of this software and associated documentation files (the 2808819b41Sbluhm "Software"), to deal in the Software without restriction, including 2908819b41Sbluhm without limitation the rights to use, copy, modify, merge, publish, 3008819b41Sbluhm distribute, sublicense, and/or sell copies of the Software, and to permit 3108819b41Sbluhm persons to whom the Software is furnished to do so, subject to the 3208819b41Sbluhm following conditions: 3308819b41Sbluhm 3408819b41Sbluhm The above copyright notice and this permission notice shall be included 3508819b41Sbluhm in all copies or substantial portions of the Software. 3608819b41Sbluhm 3708819b41Sbluhm THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 3808819b41Sbluhm EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 3908819b41Sbluhm MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN 4008819b41Sbluhm NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, 4108819b41Sbluhm DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 4208819b41Sbluhm OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 4308819b41Sbluhm USE OR OTHER DEALINGS IN THE SOFTWARE. 4408819b41Sbluhm--> 451a3ddf8cSespie <title>Expat XML Parser</title> 461a3ddf8cSespie <meta name="author" content="Clark Cooper, coopercc@netheaven.com" /> 471a3ddf8cSespie <meta http-equiv="Content-Style-Type" content="text/css" /> 4808819b41Sbluhm <link href="ok.min.css" rel="stylesheet" type="text/css" /> 491a3ddf8cSespie <link href="style.css" rel="stylesheet" type="text/css" /> 501a3ddf8cSespie</head> 511a3ddf8cSespie<body> 5208819b41Sbluhm <div> 5308819b41Sbluhm <h1> 5408819b41Sbluhm The Expat XML Parser 55*aa071e6eSbluhm <small>Release 2.6.4</small> 5608819b41Sbluhm </h1> 5708819b41Sbluhm </div> 587d36914fSalek<div class="content"> 591a3ddf8cSespie 601a3ddf8cSespie<p>Expat is a library, written in C, for parsing XML documents. It's 611a3ddf8cSespiethe underlying XML parser for the open source Mozilla project, Perl's 621a3ddf8cSespie<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and 631a3ddf8cSespieother open-source XML parsers.</p> 641a3ddf8cSespie 651a3ddf8cSespie<p>This library is the creation of James Clark, who's also given us 662e724bc9Sbluhmgroff (an nroff look-alike), Jade (an implementation of ISO's DSSSL 671a3ddf8cSespiestylesheet language for SGML), XP (a Java XML parser package), XT (a 681a3ddf8cSespieJava XSL engine). James was also the technical lead on the XML 691a3ddf8cSespieWorking Group at W3C that produced the XML specification.</p> 701a3ddf8cSespie 711a3ddf8cSespie<p>This is free software, licensed under the <a 721a3ddf8cSespiehref="../COPYING">MIT/X Consortium license</a>. You may download it 73bd8f1dc3Sbluhmfrom <a href="https://libexpat.github.io/">the Expat home page</a>. 741a3ddf8cSespie</p> 751a3ddf8cSespie 767d36914fSalek<p>The bulk of this document was originally commissioned as an article 77bd8f1dc3Sbluhmby <a href="https://www.xml.com/">XML.com</a>. They graciously allowed 787d36914fSalekClark Cooper to retain copyright and to distribute it with Expat. 797d36914fSalekThis version has been substantially extended to include documentation 807d36914fSalekon features which have been added since the original article was 817d36914fSalekpublished, and additional information on using the original 827d36914fSalekinterface.</p> 831a3ddf8cSespie 841a3ddf8cSespie<hr /> 851a3ddf8cSespie<h2>Table of Contents</h2> 861a3ddf8cSespie<ul> 871a3ddf8cSespie <li><a href="#overview">Overview</a></li> 881a3ddf8cSespie <li><a href="#building">Building and Installing</a></li> 891a3ddf8cSespie <li><a href="#using">Using Expat</a></li> 901a3ddf8cSespie <li><a href="#reference">Reference</a> 911a3ddf8cSespie <ul> 921a3ddf8cSespie <li><a href="#creation">Parser Creation Functions</a> 931a3ddf8cSespie <ul> 941a3ddf8cSespie <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li> 951a3ddf8cSespie <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li> 961a3ddf8cSespie <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li> 971a3ddf8cSespie <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li> 981a3ddf8cSespie <li><a href="#XML_ParserFree">XML_ParserFree</a></li> 991a3ddf8cSespie <li><a href="#XML_ParserReset">XML_ParserReset</a></li> 1001a3ddf8cSespie </ul> 1011a3ddf8cSespie </li> 1021a3ddf8cSespie <li><a href="#parsing">Parsing Functions</a> 1031a3ddf8cSespie <ul> 1041a3ddf8cSespie <li><a href="#XML_Parse">XML_Parse</a></li> 1051a3ddf8cSespie <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li> 1061a3ddf8cSespie <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li> 1077d36914fSalek <li><a href="#XML_StopParser">XML_StopParser</a></li> 1087d36914fSalek <li><a href="#XML_ResumeParser">XML_ResumeParser</a></li> 1097d36914fSalek <li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li> 1101a3ddf8cSespie </ul> 1111a3ddf8cSespie </li> 1121a3ddf8cSespie <li><a href="#setting">Handler Setting Functions</a> 1131a3ddf8cSespie <ul> 1141a3ddf8cSespie <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li> 1151a3ddf8cSespie <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li> 1161a3ddf8cSespie <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li> 1171a3ddf8cSespie <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li> 1181a3ddf8cSespie <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li> 1191a3ddf8cSespie <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li> 1201a3ddf8cSespie <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li> 1211a3ddf8cSespie <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li> 1221a3ddf8cSespie <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li> 1231a3ddf8cSespie <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li> 1241a3ddf8cSespie <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li> 1251a3ddf8cSespie <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li> 1261a3ddf8cSespie <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li> 1271a3ddf8cSespie <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li> 1281a3ddf8cSespie <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li> 1291a3ddf8cSespie <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li> 1301a3ddf8cSespie <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li> 1311a3ddf8cSespie <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li> 1321a3ddf8cSespie <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li> 1331a3ddf8cSespie <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li> 1341a3ddf8cSespie <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li> 1351a3ddf8cSespie <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li> 1361a3ddf8cSespie <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li> 1371a3ddf8cSespie <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li> 1381a3ddf8cSespie <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li> 1391a3ddf8cSespie <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li> 1401a3ddf8cSespie <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li> 1411a3ddf8cSespie <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li> 1421a3ddf8cSespie </ul> 1431a3ddf8cSespie </li> 1441a3ddf8cSespie <li><a href="#position">Parse Position and Error Reporting Functions</a> 1451a3ddf8cSespie <ul> 1461a3ddf8cSespie <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li> 1471a3ddf8cSespie <li><a href="#XML_ErrorString">XML_ErrorString</a></li> 1481a3ddf8cSespie <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li> 1491a3ddf8cSespie <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li> 1501a3ddf8cSespie <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li> 1511a3ddf8cSespie <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li> 1521a3ddf8cSespie <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li> 1531a3ddf8cSespie </ul> 1541a3ddf8cSespie </li> 15508819b41Sbluhm <li> 156bd8f1dc3Sbluhm <a href="#attack-protection">Attack Protection</a> 15708819b41Sbluhm <ul> 15808819b41Sbluhm <li><a href="#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a></li> 15908819b41Sbluhm <li><a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a></li> 160bd8f1dc3Sbluhm <li><a href="#XML_SetReparseDeferralEnabled">XML_SetReparseDeferralEnabled</a></li> 16108819b41Sbluhm </ul> 16208819b41Sbluhm </li> 1631a3ddf8cSespie <li><a href="#miscellaneous">Miscellaneous Functions</a> 1641a3ddf8cSespie <ul> 1651a3ddf8cSespie <li><a href="#XML_SetUserData">XML_SetUserData</a></li> 1661a3ddf8cSespie <li><a href="#XML_GetUserData">XML_GetUserData</a></li> 1671a3ddf8cSespie <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li> 1681a3ddf8cSespie <li><a href="#XML_SetBase">XML_SetBase</a></li> 1691a3ddf8cSespie <li><a href="#XML_GetBase">XML_GetBase</a></li> 1701a3ddf8cSespie <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li> 1711a3ddf8cSespie <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li> 1726400bc34Srpointel <li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li> 1731a3ddf8cSespie <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li> 1741a3ddf8cSespie <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li> 1756400bc34Srpointel <li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li> 1761a3ddf8cSespie <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li> 1771a3ddf8cSespie <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li> 1781a3ddf8cSespie <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li> 1791a3ddf8cSespie <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li> 1801a3ddf8cSespie <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li> 1811a3ddf8cSespie <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li> 1821a3ddf8cSespie <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li> 1831a3ddf8cSespie <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li> 1841a3ddf8cSespie <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li> 1851a3ddf8cSespie <li><a href="#XML_MemFree">XML_MemFree</a></li> 1861a3ddf8cSespie </ul> 1871a3ddf8cSespie </li> 1881a3ddf8cSespie </ul> 1891a3ddf8cSespie </li> 1901a3ddf8cSespie</ul> 1911a3ddf8cSespie 1921a3ddf8cSespie<hr /> 1931a3ddf8cSespie<h2><a name="overview">Overview</a></h2> 1941a3ddf8cSespie 1951a3ddf8cSespie<p>Expat is a stream-oriented parser. You register callback (or 1961a3ddf8cSespiehandler) functions with the parser and then start feeding it the 1971a3ddf8cSespiedocument. As the parser recognizes parts of the document, it will 1981a3ddf8cSespiecall the appropriate handler for that part (if you've registered one.) 1991a3ddf8cSespieThe document is fed to the parser in pieces, so you can start parsing 2001a3ddf8cSespiebefore you have all the document. This also allows you to parse really 2011a3ddf8cSespiehuge documents that won't fit into memory.</p> 2021a3ddf8cSespie 2031a3ddf8cSespie<p>Expat can be intimidating due to the many kinds of handlers and 2041a3ddf8cSespieoptions you can set. But you only need to learn four functions in 2051a3ddf8cSespieorder to do 90% of what you'll want to do with it:</p> 2061a3ddf8cSespie 2071a3ddf8cSespie<dl> 2081a3ddf8cSespie 2091a3ddf8cSespie<dt><code><a href= "#XML_ParserCreate" 2101a3ddf8cSespie >XML_ParserCreate</a></code></dt> 2111a3ddf8cSespie <dd>Create a new parser object.</dd> 2121a3ddf8cSespie 2131a3ddf8cSespie<dt><code><a href= "#XML_SetElementHandler" 2141a3ddf8cSespie >XML_SetElementHandler</a></code></dt> 2151a3ddf8cSespie <dd>Set handlers for start and end tags.</dd> 2161a3ddf8cSespie 2171a3ddf8cSespie<dt><code><a href= "#XML_SetCharacterDataHandler" 2181a3ddf8cSespie >XML_SetCharacterDataHandler</a></code></dt> 2191a3ddf8cSespie <dd>Set handler for text.</dd> 2201a3ddf8cSespie 2211a3ddf8cSespie<dt><code><a href= "#XML_Parse" 2221a3ddf8cSespie >XML_Parse</a></code></dt> 2231a3ddf8cSespie <dd>Pass a buffer full of document to the parser</dd> 2241a3ddf8cSespie</dl> 2251a3ddf8cSespie 2261a3ddf8cSespie<p>These functions and others are described in the <a 2271a3ddf8cSespiehref="#reference">reference</a> part of this document. The reference 2281a3ddf8cSespiesection also describes in detail the parameters passed to the 2291a3ddf8cSespiedifferent types of handlers.</p> 2301a3ddf8cSespie 2311a3ddf8cSespie<p>Let's look at a very simple example program that only uses 3 of the 2321a3ddf8cSespieabove functions (it doesn't need to set a character handler.) The 2331a3ddf8cSespieprogram <a href="../examples/outline.c">outline.c</a> prints an 2341a3ddf8cSespieelement outline, indenting child elements to distinguish them from the 2351a3ddf8cSespieparent element that contains them. The start handler does all the 2361a3ddf8cSespiework. It prints two indenting spaces for every level of ancestor 2371a3ddf8cSespieelements, then it prints the element and attribute 2381a3ddf8cSespieinformation. Finally it increments the global <code>Depth</code> 2391a3ddf8cSespievariable.</p> 2401a3ddf8cSespie 2411a3ddf8cSespie<pre class="eg"> 2421a3ddf8cSespieint Depth; 2431a3ddf8cSespie 2447d36914fSalekvoid XMLCALL 2451a3ddf8cSespiestart(void *data, const char *el, const char **attr) { 2461a3ddf8cSespie int i; 2471a3ddf8cSespie 2481a3ddf8cSespie for (i = 0; i < Depth; i++) 2491a3ddf8cSespie printf(" "); 2501a3ddf8cSespie 2511a3ddf8cSespie printf("%s", el); 2521a3ddf8cSespie 2531a3ddf8cSespie for (i = 0; attr[i]; i += 2) { 2541a3ddf8cSespie printf(" %s='%s'", attr[i], attr[i + 1]); 2551a3ddf8cSespie } 2561a3ddf8cSespie 2571a3ddf8cSespie printf("\n"); 2581a3ddf8cSespie Depth++; 2591a3ddf8cSespie} /* End of start handler */ 2601a3ddf8cSespie</pre> 2611a3ddf8cSespie 2621a3ddf8cSespie<p>The end tag simply does the bookkeeping work of decrementing 2631a3ddf8cSespie<code>Depth</code>.</p> 2641a3ddf8cSespie<pre class="eg"> 2657d36914fSalekvoid XMLCALL 2661a3ddf8cSespieend(void *data, const char *el) { 2671a3ddf8cSespie Depth--; 2681a3ddf8cSespie} /* End of end handler */ 2691a3ddf8cSespie</pre> 2701a3ddf8cSespie 2717d36914fSalek<p>Note the <code>XMLCALL</code> annotation used for the callbacks. 2727d36914fSalekThis is used to ensure that the Expat and the callbacks are using the 2737d36914fSaleksame calling convention in case the compiler options used for Expat 2747d36914fSalekitself and the client code are different. Expat tries not to care 2757d36914fSalekwhat the default calling convention is, though it may require that it 2767d36914fSalekbe compiled with a default convention of "cdecl" on some platforms. 2777d36914fSalekFor code which uses Expat, however, the calling convention is 2787d36914fSalekspecified by the <code>XMLCALL</code> annotation on most platforms; 2797d36914fSalekcallbacks should be defined using this annotation.</p> 2807d36914fSalek 2817d36914fSalek<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but 2827d36914fSalekexisting working Expat applications don't need to add it (since they 2837d36914fSalekare already using the "cdecl" calling convention, or they wouldn't be 2847d36914fSalekworking). The annotation is only needed if the default calling 2857d36914fSalekconvention may be something other than "cdecl". To use the annotation 2867d36914fSaleksafely with older versions of Expat, you can conditionally define it 2877d36914fSalek<em>after</em> including Expat's header file:</p> 2887d36914fSalek 2897d36914fSalek<pre class="eg"> 2907d36914fSalek#include <expat.h> 2917d36914fSalek 2927d36914fSalek#ifndef XMLCALL 2937d36914fSalek#if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) && !defined(__CYGWIN__) 2947d36914fSalek#define XMLCALL __cdecl 2957d36914fSalek#elif defined(__GNUC__) 2967d36914fSalek#define XMLCALL __attribute__((cdecl)) 2977d36914fSalek#else 2987d36914fSalek#define XMLCALL 2997d36914fSalek#endif 3007d36914fSalek#endif 3017d36914fSalek</pre> 3027d36914fSalek 3031a3ddf8cSespie<p>After creating the parser, the main program just has the job of 3041a3ddf8cSespieshoveling the document to the parser so that it can do its work.</p> 3051a3ddf8cSespie 3061a3ddf8cSespie<hr /> 3071a3ddf8cSespie<h2><a name="building">Building and Installing Expat</a></h2> 3081a3ddf8cSespie 3091a3ddf8cSespie<p>The Expat distribution comes as a compressed (with GNU gzip) tar 3101a3ddf8cSespiefile. You may download the latest version from <a href= 311bd8f1dc3Sbluhm"https://sourceforge.net/projects/expat/" >Source Forge</a>. After 3121a3ddf8cSespieunpacking this, cd into the directory. Then follow either the Win32 3131a3ddf8cSespiedirections or Unix directions below.</p> 3141a3ddf8cSespie 3151a3ddf8cSespie<h3>Building under Win32</h3> 3161a3ddf8cSespie 3171a3ddf8cSespie<p>If you're using the GNU compiler under cygwin, follow the Unix 3181a3ddf8cSespiedirections in the next section. Otherwise if you have Microsoft's 31928ce3119SbluhmDeveloper Studio installed, 32028ce3119Sbluhmyou can use CMake to generate a <code>.sln</code> file, e.g. 32128ce3119Sbluhm<code> 32261ad8a07Sbluhmcmake -G"Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=RelWithDebInfo . 32328ce3119Sbluhm</code>, and build Expat using <code>msbuild /m expat.sln</code> after.</p> 3241a3ddf8cSespie 3251a3ddf8cSespie<p>Alternatively, you may download the Win32 binary package that 3261a3ddf8cSespiecontains the "expat.h" include file and a pre-built DLL.</p> 3271a3ddf8cSespie 3281a3ddf8cSespie<h3>Building under Unix (or GNU)</h3> 3291a3ddf8cSespie 3301a3ddf8cSespie<p>First you'll need to run the configure shell script in order to 3311a3ddf8cSespieconfigure the Makefiles and headers for your system.</p> 3321a3ddf8cSespie 3331a3ddf8cSespie<p>If you're happy with all the defaults that configure picks for you, 3341a3ddf8cSespieand you have permission on your system to install into /usr/local, you 3351a3ddf8cSespiecan install Expat with this sequence of commands:</p> 3361a3ddf8cSespie 3371a3ddf8cSespie<pre class="eg"> 3381a3ddf8cSespie./configure 3391a3ddf8cSespiemake 3401a3ddf8cSespiemake install 3411a3ddf8cSespie</pre> 3421a3ddf8cSespie 3431a3ddf8cSespie<p>There are some options that you can provide to this script, but the 3441a3ddf8cSespieonly one we'll mention here is the <code>--prefix</code> option. You 3451a3ddf8cSespiecan find out all the options available by running configure with just 3461a3ddf8cSespiethe <code>--help</code> option.</p> 3471a3ddf8cSespie 3481a3ddf8cSespie<p>By default, the configure script sets things up so that the library 3491a3ddf8cSespiegets installed in <code>/usr/local/lib</code> and the associated 3501a3ddf8cSespieheader file in <code>/usr/local/include</code>. But if you were to 3511a3ddf8cSespiegive the option, <code>--prefix=/home/me/mystuff</code>, then the 3521a3ddf8cSespielibrary and header would get installed in 3531a3ddf8cSespie<code>/home/me/mystuff/lib</code> and 3541a3ddf8cSespie<code>/home/me/mystuff/include</code> respectively.</p> 3551a3ddf8cSespie 3567d36914fSalek<h3>Configuring Expat Using the Pre-Processor</h3> 3577d36914fSalek 3587d36914fSalek<p>Expat's feature set can be configured using a small number of 359c033f770Sbluhmpre-processor definitions. The symbols are:</p> 3607d36914fSalek 3617d36914fSalek<dl class="cpp-symbols"> 362bd8f1dc3Sbluhm<dt><a name="XML_GE">XML_GE</a></dt> 363bd8f1dc3Sbluhm<dd> 364bd8f1dc3SbluhmAdded in Expat 2.6.0. 365bd8f1dc3SbluhmInclude support for 366bd8f1dc3Sbluhm<a href="https://www.w3.org/TR/2006/REC-xml-20060816/#sec-physical-struct">general entities</a> 367bd8f1dc3Sbluhm(syntax <code>&e1;</code> to reference and 368bd8f1dc3Sbluhmsyntax <code><!ENTITY e1 'value1'></code> (an internal general entity) or 369bd8f1dc3Sbluhm<code><!ENTITY e2 SYSTEM 'file2'></code> (an external general entity) to declare). 370bd8f1dc3SbluhmWith <code>XML_GE</code> enabled, general entities will be replaced by their declared replacement text; 371bd8f1dc3Sbluhmfor this to work for <em>external</em> general entities, in addition an 372bd8f1dc3Sbluhm<code><a href="#XML_SetExternalEntityRefHandler">XML_ExternalEntityRefHandler</a></code> must be set using 373bd8f1dc3Sbluhm<code><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></code>. 374bd8f1dc3SbluhmAlso, enabling <code>XML_GE</code> makes 375bd8f1dc3Sbluhmthe functions <code><a href="#XML_SetBillionLaughsAttackProtectionMaximumAmplification"> 376bd8f1dc3SbluhmXML_SetBillionLaughsAttackProtectionMaximumAmplification</a></code> and <code> 377bd8f1dc3Sbluhm<a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold"> 378bd8f1dc3SbluhmXML_SetBillionLaughsAttackProtectionActivationThreshold</a></code> available. 379bd8f1dc3Sbluhm<br/> 380bd8f1dc3SbluhmWith <code>XML_GE</code> disabled, Expat has a smaller memory footprint and can be faster, but will 381bd8f1dc3Sbluhmnot load external general entities and will replace all general entities 382bd8f1dc3Sbluhm(except the <a href="https://www.w3.org/TR/2006/REC-xml-20060816/#sec-predefined-ent">predefined five</a>: 383bd8f1dc3Sbluhm<code>amp</code>, <code>apos</code>, <code>gt</code>, <code>lt</code>, <code>quot</code>) 384bd8f1dc3Sbluhmwith a self-reference: 385bd8f1dc3Sbluhmfor example, referencing an entity <code>e1</code> via <code>&e1;</code> will be replaced 386bd8f1dc3Sbluhmby text <code>&e1;</code>. 387bd8f1dc3Sbluhm</dd> 388bd8f1dc3Sbluhm 389bd8f1dc3Sbluhm<dt><a name="XML_DTD">XML_DTD</a></dt> 3907d36914fSalek<dd>Include support for using and reporting DTD-based content. If 3917d36914fSalekthis is defined, default attribute values from an external DTD subset 3927d36914fSalekare reported and attribute value normalization occurs based on the 3937d36914fSalektype of attributes defined in the external subset. Without 3947d36914fSalekthis, Expat has a smaller memory footprint and can be faster, but will 395bd8f1dc3Sbluhmnot load external parameter entities or process conditional sections. If defined, makes 3969029d806Sbluhmthe functions <code><a 3979029d806Sbluhmhref="#XML_SetBillionLaughsAttackProtectionMaximumAmplification"> 3989029d806SbluhmXML_SetBillionLaughsAttackProtectionMaximumAmplification</a></code> and <code> 3999029d806Sbluhm<a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold"> 4009029d806SbluhmXML_SetBillionLaughsAttackProtectionActivationThreshold</a></code> available.</dd> 4017d36914fSalek 402bd8f1dc3Sbluhm<dt><a name="XML_NS">XML_NS</a></dt> 4037d36914fSalek<dd>When defined, support for the <cite><a href= 404bd8f1dc3Sbluhm"https://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite> 4057d36914fSalekspecification is included.</dd> 4067d36914fSalek 407bd8f1dc3Sbluhm<dt><a name="XML_UNICODE">XML_UNICODE</a></dt> 4087d36914fSalek<dd>When defined, character data reported to the application is 4097d36914fSalekencoded in UTF-16 using wide characters of the type 4107d36914fSalek<code>XML_Char</code>. This is implied if 4117d36914fSalek<code>XML_UNICODE_WCHAR_T</code> is defined.</dd> 4127d36914fSalek 413bd8f1dc3Sbluhm<dt><a name="XML_UNICODE_WCHAR_T">XML_UNICODE_WCHAR_T</a></dt> 4147d36914fSalek<dd>If defined, causes the <code>XML_Char</code> character type to be 4157d36914fSalekdefined using the <code>wchar_t</code> type; otherwise, <code>unsigned 4167d36914fSalekshort</code> is used. Defining this implies 4177d36914fSalek<code>XML_UNICODE</code>.</dd> 4187d36914fSalek 419bd8f1dc3Sbluhm<dt><a name="XML_LARGE_SIZE">XML_LARGE_SIZE</a></dt> 4207d36914fSalek<dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code> 4217d36914fSalekinteger types to be at least 64 bits in size. This is intended to support 4227d36914fSalekprocessing of very large input streams, where the return values of 4237d36914fSalek<code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>, 4247d36914fSalek<code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and 4257d36914fSalek<code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code> 4267d36914fSalekcould overflow. It may not be supported by all compilers, and is turned 4277d36914fSalekoff by default.</dd> 4287d36914fSalek 429bd8f1dc3Sbluhm<dt><a name="XML_CONTEXT_BYTES">XML_CONTEXT_BYTES</a></dt> 4307d36914fSalek<dd>The number of input bytes of markup context which the parser will 4317d36914fSalekensure are available for reporting via <code><a href= 4327d36914fSalek"#XML_GetInputContext" >XML_GetInputContext</a></code>. This is 433bd8f1dc3Sbluhmnormally set to 1024, and must be set to a positive integer to enable. 434bd8f1dc3SbluhmIf this is set to zero, the input context will not be available and <code><a 4357d36914fSalekhref= "#XML_GetInputContext" >XML_GetInputContext</a></code> will 436bd8f1dc3Sbluhmalways report <code>NULL</code>. Without this, Expat has a smaller memory 4377d36914fSalekfootprint and can be faster.</dd> 4387d36914fSalek 439bd8f1dc3Sbluhm<dt><a name="XML_STATIC">XML_STATIC</a></dt> 4407d36914fSalek<dd>On Windows, this should be set if Expat is going to be linked 4417d36914fSalekstatically with the code that calls it; this is required to get all 4427d36914fSalekthe right MSVC magic annotations correct. This is ignored on other 4437d36914fSalekplatforms.</dd> 4446400bc34Srpointel 445bd8f1dc3Sbluhm<dt><a name="XML_ATTR_INFO">XML_ATTR_INFO</a></dt> 4462e724bc9Sbluhm<dd>If defined, makes the additional function <code><a href= 4476400bc34Srpointel"#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available 4486400bc34Srpointelfor reporting attribute byte offsets.</dd> 4497d36914fSalek</dl> 4507d36914fSalek 4511a3ddf8cSespie<hr /> 4521a3ddf8cSespie<h2><a name="using">Using Expat</a></h2> 4531a3ddf8cSespie 4541a3ddf8cSespie<h3>Compiling and Linking Against Expat</h3> 4551a3ddf8cSespie 4561a3ddf8cSespie<p>Unless you installed Expat in a location not expected by your 4571a3ddf8cSespiecompiler and linker, all you have to do to use Expat in your programs 4581a3ddf8cSespieis to include the Expat header (<code>#include <expat.h></code>) 4591a3ddf8cSespiein your files that make calls to it and to tell the linker that it 4601a3ddf8cSespieneeds to link against the Expat library. On Unix systems, this would 4611a3ddf8cSespieusually be done with the <code>-lexpat</code> argument. Otherwise, 4621a3ddf8cSespieyou'll need to tell the compiler where to look for the Expat header 4631a3ddf8cSespieand the linker where to find the Expat library. You may also need to 464b26ab0f8Smatthieutake steps to tell the operating system where to find this library at 4651a3ddf8cSespierun time.</p> 4661a3ddf8cSespie 4671a3ddf8cSespie<p>On a Unix-based system, here's what a Makefile might look like when 4681a3ddf8cSespieExpat is installed in a standard location:</p> 4691a3ddf8cSespie 4701a3ddf8cSespie<pre class="eg"> 4711a3ddf8cSespieCC=cc 4721a3ddf8cSespieLDFLAGS= 4731a3ddf8cSespieLIBS= -lexpat 4741a3ddf8cSespiexmlapp: xmlapp.o 4751a3ddf8cSespie $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 4761a3ddf8cSespie</pre> 4771a3ddf8cSespie 4781a3ddf8cSespie<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then 4791a3ddf8cSespiethe Makefile would look like this:</p> 4801a3ddf8cSespie 4811a3ddf8cSespie<pre class="eg"> 4821a3ddf8cSespieCC=cc 4831a3ddf8cSespieCFLAGS= -I/home/me/mystuff/include 4841a3ddf8cSespieLDFLAGS= 4851a3ddf8cSespieLIBS= -L/home/me/mystuff/lib -lexpat 4861a3ddf8cSespiexmlapp: xmlapp.o 4871a3ddf8cSespie $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 4881a3ddf8cSespie</pre> 4891a3ddf8cSespie 4901a3ddf8cSespie<p>You'd also have to set the environment variable 4911a3ddf8cSespie<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or 4921a3ddf8cSespieto <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if 4931a3ddf8cSespieLD_LIBRARY_PATH already has some directories in it) in order to run 4941a3ddf8cSespieyour application.</p> 4951a3ddf8cSespie 4961a3ddf8cSespie<h3>Expat Basics</h3> 4971a3ddf8cSespie 4981a3ddf8cSespie<p>As we saw in the example in the overview, the first step in parsing 4991a3ddf8cSespiean XML document with Expat is to create a parser object. There are <a 5001a3ddf8cSespiehref="#creation">three functions</a> in the Expat API for creating a 5011a3ddf8cSespieparser object. However, only two of these (<code><a href= 5021a3ddf8cSespie"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href= 5031a3ddf8cSespie"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for 5041a3ddf8cSespieconstructing a parser for a top-level document. The object returned 5051a3ddf8cSespieby these functions is an opaque pointer (i.e. "expat.h" declares it as 5061a3ddf8cSespievoid *) to data with further internal structure. In order to free the 5071a3ddf8cSespiememory associated with this object you must call <code><a href= 5081a3ddf8cSespie"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have 5097d36914fSalekprovided any <a href="#userdata">user data</a> that gets stored in the 5101a3ddf8cSespieparser, then your application is responsible for freeing it prior to 5111a3ddf8cSespiecalling <code>XML_ParserFree</code>.</p> 5121a3ddf8cSespie 5131a3ddf8cSespie<p>The objects returned by the parser creation functions are good for 5141a3ddf8cSespieparsing only one XML document or external parsed entity. If your 5151a3ddf8cSespieapplication needs to parse many XML documents, then it needs to create 5161a3ddf8cSespiea parser object for each one. The best way to deal with this is to 5171a3ddf8cSespiecreate a higher level object that contains all the default 5181a3ddf8cSespieinitialization you want for your parser objects.</p> 5191a3ddf8cSespie 5201a3ddf8cSespie<p>Walking through a document hierarchy with a stream oriented parser 5211a3ddf8cSespiewill require a good stack mechanism in order to keep track of current 5221a3ddf8cSespiecontext. For instance, to answer the simple question, "What element 5231a3ddf8cSespiedoes this text belong to?" requires a stack, since the parser may have 5241a3ddf8cSespiedescended into other elements that are children of the current one and 5251a3ddf8cSespiehas encountered this text on the way out.</p> 5261a3ddf8cSespie 5271a3ddf8cSespie<p>The things you're likely to want to keep on a stack are the 5281a3ddf8cSespiecurrently opened element and it's attributes. You push this 5291a3ddf8cSespieinformation onto the stack in the start handler and you pop it off in 5301a3ddf8cSespiethe end handler.</p> 5311a3ddf8cSespie 5321a3ddf8cSespie<p>For some tasks, it is sufficient to just keep information on what 5331a3ddf8cSespiethe depth of the stack is (or would be if you had one.) The outline 5341a3ddf8cSespieprogram shown above presents one example. Another such task would be 5351a3ddf8cSespieskipping over a complete element. When you see the start tag for the 5361a3ddf8cSespieelement you want to skip, you set a skip flag and record the depth at 5371a3ddf8cSespiewhich the element started. When the end tag handler encounters the 5381a3ddf8cSespiesame depth, the skipped element has ended and the flag may be 5391a3ddf8cSespiecleared. If you follow the convention that the root element starts at 5401a3ddf8cSespie1, then you can use the same variable for skip flag and skip 5411a3ddf8cSespiedepth.</p> 5421a3ddf8cSespie 5431a3ddf8cSespie<pre class="eg"> 5441a3ddf8cSespievoid 5451a3ddf8cSespieinit_info(Parseinfo *info) { 5461a3ddf8cSespie info->skip = 0; 5471a3ddf8cSespie info->depth = 1; 5481a3ddf8cSespie /* Other initializations here */ 5491a3ddf8cSespie} /* End of init_info */ 5501a3ddf8cSespie 5517d36914fSalekvoid XMLCALL 5521a3ddf8cSespierawstart(void *data, const char *el, const char **attr) { 5531a3ddf8cSespie Parseinfo *inf = (Parseinfo *) data; 5541a3ddf8cSespie 5551a3ddf8cSespie if (! inf->skip) { 5561a3ddf8cSespie if (should_skip(inf, el, attr)) { 5571a3ddf8cSespie inf->skip = inf->depth; 5581a3ddf8cSespie } 5591a3ddf8cSespie else 5601a3ddf8cSespie start(inf, el, attr); /* This does rest of start handling */ 5611a3ddf8cSespie } 5621a3ddf8cSespie 5631a3ddf8cSespie inf->depth++; 5641a3ddf8cSespie} /* End of rawstart */ 5651a3ddf8cSespie 5667d36914fSalekvoid XMLCALL 5671a3ddf8cSespierawend(void *data, const char *el) { 5681a3ddf8cSespie Parseinfo *inf = (Parseinfo *) data; 5691a3ddf8cSespie 5701a3ddf8cSespie inf->depth--; 5711a3ddf8cSespie 5721a3ddf8cSespie if (! inf->skip) 5731a3ddf8cSespie end(inf, el); /* This does rest of end handling */ 5741a3ddf8cSespie 5751a3ddf8cSespie if (inf->skip == inf->depth) 5761a3ddf8cSespie inf->skip = 0; 5771a3ddf8cSespie} /* End rawend */ 5781a3ddf8cSespie</pre> 5791a3ddf8cSespie 5801a3ddf8cSespie<p>Notice in the above example the difference in how depth is 5811a3ddf8cSespiemanipulated in the start and end handlers. The end tag handler should 5821a3ddf8cSespiebe the mirror image of the start tag handler. This is necessary to 5831a3ddf8cSespieproperly model containment. Since, in the start tag handler, we 5841a3ddf8cSespieincremented depth <em>after</em> the main body of start tag code, then 5851a3ddf8cSespiein the end handler, we need to manipulate it <em>before</em> the main 5861a3ddf8cSespiebody. If we'd decided to increment it first thing in the start 5871a3ddf8cSespiehandler, then we'd have had to decrement it last thing in the end 5881a3ddf8cSespiehandler.</p> 5891a3ddf8cSespie 5901a3ddf8cSespie<h3 id="userdata">Communicating between handlers</h3> 5911a3ddf8cSespie 5921a3ddf8cSespie<p>In order to be able to pass information between different handlers 5931a3ddf8cSespiewithout using globals, you'll need to define a data structure to hold 5941a3ddf8cSespiethe shared variables. You can then tell Expat (with the <code><a href= 5951a3ddf8cSespie"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a 5967d36914fSalekpointer to this structure to the handlers. This is the first 5977d36914fSalekargument received by most handlers. In the <a href="#reference" 5987d36914fSalek>reference section</a>, an argument to a callback function is named 5997d36914fSalek<code>userData</code> and have type <code>void *</code> if the user 6007d36914fSalekdata is passed; it will have the type <code>XML_Parser</code> if the 6017d36914fSalekparser itself is passed. When the parser is passed, the user data may 6027d36914fSalekbe retrieved using <code><a href="#XML_GetUserData" 6037d36914fSalek>XML_GetUserData</a></code>.</p> 6047d36914fSalek 6057d36914fSalek<p>One common case where multiple calls to a single handler may need 6067d36914fSalekto communicate using an application data structure is the case when 6077d36914fSalekcontent passed to the character data handler (set by <code><a href= 6087d36914fSalek"#XML_SetCharacterDataHandler" 6097d36914fSalek>XML_SetCharacterDataHandler</a></code>) needs to be accumulated. A 6107d36914fSalekcommon first-time mistake with any of the event-oriented interfaces to 6117d36914fSalekan XML parser is to expect all the text contained in an element to be 6127d36914fSalekreported by a single call to the character data handler. Expat, like 6137d36914fSalekmany other XML parsers, reports such data as a sequence of calls; 6147d36914fSalekthere's no way to know when the end of the sequence is reached until a 6157d36914fSalekdifferent callback is made. A buffer referenced by the user data 6167d36914fSalekstructure proves both an effective and convenient place to accumulate 6177d36914fSalekcharacter data.</p> 6187d36914fSalek 6197d36914fSalek<!-- XXX example needed here --> 6207d36914fSalek 6211a3ddf8cSespie 6221a3ddf8cSespie<h3>XML Version</h3> 6231a3ddf8cSespie 6241a3ddf8cSespie<p>Expat is an XML 1.0 parser, and as such never complains based on 6251a3ddf8cSespiethe value of the <code>version</code> pseudo-attribute in the XML 6261a3ddf8cSespiedeclaration, if present.</p> 6271a3ddf8cSespie 6281a3ddf8cSespie<p>If an application needs to check the version number (to support 6291a3ddf8cSespiealternate processing), it should use the <code><a href= 6301a3ddf8cSespie"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to 6311a3ddf8cSespieset a handler that uses the information in the XML declaration to 6321a3ddf8cSespiedetermine what to do. This example shows how to check that only a 6331a3ddf8cSespieversion number of <code>"1.0"</code> is accepted:</p> 6341a3ddf8cSespie 6351a3ddf8cSespie<pre class="eg"> 6361a3ddf8cSespiestatic int wrong_version; 6371a3ddf8cSespiestatic XML_Parser parser; 6381a3ddf8cSespie 6397d36914fSalekstatic void XMLCALL 6401a3ddf8cSespiexmldecl_handler(void *userData, 6411a3ddf8cSespie const XML_Char *version, 6421a3ddf8cSespie const XML_Char *encoding, 6431a3ddf8cSespie int standalone) 6441a3ddf8cSespie{ 6451a3ddf8cSespie static const XML_Char Version_1_0[] = {'1', '.', '0', 0}; 6461a3ddf8cSespie 6471a3ddf8cSespie int i; 6481a3ddf8cSespie 6491a3ddf8cSespie for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) { 6501a3ddf8cSespie if (version[i] != Version_1_0[i]) { 6511a3ddf8cSespie wrong_version = 1; 6521a3ddf8cSespie /* also clear all other handlers: */ 6531a3ddf8cSespie XML_SetCharacterDataHandler(parser, NULL); 6541a3ddf8cSespie ... 6551a3ddf8cSespie return; 6561a3ddf8cSespie } 6571a3ddf8cSespie } 6581a3ddf8cSespie ... 6591a3ddf8cSespie} 6601a3ddf8cSespie</pre> 6611a3ddf8cSespie 6621a3ddf8cSespie<h3>Namespace Processing</h3> 6631a3ddf8cSespie 6641a3ddf8cSespie<p>When the parser is created using the <code><a href= 6651a3ddf8cSespie"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat 6661a3ddf8cSespieperforms namespace processing. Under namespace processing, Expat 6671a3ddf8cSespieconsumes <code>xmlns</code> and <code>xmlns:...</code> attributes, 6681a3ddf8cSespiewhich declare namespaces for the scope of the element in which they 6691a3ddf8cSespieoccur. This means that your start handler will not see these 6701a3ddf8cSespieattributes. Your application can still be informed of these 6711a3ddf8cSespiedeclarations by setting namespace declaration handlers with <a href= 6721a3ddf8cSespie"#XML_SetNamespaceDeclHandler" 6731a3ddf8cSespie><code>XML_SetNamespaceDeclHandler</code></a>.</p> 6741a3ddf8cSespie 6751a3ddf8cSespie<p>Element type and attribute names that belong to a given namespace 6761a3ddf8cSespieare passed to the appropriate handler in expanded form. By default 6771a3ddf8cSespiethis expanded form is a concatenation of the namespace URI, the 6781a3ddf8cSespieseparator character (which is the 2nd argument to <code><a href= 6791a3ddf8cSespie"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local 6801a3ddf8cSespiename (i.e. the part after the colon). Names with undeclared prefixes 6817d36914fSalekare not well-formed when namespace processing is enabled, and will 6827d36914fSalektrigger an error. Unprefixed attribute names are never expanded, 6831a3ddf8cSespieand unprefixed element names are only expanded when they are in the 6841a3ddf8cSespiescope of a default namespace.</p> 6851a3ddf8cSespie 6867d36914fSalek<p>However if <code><a href= "#XML_SetReturnNSTriplet" 6871a3ddf8cSespie>XML_SetReturnNSTriplet</a></code> has been called with a non-zero 6881a3ddf8cSespie<code>do_nst</code> parameter, then the expanded form for names with 6891a3ddf8cSespiean explicit prefix is a concatenation of: URI, separator, local name, 6901a3ddf8cSespieseparator, prefix.</p> 6911a3ddf8cSespie 6921a3ddf8cSespie<p>You can set handlers for the start of a namespace declaration and 6931a3ddf8cSespiefor the end of a scope of a declaration with the <code><a href= 6941a3ddf8cSespie"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code> 6951a3ddf8cSespiefunction. The StartNamespaceDeclHandler is called prior to the start 6967d36914fSalektag handler and the EndNamespaceDeclHandler is called after the 6971a3ddf8cSespiecorresponding end tag that ends the namespace's scope. The namespace 6981a3ddf8cSespiestart handler gets passed the prefix and URI for the namespace. For a 699bd8f1dc3Sbluhmdefault namespace declaration (xmlns='...'), the prefix will be 700bd8f1dc3Sbluhm<code>NULL</code>. 701bd8f1dc3SbluhmThe URI will be <code>NULL</code> for the case where the default namespace is being 7021a3ddf8cSespieunset. The namespace end handler just gets the prefix for the closing 7031a3ddf8cSespiescope.</p> 7041a3ddf8cSespie 7051a3ddf8cSespie<p>These handlers are called for each declaration. So if, for 7061a3ddf8cSespieinstance, a start tag had three namespace declarations, then the 7071a3ddf8cSespieStartNamespaceDeclHandler would be called three times before the start 7081a3ddf8cSespietag handler is called, once for each declaration.</p> 7091a3ddf8cSespie 7101a3ddf8cSespie<h3>Character Encodings</h3> 7111a3ddf8cSespie 7121a3ddf8cSespie<p>While XML is based on Unicode, and every XML processor is required 7131a3ddf8cSespieto recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), 7141a3ddf8cSespieother encodings may be declared in XML documents or entities. For the 7151a3ddf8cSespiemain document, an XML declaration may contain an encoding 7161a3ddf8cSespiedeclaration:</p> 7171a3ddf8cSespie<pre> 7181a3ddf8cSespie<?xml version="1.0" encoding="ISO-8859-2"?> 7191a3ddf8cSespie</pre> 7201a3ddf8cSespie 7211a3ddf8cSespie<p>External parsed entities may begin with a text declaration, which 7221a3ddf8cSespielooks like an XML declaration with just an encoding declaration:</p> 7231a3ddf8cSespie<pre> 7241a3ddf8cSespie<?xml encoding="Big5"?> 7251a3ddf8cSespie</pre> 7261a3ddf8cSespie 7271a3ddf8cSespie<p>With Expat, you may also specify an encoding at the time of 7281a3ddf8cSespiecreating a parser. This is useful when the encoding information may 7291a3ddf8cSespiecome from a source outside the document itself (like a higher level 7301a3ddf8cSespieprotocol.)</p> 7311a3ddf8cSespie 7321a3ddf8cSespie<p><a name="builtin_encodings"></a>There are four built-in encodings 7331a3ddf8cSespiein Expat:</p> 7341a3ddf8cSespie<ul> 7351a3ddf8cSespie<li>UTF-8</li> 7361a3ddf8cSespie<li>UTF-16</li> 7371a3ddf8cSespie<li>ISO-8859-1</li> 7381a3ddf8cSespie<li>US-ASCII</li> 7391a3ddf8cSespie</ul> 7401a3ddf8cSespie 7411a3ddf8cSespie<p>Anything else discovered in an encoding declaration or in the 7421a3ddf8cSespieprotocol encoding specified in the parser constructor, triggers a call 7431a3ddf8cSespieto the <code>UnknownEncodingHandler</code>. This handler gets passed 7441a3ddf8cSespiethe encoding name and a pointer to an <code>XML_Encoding</code> data 7451a3ddf8cSespiestructure. Your handler must fill in this structure and return 7461a3ddf8cSespie<code>XML_STATUS_OK</code> if it knows how to deal with the 7471a3ddf8cSespieencoding. Otherwise the handler should return 7481a3ddf8cSespie<code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer 7491a3ddf8cSespieto an optional application data structure that you may indicate when 7501a3ddf8cSespieyou set the handler.</p> 7511a3ddf8cSespie 7521a3ddf8cSespie<p>Expat places restrictions on character encodings that it can 7531a3ddf8cSespiesupport by filling in the <code>XML_Encoding</code> structure. 7541a3ddf8cSespieinclude file:</p> 7551a3ddf8cSespie<ol> 7561a3ddf8cSespie<li>Every ASCII character that can appear in a well-formed XML document 7571a3ddf8cSespiemust be represented by a single byte, and that byte must correspond to 7581a3ddf8cSespieit's ASCII encoding (except for the characters $@\^'{}~)</li> 7591a3ddf8cSespie<li>Characters must be encoded in 4 bytes or less.</li> 7601a3ddf8cSespie<li>All characters encoded must have Unicode scalar values less than or 7611a3ddf8cSespieequal to 65535 (0xFFFF)<em>This does not apply to the built-in support 7621a3ddf8cSespiefor UTF-16 and UTF-8</em></li> 7631a3ddf8cSespie<li>No character may be encoded by more that one distinct sequence of 7641a3ddf8cSespiebytes</li> 7651a3ddf8cSespie</ol> 7661a3ddf8cSespie 7671a3ddf8cSespie<p><code>XML_Encoding</code> contains an array of integers that 7681a3ddf8cSespiecorrespond to the 1st byte of an encoding sequence. If the value in 7691a3ddf8cSespiethe array for a byte is zero or positive, then the byte is a single 7701a3ddf8cSespiebyte encoding that encodes the Unicode scalar value contained in the 7711a3ddf8cSespiearray. A -1 in this array indicates a malformed byte. If the value is 7721a3ddf8cSespie-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte 7731a3ddf8cSespiesequence respectively. Multi-byte sequences are sent to the convert 7741a3ddf8cSespiefunction pointed at in the <code>XML_Encoding</code> structure. This 7751a3ddf8cSespiefunction should return the Unicode scalar value for the sequence or -1 7761a3ddf8cSespieif the sequence is malformed.</p> 7771a3ddf8cSespie 7781a3ddf8cSespie<p>One pitfall that novice Expat users are likely to fall into is that 7791a3ddf8cSespiealthough Expat may accept input in various encodings, the strings that 7801a3ddf8cSespieit passes to the handlers are always encoded in UTF-8 or UTF-16 7811a3ddf8cSespie(depending on how Expat was compiled). Your application is responsible 7821a3ddf8cSespiefor any translation of these strings into other encodings.</p> 7831a3ddf8cSespie 7841a3ddf8cSespie<h3>Handling External Entity References</h3> 7851a3ddf8cSespie 7861a3ddf8cSespie<p>Expat does not read or parse external entities directly. Note that 7871a3ddf8cSespieany external DTD is a special case of an external entity. If you've 7881a3ddf8cSespieset no <code>ExternalEntityRefHandler</code>, then external entity 7891a3ddf8cSespiereferences are silently ignored. Otherwise, it calls your handler with 7901a3ddf8cSespiethe information needed to read and parse the external entity.</p> 7911a3ddf8cSespie 7921a3ddf8cSespie<p>Your handler isn't actually responsible for parsing the entity, but 7931a3ddf8cSespieit is responsible for creating a subsidiary parser with <code><a href= 7941a3ddf8cSespie"#XML_ExternalEntityParserCreate" 7951a3ddf8cSespie>XML_ExternalEntityParserCreate</a></code> that will do the job. This 7961a3ddf8cSespiereturns an instance of <code>XML_Parser</code> that has handlers and 7971a3ddf8cSespieother data structures initialized from the parent parser. You may then 7981a3ddf8cSespieuse <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a 7991a3ddf8cSespiehref= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this 8001a3ddf8cSespieparser. Since external entities my refer to other external entities, 8011a3ddf8cSespieyour handler should be prepared to be called recursively.</p> 8021a3ddf8cSespie 8031a3ddf8cSespie<h3>Parsing DTDs</h3> 8041a3ddf8cSespie 8051a3ddf8cSespie<p>In order to parse parameter entities, before starting the parse, 8061a3ddf8cSespieyou must call <code><a href= "#XML_SetParamEntityParsing" 8071a3ddf8cSespie>XML_SetParamEntityParsing</a></code> with one of the following 8081a3ddf8cSespiearguments:</p> 8091a3ddf8cSespie<dl> 8101a3ddf8cSespie<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt> 8111a3ddf8cSespie<dd>Don't parse parameter entities or the external subset</dd> 8121a3ddf8cSespie<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt> 8132e724bc9Sbluhm<dd>Parse parameter entities and the external subset unless 8141a3ddf8cSespie<code>standalone</code> was set to "yes" in the XML declaration.</dd> 8151a3ddf8cSespie<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt> 8161a3ddf8cSespie<dd>Always parse parameter entities and the external subset</dd> 8171a3ddf8cSespie</dl> 8181a3ddf8cSespie 8191a3ddf8cSespie<p>In order to read an external DTD, you also have to set an external 8201a3ddf8cSespieentity reference handler as described above.</p> 8211a3ddf8cSespie 8227d36914fSalek<h3 id="stop-resume">Temporarily Stopping Parsing</h3> 8237d36914fSalek 8247d36914fSalek<p>Expat 1.95.8 introduces a new feature: its now possible to stop 8257d36914fSalekparsing temporarily from within a handler function, even if more data 8267d36914fSalekhas already been passed into the parser. Applications for this 8277d36914fSalekinclude</p> 8287d36914fSalek 8297d36914fSalek<ul> 830bd8f1dc3Sbluhm <li>Supporting the <a href= "https://www.w3.org/TR/xinclude/" 8317d36914fSalek >XInclude</a> specification.</li> 8327d36914fSalek 8337d36914fSalek <li>Delaying further processing until additional information is 8347d36914fSalek available from some other source.</li> 8357d36914fSalek 8367d36914fSalek <li>Adjusting processor load as task priorities shift within an 8377d36914fSalek application.</li> 8387d36914fSalek 8397d36914fSalek <li>Stopping parsing completely (simply free or reset the parser 8407d36914fSalek instead of resuming in the outer parsing loop). This can be useful 8412e724bc9Sbluhm if an application-domain error is found in the XML being parsed or if 8427d36914fSalek the result of the parse is determined not to be useful after 8437d36914fSalek all.</li> 8447d36914fSalek</ul> 8457d36914fSalek 8467d36914fSalek<p>To take advantage of this feature, the main parsing loop of an 8477d36914fSalekapplication needs to support this specifically. It cannot be 8487d36914fSaleksupported with a parsing loop compatible with Expat 1.95.7 or 8497d36914fSalekearlier (though existing loops will continue to work without 8507d36914fSaleksupporting the stop/resume feature).</p> 8517d36914fSalek 8527d36914fSalek<p>An application that uses this feature for a single parser will have 8537d36914fSalekthe rough structure (in pseudo-code):</p> 8547d36914fSalek 8557d36914fSalek<pre class="pseudocode"> 8567d36914fSalekfd = open_input() 8577d36914fSalekp = create_parser() 8587d36914fSalek 8597d36914fSalekif parse_xml(p, fd) { 8607d36914fSalek /* suspended */ 8617d36914fSalek 8627d36914fSalek int suspended = 1; 8637d36914fSalek 8647d36914fSalek while (suspended) { 8657d36914fSalek do_something_else() 8667d36914fSalek if ready_to_resume() { 8677d36914fSalek suspended = continue_parsing(p, fd); 8687d36914fSalek } 8697d36914fSalek } 8707d36914fSalek} 8717d36914fSalek</pre> 8727d36914fSalek 8737d36914fSalek<p>An application that may resume any of several parsers based on 8747d36914fSalekinput (either from the XML being parsed or some other source) will 8757d36914fSalekcertainly have more interesting control structures.</p> 8767d36914fSalek 8777d36914fSalek<p>This C function could be used for the <code>parse_xml</code> 8787d36914fSalekfunction mentioned in the pseudo-code above:</p> 8797d36914fSalek 8807d36914fSalek<pre class="eg"> 8817d36914fSalek#define BUFF_SIZE 10240 8827d36914fSalek 8837d36914fSalek/* Parse a document from the open file descriptor 'fd' until the parse 8847d36914fSalek is complete (the document has been completely parsed, or there's 8857d36914fSalek been an error), or the parse is stopped. Return non-zero when 8867d36914fSalek the parse is merely suspended. 8877d36914fSalek*/ 8887d36914fSalekint 8897d36914fSalekparse_xml(XML_Parser p, int fd) 8907d36914fSalek{ 8917d36914fSalek for (;;) { 8927d36914fSalek int last_chunk; 8937d36914fSalek int bytes_read; 8947d36914fSalek enum XML_Status status; 8957d36914fSalek 8967d36914fSalek void *buff = XML_GetBuffer(p, BUFF_SIZE); 8977d36914fSalek if (buff == NULL) { 8987d36914fSalek /* handle error... */ 8997d36914fSalek return 0; 9007d36914fSalek } 9017d36914fSalek bytes_read = read(fd, buff, BUFF_SIZE); 9027d36914fSalek if (bytes_read < 0) { 9037d36914fSalek /* handle error... */ 9047d36914fSalek return 0; 9057d36914fSalek } 9067d36914fSalek status = XML_ParseBuffer(p, bytes_read, bytes_read == 0); 9077d36914fSalek switch (status) { 9087d36914fSalek case XML_STATUS_ERROR: 9097d36914fSalek /* handle error... */ 9107d36914fSalek return 0; 9117d36914fSalek case XML_STATUS_SUSPENDED: 9127d36914fSalek return 1; 9137d36914fSalek } 9147d36914fSalek if (bytes_read == 0) 9157d36914fSalek return 0; 9167d36914fSalek } 9177d36914fSalek} 9187d36914fSalek</pre> 9197d36914fSalek 9207d36914fSalek<p>The corresponding <code>continue_parsing</code> function is 9217d36914fSaleksomewhat simpler, since it only need deal with the return code from 9227d36914fSalek<code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can 9237d36914fSalekdelegate the input handling to the <code>parse_xml</code> 9247d36914fSalekfunction:</p> 9257d36914fSalek 9267d36914fSalek<pre class="eg"> 9277d36914fSalek/* Continue parsing a document which had been suspended. The 'p' and 9287d36914fSalek 'fd' arguments are the same as passed to parse_xml(). Return 9297d36914fSalek non-zero when the parse is suspended. 9307d36914fSalek*/ 9317d36914fSalekint 9327d36914fSalekcontinue_parsing(XML_Parser p, int fd) 9337d36914fSalek{ 9347d36914fSalek enum XML_Status status = XML_ResumeParser(p); 9357d36914fSalek switch (status) { 9367d36914fSalek case XML_STATUS_ERROR: 9377d36914fSalek /* handle error... */ 9387d36914fSalek return 0; 9397d36914fSalek case XML_ERROR_NOT_SUSPENDED: 9407d36914fSalek /* handle error... */ 9417d36914fSalek return 0;. 9427d36914fSalek case XML_STATUS_SUSPENDED: 9437d36914fSalek return 1; 9447d36914fSalek } 9457d36914fSalek return parse_xml(p, fd); 9467d36914fSalek} 9477d36914fSalek</pre> 9487d36914fSalek 9497d36914fSalek<p>Now that we've seen what a mess the top-level parsing loop can 9507d36914fSalekbecome, what have we gained? Very simply, we can now use the <code><a 9517d36914fSalekhref= "#XML_StopParser" >XML_StopParser</a></code> function to stop 9527d36914fSalekparsing, without having to go to great lengths to avoid additional 9537d36914fSalekprocessing that we're expecting to ignore. As a bonus, we get to stop 9547d36914fSalekparsing <em>temporarily</em>, and come back to it when we're 9557d36914fSalekready.</p> 9567d36914fSalek 9577d36914fSalek<p>To stop parsing from a handler function, use the <code><a href= 9587d36914fSalek"#XML_StopParser" >XML_StopParser</a></code> function. This function 9597d36914fSalektakes two arguments; the parser being stopped and a flag indicating 9607d36914fSalekwhether the parse can be resumed in the future.</p> 9617d36914fSalek 9627d36914fSalek<!-- XXX really need more here --> 9637d36914fSalek 9647d36914fSalek 9651a3ddf8cSespie<hr /> 9661a3ddf8cSespie<!-- ================================================================ --> 9671a3ddf8cSespie 9681a3ddf8cSespie<h2><a name="reference">Expat Reference</a></h2> 9691a3ddf8cSespie 9701a3ddf8cSespie<h3><a name="creation">Parser Creation</a></h3> 9711a3ddf8cSespie 97208819b41Sbluhm<h4 id="XML_ParserCreate">XML_ParserCreate</h4> 97308819b41Sbluhm<pre class="fcndec"> 9747d36914fSalekXML_Parser XMLCALL 9751a3ddf8cSespieXML_ParserCreate(const XML_Char *encoding); 9761a3ddf8cSespie</pre> 9771a3ddf8cSespie<div class="fcndef"> 978bd8f1dc3Sbluhm<p> 979bd8f1dc3SbluhmConstruct a new parser. If encoding is non-<code>NULL</code>, it specifies a 9801a3ddf8cSespiecharacter encoding to use for the document. This overrides the document 9811a3ddf8cSespieencoding declaration. There are four built-in encodings: 982bd8f1dc3Sbluhm</p> 9831a3ddf8cSespie<ul> 9841a3ddf8cSespie<li>US-ASCII</li> 9851a3ddf8cSespie<li>UTF-8</li> 9861a3ddf8cSespie<li>UTF-16</li> 9871a3ddf8cSespie<li>ISO-8859-1</li> 9881a3ddf8cSespie</ul> 989bd8f1dc3Sbluhm<p> 9901a3ddf8cSespieAny other value will invoke a call to the UnknownEncodingHandler. 991bd8f1dc3Sbluhm</p> 9921a3ddf8cSespie</div> 9931a3ddf8cSespie 99408819b41Sbluhm<h4 id="XML_ParserCreateNS">XML_ParserCreateNS</h4> 99508819b41Sbluhm<pre class="fcndec"> 9967d36914fSalekXML_Parser XMLCALL 9971a3ddf8cSespieXML_ParserCreateNS(const XML_Char *encoding, 9981a3ddf8cSespie XML_Char sep); 9991a3ddf8cSespie</pre> 10001a3ddf8cSespie<div class="fcndef"> 10011a3ddf8cSespieConstructs a new parser that has namespace processing in effect. Namespace 10021a3ddf8cSespieexpanded element names and attribute names are returned as a concatenation 10031a3ddf8cSespieof the namespace URI, <em>sep</em>, and the local part of the name. This 10040ad1cb5aSericmeans that you should pick a character for <em>sep</em> that can't be part 10050ad1cb5aSericof an URI. Since Expat does not check namespace URIs for conformance, the 10060ad1cb5aSericonly safe choice for a namespace separator is a character that is illegal 10070ad1cb5aSericin XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and 10080ad1cb5aSeric<code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when 10090ad1cb5aSeric<em>sep</em> is the null character <code>'\0'</code>: the namespace URI and 10100ad1cb5aSericthe local part will be concatenated without any separator - this is intended 10110ad1cb5aSericto support RDF processors. It is a programming error to use the null separator 10120ad1cb5aSericwith <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div> 10131a3ddf8cSespie 1014680fbc60Sbluhm<p><strong>Note:</strong> 1015680fbc60SbluhmExpat does not validate namespace URIs (beyond encoding) 1016680fbc60Sbluhmagainst RFC 3986 today (and is not required to do so with regard to 1017680fbc60Sbluhmthe XML 1.0 namespaces specification) but it may start doing that 1018680fbc60Sbluhmin future releases. Before that, an application using Expat must 1019680fbc60Sbluhmbe ready to receive namespace URIs containing non-URI characters. 1020680fbc60Sbluhm</p> 1021680fbc60Sbluhm 102208819b41Sbluhm<h4 id="XML_ParserCreate_MM">XML_ParserCreate_MM</h4> 102308819b41Sbluhm<pre class="fcndec"> 10247d36914fSalekXML_Parser XMLCALL 10251a3ddf8cSespieXML_ParserCreate_MM(const XML_Char *encoding, 10261a3ddf8cSespie const XML_Memory_Handling_Suite *ms, 10271a3ddf8cSespie const XML_Char *sep); 10281a3ddf8cSespie</pre> 10291a3ddf8cSespie<pre class="signature"> 10301a3ddf8cSespietypedef struct { 10317d36914fSalek void *(XMLCALL *malloc_fcn)(size_t size); 10327d36914fSalek void *(XMLCALL *realloc_fcn)(void *ptr, size_t size); 10337d36914fSalek void (XMLCALL *free_fcn)(void *ptr); 10341a3ddf8cSespie} XML_Memory_Handling_Suite; 10351a3ddf8cSespie</pre> 10361a3ddf8cSespie<div class="fcndef"> 10371a3ddf8cSespie<p>Construct a new parser using the suite of memory handling functions 1038bd8f1dc3Sbluhmspecified in <code>ms</code>. If <code>ms</code> is <code>NULL</code>, then use the 10391a3ddf8cSespiestandard set of memory management functions. If <code>sep</code> is 1040bd8f1dc3Sbluhmnon-<code>NULL</code>, then namespace processing is enabled in the created parser 10411a3ddf8cSespieand the character pointed at by sep is used as the separator between 10421a3ddf8cSespiethe namespace URI and the local part of the name.</p> 10431a3ddf8cSespie</div> 10441a3ddf8cSespie 104508819b41Sbluhm<h4 id="XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</h4> 104608819b41Sbluhm<pre class="fcndec"> 10477d36914fSalekXML_Parser XMLCALL 10481a3ddf8cSespieXML_ExternalEntityParserCreate(XML_Parser p, 10491a3ddf8cSespie const XML_Char *context, 10501a3ddf8cSespie const XML_Char *encoding); 10511a3ddf8cSespie</pre> 10521a3ddf8cSespie<div class="fcndef"> 10531a3ddf8cSespieConstruct a new <code>XML_Parser</code> object for parsing an external 10541a3ddf8cSespiegeneral entity. Context is the context argument passed in a call to a 10551a3ddf8cSespieExternalEntityRefHandler. Other state information such as handlers, 10561a3ddf8cSespieuser data, namespace processing is inherited from the parser passed as 10571a3ddf8cSespiethe 1st argument. So you shouldn't need to call any of the behavior 10581a3ddf8cSespiechanging functions on this parser (unless you want it to act 10591a3ddf8cSespiedifferently than the parent parser). 10601a3ddf8cSespie</div> 10611a3ddf8cSespie 106208819b41Sbluhm<h4 id="XML_ParserFree">XML_ParserFree</h4> 106308819b41Sbluhm<pre class="fcndec"> 10647d36914fSalekvoid XMLCALL 10651a3ddf8cSespieXML_ParserFree(XML_Parser p); 10661a3ddf8cSespie</pre> 10671a3ddf8cSespie<div class="fcndef"> 10681a3ddf8cSespieFree memory used by the parser. Your application is responsible for 10691a3ddf8cSespiefreeing any memory associated with <a href="#userdata">user data</a>. 10701a3ddf8cSespie</div> 10711a3ddf8cSespie 107208819b41Sbluhm<h4 id="XML_ParserReset">XML_ParserReset</h4> 107308819b41Sbluhm<pre class="fcndec"> 10747d36914fSalekXML_Bool XMLCALL 10757d36914fSalekXML_ParserReset(XML_Parser p, 10767d36914fSalek const XML_Char *encoding); 10771a3ddf8cSespie</pre> 10781a3ddf8cSespie<div class="fcndef"> 10791a3ddf8cSespieClean up the memory structures maintained by the parser so that it may 10801a3ddf8cSespiebe used again. After this has been called, <code>parser</code> is 10817d36914fSalekready to start parsing a new document. All handlers are cleared from 10827d36914fSalekthe parser, except for the unknownEncodingHandler. The parser's external 10837d36914fSalekstate is re-initialized except for the values of ns and ns_triplets. 10847d36914fSalekThis function may not be used on a parser created using <code><a href= 10851a3ddf8cSespie"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a 10861a3ddf8cSespie></code>; it will return <code>XML_FALSE</code> in that case. Returns 10871a3ddf8cSespie<code>XML_TRUE</code> on success. Your application is responsible for 10881a3ddf8cSespiedealing with any memory associated with <a href="#userdata">user data</a>. 10891a3ddf8cSespie</div> 10901a3ddf8cSespie 10911a3ddf8cSespie<h3><a name="parsing">Parsing</a></h3> 10921a3ddf8cSespie 10931a3ddf8cSespie<p>To state the obvious: the three parsing functions <code><a href= 10947d36914fSalek"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer"> 10957d36914fSalekXML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer"> 10967d36914fSalekXML_GetBuffer</a></code> must not be called from within a handler 10977d36914fSalekunless they operate on a separate parser instance, that is, one that 10987d36914fSalekdid not call the handler. For example, it is OK to call the parsing 10997d36914fSalekfunctions from within an <code>XML_ExternalEntityRefHandler</code>, 11007d36914fSalekif they apply to the parser created by 11017d36914fSalek<code><a href= "#XML_ExternalEntityParserCreate" 11021a3ddf8cSespie>XML_ExternalEntityParserCreate</a></code>.</p> 11031a3ddf8cSespie 110408819b41Sbluhm<p>Note: The <code>len</code> argument passed to these functions 11057d36914fSalekshould be considerably less than the maximum value for an integer, 11067d36914fSalekas it could create an integer overflow situation if the added 11077d36914fSaleklengths of a buffer and the unprocessed portion of the previous buffer 11087d36914fSalekexceed the maximum integer value. Input data at the end of a buffer 11097d36914fSalekwill remain unprocessed if it is part of an XML token for which the 11107d36914fSalekend is not part of that buffer.</p> 11117d36914fSalek 1112bd8f1dc3Sbluhm<p><a name="isFinal"></a>The application <em>must</em> make a concluding 1113bd8f1dc3Sbluhm<code><a href="#XML_Parse">XML_Parse</a></code> or 1114bd8f1dc3Sbluhm<code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> call 1115bd8f1dc3Sbluhmwith <code>isFinal</code> set to <code>XML_TRUE</code>.</p> 1116bd8f1dc3Sbluhm 111708819b41Sbluhm<h4 id="XML_Parse">XML_Parse</h4> 111808819b41Sbluhm<pre class="fcndec"> 11197d36914fSalekenum XML_Status XMLCALL 11201a3ddf8cSespieXML_Parse(XML_Parser p, 11211a3ddf8cSespie const char *s, 11221a3ddf8cSespie int len, 11231a3ddf8cSespie int isFinal); 11241a3ddf8cSespie</pre> 11251a3ddf8cSespie<pre class="signature"> 11261a3ddf8cSespieenum XML_Status { 11271a3ddf8cSespie XML_STATUS_ERROR = 0, 11281a3ddf8cSespie XML_STATUS_OK = 1 11291a3ddf8cSespie}; 11301a3ddf8cSespie</pre> 11311a3ddf8cSespie<div class="fcndef"> 1132bd8f1dc3Sbluhm<p> 11331a3ddf8cSespieParse some more of the document. The string <code>s</code> is a buffer 11341a3ddf8cSespiecontaining part (or perhaps all) of the document. The number of bytes of s 11351a3ddf8cSespiethat are part of the document is indicated by <code>len</code>. This means 1136bd8f1dc3Sbluhmthat <code>s</code> doesn't have to be null-terminated. It also means that 11371a3ddf8cSespieif <code>len</code> is larger than the number of bytes in the block of 113861ad8a07Sbluhmmemory that <code>s</code> points at, then a memory fault is likely. 113961ad8a07SbluhmNegative values for <code>len</code> are rejected since Expat 2.2.1. 114061ad8a07SbluhmThe 11411a3ddf8cSespie<code>isFinal</code> parameter informs the parser that this is the last 11421a3ddf8cSespiepiece of the document. Frequently, the last piece is empty (i.e. 11431a3ddf8cSespie<code>len</code> is zero.) 1144bd8f1dc3Sbluhm</p> 1145bd8f1dc3Sbluhm 1146bd8f1dc3Sbluhm<p> 11471a3ddf8cSespieIf a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. 11481a3ddf8cSespieOtherwise it returns <code>XML_STATUS_OK</code> value. 1149bd8f1dc3SbluhmNote that regardless of the return value, there is no guarantee that all 1150bd8f1dc3Sbluhmprovided input has been parsed; only after <a href="#isFinal">the 1151bd8f1dc3Sbluhmconcluding call</a> will all handler callbacks and parsing errors have 1152bd8f1dc3Sbluhmhappened. 1153bd8f1dc3Sbluhm</p> 1154bd8f1dc3Sbluhm 1155bd8f1dc3Sbluhm<p> 1156bd8f1dc3SbluhmSimplified, <code>XML_Parse</code> can be considered a convenience wrapper 1157bd8f1dc3Sbluhmthat is pairing calls 1158bd8f1dc3Sbluhmto <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> 1159bd8f1dc3Sbluhmand <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> 1160bd8f1dc3Sbluhm(when Expat is built with macro <code>XML_CONTEXT_BYTES</code> 1161bd8f1dc3Sbluhmdefined to a positive value, which is both common and default). 1162bd8f1dc3Sbluhm<code>XML_Parse</code> is then functionally equivalent to calling 1163bd8f1dc3Sbluhm<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>, 1164bd8f1dc3Sbluhm<code>memcpy</code>, and 1165bd8f1dc3Sbluhm<code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code>. 1166bd8f1dc3Sbluhm</p> 1167bd8f1dc3Sbluhm 1168bd8f1dc3Sbluhm<p> 1169bd8f1dc3SbluhmTo avoid double copying of the input, direct use of functions 1170bd8f1dc3Sbluhm<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> and 1171bd8f1dc3Sbluhm<code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> is advised 1172bd8f1dc3Sbluhmfor most production use, e.g. 1173bd8f1dc3Sbluhmif you're using <code>read</code> or similar functionality to fill your 1174bd8f1dc3Sbluhmbuffers, fill directly into the buffer from 1175bd8f1dc3Sbluhm<code><a href="#XML_GetBuffer">XML_GetBuffer</a></code>, 1176bd8f1dc3Sbluhmthen parse with <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code>. 1177bd8f1dc3Sbluhm</p> 11781a3ddf8cSespie</div> 11791a3ddf8cSespie 118008819b41Sbluhm<h4 id="XML_ParseBuffer">XML_ParseBuffer</h4> 118108819b41Sbluhm<pre class="fcndec"> 11827d36914fSalekenum XML_Status XMLCALL 11831a3ddf8cSespieXML_ParseBuffer(XML_Parser p, 11841a3ddf8cSespie int len, 11851a3ddf8cSespie int isFinal); 11861a3ddf8cSespie</pre> 11871a3ddf8cSespie<div class="fcndef"> 118861ad8a07Sbluhm<p> 11891a3ddf8cSespieThis is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>, 11901a3ddf8cSespieexcept in this case Expat provides the buffer. By obtaining the 11911a3ddf8cSespiebuffer from Expat with the <code><a href= "#XML_GetBuffer" 11921a3ddf8cSespie>XML_GetBuffer</a></code> function, the application can avoid double 11931a3ddf8cSespiecopying of the input. 119461ad8a07Sbluhm</p> 119561ad8a07Sbluhm 119661ad8a07Sbluhm<p> 119761ad8a07SbluhmNegative values for <code>len</code> are rejected since Expat 2.6.3. 119861ad8a07Sbluhm</p> 11991a3ddf8cSespie</div> 12001a3ddf8cSespie 120108819b41Sbluhm<h4 id="XML_GetBuffer">XML_GetBuffer</h4> 120208819b41Sbluhm<pre class="fcndec"> 12037d36914fSalekvoid * XMLCALL 12041a3ddf8cSespieXML_GetBuffer(XML_Parser p, 12051a3ddf8cSespie int len); 12061a3ddf8cSespie</pre> 12071a3ddf8cSespie<div class="fcndef"> 12081a3ddf8cSespieObtain a buffer of size <code>len</code> to read a piece of the document 1209bd8f1dc3Sbluhminto. A <code>NULL</code> value is returned if Expat can't allocate enough memory for 1210bd8f1dc3Sbluhmthis buffer. A <code>NULL</code> value may also be returned if <code>len</code> is zero. 12112c19dcf8SbluhmThis has to be called prior to every call to 12121a3ddf8cSespie<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A 12131a3ddf8cSespietypical use would look like this: 12141a3ddf8cSespie 12151a3ddf8cSespie<pre class="eg"> 12161a3ddf8cSespiefor (;;) { 12171a3ddf8cSespie int bytes_read; 12181a3ddf8cSespie void *buff = XML_GetBuffer(p, BUFF_SIZE); 12191a3ddf8cSespie if (buff == NULL) { 12201a3ddf8cSespie /* handle error */ 12211a3ddf8cSespie } 12221a3ddf8cSespie 12231a3ddf8cSespie bytes_read = read(docfd, buff, BUFF_SIZE); 12241a3ddf8cSespie if (bytes_read < 0) { 12251a3ddf8cSespie /* handle error */ 12261a3ddf8cSespie } 12271a3ddf8cSespie 12281a3ddf8cSespie if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) { 12291a3ddf8cSespie /* handle parse error */ 12301a3ddf8cSespie } 12311a3ddf8cSespie 12321a3ddf8cSespie if (bytes_read == 0) 12331a3ddf8cSespie break; 12341a3ddf8cSespie} 12351a3ddf8cSespie</pre> 12361a3ddf8cSespie</div> 12371a3ddf8cSespie 123808819b41Sbluhm<h4 id="XML_StopParser">XML_StopParser</h4> 123908819b41Sbluhm<pre class="fcndec"> 12407d36914fSalekenum XML_Status XMLCALL 12417d36914fSalekXML_StopParser(XML_Parser p, 12427d36914fSalek XML_Bool resumable); 12437d36914fSalek</pre> 12447d36914fSalek<div class="fcndef"> 12457d36914fSalek 12467d36914fSalek<p>Stops parsing, causing <code><a href= "#XML_Parse" 12477d36914fSalek>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 12487d36914fSalek>XML_ParseBuffer</a></code> to return. Must be called from within a 12497d36914fSalekcall-back handler, except when aborting (when <code>resumable</code> 12507d36914fSalekis <code>XML_FALSE</code>) an already suspended parser. Some 12517d36914fSalekcall-backs may still follow because they would otherwise get 125208819b41Sbluhmlost, including</p> 12537d36914fSalek<ul> 12547d36914fSalek <li> the end element handler for empty elements when stopped in the 12557d36914fSalek start element handler,</li> 1256b26ab0f8Smatthieu <li> the end namespace declaration handler when stopped in the end 12577d36914fSalek element handler,</li> 1258b26ab0f8Smatthieu <li> the character data handler when stopped in the character data handler 1259b26ab0f8Smatthieu while making multiple call-backs on a contiguous chunk of characters,</li> 12607d36914fSalek</ul> 126108819b41Sbluhm<p>and possibly others.</p> 12627d36914fSalek 12637d36914fSalek<p>This can be called from most handlers, including DTD related 12647d36914fSalekcall-backs, except when parsing an external parameter entity and 12657d36914fSalek<code>resumable</code> is <code>XML_TRUE</code>. Returns 12667d36914fSalek<code>XML_STATUS_OK</code> when successful, 12677d36914fSalek<code>XML_STATUS_ERROR</code> otherwise. The possible error codes 12687d36914fSalekare:</p> 12697d36914fSalek<dl> 12707d36914fSalek <dt><code>XML_ERROR_SUSPENDED</code></dt> 12717d36914fSalek <dd>when suspending an already suspended parser.</dd> 12727d36914fSalek <dt><code>XML_ERROR_FINISHED</code></dt> 12737d36914fSalek <dd>when the parser has already finished.</dd> 12747d36914fSalek <dt><code>XML_ERROR_SUSPEND_PE</code></dt> 12757d36914fSalek <dd>when suspending while parsing an external PE.</dd> 12767d36914fSalek</dl> 12777d36914fSalek 12787d36914fSalek<p>Since the stop/resume feature requires application support in the 12797d36914fSalekouter parsing loop, it is an error to call this function for a parser 12807d36914fSaleknot being handled appropriately; see <a href= "#stop-resume" 12817d36914fSalek>Temporarily Stopping Parsing</a> for more information.</p> 12827d36914fSalek 12837d36914fSalek<p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing 12847d36914fSalekis <em>suspended</em>, that is, <code><a href= "#XML_Parse" 12857d36914fSalek>XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer" 12867d36914fSalek>XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>. 12877d36914fSalekOtherwise, parsing is <em>aborted</em>, that is, <code><a href= 12887d36914fSalek"#XML_Parse" >XML_Parse</a></code> and <code><a href= 12897d36914fSalek"#XML_ParseBuffer" >XML_ParseBuffer</a></code> return 12907d36914fSalek<code>XML_STATUS_ERROR</code> with error code 12917d36914fSalek<code>XML_ERROR_ABORTED</code>.</p> 12927d36914fSalek 12937d36914fSalek<p><strong>Note:</strong> 12947d36914fSalekThis will be applied to the current parser instance only, that is, if 12957d36914fSalekthere is a parent parser then it will continue parsing when the 12967d36914fSalekexternal entity reference handler returns. It is up to the 12977d36914fSalekimplementation of that handler to call <code><a href= 12987d36914fSalek"#XML_StopParser" >XML_StopParser</a></code> on the parent parser 12997d36914fSalek(recursively), if one wants to stop parsing altogether.</p> 13007d36914fSalek 13017d36914fSalek<p>When suspended, parsing can be resumed by calling <code><a href= 13027d36914fSalek"#XML_ResumeParser" >XML_ResumeParser</a></code>.</p> 13037d36914fSalek 13047d36914fSalek<p>New in Expat 1.95.8.</p> 13057d36914fSalek</div> 13067d36914fSalek 130708819b41Sbluhm<h4 id="XML_ResumeParser">XML_ResumeParser</h4> 130808819b41Sbluhm<pre class="fcndec"> 13097d36914fSalekenum XML_Status XMLCALL 13107d36914fSalekXML_ResumeParser(XML_Parser p); 13117d36914fSalek</pre> 13127d36914fSalek<div class="fcndef"> 13137d36914fSalek<p>Resumes parsing after it has been suspended with <code><a href= 13147d36914fSalek"#XML_StopParser" >XML_StopParser</a></code>. Must not be called from 13157d36914fSalekwithin a handler call-back. Returns same status codes as <code><a 13167d36914fSalekhref= "#XML_Parse">XML_Parse</a></code> or <code><a href= 13177d36914fSalek"#XML_ParseBuffer" >XML_ParseBuffer</a></code>. An additional error 13187d36914fSalekcode, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the 13197d36914fSalekparser was not currently suspended.</p> 13207d36914fSalek 13217d36914fSalek<p><strong>Note:</strong> 13227d36914fSalekThis must be called on the most deeply nested child parser instance 13237d36914fSalekfirst, and on its parent parser only after the child parser has 13247d36914fSalekfinished, to be applied recursively until the document entity's parser 13257d36914fSalekis restarted. That is, the parent parser will not resume by itself 13267d36914fSalekand it is up to the application to call <code><a href= 13277d36914fSalek"#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the 13287d36914fSalekappropriate moment.</p> 13297d36914fSalek 13307d36914fSalek<p>New in Expat 1.95.8.</p> 13317d36914fSalek</div> 13327d36914fSalek 133308819b41Sbluhm<h4 id="XML_GetParsingStatus">XML_GetParsingStatus</h4> 133408819b41Sbluhm<pre class="fcndec"> 13357d36914fSalekvoid XMLCALL 13367d36914fSalekXML_GetParsingStatus(XML_Parser p, 13377d36914fSalek XML_ParsingStatus *status); 13387d36914fSalek</pre> 13397d36914fSalek<pre class="signature"> 13407d36914fSalekenum XML_Parsing { 13417d36914fSalek XML_INITIALIZED, 13427d36914fSalek XML_PARSING, 13437d36914fSalek XML_FINISHED, 13447d36914fSalek XML_SUSPENDED 13457d36914fSalek}; 13467d36914fSalek 13477d36914fSalektypedef struct { 13487d36914fSalek enum XML_Parsing parsing; 13497d36914fSalek XML_Bool finalBuffer; 13507d36914fSalek} XML_ParsingStatus; 13517d36914fSalek</pre> 13527d36914fSalek<div class="fcndef"> 13537d36914fSalek<p>Returns status of parser with respect to being initialized, 13547d36914fSalekparsing, finished, or suspended, and whether the final buffer is being 13557d36914fSalekprocessed. The <code>status</code> parameter <em>must not</em> be 1356bd8f1dc3Sbluhm<code>NULL</code>.</p> 13577d36914fSalek 13587d36914fSalek<p>New in Expat 1.95.8.</p> 13597d36914fSalek</div> 13607d36914fSalek 13617d36914fSalek 13621a3ddf8cSespie<h3><a name="setting">Handler Setting</a></h3> 13631a3ddf8cSespie 13641a3ddf8cSespie<p>Although handlers are typically set prior to parsing and left alone, an 13651a3ddf8cSespieapplication may choose to set or change the handler for a parsing event 13661a3ddf8cSespiewhile the parse is in progress. For instance, your application may choose 13671a3ddf8cSespieto ignore all text not descended from a <code>para</code> element. One 13681a3ddf8cSespieway it could do this is to set the character handler when a para start tag 13691a3ddf8cSespieis seen, and unset it for the corresponding end tag.</p> 13701a3ddf8cSespie 1371bd8f1dc3Sbluhm<p>A handler may be <em>unset</em> by providing a <code>NULL</code> pointer to the 13721a3ddf8cSespieappropriate handler setter. None of the handler setting functions have 13731a3ddf8cSespiea return value.</p> 13741a3ddf8cSespie 13751a3ddf8cSespie<p>Your handlers will be receiving strings in arrays of type 13767d36914fSalek<code>XML_Char</code>. This type is conditionally defined in expat.h as 13777d36914fSalekeither <code>char</code>, <code>wchar_t</code> or <code>unsigned short</code>. 13787d36914fSalekThe former implies UTF-8 encoding, the latter two imply UTF-16 encoding. 13797d36914fSalekNote that you'll receive them in this form independent of the original 13807d36914fSalekencoding of the document.</p> 13811a3ddf8cSespie 13821a3ddf8cSespie<div class="handler"> 138308819b41Sbluhm<h4 id="XML_SetStartElementHandler">XML_SetStartElementHandler</h4> 138408819b41Sbluhm<pre class="setter"> 13857d36914fSalekvoid XMLCALL 13861a3ddf8cSespieXML_SetStartElementHandler(XML_Parser p, 13871a3ddf8cSespie XML_StartElementHandler start); 13881a3ddf8cSespie</pre> 13891a3ddf8cSespie<pre class="signature"> 13901a3ddf8cSespietypedef void 13917d36914fSalek(XMLCALL *XML_StartElementHandler)(void *userData, 13921a3ddf8cSespie const XML_Char *name, 13931a3ddf8cSespie const XML_Char **atts); 13941a3ddf8cSespie</pre> 13951a3ddf8cSespie<p>Set handler for start (and empty) tags. Attributes are passed to the start 13961a3ddf8cSespiehandler as a pointer to a vector of char pointers. Each attribute seen in 13971a3ddf8cSespiea start (or empty) tag occupies 2 consecutive places in this vector: the 13981a3ddf8cSespieattribute name followed by the attribute value. These pairs are terminated 1399bd8f1dc3Sbluhmby a <code>NULL</code> pointer.</p> 14001a3ddf8cSespie<p>Note that an empty tag generates a call to both start and end handlers 14011a3ddf8cSespie(in that order).</p> 14021a3ddf8cSespie</div> 14031a3ddf8cSespie 14041a3ddf8cSespie<div class="handler"> 140508819b41Sbluhm<h4 id="XML_SetEndElementHandler">XML_SetEndElementHandler</h4> 140608819b41Sbluhm<pre class="setter"> 14077d36914fSalekvoid XMLCALL 14081a3ddf8cSespieXML_SetEndElementHandler(XML_Parser p, 14091a3ddf8cSespie XML_EndElementHandler); 14101a3ddf8cSespie</pre> 14111a3ddf8cSespie<pre class="signature"> 14121a3ddf8cSespietypedef void 14137d36914fSalek(XMLCALL *XML_EndElementHandler)(void *userData, 14141a3ddf8cSespie const XML_Char *name); 14151a3ddf8cSespie</pre> 14161a3ddf8cSespie<p>Set handler for end (and empty) tags. As noted above, an empty tag 14171a3ddf8cSespiegenerates a call to both start and end handlers.</p> 14181a3ddf8cSespie</div> 14191a3ddf8cSespie 14201a3ddf8cSespie<div class="handler"> 142108819b41Sbluhm<h4 id="XML_SetElementHandler">XML_SetElementHandler</h4> 142208819b41Sbluhm<pre class="setter"> 14237d36914fSalekvoid XMLCALL 14241a3ddf8cSespieXML_SetElementHandler(XML_Parser p, 14251a3ddf8cSespie XML_StartElementHandler start, 14261a3ddf8cSespie XML_EndElementHandler end); 14271a3ddf8cSespie</pre> 14281a3ddf8cSespie<p>Set handlers for start and end tags with one call.</p> 14291a3ddf8cSespie</div> 14301a3ddf8cSespie 14311a3ddf8cSespie<div class="handler"> 143208819b41Sbluhm<h4 id="XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</h4> 143308819b41Sbluhm<pre class="setter"> 14347d36914fSalekvoid XMLCALL 14351a3ddf8cSespieXML_SetCharacterDataHandler(XML_Parser p, 14361a3ddf8cSespie XML_CharacterDataHandler charhndl) 14371a3ddf8cSespie</pre> 14381a3ddf8cSespie<pre class="signature"> 14391a3ddf8cSespietypedef void 14407d36914fSalek(XMLCALL *XML_CharacterDataHandler)(void *userData, 14411a3ddf8cSespie const XML_Char *s, 14421a3ddf8cSespie int len); 14431a3ddf8cSespie</pre> 14441a3ddf8cSespie<p>Set a text handler. The string your handler receives 14452a4a206eSbluhmis <em>NOT null-terminated</em>. You have to use the length argument 14461a3ddf8cSespieto deal with the end of the string. A single block of contiguous text 14471a3ddf8cSespiefree of markup may still result in a sequence of calls to this handler. 14481a3ddf8cSespieIn other words, if you're searching for a pattern in the text, it may 1449bd8f1dc3Sbluhmbe split across calls to this handler. Note: Setting this handler to <code>NULL</code> 1450b26ab0f8Smatthieumay <em>NOT immediately</em> terminate call-backs if the parser is currently 1451b26ab0f8Smatthieuprocessing such a single block of contiguous markup-free text, as the parser 1452b26ab0f8Smatthieuwill continue calling back until the end of the block is reached.</p> 14531a3ddf8cSespie</div> 14541a3ddf8cSespie 14551a3ddf8cSespie<div class="handler"> 145608819b41Sbluhm<h4 id="XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</h4> 145708819b41Sbluhm<pre class="setter"> 14587d36914fSalekvoid XMLCALL 14591a3ddf8cSespieXML_SetProcessingInstructionHandler(XML_Parser p, 14601a3ddf8cSespie XML_ProcessingInstructionHandler proc) 14611a3ddf8cSespie</pre> 14621a3ddf8cSespie<pre class="signature"> 14631a3ddf8cSespietypedef void 14647d36914fSalek(XMLCALL *XML_ProcessingInstructionHandler)(void *userData, 14651a3ddf8cSespie const XML_Char *target, 14661a3ddf8cSespie const XML_Char *data); 14671a3ddf8cSespie 14681a3ddf8cSespie</pre> 14691a3ddf8cSespie<p>Set a handler for processing instructions. The target is the first word 14701a3ddf8cSespiein the processing instruction. The data is the rest of the characters in 14711a3ddf8cSespieit after skipping all whitespace after the initial word.</p> 14721a3ddf8cSespie</div> 14731a3ddf8cSespie 14741a3ddf8cSespie<div class="handler"> 147508819b41Sbluhm<h4 id="XML_SetCommentHandler">XML_SetCommentHandler</h4> 147608819b41Sbluhm<pre class="setter"> 14777d36914fSalekvoid XMLCALL 14781a3ddf8cSespieXML_SetCommentHandler(XML_Parser p, 14791a3ddf8cSespie XML_CommentHandler cmnt) 14801a3ddf8cSespie</pre> 14811a3ddf8cSespie<pre class="signature"> 14821a3ddf8cSespietypedef void 14837d36914fSalek(XMLCALL *XML_CommentHandler)(void *userData, 14841a3ddf8cSespie const XML_Char *data); 14851a3ddf8cSespie</pre> 14861a3ddf8cSespie<p>Set a handler for comments. The data is all text inside the comment 14871a3ddf8cSespiedelimiters.</p> 14881a3ddf8cSespie</div> 14891a3ddf8cSespie 14901a3ddf8cSespie<div class="handler"> 149108819b41Sbluhm<h4 id="XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</h4> 149208819b41Sbluhm<pre class="setter"> 14937d36914fSalekvoid XMLCALL 14941a3ddf8cSespieXML_SetStartCdataSectionHandler(XML_Parser p, 14951a3ddf8cSespie XML_StartCdataSectionHandler start); 14961a3ddf8cSespie</pre> 14971a3ddf8cSespie<pre class="signature"> 14981a3ddf8cSespietypedef void 14997d36914fSalek(XMLCALL *XML_StartCdataSectionHandler)(void *userData); 15001a3ddf8cSespie</pre> 15011a3ddf8cSespie<p>Set a handler that gets called at the beginning of a CDATA section.</p> 15021a3ddf8cSespie</div> 15031a3ddf8cSespie 15041a3ddf8cSespie<div class="handler"> 150508819b41Sbluhm<h4 id="XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</h4> 150608819b41Sbluhm<pre class="setter"> 15077d36914fSalekvoid XMLCALL 15081a3ddf8cSespieXML_SetEndCdataSectionHandler(XML_Parser p, 15091a3ddf8cSespie XML_EndCdataSectionHandler end); 15101a3ddf8cSespie</pre> 15111a3ddf8cSespie<pre class="signature"> 15121a3ddf8cSespietypedef void 15137d36914fSalek(XMLCALL *XML_EndCdataSectionHandler)(void *userData); 15141a3ddf8cSespie</pre> 15151a3ddf8cSespie<p>Set a handler that gets called at the end of a CDATA section.</p> 15161a3ddf8cSespie</div> 15171a3ddf8cSespie 15181a3ddf8cSespie<div class="handler"> 151908819b41Sbluhm<h4 id="XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</h4> 152008819b41Sbluhm<pre class="setter"> 15217d36914fSalekvoid XMLCALL 15221a3ddf8cSespieXML_SetCdataSectionHandler(XML_Parser p, 15231a3ddf8cSespie XML_StartCdataSectionHandler start, 15241a3ddf8cSespie XML_EndCdataSectionHandler end) 15251a3ddf8cSespie</pre> 15261a3ddf8cSespie<p>Sets both CDATA section handlers with one call.</p> 15271a3ddf8cSespie</div> 15281a3ddf8cSespie 15291a3ddf8cSespie<div class="handler"> 153008819b41Sbluhm<h4 id="XML_SetDefaultHandler">XML_SetDefaultHandler</h4> 153108819b41Sbluhm<pre class="setter"> 15327d36914fSalekvoid XMLCALL 15331a3ddf8cSespieXML_SetDefaultHandler(XML_Parser p, 15341a3ddf8cSespie XML_DefaultHandler hndl) 15351a3ddf8cSespie</pre> 15361a3ddf8cSespie<pre class="signature"> 15371a3ddf8cSespietypedef void 15387d36914fSalek(XMLCALL *XML_DefaultHandler)(void *userData, 15391a3ddf8cSespie const XML_Char *s, 15401a3ddf8cSespie int len); 15411a3ddf8cSespie</pre> 15421a3ddf8cSespie 15431a3ddf8cSespie<p>Sets a handler for any characters in the document which wouldn't 15441a3ddf8cSespieotherwise be handled. This includes both data for which no handlers 15451a3ddf8cSespiecan be set (like some kinds of DTD declarations) and data which could 15461a3ddf8cSespiebe reported but which currently has no handler set. The characters 15471a3ddf8cSespieare passed exactly as they were present in the XML document except 15481a3ddf8cSespiethat they will be encoded in UTF-8 or UTF-16. Line boundaries are not 15491a3ddf8cSespienormalized. Note that a byte order mark character is not passed to the 15501a3ddf8cSespiedefault handler. There are no guarantees about how characters are 15511a3ddf8cSespiedivided between calls to the default handler: for example, a comment 15521a3ddf8cSespiemight be split between multiple calls. Setting the handler with 15531a3ddf8cSespiethis call has the side effect of turning off expansion of references 15541a3ddf8cSespieto internally defined general entities. Instead these references are 15551a3ddf8cSespiepassed to the default handler.</p> 15561a3ddf8cSespie 15571a3ddf8cSespie<p>See also <code><a 15581a3ddf8cSespiehref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 15591a3ddf8cSespie</div> 15601a3ddf8cSespie 15611a3ddf8cSespie<div class="handler"> 156208819b41Sbluhm<h4 id="XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</h4> 156308819b41Sbluhm<pre class="setter"> 15647d36914fSalekvoid XMLCALL 15651a3ddf8cSespieXML_SetDefaultHandlerExpand(XML_Parser p, 15661a3ddf8cSespie XML_DefaultHandler hndl) 15671a3ddf8cSespie</pre> 15681a3ddf8cSespie<pre class="signature"> 15691a3ddf8cSespietypedef void 15707d36914fSalek(XMLCALL *XML_DefaultHandler)(void *userData, 15711a3ddf8cSespie const XML_Char *s, 15721a3ddf8cSespie int len); 15731a3ddf8cSespie</pre> 15741a3ddf8cSespie<p>This sets a default handler, but doesn't inhibit the expansion of 15751a3ddf8cSespieinternal entity references. The entity reference will not be passed 15761a3ddf8cSespieto the default handler.</p> 15771a3ddf8cSespie 15781a3ddf8cSespie<p>See also <code><a 15791a3ddf8cSespiehref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 15801a3ddf8cSespie</div> 15811a3ddf8cSespie 15821a3ddf8cSespie<div class="handler"> 158308819b41Sbluhm<h4 id="XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</h4> 158408819b41Sbluhm<pre class="setter"> 15857d36914fSalekvoid XMLCALL 15861a3ddf8cSespieXML_SetExternalEntityRefHandler(XML_Parser p, 15871a3ddf8cSespie XML_ExternalEntityRefHandler hndl) 15881a3ddf8cSespie</pre> 15891a3ddf8cSespie<pre class="signature"> 15901a3ddf8cSespietypedef int 15917d36914fSalek(XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p, 15921a3ddf8cSespie const XML_Char *context, 15931a3ddf8cSespie const XML_Char *base, 15941a3ddf8cSespie const XML_Char *systemId, 15951a3ddf8cSespie const XML_Char *publicId); 15961a3ddf8cSespie</pre> 15971a3ddf8cSespie<p>Set an external entity reference handler. This handler is also 15981a3ddf8cSespiecalled for processing an external DTD subset if parameter entity parsing 15991a3ddf8cSespieis in effect. (See <a href="#XML_SetParamEntityParsing"> 16001a3ddf8cSespie<code>XML_SetParamEntityParsing</code></a>.)</p> 16011a3ddf8cSespie 16021a3ddf8cSespie<p>The <code>context</code> parameter specifies the parsing context in 16031a3ddf8cSespiethe format expected by the <code>context</code> argument to <code><a 16041a3ddf8cSespiehref="#XML_ExternalEntityParserCreate" 16051a3ddf8cSespie>XML_ExternalEntityParserCreate</a></code>. <code>code</code> is 16061a3ddf8cSespievalid only until the handler returns, so if the referenced entity is 1607bd8f1dc3Sbluhmto be parsed later, it must be copied. <code>context</code> is <code>NULL</code> 16081a3ddf8cSespieonly when the entity is a parameter entity, which is how one can 16091a3ddf8cSespiedifferentiate between general and parameter entities.</p> 16101a3ddf8cSespie 16111a3ddf8cSespie<p>The <code>base</code> parameter is the base to use for relative 16121a3ddf8cSespiesystem identifiers. It is set by <code><a 1613bd8f1dc3Sbluhmhref="#XML_SetBase">XML_SetBase</a></code> and may be <code>NULL</code>. The 16141a3ddf8cSespie<code>publicId</code> parameter is the public id given in the entity 1615bd8f1dc3Sbluhmdeclaration and may be <code>NULL</code>. <code>systemId</code> is the system 1616bd8f1dc3Sbluhmidentifier specified in the entity declaration and is never <code>NULL</code>.</p> 16171a3ddf8cSespie 16181a3ddf8cSespie<p>There are a couple of ways in which this handler differs from 16191a3ddf8cSespieothers. First, this handler returns a status indicator (an 16201a3ddf8cSespieinteger). <code>XML_STATUS_OK</code> should be returned for successful 16211a3ddf8cSespiehandling of the external entity reference. Returning 16221a3ddf8cSespie<code>XML_STATUS_ERROR</code> indicates failure, and causes the 16231a3ddf8cSespiecalling parser to return an 16241a3ddf8cSespie<code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p> 16251a3ddf8cSespie 16261a3ddf8cSespie<p>Second, instead of having the user data as its first argument, it 16271a3ddf8cSespiereceives the parser that encountered the entity reference. This, along 16281a3ddf8cSespiewith the context parameter, may be used as arguments to a call to 16291a3ddf8cSespie<code><a href= "#XML_ExternalEntityParserCreate" 16301a3ddf8cSespie>XML_ExternalEntityParserCreate</a></code>. Using the returned 16311a3ddf8cSespieparser, the body of the external entity can be recursively parsed.</p> 16321a3ddf8cSespie 16331a3ddf8cSespie<p>Since this handler may be called recursively, it should not be saving 16341a3ddf8cSespieinformation into global or static variables.</p> 16351a3ddf8cSespie</div> 16361a3ddf8cSespie 163708819b41Sbluhm<h4 id="XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</h4> 163808819b41Sbluhm<pre class="fcndec"> 16397d36914fSalekvoid XMLCALL 16401a3ddf8cSespieXML_SetExternalEntityRefHandlerArg(XML_Parser p, 16411a3ddf8cSespie void *arg) 16421a3ddf8cSespie</pre> 16431a3ddf8cSespie<div class="fcndef"> 16441a3ddf8cSespie<p>Set the argument passed to the ExternalEntityRefHandler. If 1645bd8f1dc3Sbluhm<code>arg</code> is not <code>NULL</code>, it is the new value passed to the 16461a3ddf8cSespiehandler set using <code><a href="#XML_SetExternalEntityRefHandler" 16471a3ddf8cSespie>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is 1648bd8f1dc3Sbluhm<code>NULL</code>, the argument passed to the handler function will be the parser 16491a3ddf8cSespieobject itself.</p> 16501a3ddf8cSespie 16511a3ddf8cSespie<p><strong>Note:</strong> 16521a3ddf8cSespieThe type of <code>arg</code> and the type of the first argument to the 16531a3ddf8cSespieExternalEntityRefHandler do not match. This function takes a 16541a3ddf8cSespie<code>void *</code> to be passed to the handler, while the handler 16551a3ddf8cSespieaccepts an <code>XML_Parser</code>. This is a historical accident, 16561a3ddf8cSespiebut will not be corrected before Expat 2.0 (at the earliest) to avoid 16571a3ddf8cSespiecausing compiler warnings for code that's known to work with this 16581a3ddf8cSespieAPI. It is the responsibility of the application code to know the 16591a3ddf8cSespieactual type of the argument passed to the handler and to manage it 16601a3ddf8cSespieproperly.</p> 16611a3ddf8cSespie</div> 16621a3ddf8cSespie 16631a3ddf8cSespie<div class="handler"> 166408819b41Sbluhm<h4 id="XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</h4> 166508819b41Sbluhm<pre class="setter"> 16667d36914fSalekvoid XMLCALL 16671a3ddf8cSespieXML_SetSkippedEntityHandler(XML_Parser p, 16681a3ddf8cSespie XML_SkippedEntityHandler handler) 16691a3ddf8cSespie</pre> 16701a3ddf8cSespie<pre class="signature"> 16711a3ddf8cSespietypedef void 16727d36914fSalek(XMLCALL *XML_SkippedEntityHandler)(void *userData, 16731a3ddf8cSespie const XML_Char *entityName, 16741a3ddf8cSespie int is_parameter_entity); 16751a3ddf8cSespie</pre> 16761a3ddf8cSespie<p>Set a skipped entity handler. This is called in two situations:</p> 16771a3ddf8cSespie<ol> 16781a3ddf8cSespie <li>An entity reference is encountered for which no declaration 16791a3ddf8cSespie has been read <em>and</em> this is not an error.</li> 16801a3ddf8cSespie <li>An internal entity reference is read, but not expanded, because 16811a3ddf8cSespie <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> 16821a3ddf8cSespie has been called.</li> 16831a3ddf8cSespie</ol> 16841a3ddf8cSespie<p>The <code>is_parameter_entity</code> argument will be non-zero for 168508819b41Sbluhma parameter entity and zero for a general entity.</p> <p>Note: Skipped 16861a3ddf8cSespieparameter entities in declarations and skipped general entities in 16871a3ddf8cSespieattribute values cannot be reported, because the event would be out of 16881a3ddf8cSespiesync with the reporting of the declarations or attribute values</p> 16891a3ddf8cSespie</div> 16901a3ddf8cSespie 16911a3ddf8cSespie<div class="handler"> 169208819b41Sbluhm<h4 id="XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</h4> 169308819b41Sbluhm<pre class="setter"> 16947d36914fSalekvoid XMLCALL 16951a3ddf8cSespieXML_SetUnknownEncodingHandler(XML_Parser p, 16961a3ddf8cSespie XML_UnknownEncodingHandler enchandler, 16971a3ddf8cSespie void *encodingHandlerData) 16981a3ddf8cSespie</pre> 16991a3ddf8cSespie<pre class="signature"> 17001a3ddf8cSespietypedef int 17017d36914fSalek(XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData, 17021a3ddf8cSespie const XML_Char *name, 17031a3ddf8cSespie XML_Encoding *info); 17041a3ddf8cSespie 17051a3ddf8cSespietypedef struct { 17061a3ddf8cSespie int map[256]; 17071a3ddf8cSespie void *data; 17087d36914fSalek int (XMLCALL *convert)(void *data, const char *s); 17097d36914fSalek void (XMLCALL *release)(void *data); 17101a3ddf8cSespie} XML_Encoding; 17111a3ddf8cSespie</pre> 17121a3ddf8cSespie<p>Set a handler to deal with encodings other than the <a 17131a3ddf8cSespiehref="#builtin_encodings">built in set</a>. This should be done before 17141a3ddf8cSespie<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href= 17151a3ddf8cSespie"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the 17161a3ddf8cSespiegiven parser.</p> <p>If the handler knows how to deal with an encoding 17171a3ddf8cSespiewith the given name, it should fill in the <code>info</code> data 17187d36914fSalekstructure and return <code>XML_STATUS_OK</code>. Otherwise it 17197d36914fSalekshould return <code>XML_STATUS_ERROR</code>. The handler will be called 17201a3ddf8cSespieat most once per parsed (external) entity. The optional application 17211a3ddf8cSespiedata pointer <code>encodingHandlerData</code> will be passed back to 17221a3ddf8cSespiethe handler.</p> 17231a3ddf8cSespie 17242e724bc9Sbluhm<p>The map array contains information for every possible leading 17251a3ddf8cSespiebyte in a byte sequence. If the corresponding value is >= 0, then it's 17261a3ddf8cSespiea single byte sequence and the byte encodes that Unicode value. If the 17271a3ddf8cSespievalue is -1, then that byte is invalid as the initial byte in a sequence. 17281a3ddf8cSespieIf the value is -n, where n is an integer > 1, then n is the number of 17291a3ddf8cSespiebytes in the sequence and the actual conversion is accomplished by a 17301a3ddf8cSespiecall to the function pointed at by convert. This function may return -1 1731bd8f1dc3Sbluhmif the sequence itself is invalid. The convert pointer may be <code>NULL</code> if 17321a3ddf8cSespiethere are only single byte codes. The data parameter passed to the convert 17331a3ddf8cSespiefunction is the data pointer from <code>XML_Encoding</code>. The 17342a4a206eSbluhmstring s is <em>NOT</em> null-terminated and points at the sequence of 17351a3ddf8cSespiebytes to be converted.</p> 17361a3ddf8cSespie 17371a3ddf8cSespie<p>The function pointed at by <code>release</code> is called by the 1738bd8f1dc3Sbluhmparser when it is finished with the encoding. It may be <code>NULL</code>.</p> 17391a3ddf8cSespie</div> 17401a3ddf8cSespie 17411a3ddf8cSespie<div class="handler"> 174208819b41Sbluhm<h4 id="XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</h4> 174308819b41Sbluhm<pre class="setter"> 17447d36914fSalekvoid XMLCALL 17451a3ddf8cSespieXML_SetStartNamespaceDeclHandler(XML_Parser p, 17461a3ddf8cSespie XML_StartNamespaceDeclHandler start); 17471a3ddf8cSespie</pre> 17481a3ddf8cSespie<pre class="signature"> 17491a3ddf8cSespietypedef void 17507d36914fSalek(XMLCALL *XML_StartNamespaceDeclHandler)(void *userData, 17511a3ddf8cSespie const XML_Char *prefix, 17521a3ddf8cSespie const XML_Char *uri); 17531a3ddf8cSespie</pre> 17541a3ddf8cSespie<p>Set a handler to be called when a namespace is declared. Namespace 17551a3ddf8cSespiedeclarations occur inside start tags. But the namespace declaration start 17561a3ddf8cSespiehandler is called before the start tag handler for each namespace declared 17571a3ddf8cSespiein that start tag.</p> 17581a3ddf8cSespie</div> 17591a3ddf8cSespie 17601a3ddf8cSespie<div class="handler"> 176108819b41Sbluhm<h4 id="XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</h4> 176208819b41Sbluhm<pre class="setter"> 17637d36914fSalekvoid XMLCALL 17641a3ddf8cSespieXML_SetEndNamespaceDeclHandler(XML_Parser p, 17651a3ddf8cSespie XML_EndNamespaceDeclHandler end); 17661a3ddf8cSespie</pre> 17671a3ddf8cSespie<pre class="signature"> 17681a3ddf8cSespietypedef void 17697d36914fSalek(XMLCALL *XML_EndNamespaceDeclHandler)(void *userData, 17701a3ddf8cSespie const XML_Char *prefix); 17711a3ddf8cSespie</pre> 17721a3ddf8cSespie<p>Set a handler to be called when leaving the scope of a namespace 17731a3ddf8cSespiedeclaration. This will be called, for each namespace declaration, 17741a3ddf8cSespieafter the handler for the end tag of the element in which the 17751a3ddf8cSespienamespace was declared.</p> 17761a3ddf8cSespie</div> 17771a3ddf8cSespie 17781a3ddf8cSespie<div class="handler"> 177908819b41Sbluhm<h4 id="XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</h4> 178008819b41Sbluhm<pre class="setter"> 17817d36914fSalekvoid XMLCALL 17821a3ddf8cSespieXML_SetNamespaceDeclHandler(XML_Parser p, 17831a3ddf8cSespie XML_StartNamespaceDeclHandler start, 17841a3ddf8cSespie XML_EndNamespaceDeclHandler end) 17851a3ddf8cSespie</pre> 17861a3ddf8cSespie<p>Sets both namespace declaration handlers with a single call.</p> 17871a3ddf8cSespie</div> 17881a3ddf8cSespie 17891a3ddf8cSespie<div class="handler"> 179008819b41Sbluhm<h4 id="XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</h4> 179108819b41Sbluhm<pre class="setter"> 17927d36914fSalekvoid XMLCALL 17931a3ddf8cSespieXML_SetXmlDeclHandler(XML_Parser p, 17941a3ddf8cSespie XML_XmlDeclHandler xmldecl); 17951a3ddf8cSespie</pre> 17961a3ddf8cSespie<pre class="signature"> 17971a3ddf8cSespietypedef void 17987d36914fSalek(XMLCALL *XML_XmlDeclHandler)(void *userData, 17991a3ddf8cSespie const XML_Char *version, 18001a3ddf8cSespie const XML_Char *encoding, 18011a3ddf8cSespie int standalone); 18021a3ddf8cSespie</pre> 18031a3ddf8cSespie<p>Sets a handler that is called for XML declarations and also for 18041a3ddf8cSespietext declarations discovered in external entities. The way to 1805bd8f1dc3Sbluhmdistinguish is that the <code>version</code> parameter will be <code>NULL</code> 1806bd8f1dc3Sbluhmfor text declarations. The <code>encoding</code> parameter may be <code>NULL</code> 18071a3ddf8cSespiefor an XML declaration. The <code>standalone</code> argument will 18081a3ddf8cSespiecontain -1, 0, or 1 indicating respectively that there was no 18091a3ddf8cSespiestandalone parameter in the declaration, that it was given as no, or 18101a3ddf8cSespiethat it was given as yes.</p> 18111a3ddf8cSespie</div> 18121a3ddf8cSespie 18131a3ddf8cSespie<div class="handler"> 181408819b41Sbluhm<h4 id="XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</h4> 181508819b41Sbluhm<pre class="setter"> 18167d36914fSalekvoid XMLCALL 18171a3ddf8cSespieXML_SetStartDoctypeDeclHandler(XML_Parser p, 18181a3ddf8cSespie XML_StartDoctypeDeclHandler start); 18191a3ddf8cSespie</pre> 18201a3ddf8cSespie<pre class="signature"> 18211a3ddf8cSespietypedef void 18227d36914fSalek(XMLCALL *XML_StartDoctypeDeclHandler)(void *userData, 18231a3ddf8cSespie const XML_Char *doctypeName, 18241a3ddf8cSespie const XML_Char *sysid, 18251a3ddf8cSespie const XML_Char *pubid, 18261a3ddf8cSespie int has_internal_subset); 18271a3ddf8cSespie</pre> 18281a3ddf8cSespie<p>Set a handler that is called at the start of a DOCTYPE declaration, 18291a3ddf8cSespiebefore any external or internal subset is parsed. Both <code>sysid</code> 1830bd8f1dc3Sbluhmand <code>pubid</code> may be <code>NULL</code>. The <code>has_internal_subset</code> 18311a3ddf8cSespiewill be non-zero if the DOCTYPE declaration has an internal subset.</p> 18321a3ddf8cSespie</div> 18331a3ddf8cSespie 18341a3ddf8cSespie<div class="handler"> 183508819b41Sbluhm<h4 id="XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</h4> 183608819b41Sbluhm<pre class="setter"> 18377d36914fSalekvoid XMLCALL 18381a3ddf8cSespieXML_SetEndDoctypeDeclHandler(XML_Parser p, 18391a3ddf8cSespie XML_EndDoctypeDeclHandler end); 18401a3ddf8cSespie</pre> 18411a3ddf8cSespie<pre class="signature"> 18421a3ddf8cSespietypedef void 18437d36914fSalek(XMLCALL *XML_EndDoctypeDeclHandler)(void *userData); 18441a3ddf8cSespie</pre> 18451a3ddf8cSespie<p>Set a handler that is called at the end of a DOCTYPE declaration, 18461a3ddf8cSespieafter parsing any external subset.</p> 18471a3ddf8cSespie</div> 18481a3ddf8cSespie 18491a3ddf8cSespie<div class="handler"> 185008819b41Sbluhm<h4 id="XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</h4> 185108819b41Sbluhm<pre class="setter"> 18527d36914fSalekvoid XMLCALL 18531a3ddf8cSespieXML_SetDoctypeDeclHandler(XML_Parser p, 18541a3ddf8cSespie XML_StartDoctypeDeclHandler start, 18551a3ddf8cSespie XML_EndDoctypeDeclHandler end); 18561a3ddf8cSespie</pre> 18571a3ddf8cSespie<p>Set both doctype handlers with one call.</p> 18581a3ddf8cSespie</div> 18591a3ddf8cSespie 18601a3ddf8cSespie<div class="handler"> 186108819b41Sbluhm<h4 id="XML_SetElementDeclHandler">XML_SetElementDeclHandler</h4> 186208819b41Sbluhm<pre class="setter"> 18637d36914fSalekvoid XMLCALL 18641a3ddf8cSespieXML_SetElementDeclHandler(XML_Parser p, 18651a3ddf8cSespie XML_ElementDeclHandler eldecl); 18661a3ddf8cSespie</pre> 18671a3ddf8cSespie<pre class="signature"> 18681a3ddf8cSespietypedef void 18697d36914fSalek(XMLCALL *XML_ElementDeclHandler)(void *userData, 18701a3ddf8cSespie const XML_Char *name, 18711a3ddf8cSespie XML_Content *model); 18721a3ddf8cSespie</pre> 18731a3ddf8cSespie<pre class="signature"> 18741a3ddf8cSespieenum XML_Content_Type { 18751a3ddf8cSespie XML_CTYPE_EMPTY = 1, 18761a3ddf8cSespie XML_CTYPE_ANY, 18771a3ddf8cSespie XML_CTYPE_MIXED, 18781a3ddf8cSespie XML_CTYPE_NAME, 18791a3ddf8cSespie XML_CTYPE_CHOICE, 18801a3ddf8cSespie XML_CTYPE_SEQ 18811a3ddf8cSespie}; 18821a3ddf8cSespie 18831a3ddf8cSespieenum XML_Content_Quant { 18841a3ddf8cSespie XML_CQUANT_NONE, 18851a3ddf8cSespie XML_CQUANT_OPT, 18861a3ddf8cSespie XML_CQUANT_REP, 18871a3ddf8cSespie XML_CQUANT_PLUS 18881a3ddf8cSespie}; 18891a3ddf8cSespie 18901a3ddf8cSespietypedef struct XML_cp XML_Content; 18911a3ddf8cSespie 18921a3ddf8cSespiestruct XML_cp { 18931a3ddf8cSespie enum XML_Content_Type type; 18941a3ddf8cSespie enum XML_Content_Quant quant; 18951a3ddf8cSespie const XML_Char * name; 18961a3ddf8cSespie unsigned int numchildren; 18971a3ddf8cSespie XML_Content * children; 18981a3ddf8cSespie}; 18991a3ddf8cSespie</pre> 19001a3ddf8cSespie<p>Sets a handler for element declarations in a DTD. The handler gets 19011a3ddf8cSespiecalled with the name of the element in the declaration and a pointer 1902680fbc60Sbluhmto a structure that contains the element model. It's the user code's 1903680fbc60Sbluhmresponsibility to free model when finished with it. See <code> 1904680fbc60Sbluhm<a href="#XML_FreeContentModel">XML_FreeContentModel</a></code>. 1905680fbc60SbluhmThere is no need to free the model from the handler, it can be kept 1906680fbc60Sbluhmaround and freed at a later stage.</p> 19071a3ddf8cSespie 19081a3ddf8cSespie<p>The <code>model</code> argument is the root of a tree of 19091a3ddf8cSespie<code>XML_Content</code> nodes. If <code>type</code> equals 19101a3ddf8cSespie<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then 19111a3ddf8cSespie<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other 1912bd8f1dc3Sbluhmfields will be zero or <code>NULL</code>. If <code>type</code> is 19131a3ddf8cSespie<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be 19141a3ddf8cSespie<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and 19151a3ddf8cSespie<code>numchildren</code> will contain the number of elements that are 19161a3ddf8cSespieallowed to be mixed in and <code>children</code> points to an array of 19171a3ddf8cSespie<code>XML_Content</code> structures that will all have type 19181a3ddf8cSespieXML_CTYPE_NAME with no quantification. Only the root node can be type 19191a3ddf8cSespie<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or 19201a3ddf8cSespie<code>XML_CTYPE_MIXED</code>.</p> 19211a3ddf8cSespie 19221a3ddf8cSespie<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field 19231a3ddf8cSespiepoints to the name and the <code>numchildren</code> and 1924bd8f1dc3Sbluhm<code>children</code> fields will be zero and <code>NULL</code>. The 19251a3ddf8cSespie<code>quant</code> field will indicate any quantifiers placed on the 19261a3ddf8cSespiename.</p> 19271a3ddf8cSespie 19281a3ddf8cSespie<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> 19291a3ddf8cSespieindicate a choice or sequence respectively. The 19301a3ddf8cSespie<code>numchildren</code> field indicates how many nodes in the choice 19311a3ddf8cSespieor sequence and <code>children</code> points to the nodes.</p> 19321a3ddf8cSespie</div> 19331a3ddf8cSespie 19341a3ddf8cSespie<div class="handler"> 193508819b41Sbluhm<h4 id="XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</h4> 193608819b41Sbluhm<pre class="setter"> 19377d36914fSalekvoid XMLCALL 19381a3ddf8cSespieXML_SetAttlistDeclHandler(XML_Parser p, 19391a3ddf8cSespie XML_AttlistDeclHandler attdecl); 19401a3ddf8cSespie</pre> 19411a3ddf8cSespie<pre class="signature"> 19421a3ddf8cSespietypedef void 19437d36914fSalek(XMLCALL *XML_AttlistDeclHandler)(void *userData, 19441a3ddf8cSespie const XML_Char *elname, 19451a3ddf8cSespie const XML_Char *attname, 19461a3ddf8cSespie const XML_Char *att_type, 19471a3ddf8cSespie const XML_Char *dflt, 19481a3ddf8cSespie int isrequired); 19491a3ddf8cSespie</pre> 19501a3ddf8cSespie<p>Set a handler for attlist declarations in the DTD. This handler is 19511a3ddf8cSespiecalled for <em>each</em> attribute. So a single attlist declaration 19521a3ddf8cSespiewith multiple attributes declared will generate multiple calls to this 19531a3ddf8cSespiehandler. The <code>elname</code> parameter returns the name of the 19541a3ddf8cSespieelement for which the attribute is being declared. The attribute name 19551a3ddf8cSespieis in the <code>attname</code> parameter. The attribute type is in the 19561a3ddf8cSespie<code>att_type</code> parameter. It is the string representing the 19571a3ddf8cSespietype in the declaration with whitespace removed.</p> 19581a3ddf8cSespie 19591a3ddf8cSespie<p>The <code>dflt</code> parameter holds the default value. It will be 1960bd8f1dc3Sbluhm<code>NULL</code> in the case of "#IMPLIED" or "#REQUIRED" attributes. You can 19611a3ddf8cSespiedistinguish these two cases by checking the <code>isrequired</code> 19621a3ddf8cSespieparameter, which will be true in the case of "#REQUIRED" attributes. 19631a3ddf8cSespieAttributes which are "#FIXED" will have also have a true 1964bd8f1dc3Sbluhm<code>isrequired</code>, but they will have the non-<code>NULL</code> fixed value 19651a3ddf8cSespiein the <code>dflt</code> parameter.</p> 19661a3ddf8cSespie</div> 19671a3ddf8cSespie 19681a3ddf8cSespie<div class="handler"> 196908819b41Sbluhm<h4 id="XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</h4> 197008819b41Sbluhm<pre class="setter"> 19717d36914fSalekvoid XMLCALL 19721a3ddf8cSespieXML_SetEntityDeclHandler(XML_Parser p, 19731a3ddf8cSespie XML_EntityDeclHandler handler); 19741a3ddf8cSespie</pre> 19751a3ddf8cSespie<pre class="signature"> 19761a3ddf8cSespietypedef void 19777d36914fSalek(XMLCALL *XML_EntityDeclHandler)(void *userData, 19781a3ddf8cSespie const XML_Char *entityName, 19791a3ddf8cSespie int is_parameter_entity, 19801a3ddf8cSespie const XML_Char *value, 19811a3ddf8cSespie int value_length, 19821a3ddf8cSespie const XML_Char *base, 19831a3ddf8cSespie const XML_Char *systemId, 19841a3ddf8cSespie const XML_Char *publicId, 19851a3ddf8cSespie const XML_Char *notationName); 19861a3ddf8cSespie</pre> 19871a3ddf8cSespie<p>Sets a handler that will be called for all entity declarations. 19881a3ddf8cSespieThe <code>is_parameter_entity</code> argument will be non-zero in the 19891a3ddf8cSespiecase of parameter entities and zero otherwise.</p> 19901a3ddf8cSespie 19911a3ddf8cSespie<p>For internal entities (<code><!ENTITY foo "bar"></code>), 1992bd8f1dc3Sbluhm<code>value</code> will be non-<code>NULL</code> and <code>systemId</code>, 1993bd8f1dc3Sbluhm<code>publicId</code>, and <code>notationName</code> will all be <code>NULL</code>. 1994bd8f1dc3SbluhmThe value string is <em>not</em> null-terminated; the length is 19951a3ddf8cSespieprovided in the <code>value_length</code> parameter. Do not use 19961a3ddf8cSespie<code>value_length</code> to test for internal entities, since it is 19971a3ddf8cSespielegal to have zero-length values. Instead check for whether or not 1998bd8f1dc3Sbluhm<code>value</code> is <code>NULL</code>.</p> <p>The <code>notationName</code> 1999bd8f1dc3Sbluhmargument will have a non-<code>NULL</code> value only for unparsed entity 20001a3ddf8cSespiedeclarations.</p> 20011a3ddf8cSespie</div> 20021a3ddf8cSespie 20031a3ddf8cSespie<div class="handler"> 200408819b41Sbluhm<h4 id="XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</h4> 200508819b41Sbluhm<pre class="setter"> 20067d36914fSalekvoid XMLCALL 20071a3ddf8cSespieXML_SetUnparsedEntityDeclHandler(XML_Parser p, 20081a3ddf8cSespie XML_UnparsedEntityDeclHandler h) 20091a3ddf8cSespie</pre> 20101a3ddf8cSespie<pre class="signature"> 20111a3ddf8cSespietypedef void 20127d36914fSalek(XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData, 20131a3ddf8cSespie const XML_Char *entityName, 20141a3ddf8cSespie const XML_Char *base, 20151a3ddf8cSespie const XML_Char *systemId, 20161a3ddf8cSespie const XML_Char *publicId, 20171a3ddf8cSespie const XML_Char *notationName); 20181a3ddf8cSespie</pre> 20191a3ddf8cSespie<p>Set a handler that receives declarations of unparsed entities. These 20201a3ddf8cSespieare entity declarations that have a notation (NDATA) field:</p> 20211a3ddf8cSespie 20221a3ddf8cSespie<div id="eg"><pre> 20231a3ddf8cSespie<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif> 20241a3ddf8cSespie</pre></div> 20251a3ddf8cSespie<p>This handler is obsolete and is provided for backwards 20261a3ddf8cSespiecompatibility. Use instead <a href= "#XML_SetEntityDeclHandler" 20271a3ddf8cSespie>XML_SetEntityDeclHandler</a>.</p> 20281a3ddf8cSespie</div> 20291a3ddf8cSespie 20301a3ddf8cSespie<div class="handler"> 203108819b41Sbluhm<h4 id="XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</h4> 203208819b41Sbluhm<pre class="setter"> 20337d36914fSalekvoid XMLCALL 20341a3ddf8cSespieXML_SetNotationDeclHandler(XML_Parser p, 20351a3ddf8cSespie XML_NotationDeclHandler h) 20361a3ddf8cSespie</pre> 20371a3ddf8cSespie<pre class="signature"> 20381a3ddf8cSespietypedef void 20397d36914fSalek(XMLCALL *XML_NotationDeclHandler)(void *userData, 20401a3ddf8cSespie const XML_Char *notationName, 20411a3ddf8cSespie const XML_Char *base, 20421a3ddf8cSespie const XML_Char *systemId, 20431a3ddf8cSespie const XML_Char *publicId); 20441a3ddf8cSespie</pre> 20451a3ddf8cSespie<p>Set a handler that receives notation declarations.</p> 20461a3ddf8cSespie</div> 20471a3ddf8cSespie 20481a3ddf8cSespie<div class="handler"> 204908819b41Sbluhm<h4 id="XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</h4> 205008819b41Sbluhm<pre class="setter"> 20517d36914fSalekvoid XMLCALL 20521a3ddf8cSespieXML_SetNotStandaloneHandler(XML_Parser p, 20531a3ddf8cSespie XML_NotStandaloneHandler h) 20541a3ddf8cSespie</pre> 20551a3ddf8cSespie<pre class="signature"> 20561a3ddf8cSespietypedef int 20577d36914fSalek(XMLCALL *XML_NotStandaloneHandler)(void *userData); 20581a3ddf8cSespie</pre> 20591a3ddf8cSespie<p>Set a handler that is called if the document is not "standalone". 20601a3ddf8cSespieThis happens when there is an external subset or a reference to a 20611a3ddf8cSespieparameter entity, but does not have standalone set to "yes" in an XML 20621a3ddf8cSespiedeclaration. If this handler returns <code>XML_STATUS_ERROR</code>, 20631a3ddf8cSespiethen the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code> 20641a3ddf8cSespieerror.</p> 20651a3ddf8cSespie</div> 20661a3ddf8cSespie 20671a3ddf8cSespie<h3><a name="position">Parse position and error reporting functions</a></h3> 20681a3ddf8cSespie 20691a3ddf8cSespie<p>These are the functions you'll want to call when the parse 20701a3ddf8cSespiefunctions return <code>XML_STATUS_ERROR</code> (a parse error has 20717d36914fSalekoccurred), although the position reporting functions are useful outside 20721a3ddf8cSespieof errors. The position reported is the byte position (in the original 20731a3ddf8cSespiedocument or entity encoding) of the first of the sequence of 20741a3ddf8cSespiecharacters that generated the current event (or the error that caused 20757d36914fSalekthe parse functions to return <code>XML_STATUS_ERROR</code>.) The 20762a4a206eSbluhmexceptions are callbacks triggered by declarations in the document 20777d36914fSalekprologue, in which case they exact position reported is somewhere in the 20787d36914fSalekrelevant markup, but not necessarily as meaningful as for other 20797d36914fSalekevents.</p> 20801a3ddf8cSespie 20811a3ddf8cSespie<p>The position reporting functions are accurate only outside of the 20821a3ddf8cSespieDTD. In other words, they usually return bogus information when 20831a3ddf8cSespiecalled from within a DTD declaration handler.</p> 20841a3ddf8cSespie 208508819b41Sbluhm<h4 id="XML_GetErrorCode">XML_GetErrorCode</h4> 208608819b41Sbluhm<pre class="fcndec"> 20877d36914fSalekenum XML_Error XMLCALL 20881a3ddf8cSespieXML_GetErrorCode(XML_Parser p); 20891a3ddf8cSespie</pre> 20901a3ddf8cSespie<div class="fcndef"> 20911a3ddf8cSespieReturn what type of error has occurred. 20921a3ddf8cSespie</div> 20931a3ddf8cSespie 209408819b41Sbluhm<h4 id="XML_ErrorString">XML_ErrorString</h4> 209508819b41Sbluhm<pre class="fcndec"> 20967d36914fSalekconst XML_LChar * XMLCALL 20977d36914fSalekXML_ErrorString(enum XML_Error code); 20981a3ddf8cSespie</pre> 20991a3ddf8cSespie<div class="fcndef"> 21001a3ddf8cSespieReturn a string describing the error corresponding to code. 21011a3ddf8cSespieThe code should be one of the enums that can be returned from 21021a3ddf8cSespie<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>. 21031a3ddf8cSespie</div> 21041a3ddf8cSespie 210508819b41Sbluhm<h4 id="XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</h4> 210608819b41Sbluhm<pre class="fcndec"> 21077d36914fSalekXML_Index XMLCALL 21081a3ddf8cSespieXML_GetCurrentByteIndex(XML_Parser p); 21091a3ddf8cSespie</pre> 21101a3ddf8cSespie<div class="fcndef"> 21117d36914fSalekReturn the byte offset of the position. This always corresponds to 21127d36914fSalekthe values returned by <code><a href= "#XML_GetCurrentLineNumber" 21137d36914fSalek>XML_GetCurrentLineNumber</a></code> and <code><a href= 21147d36914fSalek"#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>. 21151a3ddf8cSespie</div> 21161a3ddf8cSespie 211708819b41Sbluhm<h4 id="XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</h4> 211808819b41Sbluhm<pre class="fcndec"> 21197d36914fSalekXML_Size XMLCALL 21201a3ddf8cSespieXML_GetCurrentLineNumber(XML_Parser p); 21211a3ddf8cSespie</pre> 21221a3ddf8cSespie<div class="fcndef"> 21237d36914fSalekReturn the line number of the position. The first line is reported as 21247d36914fSalek<code>1</code>. 21251a3ddf8cSespie</div> 21261a3ddf8cSespie 212708819b41Sbluhm<h4 id="XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</h4> 212808819b41Sbluhm<pre class="fcndec"> 21297d36914fSalekXML_Size XMLCALL 21301a3ddf8cSespieXML_GetCurrentColumnNumber(XML_Parser p); 21311a3ddf8cSespie</pre> 21321a3ddf8cSespie<div class="fcndef"> 21331a3ddf8cSespieReturn the offset, from the beginning of the current line, of 21341a3ddf8cSespiethe position. 21351a3ddf8cSespie</div> 21361a3ddf8cSespie 213708819b41Sbluhm<h4 id="XML_GetCurrentByteCount">XML_GetCurrentByteCount</h4> 213808819b41Sbluhm<pre class="fcndec"> 21397d36914fSalekint XMLCALL 21401a3ddf8cSespieXML_GetCurrentByteCount(XML_Parser p); 21411a3ddf8cSespie</pre> 21421a3ddf8cSespie<div class="fcndef"> 21431a3ddf8cSespieReturn the number of bytes in the current event. Returns 21441a3ddf8cSespie<code>0</code> if the event is inside a reference to an internal 21451a3ddf8cSespieentity and for the end-tag event for empty element tags (the later can 21461a3ddf8cSespiebe used to distinguish empty-element tags from empty elements using 21471a3ddf8cSespieseparate start and end tags). 21481a3ddf8cSespie</div> 21491a3ddf8cSespie 215008819b41Sbluhm<h4 id="XML_GetInputContext">XML_GetInputContext</h4> 215108819b41Sbluhm<pre class="fcndec"> 21527d36914fSalekconst char * XMLCALL 21531a3ddf8cSespieXML_GetInputContext(XML_Parser p, 21541a3ddf8cSespie int *offset, 21551a3ddf8cSespie int *size); 21561a3ddf8cSespie</pre> 21571a3ddf8cSespie<div class="fcndef"> 21581a3ddf8cSespie 21591a3ddf8cSespie<p>Returns the parser's input buffer, sets the integer pointed at by 21601a3ddf8cSespie<code>offset</code> to the offset within this buffer of the current 21611a3ddf8cSespieparse position, and set the integer pointed at by <code>size</code> to 21621a3ddf8cSespiethe size of the returned buffer.</p> 21631a3ddf8cSespie 21641a3ddf8cSespie<p>This should only be called from within a handler during an active 21651a3ddf8cSespieparse and the returned buffer should only be referred to from within 21661a3ddf8cSespiethe handler that made the call. This input buffer contains the 21671a3ddf8cSespieuntranslated bytes of the input.</p> 21681a3ddf8cSespie 21691a3ddf8cSespie<p>Only a limited amount of context is kept, so if the event 21701a3ddf8cSespietriggering a call spans over a very large amount of input, the actual 21711a3ddf8cSespieparse position may be before the beginning of the buffer.</p> 21727d36914fSalek 2173bd8f1dc3Sbluhm<p>If <code>XML_CONTEXT_BYTES</code> is zero, this will always 2174bd8f1dc3Sbluhmreturn <code>NULL</code>.</p> 21751a3ddf8cSespie</div> 21761a3ddf8cSespie 2177bd8f1dc3Sbluhm<h3><a name="attack-protection">Attack Protection</a><a name="billion-laughs"></a></h3> 217808819b41Sbluhm 217908819b41Sbluhm<h4 id="XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</h4> 218008819b41Sbluhm<pre class="fcndec"> 218108819b41Sbluhm/* Added in Expat 2.4.0. */ 218208819b41SbluhmXML_Bool XMLCALL 218308819b41SbluhmXML_SetBillionLaughsAttackProtectionMaximumAmplification(XML_Parser p, 218408819b41Sbluhm float maximumAmplificationFactor); 218508819b41Sbluhm</pre> 218608819b41Sbluhm<div class="fcndef"> 218708819b41Sbluhm <p> 218808819b41Sbluhm Sets the maximum tolerated amplification factor 218908819b41Sbluhm for protection against 219008819b41Sbluhm <a href="https://en.wikipedia.org/wiki/Billion_laughs_attack">billion laughs attacks</a> 219108819b41Sbluhm (default: <code>100.0</code>) 219208819b41Sbluhm of parser <code>p</code> to <code>maximumAmplificationFactor</code>, and 21932c19dcf8Sbluhm returns <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error. 219408819b41Sbluhm </p> 219508819b41Sbluhm 219608819b41Sbluhm The amplification factor is calculated as .. 219708819b41Sbluhm <pre> 219808819b41Sbluhm amplification := (direct + indirect) / direct 219908819b41Sbluhm </pre> 220008819b41Sbluhm .. while parsing, whereas 220108819b41Sbluhm <code>direct</code> is the number of bytes read from the primary document in parsing and 220208819b41Sbluhm <code>indirect</code> is the number of bytes added by expanding entities and reading of external DTD files, combined. 220308819b41Sbluhm 220408819b41Sbluhm <p>For a call to <code>XML_SetBillionLaughsAttackProtectionMaximumAmplification</code> to succeed:</p> 220508819b41Sbluhm <ul> 220608819b41Sbluhm <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without any parent parsers) and</li> 220708819b41Sbluhm <li><code>maximumAmplificationFactor</code> must be non-<code>NaN</code> and greater than or equal to <code>1.0</code>.</li> 220808819b41Sbluhm </ul> 220908819b41Sbluhm 221008819b41Sbluhm <p> 221108819b41Sbluhm <strong>Note:</strong> 221208819b41Sbluhm If you ever need to increase this value for non-attack payload, 221308819b41Sbluhm please <a href="https://github.com/libexpat/libexpat/issues">file a bug report</a>. 221408819b41Sbluhm </p> 221508819b41Sbluhm 221608819b41Sbluhm <p> 221708819b41Sbluhm <strong>Note:</strong> 221808819b41Sbluhm Peak amplifications 221908819b41Sbluhm of factor 15,000 for the entire payload and 222008819b41Sbluhm of factor 30,000 in the middle of parsing 222108819b41Sbluhm have been observed with small benign files in practice. 222208819b41Sbluhm 222308819b41Sbluhm So if you do reduce the maximum allowed amplification, 222408819b41Sbluhm please make sure that the activation threshold is still big enough 222508819b41Sbluhm to not end up with undesired false positives (i.e. benign files being rejected). 222608819b41Sbluhm </p> 222708819b41Sbluhm</div> 222808819b41Sbluhm 222908819b41Sbluhm<h4 id="XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</h4> 223008819b41Sbluhm<pre class="fcndec"> 223108819b41Sbluhm/* Added in Expat 2.4.0. */ 223208819b41SbluhmXML_Bool XMLCALL 223308819b41SbluhmXML_SetBillionLaughsAttackProtectionActivationThreshold(XML_Parser p, 223408819b41Sbluhm unsigned long long activationThresholdBytes); 223508819b41Sbluhm</pre> 223608819b41Sbluhm<div class="fcndef"> 223708819b41Sbluhm <p> 223808819b41Sbluhm Sets number of output bytes (including amplification from entity expansion and reading DTD files) 223908819b41Sbluhm needed to activate protection against 224008819b41Sbluhm <a href="https://en.wikipedia.org/wiki/Billion_laughs_attack">billion laughs attacks</a> 224108819b41Sbluhm (default: <code>8 MiB</code>) 224208819b41Sbluhm of parser <code>p</code> to <code>activationThresholdBytes</code>, and 22432c19dcf8Sbluhm returns <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error. 224408819b41Sbluhm </p> 224508819b41Sbluhm 224608819b41Sbluhm <p>For a call to <code>XML_SetBillionLaughsAttackProtectionActivationThreshold</code> to succeed:</p> 224708819b41Sbluhm <ul> 224808819b41Sbluhm <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without any parent parsers).</li> 224908819b41Sbluhm </ul> 225008819b41Sbluhm 225108819b41Sbluhm <p> 225208819b41Sbluhm <strong>Note:</strong> 225308819b41Sbluhm If you ever need to increase this value for non-attack payload, 225408819b41Sbluhm please <a href="https://github.com/libexpat/libexpat/issues">file a bug report</a>. 225508819b41Sbluhm </p> 225608819b41Sbluhm 225708819b41Sbluhm <p> 225808819b41Sbluhm <strong>Note:</strong> 225908819b41Sbluhm Activation thresholds below 4 MiB are known to break support for 226008819b41Sbluhm <a href="https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture">DITA</a> 1.3 payload 226108819b41Sbluhm and are hence not recommended. 226208819b41Sbluhm </p> 226308819b41Sbluhm</div> 226408819b41Sbluhm 2265bd8f1dc3Sbluhm<h4 id="XML_SetReparseDeferralEnabled">XML_SetReparseDeferralEnabled</h4> 2266bd8f1dc3Sbluhm<pre class="fcndec"> 2267bd8f1dc3Sbluhm/* Added in Expat 2.6.0. */ 2268bd8f1dc3SbluhmXML_Bool XMLCALL 2269bd8f1dc3SbluhmXML_SetReparseDeferralEnabled(XML_Parser parser, XML_Bool enabled); 2270bd8f1dc3Sbluhm</pre> 2271bd8f1dc3Sbluhm<div class="fcndef"> 2272bd8f1dc3Sbluhm <p> 2273bd8f1dc3Sbluhm Large tokens may require many parse calls before enough data is available for Expat to parse it in full. 2274bd8f1dc3Sbluhm If Expat retried parsing the token on every parse call, parsing could take quadratic time. 2275bd8f1dc3Sbluhm To avoid this, Expat only retries once a significant amount of new data is available. 2276bd8f1dc3Sbluhm This function allows disabling this behavior. 2277bd8f1dc3Sbluhm </p> 2278bd8f1dc3Sbluhm <p> 2279bd8f1dc3Sbluhm The <code>enabled</code> argument should be <code>XML_TRUE</code> or <code>XML_FALSE</code>. 2280bd8f1dc3Sbluhm </p> 2281bd8f1dc3Sbluhm <p> 2282bd8f1dc3Sbluhm Returns <code>XML_TRUE</code> on success, and <code>XML_FALSE</code> on error. 2283bd8f1dc3Sbluhm </p> 2284bd8f1dc3Sbluhm</div> 2285bd8f1dc3Sbluhm 22861a3ddf8cSespie<h3><a name="miscellaneous">Miscellaneous functions</a></h3> 22871a3ddf8cSespie 22881a3ddf8cSespie<p>The functions in this section either obtain state information from 22892e724bc9Sbluhmthe parser or can be used to dynamically set parser options.</p> 22901a3ddf8cSespie 229108819b41Sbluhm<h4 id="XML_SetUserData">XML_SetUserData</h4> 229208819b41Sbluhm<pre class="fcndec"> 22937d36914fSalekvoid XMLCALL 22941a3ddf8cSespieXML_SetUserData(XML_Parser p, 22951a3ddf8cSespie void *userData); 22961a3ddf8cSespie</pre> 22971a3ddf8cSespie<div class="fcndef"> 22981a3ddf8cSespieThis sets the user data pointer that gets passed to handlers. It 22991a3ddf8cSespieoverwrites any previous value for this pointer. Note that the 23001a3ddf8cSespieapplication is responsible for freeing the memory associated with 23011a3ddf8cSespie<code>userData</code> when it is finished with the parser. So if you 23021a3ddf8cSespiecall this when there's already a pointer there, and you haven't freed 23031a3ddf8cSespiethe memory associated with it, then you've probably just leaked 23041a3ddf8cSespiememory. 23051a3ddf8cSespie</div> 23061a3ddf8cSespie 230708819b41Sbluhm<h4 id="XML_GetUserData">XML_GetUserData</h4> 230808819b41Sbluhm<pre class="fcndec"> 23097d36914fSalekvoid * XMLCALL 23101a3ddf8cSespieXML_GetUserData(XML_Parser p); 23111a3ddf8cSespie</pre> 23121a3ddf8cSespie<div class="fcndef"> 23131a3ddf8cSespieThis returns the user data pointer that gets passed to handlers. 23141a3ddf8cSespieIt is actually implemented as a macro. 23151a3ddf8cSespie</div> 23161a3ddf8cSespie 231708819b41Sbluhm<h4 id="XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</h4> 231808819b41Sbluhm<pre class="fcndec"> 23197d36914fSalekvoid XMLCALL 23201a3ddf8cSespieXML_UseParserAsHandlerArg(XML_Parser p); 23211a3ddf8cSespie</pre> 23221a3ddf8cSespie<div class="fcndef"> 23231a3ddf8cSespieAfter this is called, handlers receive the parser in their 23241a3ddf8cSespie<code>userData</code> arguments. The user data can still be obtained 23251a3ddf8cSespieusing the <code><a href= "#XML_GetUserData" 23261a3ddf8cSespie>XML_GetUserData</a></code> function. 23271a3ddf8cSespie</div> 23281a3ddf8cSespie 232908819b41Sbluhm<h4 id="XML_SetBase">XML_SetBase</h4> 233008819b41Sbluhm<pre class="fcndec"> 23317d36914fSalekenum XML_Status XMLCALL 23321a3ddf8cSespieXML_SetBase(XML_Parser p, 23331a3ddf8cSespie const XML_Char *base); 23341a3ddf8cSespie</pre> 23351a3ddf8cSespie<div class="fcndef"> 23361a3ddf8cSespieSet the base to be used for resolving relative URIs in system 23371a3ddf8cSespieidentifiers. The return value is <code>XML_STATUS_ERROR</code> if 23381a3ddf8cSespiethere's no memory to store base, otherwise it's 23391a3ddf8cSespie<code>XML_STATUS_OK</code>. 23401a3ddf8cSespie</div> 23411a3ddf8cSespie 234208819b41Sbluhm<h4 id="XML_GetBase">XML_GetBase</h4> 234308819b41Sbluhm<pre class="fcndec"> 23447d36914fSalekconst XML_Char * XMLCALL 23451a3ddf8cSespieXML_GetBase(XML_Parser p); 23461a3ddf8cSespie</pre> 23471a3ddf8cSespie<div class="fcndef"> 23481a3ddf8cSespieReturn the base for resolving relative URIs. 23491a3ddf8cSespie</div> 23501a3ddf8cSespie 235108819b41Sbluhm<h4 id="XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</h4> 235208819b41Sbluhm<pre class="fcndec"> 23537d36914fSalekint XMLCALL 23541a3ddf8cSespieXML_GetSpecifiedAttributeCount(XML_Parser p); 23551a3ddf8cSespie</pre> 23561a3ddf8cSespie<div class="fcndef"> 23571a3ddf8cSespieWhen attributes are reported to the start handler in the atts vector, 23581a3ddf8cSespieattributes that were explicitly set in the element occur before any 23591a3ddf8cSespieattributes that receive their value from default information in an 23601a3ddf8cSespieATTLIST declaration. This function returns the number of attributes 23611a3ddf8cSespiethat were explicitly set times two, thus giving the offset in the 23621a3ddf8cSespie<code>atts</code> array passed to the start tag handler of the first 23631a3ddf8cSespieattribute set due to defaults. It supplies information for the last 23641a3ddf8cSespiecall to a start handler. If called inside a start handler, then that 23651a3ddf8cSespiemeans the current call. 23661a3ddf8cSespie</div> 23671a3ddf8cSespie 236808819b41Sbluhm<h4 id="XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</h4> 236908819b41Sbluhm<pre class="fcndec"> 23707d36914fSalekint XMLCALL 23711a3ddf8cSespieXML_GetIdAttributeIndex(XML_Parser p); 23721a3ddf8cSespie</pre> 23731a3ddf8cSespie<div class="fcndef"> 23741a3ddf8cSespieReturns the index of the ID attribute passed in the atts array in the 23751a3ddf8cSespielast call to <code><a href= "#XML_StartElementHandler" 23761a3ddf8cSespie>XML_StartElementHandler</a></code>, or -1 if there is no ID 23771a3ddf8cSespieattribute. If called inside a start handler, then that means the 23781a3ddf8cSespiecurrent call. 23791a3ddf8cSespie</div> 23801a3ddf8cSespie 238108819b41Sbluhm<h4 id="XML_GetAttributeInfo">XML_GetAttributeInfo</h4> 238208819b41Sbluhm<pre class="fcndec"> 23836400bc34Srpointelconst XML_AttrInfo * XMLCALL 23846400bc34SrpointelXML_GetAttributeInfo(XML_Parser parser); 23856400bc34Srpointel</pre> 23866400bc34Srpointel<pre class="signature"> 23876400bc34Srpointeltypedef struct { 23886400bc34Srpointel XML_Index nameStart; /* Offset to beginning of the attribute name. */ 23896400bc34Srpointel XML_Index nameEnd; /* Offset after the attribute name's last byte. */ 23906400bc34Srpointel XML_Index valueStart; /* Offset to beginning of the attribute value. */ 23916400bc34Srpointel XML_Index valueEnd; /* Offset after the attribute value's last byte. */ 23926400bc34Srpointel} XML_AttrInfo; 23936400bc34Srpointel</pre> 23946400bc34Srpointel<div class="fcndef"> 23956400bc34SrpointelReturns an array of <code>XML_AttrInfo</code> structures for the 23966400bc34Srpointelattribute/value pairs passed in the last call to the 23976400bc34Srpointel<code>XML_StartElementHandler</code> that were specified 23986400bc34Srpointelin the start-tag rather than defaulted. Each attribute/value pair counts 23996400bc34Srpointelas 1; thus the number of entries in the array is 24006400bc34Srpointel<code>XML_GetSpecifiedAttributeCount(parser) / 2</code>. 24016400bc34Srpointel</div> 24026400bc34Srpointel 240308819b41Sbluhm<h4 id="XML_SetEncoding">XML_SetEncoding</h4> 240408819b41Sbluhm<pre class="fcndec"> 24057d36914fSalekenum XML_Status XMLCALL 24061a3ddf8cSespieXML_SetEncoding(XML_Parser p, 24071a3ddf8cSespie const XML_Char *encoding); 24081a3ddf8cSespie</pre> 24091a3ddf8cSespie<div class="fcndef"> 24101a3ddf8cSespieSet the encoding to be used by the parser. It is equivalent to 2411bd8f1dc3Sbluhmpassing a non-<code>NULL</code> encoding argument to the parser creation functions. 24121a3ddf8cSespieIt must not be called after <code><a href= "#XML_Parse" 24131a3ddf8cSespie>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 24141a3ddf8cSespie>XML_ParseBuffer</a></code> have been called on the given parser. 24151a3ddf8cSespieReturns <code>XML_STATUS_OK</code> on success or 24161a3ddf8cSespie<code>XML_STATUS_ERROR</code> on error. 24171a3ddf8cSespie</div> 24181a3ddf8cSespie 241908819b41Sbluhm<h4 id="XML_SetParamEntityParsing">XML_SetParamEntityParsing</h4> 242008819b41Sbluhm<pre class="fcndec"> 24217d36914fSalekint XMLCALL 24221a3ddf8cSespieXML_SetParamEntityParsing(XML_Parser p, 24231a3ddf8cSespie enum XML_ParamEntityParsing code); 24241a3ddf8cSespie</pre> 24251a3ddf8cSespie<div class="fcndef"> 24261a3ddf8cSespieThis enables parsing of parameter entities, including the external 24271a3ddf8cSespieparameter entity that is the external DTD subset, according to 24281a3ddf8cSespie<code>code</code>. 24291a3ddf8cSespieThe choices for <code>code</code> are: 24301a3ddf8cSespie<ul> 24311a3ddf8cSespie<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li> 24321a3ddf8cSespie<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li> 24331a3ddf8cSespie<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li> 24341a3ddf8cSespie</ul> 24356400bc34Srpointel<b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after 24366400bc34Srpointel<code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has 24376400bc34Srpointelno effect and will always return 0. 24386400bc34Srpointel</div> 24396400bc34Srpointel 244008819b41Sbluhm<h4 id="XML_SetHashSalt">XML_SetHashSalt</h4> 244108819b41Sbluhm<pre class="fcndec"> 24426400bc34Srpointelint XMLCALL 24436400bc34SrpointelXML_SetHashSalt(XML_Parser p, 24446400bc34Srpointel unsigned long hash_salt); 24456400bc34Srpointel</pre> 24466400bc34Srpointel<div class="fcndef"> 24476400bc34SrpointelSets the hash salt to use for internal hash calculations. 24486400bc34SrpointelHelps in preventing DoS attacks based on predicting hash 24496400bc34Srpointelfunction behavior. In order to have an effect this must be called 24506400bc34Srpointelbefore parsing has started. Returns 1 if successful, 0 when called 24516400bc34Srpointelafter <code>XML_Parse</code> or <code>XML_ParseBuffer</code>. 2452695f0d7bSrpointel<p><b>Note:</b> This call is optional, as the parser will auto-generate 245328ce3119Sbluhma new random salt value if no value has been set at the start of parsing.</p> 2454695f0d7bSrpointel<p><b>Note:</b> One should not call <code>XML_SetHashSalt</code> with a 2455695f0d7bSrpointelhash salt value of 0, as this value is used as sentinel value to indicate 2456695f0d7bSrpointelthat <code>XML_SetHashSalt</code> has <b>not</b> been called. Consequently 2457695f0d7bSrpointelsuch a call will have no effect, even if it returns 1.</p> 24581a3ddf8cSespie</div> 24591a3ddf8cSespie 246008819b41Sbluhm<h4 id="XML_UseForeignDTD">XML_UseForeignDTD</h4> 246108819b41Sbluhm<pre class="fcndec"> 24627d36914fSalekenum XML_Error XMLCALL 24631a3ddf8cSespieXML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); 24641a3ddf8cSespie</pre> 24651a3ddf8cSespie<div class="fcndef"> 24661a3ddf8cSespie<p>This function allows an application to provide an external subset 24671a3ddf8cSespiefor the document type declaration for documents which do not specify 24681a3ddf8cSespiean external subset of their own. For documents which specify an 24691a3ddf8cSespieexternal subset in their DOCTYPE declaration, the application-provided 24701a3ddf8cSespiesubset will be ignored. If the document does not contain a DOCTYPE 24711a3ddf8cSespiedeclaration at all and <code>useDTD</code> is true, the 24721a3ddf8cSespieapplication-provided subset will be parsed, but the 24731a3ddf8cSespie<code>startDoctypeDeclHandler</code> and 24741a3ddf8cSespie<code>endDoctypeDeclHandler</code> functions, if set, will not be 24751a3ddf8cSespiecalled. The setting of parameter entity parsing, controlled using 24761a3ddf8cSespie<code><a href= "#XML_SetParamEntityParsing" 24771a3ddf8cSespie>XML_SetParamEntityParsing</a></code>, will be honored.</p> 24781a3ddf8cSespie 24791a3ddf8cSespie<p>The application-provided external subset is read by calling the 24801a3ddf8cSespieexternal entity reference handler set via <code><a href= 24811a3ddf8cSespie"#XML_SetExternalEntityRefHandler" 24821a3ddf8cSespie>XML_SetExternalEntityRefHandler</a></code> with both 2483bd8f1dc3Sbluhm<code>publicId</code> and <code>systemId</code> set to <code>NULL</code>.</p> 24841a3ddf8cSespie 24851a3ddf8cSespie<p>If this function is called after parsing has begun, it returns 24861a3ddf8cSespie<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores 24871a3ddf8cSespie<code>useDTD</code>. If called when Expat has been compiled without 24881a3ddf8cSespieDTD support, it returns 24891a3ddf8cSespie<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise, it 24901a3ddf8cSespiereturns <code>XML_ERROR_NONE</code>.</p> 24917d36914fSalek 24927d36914fSalek<p><b>Note:</b> For the purpose of checking WFC: Entity Declared, passing 24937d36914fSalek<code>useDTD == XML_TRUE</code> will make the parser behave as if 24947d36914fSalekthe document had a DTD with an external subset. This holds true even if 24957d36914fSalekthe external entity reference handler returns without action.</p> 24961a3ddf8cSespie</div> 24971a3ddf8cSespie 249808819b41Sbluhm<h4 id="XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</h4> 249908819b41Sbluhm<pre class="fcndec"> 25007d36914fSalekvoid XMLCALL 25011a3ddf8cSespieXML_SetReturnNSTriplet(XML_Parser parser, 25021a3ddf8cSespie int do_nst); 25031a3ddf8cSespie</pre> 25041a3ddf8cSespie<div class="fcndef"> 25051a3ddf8cSespie<p> 25061a3ddf8cSespieThis function only has an effect when using a parser created with 25071a3ddf8cSespie<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, 25081a3ddf8cSespiei.e. when namespace processing is in effect. The <code>do_nst</code> 25091a3ddf8cSespiesets whether or not prefixes are returned with names qualified with a 25101a3ddf8cSespienamespace prefix. If this function is called with <code>do_nst</code> 25111a3ddf8cSespienon-zero, then afterwards namespace qualified names (that is qualified 25121a3ddf8cSespiewith a prefix as opposed to belonging to a default namespace) are 25131a3ddf8cSespiereturned as a triplet with the three parts separated by the namespace 25141a3ddf8cSespieseparator specified when the parser was created. The order of 25151a3ddf8cSespiereturned parts is URI, local name, and prefix.</p> <p>If 25161a3ddf8cSespie<code>do_nst</code> is zero, then namespaces are reported in the 25171a3ddf8cSespiedefault manner, URI then local_name separated by the namespace 25181a3ddf8cSespieseparator.</p> 25191a3ddf8cSespie</div> 25201a3ddf8cSespie 252108819b41Sbluhm<h4 id="XML_DefaultCurrent">XML_DefaultCurrent</h4> 252208819b41Sbluhm<pre class="fcndec"> 25237d36914fSalekvoid XMLCALL 25241a3ddf8cSespieXML_DefaultCurrent(XML_Parser parser); 25251a3ddf8cSespie</pre> 25261a3ddf8cSespie<div class="fcndef"> 25271a3ddf8cSespieThis can be called within a handler for a start element, end element, 25281a3ddf8cSespieprocessing instruction or character data. It causes the corresponding 25291a3ddf8cSespiemarkup to be passed to the default handler set by <code><a 25301a3ddf8cSespiehref="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or 25311a3ddf8cSespie<code><a href="#XML_SetDefaultHandlerExpand" 25321a3ddf8cSespie>XML_SetDefaultHandlerExpand</a></code>. It does nothing if there is 25331a3ddf8cSespienot a default handler. 25341a3ddf8cSespie</div> 25351a3ddf8cSespie 253608819b41Sbluhm<h4 id="XML_ExpatVersion">XML_ExpatVersion</h4> 253708819b41Sbluhm<pre class="fcndec"> 25387d36914fSalekXML_LChar * XMLCALL 25391a3ddf8cSespieXML_ExpatVersion(); 25401a3ddf8cSespie</pre> 25411a3ddf8cSespie<div class="fcndef"> 25421a3ddf8cSespieReturn the library version as a string (e.g. <code>"expat_1.95.1"</code>). 25431a3ddf8cSespie</div> 25441a3ddf8cSespie 254508819b41Sbluhm<h4 id="XML_ExpatVersionInfo">XML_ExpatVersionInfo</h4> 254608819b41Sbluhm<pre class="fcndec"> 25477d36914fSalekstruct XML_Expat_Version XMLCALL 25481a3ddf8cSespieXML_ExpatVersionInfo(); 25491a3ddf8cSespie</pre> 25501a3ddf8cSespie<pre class="signature"> 25511a3ddf8cSespietypedef struct { 25521a3ddf8cSespie int major; 25531a3ddf8cSespie int minor; 25541a3ddf8cSespie int micro; 25551a3ddf8cSespie} XML_Expat_Version; 25561a3ddf8cSespie</pre> 25571a3ddf8cSespie<div class="fcndef"> 25581a3ddf8cSespieReturn the library version information as a structure. 25591a3ddf8cSespieSome macros are also defined that support compile-time tests of the 25601a3ddf8cSespielibrary version: 25611a3ddf8cSespie<ul> 25621a3ddf8cSespie<li><code>XML_MAJOR_VERSION</code></li> 25631a3ddf8cSespie<li><code>XML_MINOR_VERSION</code></li> 25641a3ddf8cSespie<li><code>XML_MICRO_VERSION</code></li> 25651a3ddf8cSespie</ul> 25661a3ddf8cSespieTesting these constants is currently the best way to determine if 25671a3ddf8cSespieparticular parts of the Expat API are available. 25681a3ddf8cSespie</div> 25691a3ddf8cSespie 257008819b41Sbluhm<h4 id="XML_GetFeatureList">XML_GetFeatureList</h4> 257108819b41Sbluhm<pre class="fcndec"> 25727d36914fSalekconst XML_Feature * XMLCALL 25731a3ddf8cSespieXML_GetFeatureList(); 25741a3ddf8cSespie</pre> 25751a3ddf8cSespie<pre class="signature"> 25761a3ddf8cSespieenum XML_FeatureEnum { 25771a3ddf8cSespie XML_FEATURE_END = 0, 25781a3ddf8cSespie XML_FEATURE_UNICODE, 25791a3ddf8cSespie XML_FEATURE_UNICODE_WCHAR_T, 25801a3ddf8cSespie XML_FEATURE_DTD, 25811a3ddf8cSespie XML_FEATURE_CONTEXT_BYTES, 25821a3ddf8cSespie XML_FEATURE_MIN_SIZE, 25831a3ddf8cSespie XML_FEATURE_SIZEOF_XML_CHAR, 2584b26ab0f8Smatthieu XML_FEATURE_SIZEOF_XML_LCHAR, 2585b26ab0f8Smatthieu XML_FEATURE_NS, 2586b26ab0f8Smatthieu XML_FEATURE_LARGE_SIZE 25871a3ddf8cSespie}; 25881a3ddf8cSespie 25891a3ddf8cSespietypedef struct { 25901a3ddf8cSespie enum XML_FeatureEnum feature; 25911a3ddf8cSespie XML_LChar *name; 25921a3ddf8cSespie long int value; 25931a3ddf8cSespie} XML_Feature; 25941a3ddf8cSespie</pre> 25951a3ddf8cSespie<div class="fcndef"> 25961a3ddf8cSespie<p>Returns a list of "feature" records, providing details on how 25971a3ddf8cSespieExpat was configured at compile time. Most applications should not 25981a3ddf8cSespieneed to worry about this, but this information is otherwise not 25991a3ddf8cSespieavailable from Expat. This function allows code that does need to 26001a3ddf8cSespiecheck these features to do so at runtime.</p> 26011a3ddf8cSespie 26021a3ddf8cSespie<p>The return value is an array of <code>XML_Feature</code>, 26031a3ddf8cSespieterminated by a record with a <code>feature</code> of 2604bd8f1dc3Sbluhm<code>XML_FEATURE_END</code> and <code>name</code> of <code>NULL</code>, 26051a3ddf8cSespieidentifying the feature-test macros Expat was compiled with. Since an 26061a3ddf8cSespieapplication that requires this kind of information needs to determine 26071a3ddf8cSespiethe type of character the <code>name</code> points to, records for the 26081a3ddf8cSespie<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and 26091a3ddf8cSespie<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the 26101a3ddf8cSespiebeginning of the list, followed by <code>XML_FEATURE_UNICODE</code> 26111a3ddf8cSespieand <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at 26121a3ddf8cSespieall.</p> 26131a3ddf8cSespie 26141a3ddf8cSespie<p>Some features have an associated value. If there isn't an 26151a3ddf8cSespieassociated value, the <code>value</code> field is set to 0. At this 26161a3ddf8cSespietime, the following features have been defined to have values:</p> 26171a3ddf8cSespie 26181a3ddf8cSespie<dl> 26191a3ddf8cSespie <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt> 26201a3ddf8cSespie <dd>The number of bytes occupied by one <code>XML_Char</code> 26211a3ddf8cSespie character.</dd> 26221a3ddf8cSespie <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt> 26231a3ddf8cSespie <dd>The number of bytes occupied by one <code>XML_LChar</code> 26241a3ddf8cSespie character.</dd> 26251a3ddf8cSespie <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt> 26261a3ddf8cSespie <dd>The maximum number of characters of context which can be 26271a3ddf8cSespie reported by <code><a href= "#XML_GetInputContext" 26281a3ddf8cSespie >XML_GetInputContext</a></code>.</dd> 26291a3ddf8cSespie</dl> 26301a3ddf8cSespie</div> 26311a3ddf8cSespie 263208819b41Sbluhm<h4 id="XML_FreeContentModel">XML_FreeContentModel</h4> 263308819b41Sbluhm<pre class="fcndec"> 26347d36914fSalekvoid XMLCALL 26351a3ddf8cSespieXML_FreeContentModel(XML_Parser parser, XML_Content *model); 26361a3ddf8cSespie</pre> 26371a3ddf8cSespie<div class="fcndef"> 26381a3ddf8cSespieFunction to deallocate the <code>model</code> argument passed to the 26391a3ddf8cSespie<code>XML_ElementDeclHandler</code> callback set using <code><a 26401a3ddf8cSespiehref="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>. 26411a3ddf8cSespieThis function should not be used for any other purpose. 26421a3ddf8cSespie</div> 26431a3ddf8cSespie 26441a3ddf8cSespie<p>The following functions allow external code to share the memory 26451a3ddf8cSespieallocator an <code>XML_Parser</code> has been configured to use. This 26461a3ddf8cSespieis especially useful for third-party libraries that interact with a 26471a3ddf8cSespieparser object created by application code, or heavily layered 26481a3ddf8cSespieapplications. This can be essential when using dynamically loaded 26491a3ddf8cSespielibraries which use different C standard libraries (this can happen on 26501a3ddf8cSespieWindows, at least).</p> 26511a3ddf8cSespie 265208819b41Sbluhm<h4 id="XML_MemMalloc">XML_MemMalloc</h4> 265308819b41Sbluhm<pre class="fcndec"> 26547d36914fSalekvoid * XMLCALL 26551a3ddf8cSespieXML_MemMalloc(XML_Parser parser, size_t size); 26561a3ddf8cSespie</pre> 26571a3ddf8cSespie<div class="fcndef"> 26581a3ddf8cSespieAllocate <code>size</code> bytes of memory using the allocator the 26591a3ddf8cSespie<code>parser</code> object has been configured to use. Returns a 2660bd8f1dc3Sbluhmpointer to the memory or <code>NULL</code> on failure. Memory allocated in this 26611a3ddf8cSespieway must be freed using <code><a href="#XML_MemFree" 26621a3ddf8cSespie>XML_MemFree</a></code>. 26631a3ddf8cSespie</div> 26641a3ddf8cSespie 266508819b41Sbluhm<h4 id="XML_MemRealloc">XML_MemRealloc</h4> 266608819b41Sbluhm<pre class="fcndec"> 26677d36914fSalekvoid * XMLCALL 26681a3ddf8cSespieXML_MemRealloc(XML_Parser parser, void *ptr, size_t size); 26691a3ddf8cSespie</pre> 26701a3ddf8cSespie<div class="fcndef"> 26711a3ddf8cSespieAllocate <code>size</code> bytes of memory using the allocator the 26721a3ddf8cSespie<code>parser</code> object has been configured to use. 26731a3ddf8cSespie<code>ptr</code> must point to a block of memory allocated by <code><a 26741a3ddf8cSespiehref="#XML_MemMalloc" >XML_MemMalloc</a></code> or 2675bd8f1dc3Sbluhm<code>XML_MemRealloc</code>, or be <code>NULL</code>. This function tries to 26761a3ddf8cSespieexpand the block pointed to by <code>ptr</code> if possible. Returns 2677bd8f1dc3Sbluhma pointer to the memory or <code>NULL</code> on failure. On success, the original 26781a3ddf8cSespieblock has either been expanded or freed. On failure, the original 26791a3ddf8cSespieblock has not been freed; the caller is responsible for freeing the 26801a3ddf8cSespieoriginal block. Memory allocated in this way must be freed using 26811a3ddf8cSespie<code><a href="#XML_MemFree" 26821a3ddf8cSespie>XML_MemFree</a></code>. 26831a3ddf8cSespie</div> 26841a3ddf8cSespie 268508819b41Sbluhm<h4 id="XML_MemFree">XML_MemFree</h4> 268608819b41Sbluhm<pre class="fcndec"> 26877d36914fSalekvoid XMLCALL 26881a3ddf8cSespieXML_MemFree(XML_Parser parser, void *ptr); 26891a3ddf8cSespie</pre> 26901a3ddf8cSespie<div class="fcndef"> 26911a3ddf8cSespieFree a block of memory pointed to by <code>ptr</code>. The block must 26921a3ddf8cSespiehave been allocated by <code><a href="#XML_MemMalloc" 2693bd8f1dc3Sbluhm>XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be <code>NULL</code>. 26941a3ddf8cSespie</div> 26951a3ddf8cSespie 26961a3ddf8cSespie<hr /> 269708819b41Sbluhm 269808819b41Sbluhm <div class="footer"> 269908819b41Sbluhm Found a bug in the documentation? 270008819b41Sbluhm <a href="https://github.com/libexpat/libexpat/issues">Please file a bug report.</a> 270108819b41Sbluhm </div> 270208819b41Sbluhm 27037d36914fSalek</div> 27041a3ddf8cSespie</body> 27051a3ddf8cSespie</html> 2706
