1104349Sphk<?xml version="1.0" encoding="iso-8859-1"?> 2104349Sphk<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 3104349Sphk "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 4104349Sphk<html> 5104349Sphk<head> 6104349Sphk<!-- Copyright 1999,2000 Clark Cooper <coopercc@netheaven.com> 7104349Sphk All rights reserved. 8104349Sphk This is free software. You may distribute or modify according to 9104349Sphk the terms of the MIT/X License --> 10104349Sphk <title>Expat XML Parser</title> 11104349Sphk <meta name="author" content="Clark Cooper, coopercc@netheaven.com" /> 12104349Sphk <meta http-equiv="Content-Style-Type" content="text/css" /> 13104349Sphk <link href="style.css" rel="stylesheet" type="text/css" /> 14104349Sphk</head> 15104349Sphk<body> 16178848Scokane <table cellspacing="0" cellpadding="0" width="100%"> 17178848Scokane <tr> 18178848Scokane <td class="corner"><img src="expat.png" alt="(Expat logo)" /></td> 19178848Scokane <td class="banner"><h1>The Expat XML Parser</h1></td> 20178848Scokane </tr> 21178848Scokane <tr> 22178848Scokane <td class="releaseno">Release 2.0.1</td> 23178848Scokane <td></td> 24178848Scokane </tr> 25178848Scokane </table> 26178848Scokane<div class="content"> 27104349Sphk 28104349Sphk<p>Expat is a library, written in C, for parsing XML documents. It's 29104349Sphkthe underlying XML parser for the open source Mozilla project, Perl's 30104349Sphk<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and 31104349Sphkother open-source XML parsers.</p> 32104349Sphk 33104349Sphk<p>This library is the creation of James Clark, who's also given us 34104349Sphkgroff (an nroff look-alike), Jade (an implemention of ISO's DSSSL 35104349Sphkstylesheet language for SGML), XP (a Java XML parser package), XT (a 36104349SphkJava XSL engine). James was also the technical lead on the XML 37104349SphkWorking Group at W3C that produced the XML specification.</p> 38104349Sphk 39104349Sphk<p>This is free software, licensed under the <a 40104349Sphkhref="../COPYING">MIT/X Consortium license</a>. You may download it 41104349Sphkfrom <a href="http://www.libexpat.org/">the Expat home page</a>. 42104349Sphk</p> 43104349Sphk 44178848Scokane<p>The bulk of this document was originally commissioned as an article 45178848Scokaneby <a href="http://www.xml.com/">XML.com</a>. They graciously allowed 46178848ScokaneClark Cooper to retain copyright and to distribute it with Expat. 47178848ScokaneThis version has been substantially extended to include documentation 48178848Scokaneon features which have been added since the original article was 49178848Scokanepublished, and additional information on using the original 50178848Scokaneinterface.</p> 51104349Sphk 52104349Sphk<hr /> 53104349Sphk<h2>Table of Contents</h2> 54104349Sphk<ul> 55104349Sphk <li><a href="#overview">Overview</a></li> 56104349Sphk <li><a href="#building">Building and Installing</a></li> 57104349Sphk <li><a href="#using">Using Expat</a></li> 58104349Sphk <li><a href="#reference">Reference</a> 59104349Sphk <ul> 60104349Sphk <li><a href="#creation">Parser Creation Functions</a> 61104349Sphk <ul> 62104349Sphk <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li> 63104349Sphk <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li> 64104349Sphk <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li> 65104349Sphk <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li> 66104349Sphk <li><a href="#XML_ParserFree">XML_ParserFree</a></li> 67104349Sphk <li><a href="#XML_ParserReset">XML_ParserReset</a></li> 68104349Sphk </ul> 69104349Sphk </li> 70104349Sphk <li><a href="#parsing">Parsing Functions</a> 71104349Sphk <ul> 72104349Sphk <li><a href="#XML_Parse">XML_Parse</a></li> 73104349Sphk <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li> 74104349Sphk <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li> 75178848Scokane <li><a href="#XML_StopParser">XML_StopParser</a></li> 76178848Scokane <li><a href="#XML_ResumeParser">XML_ResumeParser</a></li> 77178848Scokane <li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li> 78104349Sphk </ul> 79104349Sphk </li> 80104349Sphk <li><a href="#setting">Handler Setting Functions</a> 81104349Sphk <ul> 82104349Sphk <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li> 83104349Sphk <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li> 84104349Sphk <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li> 85104349Sphk <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li> 86104349Sphk <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li> 87104349Sphk <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li> 88104349Sphk <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li> 89104349Sphk <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li> 90104349Sphk <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li> 91104349Sphk <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li> 92104349Sphk <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li> 93104349Sphk <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li> 94178848Scokane <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li> 95104349Sphk <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li> 96104349Sphk <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li> 97104349Sphk <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li> 98104349Sphk <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li> 99104349Sphk <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li> 100104349Sphk <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li> 101104349Sphk <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li> 102104349Sphk <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li> 103104349Sphk <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li> 104104349Sphk <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li> 105104349Sphk <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li> 106104349Sphk <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li> 107104349Sphk <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li> 108104349Sphk <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li> 109104349Sphk <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li> 110104349Sphk </ul> 111104349Sphk </li> 112104349Sphk <li><a href="#position">Parse Position and Error Reporting Functions</a> 113104349Sphk <ul> 114104349Sphk <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li> 115104349Sphk <li><a href="#XML_ErrorString">XML_ErrorString</a></li> 116104349Sphk <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li> 117104349Sphk <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li> 118104349Sphk <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li> 119104349Sphk <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li> 120104349Sphk <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li> 121104349Sphk </ul> 122104349Sphk </li> 123104349Sphk <li><a href="#miscellaneous">Miscellaneous Functions</a> 124104349Sphk <ul> 125104349Sphk <li><a href="#XML_SetUserData">XML_SetUserData</a></li> 126104349Sphk <li><a href="#XML_GetUserData">XML_GetUserData</a></li> 127104349Sphk <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li> 128104349Sphk <li><a href="#XML_SetBase">XML_SetBase</a></li> 129104349Sphk <li><a href="#XML_GetBase">XML_GetBase</a></li> 130104349Sphk <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li> 131104349Sphk <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li> 132247513Sdelphij <li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li> 133104349Sphk <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li> 134104349Sphk <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li> 135247513Sdelphij <li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li> 136104349Sphk <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li> 137104349Sphk <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li> 138104349Sphk <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li> 139104349Sphk <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li> 140104349Sphk <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li> 141104349Sphk <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li> 142178848Scokane <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li> 143178848Scokane <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li> 144178848Scokane <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li> 145178848Scokane <li><a href="#XML_MemFree">XML_MemFree</a></li> 146104349Sphk </ul> 147104349Sphk </li> 148104349Sphk </ul> 149104349Sphk </li> 150104349Sphk</ul> 151104349Sphk 152104349Sphk<hr /> 153104349Sphk<h2><a name="overview">Overview</a></h2> 154104349Sphk 155104349Sphk<p>Expat is a stream-oriented parser. You register callback (or 156104349Sphkhandler) functions with the parser and then start feeding it the 157104349Sphkdocument. As the parser recognizes parts of the document, it will 158104349Sphkcall the appropriate handler for that part (if you've registered one.) 159104349SphkThe document is fed to the parser in pieces, so you can start parsing 160104349Sphkbefore you have all the document. This also allows you to parse really 161104349Sphkhuge documents that won't fit into memory.</p> 162104349Sphk 163104349Sphk<p>Expat can be intimidating due to the many kinds of handlers and 164104349Sphkoptions you can set. But you only need to learn four functions in 165104349Sphkorder to do 90% of what you'll want to do with it:</p> 166104349Sphk 167104349Sphk<dl> 168104349Sphk 169104349Sphk<dt><code><a href= "#XML_ParserCreate" 170104349Sphk >XML_ParserCreate</a></code></dt> 171104349Sphk <dd>Create a new parser object.</dd> 172104349Sphk 173104349Sphk<dt><code><a href= "#XML_SetElementHandler" 174104349Sphk >XML_SetElementHandler</a></code></dt> 175104349Sphk <dd>Set handlers for start and end tags.</dd> 176104349Sphk 177104349Sphk<dt><code><a href= "#XML_SetCharacterDataHandler" 178104349Sphk >XML_SetCharacterDataHandler</a></code></dt> 179104349Sphk <dd>Set handler for text.</dd> 180104349Sphk 181104349Sphk<dt><code><a href= "#XML_Parse" 182104349Sphk >XML_Parse</a></code></dt> 183104349Sphk <dd>Pass a buffer full of document to the parser</dd> 184104349Sphk</dl> 185104349Sphk 186104349Sphk<p>These functions and others are described in the <a 187104349Sphkhref="#reference">reference</a> part of this document. The reference 188104349Sphksection also describes in detail the parameters passed to the 189104349Sphkdifferent types of handlers.</p> 190104349Sphk 191104349Sphk<p>Let's look at a very simple example program that only uses 3 of the 192104349Sphkabove functions (it doesn't need to set a character handler.) The 193104349Sphkprogram <a href="../examples/outline.c">outline.c</a> prints an 194104349Sphkelement outline, indenting child elements to distinguish them from the 195104349Sphkparent element that contains them. The start handler does all the 196104349Sphkwork. It prints two indenting spaces for every level of ancestor 197104349Sphkelements, then it prints the element and attribute 198104349Sphkinformation. Finally it increments the global <code>Depth</code> 199104349Sphkvariable.</p> 200104349Sphk 201104349Sphk<pre class="eg"> 202104349Sphkint Depth; 203104349Sphk 204178848Scokanevoid XMLCALL 205104349Sphkstart(void *data, const char *el, const char **attr) { 206104349Sphk int i; 207104349Sphk 208104349Sphk for (i = 0; i < Depth; i++) 209104349Sphk printf(" "); 210104349Sphk 211104349Sphk printf("%s", el); 212104349Sphk 213104349Sphk for (i = 0; attr[i]; i += 2) { 214104349Sphk printf(" %s='%s'", attr[i], attr[i + 1]); 215104349Sphk } 216104349Sphk 217104349Sphk printf("\n"); 218104349Sphk Depth++; 219104349Sphk} /* End of start handler */ 220104349Sphk</pre> 221104349Sphk 222104349Sphk<p>The end tag simply does the bookkeeping work of decrementing 223104349Sphk<code>Depth</code>.</p> 224104349Sphk<pre class="eg"> 225178848Scokanevoid XMLCALL 226104349Sphkend(void *data, const char *el) { 227104349Sphk Depth--; 228104349Sphk} /* End of end handler */ 229104349Sphk</pre> 230104349Sphk 231178848Scokane<p>Note the <code>XMLCALL</code> annotation used for the callbacks. 232178848ScokaneThis is used to ensure that the Expat and the callbacks are using the 233178848Scokanesame calling convention in case the compiler options used for Expat 234178848Scokaneitself and the client code are different. Expat tries not to care 235178848Scokanewhat the default calling convention is, though it may require that it 236178848Scokanebe compiled with a default convention of "cdecl" on some platforms. 237178848ScokaneFor code which uses Expat, however, the calling convention is 238178848Scokanespecified by the <code>XMLCALL</code> annotation on most platforms; 239178848Scokanecallbacks should be defined using this annotation.</p> 240178848Scokane 241178848Scokane<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but 242178848Scokaneexisting working Expat applications don't need to add it (since they 243178848Scokaneare already using the "cdecl" calling convention, or they wouldn't be 244178848Scokaneworking). The annotation is only needed if the default calling 245178848Scokaneconvention may be something other than "cdecl". To use the annotation 246178848Scokanesafely with older versions of Expat, you can conditionally define it 247178848Scokane<em>after</em> including Expat's header file:</p> 248178848Scokane 249178848Scokane<pre class="eg"> 250178848Scokane#include <expat.h> 251178848Scokane 252178848Scokane#ifndef XMLCALL 253178848Scokane#if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) && !defined(__CYGWIN__) 254178848Scokane#define XMLCALL __cdecl 255178848Scokane#elif defined(__GNUC__) 256178848Scokane#define XMLCALL __attribute__((cdecl)) 257178848Scokane#else 258178848Scokane#define XMLCALL 259178848Scokane#endif 260178848Scokane#endif 261178848Scokane</pre> 262178848Scokane 263104349Sphk<p>After creating the parser, the main program just has the job of 264104349Sphkshoveling the document to the parser so that it can do its work.</p> 265104349Sphk 266104349Sphk<hr /> 267104349Sphk<h2><a name="building">Building and Installing Expat</a></h2> 268104349Sphk 269104349Sphk<p>The Expat distribution comes as a compressed (with GNU gzip) tar 270104349Sphkfile. You may download the latest version from <a href= 271104349Sphk"http://sourceforge.net/projects/expat/" >Source Forge</a>. After 272104349Sphkunpacking this, cd into the directory. Then follow either the Win32 273104349Sphkdirections or Unix directions below.</p> 274104349Sphk 275104349Sphk<h3>Building under Win32</h3> 276104349Sphk 277104349Sphk<p>If you're using the GNU compiler under cygwin, follow the Unix 278104349Sphkdirections in the next section. Otherwise if you have Microsoft's 279104349SphkDeveloper Studio installed, then from Windows Explorer double-click on 280104349Sphk"expat.dsp" in the lib directory and build and install in the usual 281104349Sphkmanner.</p> 282104349Sphk 283104349Sphk<p>Alternatively, you may download the Win32 binary package that 284104349Sphkcontains the "expat.h" include file and a pre-built DLL.</p> 285104349Sphk 286104349Sphk<h3>Building under Unix (or GNU)</h3> 287104349Sphk 288104349Sphk<p>First you'll need to run the configure shell script in order to 289104349Sphkconfigure the Makefiles and headers for your system.</p> 290104349Sphk 291104349Sphk<p>If you're happy with all the defaults that configure picks for you, 292104349Sphkand you have permission on your system to install into /usr/local, you 293104349Sphkcan install Expat with this sequence of commands:</p> 294104349Sphk 295104349Sphk<pre class="eg"> 296178848Scokane./configure 297178848Scokanemake 298178848Scokanemake install 299104349Sphk</pre> 300104349Sphk 301104349Sphk<p>There are some options that you can provide to this script, but the 302104349Sphkonly one we'll mention here is the <code>--prefix</code> option. You 303104349Sphkcan find out all the options available by running configure with just 304104349Sphkthe <code>--help</code> option.</p> 305104349Sphk 306104349Sphk<p>By default, the configure script sets things up so that the library 307104349Sphkgets installed in <code>/usr/local/lib</code> and the associated 308104349Sphkheader file in <code>/usr/local/include</code>. But if you were to 309104349Sphkgive the option, <code>--prefix=/home/me/mystuff</code>, then the 310104349Sphklibrary and header would get installed in 311104349Sphk<code>/home/me/mystuff/lib</code> and 312104349Sphk<code>/home/me/mystuff/include</code> respectively.</p> 313104349Sphk 314178848Scokane<h3>Configuring Expat Using the Pre-Processor</h3> 315178848Scokane 316178848Scokane<p>Expat's feature set can be configured using a small number of 317178848Scokanepre-processor definitions. The definition of this symbols does not 318178848Scokaneaffect the set of entry points for Expat, only the behavior of the API 319178848Scokaneand the definition of character types in the case of 320178848Scokane<code>XML_UNICODE_WCHAR_T</code>. The symbols are:</p> 321178848Scokane 322178848Scokane<dl class="cpp-symbols"> 323178848Scokane<dt>XML_DTD</dt> 324178848Scokane<dd>Include support for using and reporting DTD-based content. If 325178848Scokanethis is defined, default attribute values from an external DTD subset 326178848Scokaneare reported and attribute value normalization occurs based on the 327178848Scokanetype of attributes defined in the external subset. Without 328178848Scokanethis, Expat has a smaller memory footprint and can be faster, but will 329178848Scokanenot load external entities or process conditional sections. This does 330178848Scokanenot affect the set of functions available in the API.</dd> 331178848Scokane 332178848Scokane<dt>XML_NS</dt> 333178848Scokane<dd>When defined, support for the <cite><a href= 334178848Scokane"http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite> 335178848Scokanespecification is included.</dd> 336178848Scokane 337178848Scokane<dt>XML_UNICODE</dt> 338178848Scokane<dd>When defined, character data reported to the application is 339178848Scokaneencoded in UTF-16 using wide characters of the type 340178848Scokane<code>XML_Char</code>. This is implied if 341178848Scokane<code>XML_UNICODE_WCHAR_T</code> is defined.</dd> 342178848Scokane 343178848Scokane<dt>XML_UNICODE_WCHAR_T</dt> 344178848Scokane<dd>If defined, causes the <code>XML_Char</code> character type to be 345178848Scokanedefined using the <code>wchar_t</code> type; otherwise, <code>unsigned 346178848Scokaneshort</code> is used. Defining this implies 347178848Scokane<code>XML_UNICODE</code>.</dd> 348178848Scokane 349178848Scokane<dt>XML_LARGE_SIZE</dt> 350178848Scokane<dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code> 351178848Scokaneinteger types to be at least 64 bits in size. This is intended to support 352178848Scokaneprocessing of very large input streams, where the return values of 353178848Scokane<code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>, 354178848Scokane<code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and 355178848Scokane<code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code> 356178848Scokanecould overflow. It may not be supported by all compilers, and is turned 357178848Scokaneoff by default.</dd> 358178848Scokane 359178848Scokane<dt>XML_CONTEXT_BYTES</dt> 360178848Scokane<dd>The number of input bytes of markup context which the parser will 361178848Scokaneensure are available for reporting via <code><a href= 362178848Scokane"#XML_GetInputContext" >XML_GetInputContext</a></code>. This is 363178848Scokanenormally set to 1024, and must be set to a positive interger. If this 364178848Scokaneis not defined, the input context will not be available and <code><a 365178848Scokanehref= "#XML_GetInputContext" >XML_GetInputContext</a></code> will 366178848Scokanealways report NULL. Without this, Expat has a smaller memory 367178848Scokanefootprint and can be faster.</dd> 368178848Scokane 369178848Scokane<dt>XML_STATIC</dt> 370178848Scokane<dd>On Windows, this should be set if Expat is going to be linked 371178848Scokanestatically with the code that calls it; this is required to get all 372178848Scokanethe right MSVC magic annotations correct. This is ignored on other 373178848Scokaneplatforms.</dd> 374247513Sdelphij 375247513Sdelphij<dt>XML_ATTR_INFO</dt> 376247513Sdelphij<dd>If defined, makes the the additional function <code><a href= 377247513Sdelphij"#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available 378247513Sdelphijfor reporting attribute byte offsets.</dd> 379178848Scokane</dl> 380178848Scokane 381104349Sphk<hr /> 382104349Sphk<h2><a name="using">Using Expat</a></h2> 383104349Sphk 384104349Sphk<h3>Compiling and Linking Against Expat</h3> 385104349Sphk 386104349Sphk<p>Unless you installed Expat in a location not expected by your 387104349Sphkcompiler and linker, all you have to do to use Expat in your programs 388104349Sphkis to include the Expat header (<code>#include <expat.h></code>) 389104349Sphkin your files that make calls to it and to tell the linker that it 390104349Sphkneeds to link against the Expat library. On Unix systems, this would 391104349Sphkusually be done with the <code>-lexpat</code> argument. Otherwise, 392104349Sphkyou'll need to tell the compiler where to look for the Expat header 393104349Sphkand the linker where to find the Expat library. You may also need to 394178848Scokanetake steps to tell the operating system where to find this library at 395104349Sphkrun time.</p> 396104349Sphk 397104349Sphk<p>On a Unix-based system, here's what a Makefile might look like when 398104349SphkExpat is installed in a standard location:</p> 399104349Sphk 400104349Sphk<pre class="eg"> 401104349SphkCC=cc 402104349SphkLDFLAGS= 403104349SphkLIBS= -lexpat 404104349Sphkxmlapp: xmlapp.o 405104349Sphk $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 406104349Sphk</pre> 407104349Sphk 408104349Sphk<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then 409104349Sphkthe Makefile would look like this:</p> 410104349Sphk 411104349Sphk<pre class="eg"> 412104349SphkCC=cc 413104349SphkCFLAGS= -I/home/me/mystuff/include 414104349SphkLDFLAGS= 415104349SphkLIBS= -L/home/me/mystuff/lib -lexpat 416104349Sphkxmlapp: xmlapp.o 417104349Sphk $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 418104349Sphk</pre> 419104349Sphk 420104349Sphk<p>You'd also have to set the environment variable 421104349Sphk<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or 422104349Sphkto <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if 423104349SphkLD_LIBRARY_PATH already has some directories in it) in order to run 424104349Sphkyour application.</p> 425104349Sphk 426104349Sphk<h3>Expat Basics</h3> 427104349Sphk 428104349Sphk<p>As we saw in the example in the overview, the first step in parsing 429104349Sphkan XML document with Expat is to create a parser object. There are <a 430104349Sphkhref="#creation">three functions</a> in the Expat API for creating a 431104349Sphkparser object. However, only two of these (<code><a href= 432104349Sphk"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href= 433104349Sphk"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for 434104349Sphkconstructing a parser for a top-level document. The object returned 435104349Sphkby these functions is an opaque pointer (i.e. "expat.h" declares it as 436104349Sphkvoid *) to data with further internal structure. In order to free the 437104349Sphkmemory associated with this object you must call <code><a href= 438104349Sphk"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have 439178848Scokaneprovided any <a href="#userdata">user data</a> that gets stored in the 440104349Sphkparser, then your application is responsible for freeing it prior to 441104349Sphkcalling <code>XML_ParserFree</code>.</p> 442104349Sphk 443104349Sphk<p>The objects returned by the parser creation functions are good for 444104349Sphkparsing only one XML document or external parsed entity. If your 445104349Sphkapplication needs to parse many XML documents, then it needs to create 446104349Sphka parser object for each one. The best way to deal with this is to 447104349Sphkcreate a higher level object that contains all the default 448104349Sphkinitialization you want for your parser objects.</p> 449104349Sphk 450104349Sphk<p>Walking through a document hierarchy with a stream oriented parser 451104349Sphkwill require a good stack mechanism in order to keep track of current 452104349Sphkcontext. For instance, to answer the simple question, "What element 453104349Sphkdoes this text belong to?" requires a stack, since the parser may have 454104349Sphkdescended into other elements that are children of the current one and 455104349Sphkhas encountered this text on the way out.</p> 456104349Sphk 457104349Sphk<p>The things you're likely to want to keep on a stack are the 458104349Sphkcurrently opened element and it's attributes. You push this 459104349Sphkinformation onto the stack in the start handler and you pop it off in 460104349Sphkthe end handler.</p> 461104349Sphk 462104349Sphk<p>For some tasks, it is sufficient to just keep information on what 463104349Sphkthe depth of the stack is (or would be if you had one.) The outline 464104349Sphkprogram shown above presents one example. Another such task would be 465104349Sphkskipping over a complete element. When you see the start tag for the 466104349Sphkelement you want to skip, you set a skip flag and record the depth at 467104349Sphkwhich the element started. When the end tag handler encounters the 468104349Sphksame depth, the skipped element has ended and the flag may be 469104349Sphkcleared. If you follow the convention that the root element starts at 470104349Sphk1, then you can use the same variable for skip flag and skip 471104349Sphkdepth.</p> 472104349Sphk 473104349Sphk<pre class="eg"> 474104349Sphkvoid 475104349Sphkinit_info(Parseinfo *info) { 476104349Sphk info->skip = 0; 477104349Sphk info->depth = 1; 478104349Sphk /* Other initializations here */ 479104349Sphk} /* End of init_info */ 480104349Sphk 481178848Scokanevoid XMLCALL 482104349Sphkrawstart(void *data, const char *el, const char **attr) { 483104349Sphk Parseinfo *inf = (Parseinfo *) data; 484104349Sphk 485104349Sphk if (! inf->skip) { 486104349Sphk if (should_skip(inf, el, attr)) { 487104349Sphk inf->skip = inf->depth; 488104349Sphk } 489104349Sphk else 490104349Sphk start(inf, el, attr); /* This does rest of start handling */ 491104349Sphk } 492104349Sphk 493104349Sphk inf->depth++; 494104349Sphk} /* End of rawstart */ 495104349Sphk 496178848Scokanevoid XMLCALL 497104349Sphkrawend(void *data, const char *el) { 498104349Sphk Parseinfo *inf = (Parseinfo *) data; 499104349Sphk 500104349Sphk inf->depth--; 501104349Sphk 502104349Sphk if (! inf->skip) 503104349Sphk end(inf, el); /* This does rest of end handling */ 504104349Sphk 505104349Sphk if (inf->skip == inf->depth) 506104349Sphk inf->skip = 0; 507104349Sphk} /* End rawend */ 508104349Sphk</pre> 509104349Sphk 510104349Sphk<p>Notice in the above example the difference in how depth is 511104349Sphkmanipulated in the start and end handlers. The end tag handler should 512104349Sphkbe the mirror image of the start tag handler. This is necessary to 513104349Sphkproperly model containment. Since, in the start tag handler, we 514104349Sphkincremented depth <em>after</em> the main body of start tag code, then 515104349Sphkin the end handler, we need to manipulate it <em>before</em> the main 516104349Sphkbody. If we'd decided to increment it first thing in the start 517104349Sphkhandler, then we'd have had to decrement it last thing in the end 518104349Sphkhandler.</p> 519104349Sphk 520104349Sphk<h3 id="userdata">Communicating between handlers</h3> 521104349Sphk 522104349Sphk<p>In order to be able to pass information between different handlers 523104349Sphkwithout using globals, you'll need to define a data structure to hold 524104349Sphkthe shared variables. You can then tell Expat (with the <code><a href= 525104349Sphk"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a 526178848Scokanepointer to this structure to the handlers. This is the first 527178848Scokaneargument received by most handlers. In the <a href="#reference" 528178848Scokane>reference section</a>, an argument to a callback function is named 529178848Scokane<code>userData</code> and have type <code>void *</code> if the user 530178848Scokanedata is passed; it will have the type <code>XML_Parser</code> if the 531178848Scokaneparser itself is passed. When the parser is passed, the user data may 532178848Scokanebe retrieved using <code><a href="#XML_GetUserData" 533178848Scokane>XML_GetUserData</a></code>.</p> 534104349Sphk 535178848Scokane<p>One common case where multiple calls to a single handler may need 536178848Scokaneto communicate using an application data structure is the case when 537178848Scokanecontent passed to the character data handler (set by <code><a href= 538178848Scokane"#XML_SetCharacterDataHandler" 539178848Scokane>XML_SetCharacterDataHandler</a></code>) needs to be accumulated. A 540178848Scokanecommon first-time mistake with any of the event-oriented interfaces to 541178848Scokanean XML parser is to expect all the text contained in an element to be 542178848Scokanereported by a single call to the character data handler. Expat, like 543178848Scokanemany other XML parsers, reports such data as a sequence of calls; 544178848Scokanethere's no way to know when the end of the sequence is reached until a 545178848Scokanedifferent callback is made. A buffer referenced by the user data 546178848Scokanestructure proves both an effective and convenient place to accumulate 547178848Scokanecharacter data.</p> 548178848Scokane 549178848Scokane<!-- XXX example needed here --> 550178848Scokane 551178848Scokane 552104349Sphk<h3>XML Version</h3> 553104349Sphk 554104349Sphk<p>Expat is an XML 1.0 parser, and as such never complains based on 555104349Sphkthe value of the <code>version</code> pseudo-attribute in the XML 556104349Sphkdeclaration, if present.</p> 557104349Sphk 558104349Sphk<p>If an application needs to check the version number (to support 559104349Sphkalternate processing), it should use the <code><a href= 560104349Sphk"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to 561104349Sphkset a handler that uses the information in the XML declaration to 562104349Sphkdetermine what to do. This example shows how to check that only a 563104349Sphkversion number of <code>"1.0"</code> is accepted:</p> 564104349Sphk 565104349Sphk<pre class="eg"> 566104349Sphkstatic int wrong_version; 567104349Sphkstatic XML_Parser parser; 568104349Sphk 569178848Scokanestatic void XMLCALL 570104349Sphkxmldecl_handler(void *userData, 571104349Sphk const XML_Char *version, 572104349Sphk const XML_Char *encoding, 573104349Sphk int standalone) 574104349Sphk{ 575104349Sphk static const XML_Char Version_1_0[] = {'1', '.', '0', 0}; 576104349Sphk 577104349Sphk int i; 578104349Sphk 579104349Sphk for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) { 580104349Sphk if (version[i] != Version_1_0[i]) { 581104349Sphk wrong_version = 1; 582104349Sphk /* also clear all other handlers: */ 583104349Sphk XML_SetCharacterDataHandler(parser, NULL); 584104349Sphk ... 585104349Sphk return; 586104349Sphk } 587104349Sphk } 588104349Sphk ... 589104349Sphk} 590104349Sphk</pre> 591104349Sphk 592104349Sphk<h3>Namespace Processing</h3> 593104349Sphk 594104349Sphk<p>When the parser is created using the <code><a href= 595104349Sphk"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat 596104349Sphkperforms namespace processing. Under namespace processing, Expat 597104349Sphkconsumes <code>xmlns</code> and <code>xmlns:...</code> attributes, 598104349Sphkwhich declare namespaces for the scope of the element in which they 599104349Sphkoccur. This means that your start handler will not see these 600104349Sphkattributes. Your application can still be informed of these 601104349Sphkdeclarations by setting namespace declaration handlers with <a href= 602104349Sphk"#XML_SetNamespaceDeclHandler" 603104349Sphk><code>XML_SetNamespaceDeclHandler</code></a>.</p> 604104349Sphk 605104349Sphk<p>Element type and attribute names that belong to a given namespace 606104349Sphkare passed to the appropriate handler in expanded form. By default 607104349Sphkthis expanded form is a concatenation of the namespace URI, the 608104349Sphkseparator character (which is the 2nd argument to <code><a href= 609104349Sphk"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local 610104349Sphkname (i.e. the part after the colon). Names with undeclared prefixes 611178848Scokaneare not well-formed when namespace processing is enabled, and will 612178848Scokanetrigger an error. Unprefixed attribute names are never expanded, 613104349Sphkand unprefixed element names are only expanded when they are in the 614104349Sphkscope of a default namespace.</p> 615104349Sphk 616178848Scokane<p>However if <code><a href= "#XML_SetReturnNSTriplet" 617104349Sphk>XML_SetReturnNSTriplet</a></code> has been called with a non-zero 618104349Sphk<code>do_nst</code> parameter, then the expanded form for names with 619104349Sphkan explicit prefix is a concatenation of: URI, separator, local name, 620104349Sphkseparator, prefix.</p> 621104349Sphk 622104349Sphk<p>You can set handlers for the start of a namespace declaration and 623104349Sphkfor the end of a scope of a declaration with the <code><a href= 624104349Sphk"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code> 625104349Sphkfunction. The StartNamespaceDeclHandler is called prior to the start 626178848Scokanetag handler and the EndNamespaceDeclHandler is called after the 627104349Sphkcorresponding end tag that ends the namespace's scope. The namespace 628104349Sphkstart handler gets passed the prefix and URI for the namespace. For a 629104349Sphkdefault namespace declaration (xmlns='...'), the prefix will be null. 630104349SphkThe URI will be null for the case where the default namespace is being 631104349Sphkunset. The namespace end handler just gets the prefix for the closing 632104349Sphkscope.</p> 633104349Sphk 634104349Sphk<p>These handlers are called for each declaration. So if, for 635104349Sphkinstance, a start tag had three namespace declarations, then the 636104349SphkStartNamespaceDeclHandler would be called three times before the start 637104349Sphktag handler is called, once for each declaration.</p> 638104349Sphk 639104349Sphk<h3>Character Encodings</h3> 640104349Sphk 641104349Sphk<p>While XML is based on Unicode, and every XML processor is required 642104349Sphkto recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), 643104349Sphkother encodings may be declared in XML documents or entities. For the 644104349Sphkmain document, an XML declaration may contain an encoding 645104349Sphkdeclaration:</p> 646104349Sphk<pre> 647104349Sphk<?xml version="1.0" encoding="ISO-8859-2"?> 648104349Sphk</pre> 649104349Sphk 650104349Sphk<p>External parsed entities may begin with a text declaration, which 651104349Sphklooks like an XML declaration with just an encoding declaration:</p> 652104349Sphk<pre> 653104349Sphk<?xml encoding="Big5"?> 654104349Sphk</pre> 655104349Sphk 656104349Sphk<p>With Expat, you may also specify an encoding at the time of 657104349Sphkcreating a parser. This is useful when the encoding information may 658104349Sphkcome from a source outside the document itself (like a higher level 659104349Sphkprotocol.)</p> 660104349Sphk 661104349Sphk<p><a name="builtin_encodings"></a>There are four built-in encodings 662104349Sphkin Expat:</p> 663104349Sphk<ul> 664104349Sphk<li>UTF-8</li> 665104349Sphk<li>UTF-16</li> 666104349Sphk<li>ISO-8859-1</li> 667104349Sphk<li>US-ASCII</li> 668104349Sphk</ul> 669104349Sphk 670104349Sphk<p>Anything else discovered in an encoding declaration or in the 671104349Sphkprotocol encoding specified in the parser constructor, triggers a call 672104349Sphkto the <code>UnknownEncodingHandler</code>. This handler gets passed 673104349Sphkthe encoding name and a pointer to an <code>XML_Encoding</code> data 674178848Scokanestructure. Your handler must fill in this structure and return 675178848Scokane<code>XML_STATUS_OK</code> if it knows how to deal with the 676178848Scokaneencoding. Otherwise the handler should return 677178848Scokane<code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer 678178848Scokaneto an optional application data structure that you may indicate when 679178848Scokaneyou set the handler.</p> 680104349Sphk 681104349Sphk<p>Expat places restrictions on character encodings that it can 682104349Sphksupport by filling in the <code>XML_Encoding</code> structure. 683104349Sphkinclude file:</p> 684104349Sphk<ol> 685104349Sphk<li>Every ASCII character that can appear in a well-formed XML document 686104349Sphkmust be represented by a single byte, and that byte must correspond to 687104349Sphkit's ASCII encoding (except for the characters $@\^'{}~)</li> 688104349Sphk<li>Characters must be encoded in 4 bytes or less.</li> 689104349Sphk<li>All characters encoded must have Unicode scalar values less than or 690104349Sphkequal to 65535 (0xFFFF)<em>This does not apply to the built-in support 691104349Sphkfor UTF-16 and UTF-8</em></li> 692104349Sphk<li>No character may be encoded by more that one distinct sequence of 693104349Sphkbytes</li> 694104349Sphk</ol> 695104349Sphk 696104349Sphk<p><code>XML_Encoding</code> contains an array of integers that 697104349Sphkcorrespond to the 1st byte of an encoding sequence. If the value in 698104349Sphkthe array for a byte is zero or positive, then the byte is a single 699104349Sphkbyte encoding that encodes the Unicode scalar value contained in the 700104349Sphkarray. A -1 in this array indicates a malformed byte. If the value is 701104349Sphk-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte 702104349Sphksequence respectively. Multi-byte sequences are sent to the convert 703104349Sphkfunction pointed at in the <code>XML_Encoding</code> structure. This 704104349Sphkfunction should return the Unicode scalar value for the sequence or -1 705104349Sphkif the sequence is malformed.</p> 706104349Sphk 707104349Sphk<p>One pitfall that novice Expat users are likely to fall into is that 708104349Sphkalthough Expat may accept input in various encodings, the strings that 709104349Sphkit passes to the handlers are always encoded in UTF-8 or UTF-16 710104349Sphk(depending on how Expat was compiled). Your application is responsible 711104349Sphkfor any translation of these strings into other encodings.</p> 712104349Sphk 713104349Sphk<h3>Handling External Entity References</h3> 714104349Sphk 715104349Sphk<p>Expat does not read or parse external entities directly. Note that 716104349Sphkany external DTD is a special case of an external entity. If you've 717104349Sphkset no <code>ExternalEntityRefHandler</code>, then external entity 718104349Sphkreferences are silently ignored. Otherwise, it calls your handler with 719104349Sphkthe information needed to read and parse the external entity.</p> 720104349Sphk 721104349Sphk<p>Your handler isn't actually responsible for parsing the entity, but 722104349Sphkit is responsible for creating a subsidiary parser with <code><a href= 723104349Sphk"#XML_ExternalEntityParserCreate" 724104349Sphk>XML_ExternalEntityParserCreate</a></code> that will do the job. This 725104349Sphkreturns an instance of <code>XML_Parser</code> that has handlers and 726104349Sphkother data structures initialized from the parent parser. You may then 727104349Sphkuse <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a 728104349Sphkhref= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this 729104349Sphkparser. Since external entities my refer to other external entities, 730104349Sphkyour handler should be prepared to be called recursively.</p> 731104349Sphk 732104349Sphk<h3>Parsing DTDs</h3> 733104349Sphk 734104349Sphk<p>In order to parse parameter entities, before starting the parse, 735104349Sphkyou must call <code><a href= "#XML_SetParamEntityParsing" 736104349Sphk>XML_SetParamEntityParsing</a></code> with one of the following 737104349Sphkarguments:</p> 738104349Sphk<dl> 739104349Sphk<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt> 740104349Sphk<dd>Don't parse parameter entities or the external subset</dd> 741104349Sphk<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt> 742104349Sphk<dd>Parse parameter entites and the external subset unless 743104349Sphk<code>standalone</code> was set to "yes" in the XML declaration.</dd> 744104349Sphk<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt> 745104349Sphk<dd>Always parse parameter entities and the external subset</dd> 746104349Sphk</dl> 747104349Sphk 748104349Sphk<p>In order to read an external DTD, you also have to set an external 749104349Sphkentity reference handler as described above.</p> 750104349Sphk 751178848Scokane<h3 id="stop-resume">Temporarily Stopping Parsing</h3> 752178848Scokane 753178848Scokane<p>Expat 1.95.8 introduces a new feature: its now possible to stop 754178848Scokaneparsing temporarily from within a handler function, even if more data 755178848Scokanehas already been passed into the parser. Applications for this 756178848Scokaneinclude</p> 757178848Scokane 758178848Scokane<ul> 759178848Scokane <li>Supporting the <a href= "http://www.w3.org/TR/xinclude/" 760178848Scokane >XInclude</a> specification.</li> 761178848Scokane 762178848Scokane <li>Delaying further processing until additional information is 763178848Scokane available from some other source.</li> 764178848Scokane 765178848Scokane <li>Adjusting processor load as task priorities shift within an 766178848Scokane application.</li> 767178848Scokane 768178848Scokane <li>Stopping parsing completely (simply free or reset the parser 769178848Scokane instead of resuming in the outer parsing loop). This can be useful 770178848Scokane if a application-domain error is found in the XML being parsed or if 771178848Scokane the result of the parse is determined not to be useful after 772178848Scokane all.</li> 773178848Scokane</ul> 774178848Scokane 775178848Scokane<p>To take advantage of this feature, the main parsing loop of an 776178848Scokaneapplication needs to support this specifically. It cannot be 777178848Scokanesupported with a parsing loop compatible with Expat 1.95.7 or 778178848Scokaneearlier (though existing loops will continue to work without 779178848Scokanesupporting the stop/resume feature).</p> 780178848Scokane 781178848Scokane<p>An application that uses this feature for a single parser will have 782178848Scokanethe rough structure (in pseudo-code):</p> 783178848Scokane 784178848Scokane<pre class="pseudocode"> 785178848Scokanefd = open_input() 786178848Scokanep = create_parser() 787178848Scokane 788178848Scokaneif parse_xml(p, fd) { 789178848Scokane /* suspended */ 790178848Scokane 791178848Scokane int suspended = 1; 792178848Scokane 793178848Scokane while (suspended) { 794178848Scokane do_something_else() 795178848Scokane if ready_to_resume() { 796178848Scokane suspended = continue_parsing(p, fd); 797178848Scokane } 798178848Scokane } 799178848Scokane} 800178848Scokane</pre> 801178848Scokane 802178848Scokane<p>An application that may resume any of several parsers based on 803178848Scokaneinput (either from the XML being parsed or some other source) will 804178848Scokanecertainly have more interesting control structures.</p> 805178848Scokane 806178848Scokane<p>This C function could be used for the <code>parse_xml</code> 807178848Scokanefunction mentioned in the pseudo-code above:</p> 808178848Scokane 809178848Scokane<pre class="eg"> 810178848Scokane#define BUFF_SIZE 10240 811178848Scokane 812178848Scokane/* Parse a document from the open file descriptor 'fd' until the parse 813178848Scokane is complete (the document has been completely parsed, or there's 814178848Scokane been an error), or the parse is stopped. Return non-zero when 815178848Scokane the parse is merely suspended. 816178848Scokane*/ 817178848Scokaneint 818178848Scokaneparse_xml(XML_Parser p, int fd) 819178848Scokane{ 820178848Scokane for (;;) { 821178848Scokane int last_chunk; 822178848Scokane int bytes_read; 823178848Scokane enum XML_Status status; 824178848Scokane 825178848Scokane void *buff = XML_GetBuffer(p, BUFF_SIZE); 826178848Scokane if (buff == NULL) { 827178848Scokane /* handle error... */ 828178848Scokane return 0; 829178848Scokane } 830178848Scokane bytes_read = read(fd, buff, BUFF_SIZE); 831178848Scokane if (bytes_read < 0) { 832178848Scokane /* handle error... */ 833178848Scokane return 0; 834178848Scokane } 835178848Scokane status = XML_ParseBuffer(p, bytes_read, bytes_read == 0); 836178848Scokane switch (status) { 837178848Scokane case XML_STATUS_ERROR: 838178848Scokane /* handle error... */ 839178848Scokane return 0; 840178848Scokane case XML_STATUS_SUSPENDED: 841178848Scokane return 1; 842178848Scokane } 843178848Scokane if (bytes_read == 0) 844178848Scokane return 0; 845178848Scokane } 846178848Scokane} 847178848Scokane</pre> 848178848Scokane 849178848Scokane<p>The corresponding <code>continue_parsing</code> function is 850178848Scokanesomewhat simpler, since it only need deal with the return code from 851178848Scokane<code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can 852178848Scokanedelegate the input handling to the <code>parse_xml</code> 853178848Scokanefunction:</p> 854178848Scokane 855178848Scokane<pre class="eg"> 856178848Scokane/* Continue parsing a document which had been suspended. The 'p' and 857178848Scokane 'fd' arguments are the same as passed to parse_xml(). Return 858178848Scokane non-zero when the parse is suspended. 859178848Scokane*/ 860178848Scokaneint 861178848Scokanecontinue_parsing(XML_Parser p, int fd) 862178848Scokane{ 863178848Scokane enum XML_Status status = XML_ResumeParser(p); 864178848Scokane switch (status) { 865178848Scokane case XML_STATUS_ERROR: 866178848Scokane /* handle error... */ 867178848Scokane return 0; 868178848Scokane case XML_ERROR_NOT_SUSPENDED: 869178848Scokane /* handle error... */ 870178848Scokane return 0;. 871178848Scokane case XML_STATUS_SUSPENDED: 872178848Scokane return 1; 873178848Scokane } 874178848Scokane return parse_xml(p, fd); 875178848Scokane} 876178848Scokane</pre> 877178848Scokane 878178848Scokane<p>Now that we've seen what a mess the top-level parsing loop can 879178848Scokanebecome, what have we gained? Very simply, we can now use the <code><a 880178848Scokanehref= "#XML_StopParser" >XML_StopParser</a></code> function to stop 881178848Scokaneparsing, without having to go to great lengths to avoid additional 882178848Scokaneprocessing that we're expecting to ignore. As a bonus, we get to stop 883178848Scokaneparsing <em>temporarily</em>, and come back to it when we're 884178848Scokaneready.</p> 885178848Scokane 886178848Scokane<p>To stop parsing from a handler function, use the <code><a href= 887178848Scokane"#XML_StopParser" >XML_StopParser</a></code> function. This function 888178848Scokanetakes two arguments; the parser being stopped and a flag indicating 889178848Scokanewhether the parse can be resumed in the future.</p> 890178848Scokane 891178848Scokane<!-- XXX really need more here --> 892178848Scokane 893178848Scokane 894104349Sphk<hr /> 895104349Sphk<!-- ================================================================ --> 896104349Sphk 897104349Sphk<h2><a name="reference">Expat Reference</a></h2> 898104349Sphk 899104349Sphk<h3><a name="creation">Parser Creation</a></h3> 900104349Sphk 901104349Sphk<pre class="fcndec" id="XML_ParserCreate"> 902178848ScokaneXML_Parser XMLCALL 903104349SphkXML_ParserCreate(const XML_Char *encoding); 904104349Sphk</pre> 905104349Sphk<div class="fcndef"> 906104349SphkConstruct a new parser. If encoding is non-null, it specifies a 907104349Sphkcharacter encoding to use for the document. This overrides the document 908104349Sphkencoding declaration. There are four built-in encodings: 909104349Sphk<ul> 910104349Sphk<li>US-ASCII</li> 911104349Sphk<li>UTF-8</li> 912104349Sphk<li>UTF-16</li> 913104349Sphk<li>ISO-8859-1</li> 914104349Sphk</ul> 915104349SphkAny other value will invoke a call to the UnknownEncodingHandler. 916104349Sphk</div> 917104349Sphk 918104349Sphk<pre class="fcndec" id="XML_ParserCreateNS"> 919178848ScokaneXML_Parser XMLCALL 920104349SphkXML_ParserCreateNS(const XML_Char *encoding, 921104349Sphk XML_Char sep); 922104349Sphk</pre> 923104349Sphk<div class="fcndef"> 924104349SphkConstructs a new parser that has namespace processing in effect. Namespace 925104349Sphkexpanded element names and attribute names are returned as a concatenation 926104349Sphkof the namespace URI, <em>sep</em>, and the local part of the name. This 927247513Sdelphijmeans that you should pick a character for <em>sep</em> that can't be part 928247513Sdelphijof an URI. Since Expat does not check namespace URIs for conformance, the 929247513Sdelphijonly safe choice for a namespace separator is a character that is illegal 930247513Sdelphijin XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and 931247513Sdelphij<code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when 932247513Sdelphij<em>sep</em> is the null character <code>'\0'</code>: the namespace URI and 933247513Sdelphijthe local part will be concatenated without any separator - this is intended 934247513Sdelphijto support RDF processors. It is a programming error to use the null separator 935247513Sdelphijwith <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div> 936104349Sphk 937104349Sphk<pre class="fcndec" id="XML_ParserCreate_MM"> 938178848ScokaneXML_Parser XMLCALL 939104349SphkXML_ParserCreate_MM(const XML_Char *encoding, 940104349Sphk const XML_Memory_Handling_Suite *ms, 941104349Sphk const XML_Char *sep); 942104349Sphk</pre> 943104349Sphk<pre class="signature"> 944104349Sphktypedef struct { 945178848Scokane void *(XMLCALL *malloc_fcn)(size_t size); 946178848Scokane void *(XMLCALL *realloc_fcn)(void *ptr, size_t size); 947178848Scokane void (XMLCALL *free_fcn)(void *ptr); 948104349Sphk} XML_Memory_Handling_Suite; 949104349Sphk</pre> 950104349Sphk<div class="fcndef"> 951104349Sphk<p>Construct a new parser using the suite of memory handling functions 952104349Sphkspecified in <code>ms</code>. If <code>ms</code> is NULL, then use the 953104349Sphkstandard set of memory management functions. If <code>sep</code> is 954104349Sphknon NULL, then namespace processing is enabled in the created parser 955104349Sphkand the character pointed at by sep is used as the separator between 956104349Sphkthe namespace URI and the local part of the name.</p> 957104349Sphk</div> 958104349Sphk 959104349Sphk<pre class="fcndec" id="XML_ExternalEntityParserCreate"> 960178848ScokaneXML_Parser XMLCALL 961104349SphkXML_ExternalEntityParserCreate(XML_Parser p, 962104349Sphk const XML_Char *context, 963104349Sphk const XML_Char *encoding); 964104349Sphk</pre> 965104349Sphk<div class="fcndef"> 966104349SphkConstruct a new <code>XML_Parser</code> object for parsing an external 967104349Sphkgeneral entity. Context is the context argument passed in a call to a 968104349SphkExternalEntityRefHandler. Other state information such as handlers, 969104349Sphkuser data, namespace processing is inherited from the parser passed as 970104349Sphkthe 1st argument. So you shouldn't need to call any of the behavior 971104349Sphkchanging functions on this parser (unless you want it to act 972104349Sphkdifferently than the parent parser). 973104349Sphk</div> 974104349Sphk 975104349Sphk<pre class="fcndec" id="XML_ParserFree"> 976178848Scokanevoid XMLCALL 977104349SphkXML_ParserFree(XML_Parser p); 978104349Sphk</pre> 979104349Sphk<div class="fcndef"> 980104349SphkFree memory used by the parser. Your application is responsible for 981104349Sphkfreeing any memory associated with <a href="#userdata">user data</a>. 982104349Sphk</div> 983104349Sphk 984104349Sphk<pre class="fcndec" id="XML_ParserReset"> 985178848ScokaneXML_Bool XMLCALL 986178848ScokaneXML_ParserReset(XML_Parser p, 987178848Scokane const XML_Char *encoding); 988104349Sphk</pre> 989104349Sphk<div class="fcndef"> 990104349SphkClean up the memory structures maintained by the parser so that it may 991104349Sphkbe used again. After this has been called, <code>parser</code> is 992178848Scokaneready to start parsing a new document. All handlers are cleared from 993178848Scokanethe parser, except for the unknownEncodingHandler. The parser's external 994178848Scokanestate is re-initialized except for the values of ns and ns_triplets. 995178848ScokaneThis function may not be used on a parser created using <code><a href= 996104349Sphk"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a 997104349Sphk></code>; it will return <code>XML_FALSE</code> in that case. Returns 998104349Sphk<code>XML_TRUE</code> on success. Your application is responsible for 999104349Sphkdealing with any memory associated with <a href="#userdata">user data</a>. 1000104349Sphk</div> 1001104349Sphk 1002104349Sphk<h3><a name="parsing">Parsing</a></h3> 1003104349Sphk 1004104349Sphk<p>To state the obvious: the three parsing functions <code><a href= 1005178848Scokane"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer"> 1006178848ScokaneXML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer"> 1007178848ScokaneXML_GetBuffer</a></code> must not be called from within a handler 1008178848Scokaneunless they operate on a separate parser instance, that is, one that 1009178848Scokanedid not call the handler. For example, it is OK to call the parsing 1010178848Scokanefunctions from within an <code>XML_ExternalEntityRefHandler</code>, 1011178848Scokaneif they apply to the parser created by 1012178848Scokane<code><a href= "#XML_ExternalEntityParserCreate" 1013104349Sphk>XML_ExternalEntityParserCreate</a></code>.</p> 1014104349Sphk 1015178848Scokane<p>Note: the <code>len</code> argument passed to these functions 1016178848Scokaneshould be considerably less than the maximum value for an integer, 1017178848Scokaneas it could create an integer overflow situation if the added 1018178848Scokanelengths of a buffer and the unprocessed portion of the previous buffer 1019178848Scokaneexceed the maximum integer value. Input data at the end of a buffer 1020178848Scokanewill remain unprocessed if it is part of an XML token for which the 1021178848Scokaneend is not part of that buffer.</p> 1022178848Scokane 1023104349Sphk<pre class="fcndec" id="XML_Parse"> 1024178848Scokaneenum XML_Status XMLCALL 1025104349SphkXML_Parse(XML_Parser p, 1026104349Sphk const char *s, 1027104349Sphk int len, 1028104349Sphk int isFinal); 1029104349Sphk</pre> 1030104349Sphk<pre class="signature"> 1031104349Sphkenum XML_Status { 1032104349Sphk XML_STATUS_ERROR = 0, 1033104349Sphk XML_STATUS_OK = 1 1034104349Sphk}; 1035104349Sphk</pre> 1036104349Sphk<div class="fcndef"> 1037104349SphkParse some more of the document. The string <code>s</code> is a buffer 1038104349Sphkcontaining part (or perhaps all) of the document. The number of bytes of s 1039104349Sphkthat are part of the document is indicated by <code>len</code>. This means 1040104349Sphkthat <code>s</code> doesn't have to be null terminated. It also means that 1041104349Sphkif <code>len</code> is larger than the number of bytes in the block of 1042104349Sphkmemory that <code>s</code> points at, then a memory fault is likely. The 1043104349Sphk<code>isFinal</code> parameter informs the parser that this is the last 1044104349Sphkpiece of the document. Frequently, the last piece is empty (i.e. 1045104349Sphk<code>len</code> is zero.) 1046104349SphkIf a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. 1047104349SphkOtherwise it returns <code>XML_STATUS_OK</code> value. 1048104349Sphk</div> 1049104349Sphk 1050104349Sphk<pre class="fcndec" id="XML_ParseBuffer"> 1051178848Scokaneenum XML_Status XMLCALL 1052104349SphkXML_ParseBuffer(XML_Parser p, 1053104349Sphk int len, 1054104349Sphk int isFinal); 1055104349Sphk</pre> 1056104349Sphk<div class="fcndef"> 1057104349SphkThis is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>, 1058104349Sphkexcept in this case Expat provides the buffer. By obtaining the 1059104349Sphkbuffer from Expat with the <code><a href= "#XML_GetBuffer" 1060104349Sphk>XML_GetBuffer</a></code> function, the application can avoid double 1061104349Sphkcopying of the input. 1062104349Sphk</div> 1063104349Sphk 1064104349Sphk<pre class="fcndec" id="XML_GetBuffer"> 1065178848Scokanevoid * XMLCALL 1066104349SphkXML_GetBuffer(XML_Parser p, 1067104349Sphk int len); 1068104349Sphk</pre> 1069104349Sphk<div class="fcndef"> 1070104349SphkObtain a buffer of size <code>len</code> to read a piece of the document 1071104349Sphkinto. A NULL value is returned if Expat can't allocate enough memory for 1072104349Sphkthis buffer. This has to be called prior to every call to 1073104349Sphk<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A 1074104349Sphktypical use would look like this: 1075104349Sphk 1076104349Sphk<pre class="eg"> 1077104349Sphkfor (;;) { 1078104349Sphk int bytes_read; 1079104349Sphk void *buff = XML_GetBuffer(p, BUFF_SIZE); 1080104349Sphk if (buff == NULL) { 1081104349Sphk /* handle error */ 1082104349Sphk } 1083104349Sphk 1084104349Sphk bytes_read = read(docfd, buff, BUFF_SIZE); 1085104349Sphk if (bytes_read < 0) { 1086104349Sphk /* handle error */ 1087104349Sphk } 1088104349Sphk 1089104349Sphk if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) { 1090104349Sphk /* handle parse error */ 1091104349Sphk } 1092104349Sphk 1093104349Sphk if (bytes_read == 0) 1094104349Sphk break; 1095104349Sphk} 1096104349Sphk</pre> 1097104349Sphk</div> 1098104349Sphk 1099178848Scokane<pre class="fcndec" id="XML_StopParser"> 1100178848Scokaneenum XML_Status XMLCALL 1101178848ScokaneXML_StopParser(XML_Parser p, 1102178848Scokane XML_Bool resumable); 1103178848Scokane</pre> 1104178848Scokane<div class="fcndef"> 1105178848Scokane 1106178848Scokane<p>Stops parsing, causing <code><a href= "#XML_Parse" 1107178848Scokane>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 1108178848Scokane>XML_ParseBuffer</a></code> to return. Must be called from within a 1109178848Scokanecall-back handler, except when aborting (when <code>resumable</code> 1110178848Scokaneis <code>XML_FALSE</code>) an already suspended parser. Some 1111178848Scokanecall-backs may still follow because they would otherwise get 1112178848Scokanelost, including 1113178848Scokane<ul> 1114178848Scokane <li> the end element handler for empty elements when stopped in the 1115178848Scokane start element handler,</li> 1116178848Scokane <li> the end namespace declaration handler when stopped in the end 1117178848Scokane element handler,</li> 1118178848Scokane <li> the character data handler when stopped in the character data handler 1119178848Scokane while making multiple call-backs on a contiguous chunk of characters,</li> 1120178848Scokane</ul> 1121178848Scokaneand possibly others.</p> 1122178848Scokane 1123178848Scokane<p>This can be called from most handlers, including DTD related 1124178848Scokanecall-backs, except when parsing an external parameter entity and 1125178848Scokane<code>resumable</code> is <code>XML_TRUE</code>. Returns 1126178848Scokane<code>XML_STATUS_OK</code> when successful, 1127178848Scokane<code>XML_STATUS_ERROR</code> otherwise. The possible error codes 1128178848Scokaneare:</p> 1129178848Scokane<dl> 1130178848Scokane <dt><code>XML_ERROR_SUSPENDED</code></dt> 1131178848Scokane <dd>when suspending an already suspended parser.</dd> 1132178848Scokane <dt><code>XML_ERROR_FINISHED</code></dt> 1133178848Scokane <dd>when the parser has already finished.</dd> 1134178848Scokane <dt><code>XML_ERROR_SUSPEND_PE</code></dt> 1135178848Scokane <dd>when suspending while parsing an external PE.</dd> 1136178848Scokane</dl> 1137178848Scokane 1138178848Scokane<p>Since the stop/resume feature requires application support in the 1139178848Scokaneouter parsing loop, it is an error to call this function for a parser 1140178848Scokanenot being handled appropriately; see <a href= "#stop-resume" 1141178848Scokane>Temporarily Stopping Parsing</a> for more information.</p> 1142178848Scokane 1143178848Scokane<p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing 1144178848Scokaneis <em>suspended</em>, that is, <code><a href= "#XML_Parse" 1145178848Scokane>XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer" 1146178848Scokane>XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>. 1147178848ScokaneOtherwise, parsing is <em>aborted</em>, that is, <code><a href= 1148178848Scokane"#XML_Parse" >XML_Parse</a></code> and <code><a href= 1149178848Scokane"#XML_ParseBuffer" >XML_ParseBuffer</a></code> return 1150178848Scokane<code>XML_STATUS_ERROR</code> with error code 1151178848Scokane<code>XML_ERROR_ABORTED</code>.</p> 1152178848Scokane 1153178848Scokane<p><strong>Note:</strong> 1154178848ScokaneThis will be applied to the current parser instance only, that is, if 1155178848Scokanethere is a parent parser then it will continue parsing when the 1156178848Scokaneexternal entity reference handler returns. It is up to the 1157178848Scokaneimplementation of that handler to call <code><a href= 1158178848Scokane"#XML_StopParser" >XML_StopParser</a></code> on the parent parser 1159178848Scokane(recursively), if one wants to stop parsing altogether.</p> 1160178848Scokane 1161178848Scokane<p>When suspended, parsing can be resumed by calling <code><a href= 1162178848Scokane"#XML_ResumeParser" >XML_ResumeParser</a></code>.</p> 1163178848Scokane 1164178848Scokane<p>New in Expat 1.95.8.</p> 1165178848Scokane</div> 1166178848Scokane 1167178848Scokane<pre class="fcndec" id="XML_ResumeParser"> 1168178848Scokaneenum XML_Status XMLCALL 1169178848ScokaneXML_ResumeParser(XML_Parser p); 1170178848Scokane</pre> 1171178848Scokane<div class="fcndef"> 1172178848Scokane<p>Resumes parsing after it has been suspended with <code><a href= 1173178848Scokane"#XML_StopParser" >XML_StopParser</a></code>. Must not be called from 1174178848Scokanewithin a handler call-back. Returns same status codes as <code><a 1175178848Scokanehref= "#XML_Parse">XML_Parse</a></code> or <code><a href= 1176178848Scokane"#XML_ParseBuffer" >XML_ParseBuffer</a></code>. An additional error 1177178848Scokanecode, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the 1178178848Scokaneparser was not currently suspended.</p> 1179178848Scokane 1180178848Scokane<p><strong>Note:</strong> 1181178848ScokaneThis must be called on the most deeply nested child parser instance 1182178848Scokanefirst, and on its parent parser only after the child parser has 1183178848Scokanefinished, to be applied recursively until the document entity's parser 1184178848Scokaneis restarted. That is, the parent parser will not resume by itself 1185178848Scokaneand it is up to the application to call <code><a href= 1186178848Scokane"#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the 1187178848Scokaneappropriate moment.</p> 1188178848Scokane 1189178848Scokane<p>New in Expat 1.95.8.</p> 1190178848Scokane</div> 1191178848Scokane 1192178848Scokane<pre class="fcndec" id="XML_GetParsingStatus"> 1193178848Scokanevoid XMLCALL 1194178848ScokaneXML_GetParsingStatus(XML_Parser p, 1195178848Scokane XML_ParsingStatus *status); 1196178848Scokane</pre> 1197178848Scokane<pre class="signature"> 1198178848Scokaneenum XML_Parsing { 1199178848Scokane XML_INITIALIZED, 1200178848Scokane XML_PARSING, 1201178848Scokane XML_FINISHED, 1202178848Scokane XML_SUSPENDED 1203178848Scokane}; 1204178848Scokane 1205178848Scokanetypedef struct { 1206178848Scokane enum XML_Parsing parsing; 1207178848Scokane XML_Bool finalBuffer; 1208178848Scokane} XML_ParsingStatus; 1209178848Scokane</pre> 1210178848Scokane<div class="fcndef"> 1211178848Scokane<p>Returns status of parser with respect to being initialized, 1212178848Scokaneparsing, finished, or suspended, and whether the final buffer is being 1213178848Scokaneprocessed. The <code>status</code> parameter <em>must not</em> be 1214178848ScokaneNULL.</p> 1215178848Scokane 1216178848Scokane<p>New in Expat 1.95.8.</p> 1217178848Scokane</div> 1218178848Scokane 1219178848Scokane 1220104349Sphk<h3><a name="setting">Handler Setting</a></h3> 1221104349Sphk 1222104349Sphk<p>Although handlers are typically set prior to parsing and left alone, an 1223104349Sphkapplication may choose to set or change the handler for a parsing event 1224104349Sphkwhile the parse is in progress. For instance, your application may choose 1225104349Sphkto ignore all text not descended from a <code>para</code> element. One 1226104349Sphkway it could do this is to set the character handler when a para start tag 1227104349Sphkis seen, and unset it for the corresponding end tag.</p> 1228104349Sphk 1229104349Sphk<p>A handler may be <em>unset</em> by providing a NULL pointer to the 1230104349Sphkappropriate handler setter. None of the handler setting functions have 1231104349Sphka return value.</p> 1232104349Sphk 1233104349Sphk<p>Your handlers will be receiving strings in arrays of type 1234178848Scokane<code>XML_Char</code>. This type is conditionally defined in expat.h as 1235178848Scokaneeither <code>char</code>, <code>wchar_t</code> or <code>unsigned short</code>. 1236178848ScokaneThe former implies UTF-8 encoding, the latter two imply UTF-16 encoding. 1237178848ScokaneNote that you'll receive them in this form independent of the original 1238178848Scokaneencoding of the document.</p> 1239104349Sphk 1240104349Sphk<div class="handler"> 1241104349Sphk<pre class="setter" id="XML_SetStartElementHandler"> 1242178848Scokanevoid XMLCALL 1243104349SphkXML_SetStartElementHandler(XML_Parser p, 1244104349Sphk XML_StartElementHandler start); 1245104349Sphk</pre> 1246104349Sphk<pre class="signature"> 1247104349Sphktypedef void 1248178848Scokane(XMLCALL *XML_StartElementHandler)(void *userData, 1249178848Scokane const XML_Char *name, 1250178848Scokane const XML_Char **atts); 1251104349Sphk</pre> 1252104349Sphk<p>Set handler for start (and empty) tags. Attributes are passed to the start 1253104349Sphkhandler as a pointer to a vector of char pointers. Each attribute seen in 1254104349Sphka start (or empty) tag occupies 2 consecutive places in this vector: the 1255104349Sphkattribute name followed by the attribute value. These pairs are terminated 1256104349Sphkby a null pointer.</p> 1257104349Sphk<p>Note that an empty tag generates a call to both start and end handlers 1258104349Sphk(in that order).</p> 1259104349Sphk</div> 1260104349Sphk 1261104349Sphk<div class="handler"> 1262104349Sphk<pre class="setter" id="XML_SetEndElementHandler"> 1263178848Scokanevoid XMLCALL 1264104349SphkXML_SetEndElementHandler(XML_Parser p, 1265104349Sphk XML_EndElementHandler); 1266104349Sphk</pre> 1267104349Sphk<pre class="signature"> 1268104349Sphktypedef void 1269178848Scokane(XMLCALL *XML_EndElementHandler)(void *userData, 1270178848Scokane const XML_Char *name); 1271104349Sphk</pre> 1272104349Sphk<p>Set handler for end (and empty) tags. As noted above, an empty tag 1273104349Sphkgenerates a call to both start and end handlers.</p> 1274104349Sphk</div> 1275104349Sphk 1276104349Sphk<div class="handler"> 1277104349Sphk<pre class="setter" id="XML_SetElementHandler"> 1278178848Scokanevoid XMLCALL 1279104349SphkXML_SetElementHandler(XML_Parser p, 1280104349Sphk XML_StartElementHandler start, 1281104349Sphk XML_EndElementHandler end); 1282104349Sphk</pre> 1283104349Sphk<p>Set handlers for start and end tags with one call.</p> 1284104349Sphk</div> 1285104349Sphk 1286104349Sphk<div class="handler"> 1287104349Sphk<pre class="setter" id="XML_SetCharacterDataHandler"> 1288178848Scokanevoid XMLCALL 1289104349SphkXML_SetCharacterDataHandler(XML_Parser p, 1290104349Sphk XML_CharacterDataHandler charhndl) 1291104349Sphk</pre> 1292104349Sphk<pre class="signature"> 1293104349Sphktypedef void 1294178848Scokane(XMLCALL *XML_CharacterDataHandler)(void *userData, 1295178848Scokane const XML_Char *s, 1296178848Scokane int len); 1297104349Sphk</pre> 1298104349Sphk<p>Set a text handler. The string your handler receives 1299104349Sphkis <em>NOT nul-terminated</em>. You have to use the length argument 1300104349Sphkto deal with the end of the string. A single block of contiguous text 1301104349Sphkfree of markup may still result in a sequence of calls to this handler. 1302104349SphkIn other words, if you're searching for a pattern in the text, it may 1303178848Scokanebe split across calls to this handler. Note: Setting this handler to NULL 1304178848Scokanemay <em>NOT immediately</em> terminate call-backs if the parser is currently 1305178848Scokaneprocessing such a single block of contiguous markup-free text, as the parser 1306178848Scokanewill continue calling back until the end of the block is reached.</p> 1307104349Sphk</div> 1308104349Sphk 1309104349Sphk<div class="handler"> 1310104349Sphk<pre class="setter" id="XML_SetProcessingInstructionHandler"> 1311178848Scokanevoid XMLCALL 1312104349SphkXML_SetProcessingInstructionHandler(XML_Parser p, 1313104349Sphk XML_ProcessingInstructionHandler proc) 1314104349Sphk</pre> 1315104349Sphk<pre class="signature"> 1316104349Sphktypedef void 1317178848Scokane(XMLCALL *XML_ProcessingInstructionHandler)(void *userData, 1318178848Scokane const XML_Char *target, 1319178848Scokane const XML_Char *data); 1320104349Sphk 1321104349Sphk</pre> 1322104349Sphk<p>Set a handler for processing instructions. The target is the first word 1323104349Sphkin the processing instruction. The data is the rest of the characters in 1324104349Sphkit after skipping all whitespace after the initial word.</p> 1325104349Sphk</div> 1326104349Sphk 1327104349Sphk<div class="handler"> 1328104349Sphk<pre class="setter" id="XML_SetCommentHandler"> 1329178848Scokanevoid XMLCALL 1330104349SphkXML_SetCommentHandler(XML_Parser p, 1331104349Sphk XML_CommentHandler cmnt) 1332104349Sphk</pre> 1333104349Sphk<pre class="signature"> 1334104349Sphktypedef void 1335178848Scokane(XMLCALL *XML_CommentHandler)(void *userData, 1336178848Scokane const XML_Char *data); 1337104349Sphk</pre> 1338104349Sphk<p>Set a handler for comments. The data is all text inside the comment 1339104349Sphkdelimiters.</p> 1340104349Sphk</div> 1341104349Sphk 1342104349Sphk<div class="handler"> 1343104349Sphk<pre class="setter" id="XML_SetStartCdataSectionHandler"> 1344178848Scokanevoid XMLCALL 1345104349SphkXML_SetStartCdataSectionHandler(XML_Parser p, 1346104349Sphk XML_StartCdataSectionHandler start); 1347104349Sphk</pre> 1348104349Sphk<pre class="signature"> 1349104349Sphktypedef void 1350178848Scokane(XMLCALL *XML_StartCdataSectionHandler)(void *userData); 1351104349Sphk</pre> 1352104349Sphk<p>Set a handler that gets called at the beginning of a CDATA section.</p> 1353104349Sphk</div> 1354104349Sphk 1355104349Sphk<div class="handler"> 1356104349Sphk<pre class="setter" id="XML_SetEndCdataSectionHandler"> 1357178848Scokanevoid XMLCALL 1358104349SphkXML_SetEndCdataSectionHandler(XML_Parser p, 1359104349Sphk XML_EndCdataSectionHandler end); 1360104349Sphk</pre> 1361104349Sphk<pre class="signature"> 1362104349Sphktypedef void 1363178848Scokane(XMLCALL *XML_EndCdataSectionHandler)(void *userData); 1364104349Sphk</pre> 1365104349Sphk<p>Set a handler that gets called at the end of a CDATA section.</p> 1366104349Sphk</div> 1367104349Sphk 1368104349Sphk<div class="handler"> 1369104349Sphk<pre class="setter" id="XML_SetCdataSectionHandler"> 1370178848Scokanevoid XMLCALL 1371104349SphkXML_SetCdataSectionHandler(XML_Parser p, 1372104349Sphk XML_StartCdataSectionHandler start, 1373104349Sphk XML_EndCdataSectionHandler end) 1374104349Sphk</pre> 1375104349Sphk<p>Sets both CDATA section handlers with one call.</p> 1376104349Sphk</div> 1377104349Sphk 1378104349Sphk<div class="handler"> 1379104349Sphk<pre class="setter" id="XML_SetDefaultHandler"> 1380178848Scokanevoid XMLCALL 1381104349SphkXML_SetDefaultHandler(XML_Parser p, 1382104349Sphk XML_DefaultHandler hndl) 1383104349Sphk</pre> 1384104349Sphk<pre class="signature"> 1385104349Sphktypedef void 1386178848Scokane(XMLCALL *XML_DefaultHandler)(void *userData, 1387178848Scokane const XML_Char *s, 1388178848Scokane int len); 1389104349Sphk</pre> 1390104349Sphk 1391104349Sphk<p>Sets a handler for any characters in the document which wouldn't 1392104349Sphkotherwise be handled. This includes both data for which no handlers 1393104349Sphkcan be set (like some kinds of DTD declarations) and data which could 1394104349Sphkbe reported but which currently has no handler set. The characters 1395104349Sphkare passed exactly as they were present in the XML document except 1396104349Sphkthat they will be encoded in UTF-8 or UTF-16. Line boundaries are not 1397104349Sphknormalized. Note that a byte order mark character is not passed to the 1398104349Sphkdefault handler. There are no guarantees about how characters are 1399104349Sphkdivided between calls to the default handler: for example, a comment 1400104349Sphkmight be split between multiple calls. Setting the handler with 1401104349Sphkthis call has the side effect of turning off expansion of references 1402104349Sphkto internally defined general entities. Instead these references are 1403104349Sphkpassed to the default handler.</p> 1404104349Sphk 1405104349Sphk<p>See also <code><a 1406104349Sphkhref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 1407104349Sphk</div> 1408104349Sphk 1409104349Sphk<div class="handler"> 1410104349Sphk<pre class="setter" id="XML_SetDefaultHandlerExpand"> 1411178848Scokanevoid XMLCALL 1412104349SphkXML_SetDefaultHandlerExpand(XML_Parser p, 1413104349Sphk XML_DefaultHandler hndl) 1414104349Sphk</pre> 1415104349Sphk<pre class="signature"> 1416104349Sphktypedef void 1417178848Scokane(XMLCALL *XML_DefaultHandler)(void *userData, 1418178848Scokane const XML_Char *s, 1419178848Scokane int len); 1420104349Sphk</pre> 1421104349Sphk<p>This sets a default handler, but doesn't inhibit the expansion of 1422104349Sphkinternal entity references. The entity reference will not be passed 1423104349Sphkto the default handler.</p> 1424104349Sphk 1425104349Sphk<p>See also <code><a 1426104349Sphkhref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 1427104349Sphk</div> 1428104349Sphk 1429104349Sphk<div class="handler"> 1430104349Sphk<pre class="setter" id="XML_SetExternalEntityRefHandler"> 1431178848Scokanevoid XMLCALL 1432104349SphkXML_SetExternalEntityRefHandler(XML_Parser p, 1433104349Sphk XML_ExternalEntityRefHandler hndl) 1434104349Sphk</pre> 1435104349Sphk<pre class="signature"> 1436104349Sphktypedef int 1437178848Scokane(XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p, 1438178848Scokane const XML_Char *context, 1439178848Scokane const XML_Char *base, 1440178848Scokane const XML_Char *systemId, 1441178848Scokane const XML_Char *publicId); 1442104349Sphk</pre> 1443104349Sphk<p>Set an external entity reference handler. This handler is also 1444104349Sphkcalled for processing an external DTD subset if parameter entity parsing 1445104349Sphkis in effect. (See <a href="#XML_SetParamEntityParsing"> 1446104349Sphk<code>XML_SetParamEntityParsing</code></a>.)</p> 1447104349Sphk 1448178848Scokane<p>The <code>context</code> parameter specifies the parsing context in 1449178848Scokanethe format expected by the <code>context</code> argument to <code><a 1450178848Scokanehref="#XML_ExternalEntityParserCreate" 1451178848Scokane>XML_ExternalEntityParserCreate</a></code>. <code>code</code> is 1452178848Scokanevalid only until the handler returns, so if the referenced entity is 1453178848Scokaneto be parsed later, it must be copied. <code>context</code> is NULL 1454178848Scokaneonly when the entity is a parameter entity, which is how one can 1455178848Scokanedifferentiate between general and parameter entities.</p> 1456104349Sphk 1457178848Scokane<p>The <code>base</code> parameter is the base to use for relative 1458178848Scokanesystem identifiers. It is set by <code><a 1459178848Scokanehref="#XML_SetBase">XML_SetBase</a></code> and may be NULL. The 1460178848Scokane<code>publicId</code> parameter is the public id given in the entity 1461178848Scokanedeclaration and may be NULL. <code>systemId</code> is the system 1462178848Scokaneidentifier specified in the entity declaration and is never NULL.</p> 1463104349Sphk 1464178848Scokane<p>There are a couple of ways in which this handler differs from 1465178848Scokaneothers. First, this handler returns a status indicator (an 1466178848Scokaneinteger). <code>XML_STATUS_OK</code> should be returned for successful 1467178848Scokanehandling of the external entity reference. Returning 1468178848Scokane<code>XML_STATUS_ERROR</code> indicates failure, and causes the 1469178848Scokanecalling parser to return an 1470178848Scokane<code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p> 1471104349Sphk 1472178848Scokane<p>Second, instead of having the user data as its first argument, it 1473178848Scokanereceives the parser that encountered the entity reference. This, along 1474178848Scokanewith the context parameter, may be used as arguments to a call to 1475178848Scokane<code><a href= "#XML_ExternalEntityParserCreate" 1476178848Scokane>XML_ExternalEntityParserCreate</a></code>. Using the returned 1477178848Scokaneparser, the body of the external entity can be recursively parsed.</p> 1478104349Sphk 1479104349Sphk<p>Since this handler may be called recursively, it should not be saving 1480104349Sphkinformation into global or static variables.</p> 1481104349Sphk</div> 1482104349Sphk 1483178848Scokane<pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg"> 1484178848Scokanevoid XMLCALL 1485178848ScokaneXML_SetExternalEntityRefHandlerArg(XML_Parser p, 1486178848Scokane void *arg) 1487178848Scokane</pre> 1488178848Scokane<div class="fcndef"> 1489178848Scokane<p>Set the argument passed to the ExternalEntityRefHandler. If 1490178848Scokane<code>arg</code> is not NULL, it is the new value passed to the 1491178848Scokanehandler set using <code><a href="#XML_SetExternalEntityRefHandler" 1492178848Scokane>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is 1493178848ScokaneNULL, the argument passed to the handler function will be the parser 1494178848Scokaneobject itself.</p> 1495178848Scokane 1496178848Scokane<p><strong>Note:</strong> 1497178848ScokaneThe type of <code>arg</code> and the type of the first argument to the 1498178848ScokaneExternalEntityRefHandler do not match. This function takes a 1499178848Scokane<code>void *</code> to be passed to the handler, while the handler 1500178848Scokaneaccepts an <code>XML_Parser</code>. This is a historical accident, 1501178848Scokanebut will not be corrected before Expat 2.0 (at the earliest) to avoid 1502178848Scokanecausing compiler warnings for code that's known to work with this 1503178848ScokaneAPI. It is the responsibility of the application code to know the 1504178848Scokaneactual type of the argument passed to the handler and to manage it 1505178848Scokaneproperly.</p> 1506178848Scokane</div> 1507178848Scokane 1508104349Sphk<div class="handler"> 1509104349Sphk<pre class="setter" id="XML_SetSkippedEntityHandler"> 1510178848Scokanevoid XMLCALL 1511104349SphkXML_SetSkippedEntityHandler(XML_Parser p, 1512104349Sphk XML_SkippedEntityHandler handler) 1513104349Sphk</pre> 1514104349Sphk<pre class="signature"> 1515104349Sphktypedef void 1516178848Scokane(XMLCALL *XML_SkippedEntityHandler)(void *userData, 1517178848Scokane const XML_Char *entityName, 1518178848Scokane int is_parameter_entity); 1519104349Sphk</pre> 1520104349Sphk<p>Set a skipped entity handler. This is called in two situations:</p> 1521104349Sphk<ol> 1522104349Sphk <li>An entity reference is encountered for which no declaration 1523104349Sphk has been read <em>and</em> this is not an error.</li> 1524104349Sphk <li>An internal entity reference is read, but not expanded, because 1525104349Sphk <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> 1526104349Sphk has been called.</li> 1527104349Sphk</ol> 1528104349Sphk<p>The <code>is_parameter_entity</code> argument will be non-zero for 1529104349Sphka parameter entity and zero for a general entity.</p> <p>Note: skipped 1530104349Sphkparameter entities in declarations and skipped general entities in 1531104349Sphkattribute values cannot be reported, because the event would be out of 1532104349Sphksync with the reporting of the declarations or attribute values</p> 1533104349Sphk</div> 1534104349Sphk 1535104349Sphk<div class="handler"> 1536104349Sphk<pre class="setter" id="XML_SetUnknownEncodingHandler"> 1537178848Scokanevoid XMLCALL 1538104349SphkXML_SetUnknownEncodingHandler(XML_Parser p, 1539104349Sphk XML_UnknownEncodingHandler enchandler, 1540104349Sphk void *encodingHandlerData) 1541104349Sphk</pre> 1542104349Sphk<pre class="signature"> 1543104349Sphktypedef int 1544178848Scokane(XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData, 1545178848Scokane const XML_Char *name, 1546178848Scokane XML_Encoding *info); 1547104349Sphk 1548104349Sphktypedef struct { 1549104349Sphk int map[256]; 1550104349Sphk void *data; 1551178848Scokane int (XMLCALL *convert)(void *data, const char *s); 1552178848Scokane void (XMLCALL *release)(void *data); 1553104349Sphk} XML_Encoding; 1554104349Sphk</pre> 1555178848Scokane<p>Set a handler to deal with encodings other than the <a 1556178848Scokanehref="#builtin_encodings">built in set</a>. This should be done before 1557104349Sphk<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href= 1558104349Sphk"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the 1559178848Scokanegiven parser.</p> <p>If the handler knows how to deal with an encoding 1560178848Scokanewith the given name, it should fill in the <code>info</code> data 1561178848Scokanestructure and return <code>XML_STATUS_OK</code>. Otherwise it 1562178848Scokaneshould return <code>XML_STATUS_ERROR</code>. The handler will be called 1563178848Scokaneat most once per parsed (external) entity. The optional application 1564178848Scokanedata pointer <code>encodingHandlerData</code> will be passed back to 1565178848Scokanethe handler.</p> 1566104349Sphk 1567104349Sphk<p>The map array contains information for every possible possible leading 1568104349Sphkbyte in a byte sequence. If the corresponding value is >= 0, then it's 1569104349Sphka single byte sequence and the byte encodes that Unicode value. If the 1570104349Sphkvalue is -1, then that byte is invalid as the initial byte in a sequence. 1571104349SphkIf the value is -n, where n is an integer > 1, then n is the number of 1572104349Sphkbytes in the sequence and the actual conversion is accomplished by a 1573104349Sphkcall to the function pointed at by convert. This function may return -1 1574104349Sphkif the sequence itself is invalid. The convert pointer may be null if 1575104349Sphkthere are only single byte codes. The data parameter passed to the convert 1576104349Sphkfunction is the data pointer from <code>XML_Encoding</code>. The 1577104349Sphkstring s is <em>NOT</em> nul-terminated and points at the sequence of 1578104349Sphkbytes to be converted.</p> 1579104349Sphk 1580104349Sphk<p>The function pointed at by <code>release</code> is called by the 1581104349Sphkparser when it is finished with the encoding. It may be NULL.</p> 1582104349Sphk</div> 1583104349Sphk 1584104349Sphk<div class="handler"> 1585104349Sphk<pre class="setter" id="XML_SetStartNamespaceDeclHandler"> 1586178848Scokanevoid XMLCALL 1587104349SphkXML_SetStartNamespaceDeclHandler(XML_Parser p, 1588104349Sphk XML_StartNamespaceDeclHandler start); 1589104349Sphk</pre> 1590104349Sphk<pre class="signature"> 1591104349Sphktypedef void 1592178848Scokane(XMLCALL *XML_StartNamespaceDeclHandler)(void *userData, 1593178848Scokane const XML_Char *prefix, 1594178848Scokane const XML_Char *uri); 1595104349Sphk</pre> 1596104349Sphk<p>Set a handler to be called when a namespace is declared. Namespace 1597104349Sphkdeclarations occur inside start tags. But the namespace declaration start 1598104349Sphkhandler is called before the start tag handler for each namespace declared 1599104349Sphkin that start tag.</p> 1600104349Sphk</div> 1601104349Sphk 1602104349Sphk<div class="handler"> 1603104349Sphk<pre class="setter" id="XML_SetEndNamespaceDeclHandler"> 1604178848Scokanevoid XMLCALL 1605104349SphkXML_SetEndNamespaceDeclHandler(XML_Parser p, 1606104349Sphk XML_EndNamespaceDeclHandler end); 1607104349Sphk</pre> 1608104349Sphk<pre class="signature"> 1609104349Sphktypedef void 1610178848Scokane(XMLCALL *XML_EndNamespaceDeclHandler)(void *userData, 1611178848Scokane const XML_Char *prefix); 1612104349Sphk</pre> 1613104349Sphk<p>Set a handler to be called when leaving the scope of a namespace 1614104349Sphkdeclaration. This will be called, for each namespace declaration, 1615104349Sphkafter the handler for the end tag of the element in which the 1616104349Sphknamespace was declared.</p> 1617104349Sphk</div> 1618104349Sphk 1619104349Sphk<div class="handler"> 1620104349Sphk<pre class="setter" id="XML_SetNamespaceDeclHandler"> 1621178848Scokanevoid XMLCALL 1622104349SphkXML_SetNamespaceDeclHandler(XML_Parser p, 1623104349Sphk XML_StartNamespaceDeclHandler start, 1624104349Sphk XML_EndNamespaceDeclHandler end) 1625104349Sphk</pre> 1626178848Scokane<p>Sets both namespace declaration handlers with a single call.</p> 1627104349Sphk</div> 1628104349Sphk 1629104349Sphk<div class="handler"> 1630104349Sphk<pre class="setter" id="XML_SetXmlDeclHandler"> 1631178848Scokanevoid XMLCALL 1632104349SphkXML_SetXmlDeclHandler(XML_Parser p, 1633104349Sphk XML_XmlDeclHandler xmldecl); 1634104349Sphk</pre> 1635104349Sphk<pre class="signature"> 1636104349Sphktypedef void 1637178848Scokane(XMLCALL *XML_XmlDeclHandler)(void *userData, 1638178848Scokane const XML_Char *version, 1639178848Scokane const XML_Char *encoding, 1640178848Scokane int standalone); 1641104349Sphk</pre> 1642104349Sphk<p>Sets a handler that is called for XML declarations and also for 1643104349Sphktext declarations discovered in external entities. The way to 1644104349Sphkdistinguish is that the <code>version</code> parameter will be NULL 1645104349Sphkfor text declarations. The <code>encoding</code> parameter may be NULL 1646104349Sphkfor an XML declaration. The <code>standalone</code> argument will 1647104349Sphkcontain -1, 0, or 1 indicating respectively that there was no 1648104349Sphkstandalone parameter in the declaration, that it was given as no, or 1649104349Sphkthat it was given as yes.</p> 1650104349Sphk</div> 1651104349Sphk 1652104349Sphk<div class="handler"> 1653104349Sphk<pre class="setter" id="XML_SetStartDoctypeDeclHandler"> 1654178848Scokanevoid XMLCALL 1655104349SphkXML_SetStartDoctypeDeclHandler(XML_Parser p, 1656104349Sphk XML_StartDoctypeDeclHandler start); 1657104349Sphk</pre> 1658104349Sphk<pre class="signature"> 1659104349Sphktypedef void 1660178848Scokane(XMLCALL *XML_StartDoctypeDeclHandler)(void *userData, 1661178848Scokane const XML_Char *doctypeName, 1662178848Scokane const XML_Char *sysid, 1663178848Scokane const XML_Char *pubid, 1664178848Scokane int has_internal_subset); 1665104349Sphk</pre> 1666104349Sphk<p>Set a handler that is called at the start of a DOCTYPE declaration, 1667104349Sphkbefore any external or internal subset is parsed. Both <code>sysid</code> 1668104349Sphkand <code>pubid</code> may be NULL. The <code>has_internal_subset</code> 1669104349Sphkwill be non-zero if the DOCTYPE declaration has an internal subset.</p> 1670104349Sphk</div> 1671104349Sphk 1672104349Sphk<div class="handler"> 1673104349Sphk<pre class="setter" id="XML_SetEndDoctypeDeclHandler"> 1674178848Scokanevoid XMLCALL 1675104349SphkXML_SetEndDoctypeDeclHandler(XML_Parser p, 1676104349Sphk XML_EndDoctypeDeclHandler end); 1677104349Sphk</pre> 1678104349Sphk<pre class="signature"> 1679104349Sphktypedef void 1680178848Scokane(XMLCALL *XML_EndDoctypeDeclHandler)(void *userData); 1681104349Sphk</pre> 1682104349Sphk<p>Set a handler that is called at the end of a DOCTYPE declaration, 1683104349Sphkafter parsing any external subset.</p> 1684104349Sphk</div> 1685104349Sphk 1686104349Sphk<div class="handler"> 1687104349Sphk<pre class="setter" id="XML_SetDoctypeDeclHandler"> 1688178848Scokanevoid XMLCALL 1689104349SphkXML_SetDoctypeDeclHandler(XML_Parser p, 1690104349Sphk XML_StartDoctypeDeclHandler start, 1691104349Sphk XML_EndDoctypeDeclHandler end); 1692104349Sphk</pre> 1693104349Sphk<p>Set both doctype handlers with one call.</p> 1694104349Sphk</div> 1695104349Sphk 1696104349Sphk<div class="handler"> 1697104349Sphk<pre class="setter" id="XML_SetElementDeclHandler"> 1698178848Scokanevoid XMLCALL 1699104349SphkXML_SetElementDeclHandler(XML_Parser p, 1700104349Sphk XML_ElementDeclHandler eldecl); 1701104349Sphk</pre> 1702104349Sphk<pre class="signature"> 1703104349Sphktypedef void 1704178848Scokane(XMLCALL *XML_ElementDeclHandler)(void *userData, 1705178848Scokane const XML_Char *name, 1706178848Scokane XML_Content *model); 1707104349Sphk</pre> 1708104349Sphk<pre class="signature"> 1709104349Sphkenum XML_Content_Type { 1710104349Sphk XML_CTYPE_EMPTY = 1, 1711104349Sphk XML_CTYPE_ANY, 1712104349Sphk XML_CTYPE_MIXED, 1713104349Sphk XML_CTYPE_NAME, 1714104349Sphk XML_CTYPE_CHOICE, 1715104349Sphk XML_CTYPE_SEQ 1716104349Sphk}; 1717104349Sphk 1718104349Sphkenum XML_Content_Quant { 1719104349Sphk XML_CQUANT_NONE, 1720104349Sphk XML_CQUANT_OPT, 1721104349Sphk XML_CQUANT_REP, 1722104349Sphk XML_CQUANT_PLUS 1723104349Sphk}; 1724104349Sphk 1725104349Sphktypedef struct XML_cp XML_Content; 1726104349Sphk 1727104349Sphkstruct XML_cp { 1728104349Sphk enum XML_Content_Type type; 1729104349Sphk enum XML_Content_Quant quant; 1730104349Sphk const XML_Char * name; 1731104349Sphk unsigned int numchildren; 1732104349Sphk XML_Content * children; 1733104349Sphk}; 1734104349Sphk</pre> 1735104349Sphk<p>Sets a handler for element declarations in a DTD. The handler gets 1736104349Sphkcalled with the name of the element in the declaration and a pointer 1737104349Sphkto a structure that contains the element model. It is the 1738178848Scokaneapplication's responsibility to free this data structure using 1739178848Scokane<code><a href="#XML_FreeContentModel" 1740178848Scokane>XML_FreeContentModel</a></code>.</p> 1741104349Sphk 1742104349Sphk<p>The <code>model</code> argument is the root of a tree of 1743104349Sphk<code>XML_Content</code> nodes. If <code>type</code> equals 1744104349Sphk<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then 1745104349Sphk<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other 1746104349Sphkfields will be zero or NULL. If <code>type</code> is 1747104349Sphk<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be 1748104349Sphk<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and 1749104349Sphk<code>numchildren</code> will contain the number of elements that are 1750104349Sphkallowed to be mixed in and <code>children</code> points to an array of 1751104349Sphk<code>XML_Content</code> structures that will all have type 1752104349SphkXML_CTYPE_NAME with no quantification. Only the root node can be type 1753104349Sphk<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or 1754104349Sphk<code>XML_CTYPE_MIXED</code>.</p> 1755104349Sphk 1756104349Sphk<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field 1757104349Sphkpoints to the name and the <code>numchildren</code> and 1758104349Sphk<code>children</code> fields will be zero and NULL. The 1759104349Sphk<code>quant</code> field will indicate any quantifiers placed on the 1760104349Sphkname.</p> 1761104349Sphk 1762104349Sphk<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> 1763104349Sphkindicate a choice or sequence respectively. The 1764104349Sphk<code>numchildren</code> field indicates how many nodes in the choice 1765104349Sphkor sequence and <code>children</code> points to the nodes.</p> 1766104349Sphk</div> 1767104349Sphk 1768104349Sphk<div class="handler"> 1769104349Sphk<pre class="setter" id="XML_SetAttlistDeclHandler"> 1770178848Scokanevoid XMLCALL 1771104349SphkXML_SetAttlistDeclHandler(XML_Parser p, 1772104349Sphk XML_AttlistDeclHandler attdecl); 1773104349Sphk</pre> 1774104349Sphk<pre class="signature"> 1775104349Sphktypedef void 1776178848Scokane(XMLCALL *XML_AttlistDeclHandler)(void *userData, 1777178848Scokane const XML_Char *elname, 1778178848Scokane const XML_Char *attname, 1779178848Scokane const XML_Char *att_type, 1780178848Scokane const XML_Char *dflt, 1781178848Scokane int isrequired); 1782104349Sphk</pre> 1783104349Sphk<p>Set a handler for attlist declarations in the DTD. This handler is 1784104349Sphkcalled for <em>each</em> attribute. So a single attlist declaration 1785104349Sphkwith multiple attributes declared will generate multiple calls to this 1786104349Sphkhandler. The <code>elname</code> parameter returns the name of the 1787104349Sphkelement for which the attribute is being declared. The attribute name 1788104349Sphkis in the <code>attname</code> parameter. The attribute type is in the 1789104349Sphk<code>att_type</code> parameter. It is the string representing the 1790104349Sphktype in the declaration with whitespace removed.</p> 1791104349Sphk 1792104349Sphk<p>The <code>dflt</code> parameter holds the default value. It will be 1793104349SphkNULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can 1794104349Sphkdistinguish these two cases by checking the <code>isrequired</code> 1795104349Sphkparameter, which will be true in the case of "#REQUIRED" attributes. 1796104349SphkAttributes which are "#FIXED" will have also have a true 1797104349Sphk<code>isrequired</code>, but they will have the non-NULL fixed value 1798104349Sphkin the <code>dflt</code> parameter.</p> 1799104349Sphk</div> 1800104349Sphk 1801104349Sphk<div class="handler"> 1802104349Sphk<pre class="setter" id="XML_SetEntityDeclHandler"> 1803178848Scokanevoid XMLCALL 1804104349SphkXML_SetEntityDeclHandler(XML_Parser p, 1805104349Sphk XML_EntityDeclHandler handler); 1806104349Sphk</pre> 1807104349Sphk<pre class="signature"> 1808104349Sphktypedef void 1809178848Scokane(XMLCALL *XML_EntityDeclHandler)(void *userData, 1810178848Scokane const XML_Char *entityName, 1811178848Scokane int is_parameter_entity, 1812178848Scokane const XML_Char *value, 1813178848Scokane int value_length, 1814178848Scokane const XML_Char *base, 1815178848Scokane const XML_Char *systemId, 1816178848Scokane const XML_Char *publicId, 1817178848Scokane const XML_Char *notationName); 1818104349Sphk</pre> 1819104349Sphk<p>Sets a handler that will be called for all entity declarations. 1820104349SphkThe <code>is_parameter_entity</code> argument will be non-zero in the 1821104349Sphkcase of parameter entities and zero otherwise.</p> 1822104349Sphk 1823104349Sphk<p>For internal entities (<code><!ENTITY foo "bar"></code>), 1824104349Sphk<code>value</code> will be non-NULL and <code>systemId</code>, 1825104349Sphk<code>publicId</code>, and <code>notationName</code> will all be NULL. 1826104349SphkThe value string is <em>not</em> NULL terminated; the length is 1827104349Sphkprovided in the <code>value_length</code> parameter. Do not use 1828104349Sphk<code>value_length</code> to test for internal entities, since it is 1829104349Sphklegal to have zero-length values. Instead check for whether or not 1830104349Sphk<code>value</code> is NULL.</p> <p>The <code>notationName</code> 1831104349Sphkargument will have a non-NULL value only for unparsed entity 1832104349Sphkdeclarations.</p> 1833104349Sphk</div> 1834104349Sphk 1835104349Sphk<div class="handler"> 1836104349Sphk<pre class="setter" id="XML_SetUnparsedEntityDeclHandler"> 1837178848Scokanevoid XMLCALL 1838104349SphkXML_SetUnparsedEntityDeclHandler(XML_Parser p, 1839104349Sphk XML_UnparsedEntityDeclHandler h) 1840104349Sphk</pre> 1841104349Sphk<pre class="signature"> 1842104349Sphktypedef void 1843178848Scokane(XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData, 1844178848Scokane const XML_Char *entityName, 1845178848Scokane const XML_Char *base, 1846178848Scokane const XML_Char *systemId, 1847178848Scokane const XML_Char *publicId, 1848178848Scokane const XML_Char *notationName); 1849104349Sphk</pre> 1850104349Sphk<p>Set a handler that receives declarations of unparsed entities. These 1851104349Sphkare entity declarations that have a notation (NDATA) field:</p> 1852104349Sphk 1853104349Sphk<div id="eg"><pre> 1854104349Sphk<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif> 1855104349Sphk</pre></div> 1856104349Sphk<p>This handler is obsolete and is provided for backwards 1857104349Sphkcompatibility. Use instead <a href= "#XML_SetEntityDeclHandler" 1858104349Sphk>XML_SetEntityDeclHandler</a>.</p> 1859104349Sphk</div> 1860104349Sphk 1861104349Sphk<div class="handler"> 1862104349Sphk<pre class="setter" id="XML_SetNotationDeclHandler"> 1863178848Scokanevoid XMLCALL 1864104349SphkXML_SetNotationDeclHandler(XML_Parser p, 1865104349Sphk XML_NotationDeclHandler h) 1866104349Sphk</pre> 1867104349Sphk<pre class="signature"> 1868104349Sphktypedef void 1869178848Scokane(XMLCALL *XML_NotationDeclHandler)(void *userData, 1870178848Scokane const XML_Char *notationName, 1871178848Scokane const XML_Char *base, 1872178848Scokane const XML_Char *systemId, 1873178848Scokane const XML_Char *publicId); 1874104349Sphk</pre> 1875104349Sphk<p>Set a handler that receives notation declarations.</p> 1876104349Sphk</div> 1877104349Sphk 1878104349Sphk<div class="handler"> 1879104349Sphk<pre class="setter" id="XML_SetNotStandaloneHandler"> 1880178848Scokanevoid XMLCALL 1881104349SphkXML_SetNotStandaloneHandler(XML_Parser p, 1882104349Sphk XML_NotStandaloneHandler h) 1883104349Sphk</pre> 1884104349Sphk<pre class="signature"> 1885104349Sphktypedef int 1886178848Scokane(XMLCALL *XML_NotStandaloneHandler)(void *userData); 1887104349Sphk</pre> 1888104349Sphk<p>Set a handler that is called if the document is not "standalone". 1889104349SphkThis happens when there is an external subset or a reference to a 1890104349Sphkparameter entity, but does not have standalone set to "yes" in an XML 1891178848Scokanedeclaration. If this handler returns <code>XML_STATUS_ERROR</code>, 1892178848Scokanethen the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code> 1893178848Scokaneerror.</p> 1894104349Sphk</div> 1895104349Sphk 1896104349Sphk<h3><a name="position">Parse position and error reporting functions</a></h3> 1897104349Sphk 1898104349Sphk<p>These are the functions you'll want to call when the parse 1899178848Scokanefunctions return <code>XML_STATUS_ERROR</code> (a parse error has 1900178848Scokaneoccurred), although the position reporting functions are useful outside 1901178848Scokaneof errors. The position reported is the byte position (in the original 1902178848Scokanedocument or entity encoding) of the first of the sequence of 1903178848Scokanecharacters that generated the current event (or the error that caused 1904178848Scokanethe parse functions to return <code>XML_STATUS_ERROR</code>.) The 1905178848Scokaneexceptions are callbacks trigged by declarations in the document 1906178848Scokaneprologue, in which case they exact position reported is somewhere in the 1907178848Scokanerelevant markup, but not necessarily as meaningful as for other 1908178848Scokaneevents.</p> 1909104349Sphk 1910104349Sphk<p>The position reporting functions are accurate only outside of the 1911104349SphkDTD. In other words, they usually return bogus information when 1912104349Sphkcalled from within a DTD declaration handler.</p> 1913104349Sphk 1914104349Sphk<pre class="fcndec" id="XML_GetErrorCode"> 1915178848Scokaneenum XML_Error XMLCALL 1916104349SphkXML_GetErrorCode(XML_Parser p); 1917104349Sphk</pre> 1918104349Sphk<div class="fcndef"> 1919104349SphkReturn what type of error has occurred. 1920104349Sphk</div> 1921104349Sphk 1922104349Sphk<pre class="fcndec" id="XML_ErrorString"> 1923178848Scokaneconst XML_LChar * XMLCALL 1924178848ScokaneXML_ErrorString(enum XML_Error code); 1925104349Sphk</pre> 1926104349Sphk<div class="fcndef"> 1927104349SphkReturn a string describing the error corresponding to code. 1928104349SphkThe code should be one of the enums that can be returned from 1929104349Sphk<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>. 1930104349Sphk</div> 1931104349Sphk 1932104349Sphk<pre class="fcndec" id="XML_GetCurrentByteIndex"> 1933178848ScokaneXML_Index XMLCALL 1934104349SphkXML_GetCurrentByteIndex(XML_Parser p); 1935104349Sphk</pre> 1936104349Sphk<div class="fcndef"> 1937178848ScokaneReturn the byte offset of the position. This always corresponds to 1938178848Scokanethe values returned by <code><a href= "#XML_GetCurrentLineNumber" 1939178848Scokane>XML_GetCurrentLineNumber</a></code> and <code><a href= 1940178848Scokane"#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>. 1941104349Sphk</div> 1942104349Sphk 1943104349Sphk<pre class="fcndec" id="XML_GetCurrentLineNumber"> 1944178848ScokaneXML_Size XMLCALL 1945104349SphkXML_GetCurrentLineNumber(XML_Parser p); 1946104349Sphk</pre> 1947104349Sphk<div class="fcndef"> 1948178848ScokaneReturn the line number of the position. The first line is reported as 1949178848Scokane<code>1</code>. 1950104349Sphk</div> 1951104349Sphk 1952104349Sphk<pre class="fcndec" id="XML_GetCurrentColumnNumber"> 1953178848ScokaneXML_Size XMLCALL 1954104349SphkXML_GetCurrentColumnNumber(XML_Parser p); 1955104349Sphk</pre> 1956104349Sphk<div class="fcndef"> 1957104349SphkReturn the offset, from the beginning of the current line, of 1958104349Sphkthe position. 1959104349Sphk</div> 1960104349Sphk 1961104349Sphk<pre class="fcndec" id="XML_GetCurrentByteCount"> 1962178848Scokaneint XMLCALL 1963104349SphkXML_GetCurrentByteCount(XML_Parser p); 1964104349Sphk</pre> 1965104349Sphk<div class="fcndef"> 1966104349SphkReturn the number of bytes in the current event. Returns 1967104349Sphk<code>0</code> if the event is inside a reference to an internal 1968104349Sphkentity and for the end-tag event for empty element tags (the later can 1969104349Sphkbe used to distinguish empty-element tags from empty elements using 1970104349Sphkseparate start and end tags). 1971104349Sphk</div> 1972104349Sphk 1973104349Sphk<pre class="fcndec" id="XML_GetInputContext"> 1974178848Scokaneconst char * XMLCALL 1975104349SphkXML_GetInputContext(XML_Parser p, 1976104349Sphk int *offset, 1977104349Sphk int *size); 1978104349Sphk</pre> 1979104349Sphk<div class="fcndef"> 1980104349Sphk 1981104349Sphk<p>Returns the parser's input buffer, sets the integer pointed at by 1982104349Sphk<code>offset</code> to the offset within this buffer of the current 1983104349Sphkparse position, and set the integer pointed at by <code>size</code> to 1984104349Sphkthe size of the returned buffer.</p> 1985104349Sphk 1986104349Sphk<p>This should only be called from within a handler during an active 1987104349Sphkparse and the returned buffer should only be referred to from within 1988104349Sphkthe handler that made the call. This input buffer contains the 1989104349Sphkuntranslated bytes of the input.</p> 1990104349Sphk 1991104349Sphk<p>Only a limited amount of context is kept, so if the event 1992104349Sphktriggering a call spans over a very large amount of input, the actual 1993104349Sphkparse position may be before the beginning of the buffer.</p> 1994178848Scokane 1995178848Scokane<p>If <code>XML_CONTEXT_BYTES</code> is not defined, this will always 1996178848Scokanereturn NULL.</p> 1997104349Sphk</div> 1998104349Sphk 1999104349Sphk<h3><a name="miscellaneous">Miscellaneous functions</a></h3> 2000104349Sphk 2001104349Sphk<p>The functions in this section either obtain state information from 2002104349Sphkthe parser or can be used to dynamicly set parser options.</p> 2003104349Sphk 2004104349Sphk<pre class="fcndec" id="XML_SetUserData"> 2005178848Scokanevoid XMLCALL 2006104349SphkXML_SetUserData(XML_Parser p, 2007104349Sphk void *userData); 2008104349Sphk</pre> 2009104349Sphk<div class="fcndef"> 2010104349SphkThis sets the user data pointer that gets passed to handlers. It 2011104349Sphkoverwrites any previous value for this pointer. Note that the 2012104349Sphkapplication is responsible for freeing the memory associated with 2013104349Sphk<code>userData</code> when it is finished with the parser. So if you 2014104349Sphkcall this when there's already a pointer there, and you haven't freed 2015104349Sphkthe memory associated with it, then you've probably just leaked 2016104349Sphkmemory. 2017104349Sphk</div> 2018104349Sphk 2019104349Sphk<pre class="fcndec" id="XML_GetUserData"> 2020178848Scokanevoid * XMLCALL 2021104349SphkXML_GetUserData(XML_Parser p); 2022104349Sphk</pre> 2023104349Sphk<div class="fcndef"> 2024104349SphkThis returns the user data pointer that gets passed to handlers. 2025104349SphkIt is actually implemented as a macro. 2026104349Sphk</div> 2027104349Sphk 2028104349Sphk<pre class="fcndec" id="XML_UseParserAsHandlerArg"> 2029178848Scokanevoid XMLCALL 2030104349SphkXML_UseParserAsHandlerArg(XML_Parser p); 2031104349Sphk</pre> 2032104349Sphk<div class="fcndef"> 2033178848ScokaneAfter this is called, handlers receive the parser in their 2034178848Scokane<code>userData</code> arguments. The user data can still be obtained 2035178848Scokaneusing the <code><a href= "#XML_GetUserData" 2036178848Scokane>XML_GetUserData</a></code> function. 2037104349Sphk</div> 2038104349Sphk 2039104349Sphk<pre class="fcndec" id="XML_SetBase"> 2040178848Scokaneenum XML_Status XMLCALL 2041104349SphkXML_SetBase(XML_Parser p, 2042104349Sphk const XML_Char *base); 2043104349Sphk</pre> 2044104349Sphk<div class="fcndef"> 2045104349SphkSet the base to be used for resolving relative URIs in system 2046178848Scokaneidentifiers. The return value is <code>XML_STATUS_ERROR</code> if 2047178848Scokanethere's no memory to store base, otherwise it's 2048178848Scokane<code>XML_STATUS_OK</code>. 2049104349Sphk</div> 2050104349Sphk 2051104349Sphk<pre class="fcndec" id="XML_GetBase"> 2052178848Scokaneconst XML_Char * XMLCALL 2053104349SphkXML_GetBase(XML_Parser p); 2054104349Sphk</pre> 2055104349Sphk<div class="fcndef"> 2056104349SphkReturn the base for resolving relative URIs. 2057104349Sphk</div> 2058104349Sphk 2059104349Sphk<pre class="fcndec" id="XML_GetSpecifiedAttributeCount"> 2060178848Scokaneint XMLCALL 2061104349SphkXML_GetSpecifiedAttributeCount(XML_Parser p); 2062104349Sphk</pre> 2063104349Sphk<div class="fcndef"> 2064104349SphkWhen attributes are reported to the start handler in the atts vector, 2065104349Sphkattributes that were explicitly set in the element occur before any 2066104349Sphkattributes that receive their value from default information in an 2067104349SphkATTLIST declaration. This function returns the number of attributes 2068104349Sphkthat were explicitly set times two, thus giving the offset in the 2069104349Sphk<code>atts</code> array passed to the start tag handler of the first 2070104349Sphkattribute set due to defaults. It supplies information for the last 2071104349Sphkcall to a start handler. If called inside a start handler, then that 2072104349Sphkmeans the current call. 2073104349Sphk</div> 2074104349Sphk 2075104349Sphk<pre class="fcndec" id="XML_GetIdAttributeIndex"> 2076178848Scokaneint XMLCALL 2077104349SphkXML_GetIdAttributeIndex(XML_Parser p); 2078104349Sphk</pre> 2079104349Sphk<div class="fcndef"> 2080104349SphkReturns the index of the ID attribute passed in the atts array in the 2081104349Sphklast call to <code><a href= "#XML_StartElementHandler" 2082104349Sphk>XML_StartElementHandler</a></code>, or -1 if there is no ID 2083104349Sphkattribute. If called inside a start handler, then that means the 2084104349Sphkcurrent call. 2085104349Sphk</div> 2086104349Sphk 2087247513Sdelphij<pre class="fcndec" id="XML_GetAttributeInfo"> 2088247513Sdelphijconst XML_AttrInfo * XMLCALL 2089247513SdelphijXML_GetAttributeInfo(XML_Parser parser); 2090247513Sdelphij</pre> 2091247513Sdelphij<pre class="signature"> 2092247513Sdelphijtypedef struct { 2093247513Sdelphij XML_Index nameStart; /* Offset to beginning of the attribute name. */ 2094247513Sdelphij XML_Index nameEnd; /* Offset after the attribute name's last byte. */ 2095247513Sdelphij XML_Index valueStart; /* Offset to beginning of the attribute value. */ 2096247513Sdelphij XML_Index valueEnd; /* Offset after the attribute value's last byte. */ 2097247513Sdelphij} XML_AttrInfo; 2098247513Sdelphij</pre> 2099247513Sdelphij<div class="fcndef"> 2100247513SdelphijReturns an array of <code>XML_AttrInfo</code> structures for the 2101247513Sdelphijattribute/value pairs passed in the last call to the 2102247513Sdelphij<code>XML_StartElementHandler</code> that were specified 2103247513Sdelphijin the start-tag rather than defaulted. Each attribute/value pair counts 2104247513Sdelphijas 1; thus the number of entries in the array is 2105247513Sdelphij<code>XML_GetSpecifiedAttributeCount(parser) / 2</code>. 2106247513Sdelphij</div> 2107247513Sdelphij 2108104349Sphk<pre class="fcndec" id="XML_SetEncoding"> 2109178848Scokaneenum XML_Status XMLCALL 2110104349SphkXML_SetEncoding(XML_Parser p, 2111104349Sphk const XML_Char *encoding); 2112104349Sphk</pre> 2113104349Sphk<div class="fcndef"> 2114104349SphkSet the encoding to be used by the parser. It is equivalent to 2115104349Sphkpassing a non-null encoding argument to the parser creation functions. 2116104349SphkIt must not be called after <code><a href= "#XML_Parse" 2117104349Sphk>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 2118104349Sphk>XML_ParseBuffer</a></code> have been called on the given parser. 2119178848ScokaneReturns <code>XML_STATUS_OK</code> on success or 2120178848Scokane<code>XML_STATUS_ERROR</code> on error. 2121104349Sphk</div> 2122104349Sphk 2123104349Sphk<pre class="fcndec" id="XML_SetParamEntityParsing"> 2124178848Scokaneint XMLCALL 2125104349SphkXML_SetParamEntityParsing(XML_Parser p, 2126104349Sphk enum XML_ParamEntityParsing code); 2127104349Sphk</pre> 2128104349Sphk<div class="fcndef"> 2129104349SphkThis enables parsing of parameter entities, including the external 2130104349Sphkparameter entity that is the external DTD subset, according to 2131104349Sphk<code>code</code>. 2132104349SphkThe choices for <code>code</code> are: 2133104349Sphk<ul> 2134104349Sphk<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li> 2135104349Sphk<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li> 2136104349Sphk<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li> 2137104349Sphk</ul> 2138247513Sdelphij<b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after 2139247513Sdelphij<code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has 2140247513Sdelphijno effect and will always return 0. 2141104349Sphk</div> 2142104349Sphk 2143247513Sdelphij<pre class="fcndec" id="XML_SetHashSalt"> 2144247513Sdelphijint XMLCALL 2145247513SdelphijXML_SetHashSalt(XML_Parser p, 2146247513Sdelphij unsigned long hash_salt); 2147247513Sdelphij</pre> 2148247513Sdelphij<div class="fcndef"> 2149247513SdelphijSets the hash salt to use for internal hash calculations. 2150247513SdelphijHelps in preventing DoS attacks based on predicting hash 2151247513Sdelphijfunction behavior. In order to have an effect this must be called 2152247513Sdelphijbefore parsing has started. Returns 1 if successful, 0 when called 2153247513Sdelphijafter <code>XML_Parse</code> or <code>XML_ParseBuffer</code>. 2154247513Sdelphij<p><b>Note:</b> This call is optional, as the parser will auto-generate a new 2155247513Sdelphijrandom salt value if no value has been set at the start of parsing.</p> 2156247513Sdelphij</div> 2157247513Sdelphij 2158104349Sphk<pre class="fcndec" id="XML_UseForeignDTD"> 2159178848Scokaneenum XML_Error XMLCALL 2160104349SphkXML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); 2161104349Sphk</pre> 2162104349Sphk<div class="fcndef"> 2163104349Sphk<p>This function allows an application to provide an external subset 2164104349Sphkfor the document type declaration for documents which do not specify 2165104349Sphkan external subset of their own. For documents which specify an 2166104349Sphkexternal subset in their DOCTYPE declaration, the application-provided 2167104349Sphksubset will be ignored. If the document does not contain a DOCTYPE 2168104349Sphkdeclaration at all and <code>useDTD</code> is true, the 2169104349Sphkapplication-provided subset will be parsed, but the 2170104349Sphk<code>startDoctypeDeclHandler</code> and 2171104349Sphk<code>endDoctypeDeclHandler</code> functions, if set, will not be 2172104349Sphkcalled. The setting of parameter entity parsing, controlled using 2173104349Sphk<code><a href= "#XML_SetParamEntityParsing" 2174104349Sphk>XML_SetParamEntityParsing</a></code>, will be honored.</p> 2175104349Sphk 2176104349Sphk<p>The application-provided external subset is read by calling the 2177104349Sphkexternal entity reference handler set via <code><a href= 2178104349Sphk"#XML_SetExternalEntityRefHandler" 2179104349Sphk>XML_SetExternalEntityRefHandler</a></code> with both 2180104349Sphk<code>publicId</code> and <code>systemId</code> set to NULL.</p> 2181104349Sphk 2182104349Sphk<p>If this function is called after parsing has begun, it returns 2183104349Sphk<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores 2184104349Sphk<code>useDTD</code>. If called when Expat has been compiled without 2185104349SphkDTD support, it returns 2186104349Sphk<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise, it 2187104349Sphkreturns <code>XML_ERROR_NONE</code>.</p> 2188178848Scokane 2189178848Scokane<p><b>Note:</b> For the purpose of checking WFC: Entity Declared, passing 2190178848Scokane<code>useDTD == XML_TRUE</code> will make the parser behave as if 2191178848Scokanethe document had a DTD with an external subset. This holds true even if 2192178848Scokanethe external entity reference handler returns without action.</p> 2193104349Sphk</div> 2194104349Sphk 2195104349Sphk<pre class="fcndec" id="XML_SetReturnNSTriplet"> 2196178848Scokanevoid XMLCALL 2197104349SphkXML_SetReturnNSTriplet(XML_Parser parser, 2198104349Sphk int do_nst); 2199104349Sphk</pre> 2200104349Sphk<div class="fcndef"> 2201104349Sphk<p> 2202104349SphkThis function only has an effect when using a parser created with 2203104349Sphk<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, 2204104349Sphki.e. when namespace processing is in effect. The <code>do_nst</code> 2205104349Sphksets whether or not prefixes are returned with names qualified with a 2206104349Sphknamespace prefix. If this function is called with <code>do_nst</code> 2207104349Sphknon-zero, then afterwards namespace qualified names (that is qualified 2208104349Sphkwith a prefix as opposed to belonging to a default namespace) are 2209104349Sphkreturned as a triplet with the three parts separated by the namespace 2210104349Sphkseparator specified when the parser was created. The order of 2211104349Sphkreturned parts is URI, local name, and prefix.</p> <p>If 2212104349Sphk<code>do_nst</code> is zero, then namespaces are reported in the 2213104349Sphkdefault manner, URI then local_name separated by the namespace 2214104349Sphkseparator.</p> 2215104349Sphk</div> 2216104349Sphk 2217104349Sphk<pre class="fcndec" id="XML_DefaultCurrent"> 2218178848Scokanevoid XMLCALL 2219104349SphkXML_DefaultCurrent(XML_Parser parser); 2220104349Sphk</pre> 2221104349Sphk<div class="fcndef"> 2222104349SphkThis can be called within a handler for a start element, end element, 2223104349Sphkprocessing instruction or character data. It causes the corresponding 2224104349Sphkmarkup to be passed to the default handler set by <code><a 2225104349Sphkhref="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or 2226104349Sphk<code><a href="#XML_SetDefaultHandlerExpand" 2227104349Sphk>XML_SetDefaultHandlerExpand</a></code>. It does nothing if there is 2228104349Sphknot a default handler. 2229104349Sphk</div> 2230104349Sphk 2231104349Sphk<pre class="fcndec" id="XML_ExpatVersion"> 2232178848ScokaneXML_LChar * XMLCALL 2233104349SphkXML_ExpatVersion(); 2234104349Sphk</pre> 2235104349Sphk<div class="fcndef"> 2236104349SphkReturn the library version as a string (e.g. <code>"expat_1.95.1"</code>). 2237104349Sphk</div> 2238104349Sphk 2239104349Sphk<pre class="fcndec" id="XML_ExpatVersionInfo"> 2240178848Scokanestruct XML_Expat_Version XMLCALL 2241104349SphkXML_ExpatVersionInfo(); 2242104349Sphk</pre> 2243104349Sphk<pre class="signature"> 2244104349Sphktypedef struct { 2245104349Sphk int major; 2246104349Sphk int minor; 2247104349Sphk int micro; 2248104349Sphk} XML_Expat_Version; 2249104349Sphk</pre> 2250104349Sphk<div class="fcndef"> 2251104349SphkReturn the library version information as a structure. 2252104349SphkSome macros are also defined that support compile-time tests of the 2253104349Sphklibrary version: 2254104349Sphk<ul> 2255104349Sphk<li><code>XML_MAJOR_VERSION</code></li> 2256104349Sphk<li><code>XML_MINOR_VERSION</code></li> 2257104349Sphk<li><code>XML_MICRO_VERSION</code></li> 2258104349Sphk</ul> 2259104349SphkTesting these constants is currently the best way to determine if 2260104349Sphkparticular parts of the Expat API are available. 2261104349Sphk</div> 2262104349Sphk 2263104349Sphk<pre class="fcndec" id="XML_GetFeatureList"> 2264178848Scokaneconst XML_Feature * XMLCALL 2265104349SphkXML_GetFeatureList(); 2266104349Sphk</pre> 2267104349Sphk<pre class="signature"> 2268104349Sphkenum XML_FeatureEnum { 2269104349Sphk XML_FEATURE_END = 0, 2270104349Sphk XML_FEATURE_UNICODE, 2271104349Sphk XML_FEATURE_UNICODE_WCHAR_T, 2272104349Sphk XML_FEATURE_DTD, 2273104349Sphk XML_FEATURE_CONTEXT_BYTES, 2274104349Sphk XML_FEATURE_MIN_SIZE, 2275104349Sphk XML_FEATURE_SIZEOF_XML_CHAR, 2276178848Scokane XML_FEATURE_SIZEOF_XML_LCHAR, 2277178848Scokane XML_FEATURE_NS, 2278178848Scokane XML_FEATURE_LARGE_SIZE 2279104349Sphk}; 2280104349Sphk 2281104349Sphktypedef struct { 2282104349Sphk enum XML_FeatureEnum feature; 2283104349Sphk XML_LChar *name; 2284104349Sphk long int value; 2285104349Sphk} XML_Feature; 2286104349Sphk</pre> 2287104349Sphk<div class="fcndef"> 2288104349Sphk<p>Returns a list of "feature" records, providing details on how 2289104349SphkExpat was configured at compile time. Most applications should not 2290104349Sphkneed to worry about this, but this information is otherwise not 2291104349Sphkavailable from Expat. This function allows code that does need to 2292104349Sphkcheck these features to do so at runtime.</p> 2293104349Sphk 2294104349Sphk<p>The return value is an array of <code>XML_Feature</code>, 2295104349Sphkterminated by a record with a <code>feature</code> of 2296104349Sphk<code>XML_FEATURE_END</code> and <code>name</code> of NULL, 2297104349Sphkidentifying the feature-test macros Expat was compiled with. Since an 2298104349Sphkapplication that requires this kind of information needs to determine 2299104349Sphkthe type of character the <code>name</code> points to, records for the 2300104349Sphk<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and 2301104349Sphk<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the 2302104349Sphkbeginning of the list, followed by <code>XML_FEATURE_UNICODE</code> 2303104349Sphkand <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at 2304104349Sphkall.</p> 2305104349Sphk 2306104349Sphk<p>Some features have an associated value. If there isn't an 2307104349Sphkassociated value, the <code>value</code> field is set to 0. At this 2308104349Sphktime, the following features have been defined to have values:</p> 2309104349Sphk 2310104349Sphk<dl> 2311104349Sphk <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt> 2312104349Sphk <dd>The number of bytes occupied by one <code>XML_Char</code> 2313104349Sphk character.</dd> 2314104349Sphk <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt> 2315104349Sphk <dd>The number of bytes occupied by one <code>XML_LChar</code> 2316104349Sphk character.</dd> 2317104349Sphk <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt> 2318104349Sphk <dd>The maximum number of characters of context which can be 2319104349Sphk reported by <code><a href= "#XML_GetInputContext" 2320104349Sphk >XML_GetInputContext</a></code>.</dd> 2321104349Sphk</dl> 2322104349Sphk</div> 2323104349Sphk 2324178848Scokane<pre class="fcndec" id="XML_FreeContentModel"> 2325178848Scokanevoid XMLCALL 2326178848ScokaneXML_FreeContentModel(XML_Parser parser, XML_Content *model); 2327178848Scokane</pre> 2328178848Scokane<div class="fcndef"> 2329178848ScokaneFunction to deallocate the <code>model</code> argument passed to the 2330178848Scokane<code>XML_ElementDeclHandler</code> callback set using <code><a 2331178848Scokanehref="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>. 2332178848ScokaneThis function should not be used for any other purpose. 2333178848Scokane</div> 2334178848Scokane 2335178848Scokane<p>The following functions allow external code to share the memory 2336178848Scokaneallocator an <code>XML_Parser</code> has been configured to use. This 2337178848Scokaneis especially useful for third-party libraries that interact with a 2338178848Scokaneparser object created by application code, or heavily layered 2339178848Scokaneapplications. This can be essential when using dynamically loaded 2340178848Scokanelibraries which use different C standard libraries (this can happen on 2341178848ScokaneWindows, at least).</p> 2342178848Scokane 2343178848Scokane<pre class="fcndec" id="XML_MemMalloc"> 2344178848Scokanevoid * XMLCALL 2345178848ScokaneXML_MemMalloc(XML_Parser parser, size_t size); 2346178848Scokane</pre> 2347178848Scokane<div class="fcndef"> 2348178848ScokaneAllocate <code>size</code> bytes of memory using the allocator the 2349178848Scokane<code>parser</code> object has been configured to use. Returns a 2350178848Scokanepointer to the memory or NULL on failure. Memory allocated in this 2351178848Scokaneway must be freed using <code><a href="#XML_MemFree" 2352178848Scokane>XML_MemFree</a></code>. 2353178848Scokane</div> 2354178848Scokane 2355178848Scokane<pre class="fcndec" id="XML_MemRealloc"> 2356178848Scokanevoid * XMLCALL 2357178848ScokaneXML_MemRealloc(XML_Parser parser, void *ptr, size_t size); 2358178848Scokane</pre> 2359178848Scokane<div class="fcndef"> 2360178848ScokaneAllocate <code>size</code> bytes of memory using the allocator the 2361178848Scokane<code>parser</code> object has been configured to use. 2362178848Scokane<code>ptr</code> must point to a block of memory allocated by <code><a 2363178848Scokanehref="#XML_MemMalloc" >XML_MemMalloc</a></code> or 2364178848Scokane<code>XML_MemRealloc</code>, or be NULL. This function tries to 2365178848Scokaneexpand the block pointed to by <code>ptr</code> if possible. Returns 2366178848Scokanea pointer to the memory or NULL on failure. On success, the original 2367178848Scokaneblock has either been expanded or freed. On failure, the original 2368178848Scokaneblock has not been freed; the caller is responsible for freeing the 2369178848Scokaneoriginal block. Memory allocated in this way must be freed using 2370178848Scokane<code><a href="#XML_MemFree" 2371178848Scokane>XML_MemFree</a></code>. 2372178848Scokane</div> 2373178848Scokane 2374178848Scokane<pre class="fcndec" id="XML_MemFree"> 2375178848Scokanevoid XMLCALL 2376178848ScokaneXML_MemFree(XML_Parser parser, void *ptr); 2377178848Scokane</pre> 2378178848Scokane<div class="fcndef"> 2379178848ScokaneFree a block of memory pointed to by <code>ptr</code>. The block must 2380178848Scokanehave been allocated by <code><a href="#XML_MemMalloc" 2381178848Scokane>XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be NULL. 2382178848Scokane</div> 2383178848Scokane 2384104349Sphk<hr /> 2385104349Sphk<p><a href="http://validator.w3.org/check/referer"><img 2386104349Sphk src="valid-xhtml10.png" alt="Valid XHTML 1.0!" 2387104349Sphk height="31" width="88" class="noborder" /></a></p> 2388178848Scokane</div> 2389104349Sphk</body> 2390104349Sphk</html> 2391
