1*1230fdc1SLionel Sambuc<?xml version="1.0" encoding="iso-8859-1"?> 2*1230fdc1SLionel Sambuc<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 3*1230fdc1SLionel Sambuc "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 4*1230fdc1SLionel Sambuc<html> 5*1230fdc1SLionel Sambuc<head> 6*1230fdc1SLionel Sambuc<!-- Copyright 1999,2000 Clark Cooper <coopercc@netheaven.com> 7*1230fdc1SLionel Sambuc All rights reserved. 8*1230fdc1SLionel Sambuc This is free software. You may distribute or modify according to 9*1230fdc1SLionel Sambuc the terms of the MIT/X License --> 10*1230fdc1SLionel Sambuc <title>Expat XML Parser</title> 11*1230fdc1SLionel Sambuc <meta name="author" content="Clark Cooper, coopercc@netheaven.com" /> 12*1230fdc1SLionel Sambuc <meta http-equiv="Content-Style-Type" content="text/css" /> 13*1230fdc1SLionel Sambuc <link href="style.css" rel="stylesheet" type="text/css" /> 14*1230fdc1SLionel Sambuc</head> 15*1230fdc1SLionel Sambuc<body> 16*1230fdc1SLionel Sambuc <table cellspacing="0" cellpadding="0" width="100%"> 17*1230fdc1SLionel Sambuc <tr> 18*1230fdc1SLionel Sambuc <td class="corner"><img src="expat.png" alt="(Expat logo)" /></td> 19*1230fdc1SLionel Sambuc <td class="banner"><h1>The Expat XML Parser</h1></td> 20*1230fdc1SLionel Sambuc </tr> 21*1230fdc1SLionel Sambuc <tr> 22*1230fdc1SLionel Sambuc <td class="releaseno">Release 2.0.1</td> 23*1230fdc1SLionel Sambuc <td></td> 24*1230fdc1SLionel Sambuc </tr> 25*1230fdc1SLionel Sambuc </table> 26*1230fdc1SLionel Sambuc<div class="content"> 27*1230fdc1SLionel Sambuc 28*1230fdc1SLionel Sambuc<p>Expat is a library, written in C, for parsing XML documents. It's 29*1230fdc1SLionel Sambucthe underlying XML parser for the open source Mozilla project, Perl's 30*1230fdc1SLionel Sambuc<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and 31*1230fdc1SLionel Sambucother open-source XML parsers.</p> 32*1230fdc1SLionel Sambuc 33*1230fdc1SLionel Sambuc<p>This library is the creation of James Clark, who's also given us 34*1230fdc1SLionel Sambucgroff (an nroff look-alike), Jade (an implemention of ISO's DSSSL 35*1230fdc1SLionel Sambucstylesheet language for SGML), XP (a Java XML parser package), XT (a 36*1230fdc1SLionel SambucJava XSL engine). James was also the technical lead on the XML 37*1230fdc1SLionel SambucWorking Group at W3C that produced the XML specification.</p> 38*1230fdc1SLionel Sambuc 39*1230fdc1SLionel Sambuc<p>This is free software, licensed under the <a 40*1230fdc1SLionel Sambuchref="../COPYING">MIT/X Consortium license</a>. You may download it 41*1230fdc1SLionel Sambucfrom <a href="http://www.libexpat.org/">the Expat home page</a>. 42*1230fdc1SLionel Sambuc</p> 43*1230fdc1SLionel Sambuc 44*1230fdc1SLionel Sambuc<p>The bulk of this document was originally commissioned as an article 45*1230fdc1SLionel Sambucby <a href="http://www.xml.com/">XML.com</a>. They graciously allowed 46*1230fdc1SLionel SambucClark Cooper to retain copyright and to distribute it with Expat. 47*1230fdc1SLionel SambucThis version has been substantially extended to include documentation 48*1230fdc1SLionel Sambucon features which have been added since the original article was 49*1230fdc1SLionel Sambucpublished, and additional information on using the original 50*1230fdc1SLionel Sambucinterface.</p> 51*1230fdc1SLionel Sambuc 52*1230fdc1SLionel Sambuc<hr /> 53*1230fdc1SLionel Sambuc<h2>Table of Contents</h2> 54*1230fdc1SLionel Sambuc<ul> 55*1230fdc1SLionel Sambuc <li><a href="#overview">Overview</a></li> 56*1230fdc1SLionel Sambuc <li><a href="#building">Building and Installing</a></li> 57*1230fdc1SLionel Sambuc <li><a href="#using">Using Expat</a></li> 58*1230fdc1SLionel Sambuc <li><a href="#reference">Reference</a> 59*1230fdc1SLionel Sambuc <ul> 60*1230fdc1SLionel Sambuc <li><a href="#creation">Parser Creation Functions</a> 61*1230fdc1SLionel Sambuc <ul> 62*1230fdc1SLionel Sambuc <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li> 63*1230fdc1SLionel Sambuc <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li> 64*1230fdc1SLionel Sambuc <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li> 65*1230fdc1SLionel Sambuc <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li> 66*1230fdc1SLionel Sambuc <li><a href="#XML_ParserFree">XML_ParserFree</a></li> 67*1230fdc1SLionel Sambuc <li><a href="#XML_ParserReset">XML_ParserReset</a></li> 68*1230fdc1SLionel Sambuc </ul> 69*1230fdc1SLionel Sambuc </li> 70*1230fdc1SLionel Sambuc <li><a href="#parsing">Parsing Functions</a> 71*1230fdc1SLionel Sambuc <ul> 72*1230fdc1SLionel Sambuc <li><a href="#XML_Parse">XML_Parse</a></li> 73*1230fdc1SLionel Sambuc <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li> 74*1230fdc1SLionel Sambuc <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li> 75*1230fdc1SLionel Sambuc <li><a href="#XML_StopParser">XML_StopParser</a></li> 76*1230fdc1SLionel Sambuc <li><a href="#XML_ResumeParser">XML_ResumeParser</a></li> 77*1230fdc1SLionel Sambuc <li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li> 78*1230fdc1SLionel Sambuc </ul> 79*1230fdc1SLionel Sambuc </li> 80*1230fdc1SLionel Sambuc <li><a href="#setting">Handler Setting Functions</a> 81*1230fdc1SLionel Sambuc <ul> 82*1230fdc1SLionel Sambuc <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li> 83*1230fdc1SLionel Sambuc <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li> 84*1230fdc1SLionel Sambuc <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li> 85*1230fdc1SLionel Sambuc <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li> 86*1230fdc1SLionel Sambuc <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li> 87*1230fdc1SLionel Sambuc <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li> 88*1230fdc1SLionel Sambuc <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li> 89*1230fdc1SLionel Sambuc <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li> 90*1230fdc1SLionel Sambuc <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li> 91*1230fdc1SLionel Sambuc <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li> 92*1230fdc1SLionel Sambuc <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li> 93*1230fdc1SLionel Sambuc <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li> 94*1230fdc1SLionel Sambuc <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li> 95*1230fdc1SLionel Sambuc <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li> 96*1230fdc1SLionel Sambuc <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li> 97*1230fdc1SLionel Sambuc <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li> 98*1230fdc1SLionel Sambuc <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li> 99*1230fdc1SLionel Sambuc <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li> 100*1230fdc1SLionel Sambuc <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li> 101*1230fdc1SLionel Sambuc <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li> 102*1230fdc1SLionel Sambuc <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li> 103*1230fdc1SLionel Sambuc <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li> 104*1230fdc1SLionel Sambuc <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li> 105*1230fdc1SLionel Sambuc <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li> 106*1230fdc1SLionel Sambuc <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li> 107*1230fdc1SLionel Sambuc <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li> 108*1230fdc1SLionel Sambuc <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li> 109*1230fdc1SLionel Sambuc <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li> 110*1230fdc1SLionel Sambuc </ul> 111*1230fdc1SLionel Sambuc </li> 112*1230fdc1SLionel Sambuc <li><a href="#position">Parse Position and Error Reporting Functions</a> 113*1230fdc1SLionel Sambuc <ul> 114*1230fdc1SLionel Sambuc <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li> 115*1230fdc1SLionel Sambuc <li><a href="#XML_ErrorString">XML_ErrorString</a></li> 116*1230fdc1SLionel Sambuc <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li> 117*1230fdc1SLionel Sambuc <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li> 118*1230fdc1SLionel Sambuc <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li> 119*1230fdc1SLionel Sambuc <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li> 120*1230fdc1SLionel Sambuc <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li> 121*1230fdc1SLionel Sambuc </ul> 122*1230fdc1SLionel Sambuc </li> 123*1230fdc1SLionel Sambuc <li><a href="#miscellaneous">Miscellaneous Functions</a> 124*1230fdc1SLionel Sambuc <ul> 125*1230fdc1SLionel Sambuc <li><a href="#XML_SetUserData">XML_SetUserData</a></li> 126*1230fdc1SLionel Sambuc <li><a href="#XML_GetUserData">XML_GetUserData</a></li> 127*1230fdc1SLionel Sambuc <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li> 128*1230fdc1SLionel Sambuc <li><a href="#XML_SetBase">XML_SetBase</a></li> 129*1230fdc1SLionel Sambuc <li><a href="#XML_GetBase">XML_GetBase</a></li> 130*1230fdc1SLionel Sambuc <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li> 131*1230fdc1SLionel Sambuc <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li> 132*1230fdc1SLionel Sambuc <li><a href="#XML_GetAttributeInfo">XML_GetAttributeInfo</a></li> 133*1230fdc1SLionel Sambuc <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li> 134*1230fdc1SLionel Sambuc <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li> 135*1230fdc1SLionel Sambuc <li><a href="#XML_SetHashSalt">XML_SetHashSalt</a></li> 136*1230fdc1SLionel Sambuc <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li> 137*1230fdc1SLionel Sambuc <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li> 138*1230fdc1SLionel Sambuc <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li> 139*1230fdc1SLionel Sambuc <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li> 140*1230fdc1SLionel Sambuc <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li> 141*1230fdc1SLionel Sambuc <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li> 142*1230fdc1SLionel Sambuc <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li> 143*1230fdc1SLionel Sambuc <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li> 144*1230fdc1SLionel Sambuc <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li> 145*1230fdc1SLionel Sambuc <li><a href="#XML_MemFree">XML_MemFree</a></li> 146*1230fdc1SLionel Sambuc </ul> 147*1230fdc1SLionel Sambuc </li> 148*1230fdc1SLionel Sambuc </ul> 149*1230fdc1SLionel Sambuc </li> 150*1230fdc1SLionel Sambuc</ul> 151*1230fdc1SLionel Sambuc 152*1230fdc1SLionel Sambuc<hr /> 153*1230fdc1SLionel Sambuc<h2><a name="overview">Overview</a></h2> 154*1230fdc1SLionel Sambuc 155*1230fdc1SLionel Sambuc<p>Expat is a stream-oriented parser. You register callback (or 156*1230fdc1SLionel Sambuchandler) functions with the parser and then start feeding it the 157*1230fdc1SLionel Sambucdocument. As the parser recognizes parts of the document, it will 158*1230fdc1SLionel Sambuccall the appropriate handler for that part (if you've registered one.) 159*1230fdc1SLionel SambucThe document is fed to the parser in pieces, so you can start parsing 160*1230fdc1SLionel Sambucbefore you have all the document. This also allows you to parse really 161*1230fdc1SLionel Sambuchuge documents that won't fit into memory.</p> 162*1230fdc1SLionel Sambuc 163*1230fdc1SLionel Sambuc<p>Expat can be intimidating due to the many kinds of handlers and 164*1230fdc1SLionel Sambucoptions you can set. But you only need to learn four functions in 165*1230fdc1SLionel Sambucorder to do 90% of what you'll want to do with it:</p> 166*1230fdc1SLionel Sambuc 167*1230fdc1SLionel Sambuc<dl> 168*1230fdc1SLionel Sambuc 169*1230fdc1SLionel Sambuc<dt><code><a href= "#XML_ParserCreate" 170*1230fdc1SLionel Sambuc >XML_ParserCreate</a></code></dt> 171*1230fdc1SLionel Sambuc <dd>Create a new parser object.</dd> 172*1230fdc1SLionel Sambuc 173*1230fdc1SLionel Sambuc<dt><code><a href= "#XML_SetElementHandler" 174*1230fdc1SLionel Sambuc >XML_SetElementHandler</a></code></dt> 175*1230fdc1SLionel Sambuc <dd>Set handlers for start and end tags.</dd> 176*1230fdc1SLionel Sambuc 177*1230fdc1SLionel Sambuc<dt><code><a href= "#XML_SetCharacterDataHandler" 178*1230fdc1SLionel Sambuc >XML_SetCharacterDataHandler</a></code></dt> 179*1230fdc1SLionel Sambuc <dd>Set handler for text.</dd> 180*1230fdc1SLionel Sambuc 181*1230fdc1SLionel Sambuc<dt><code><a href= "#XML_Parse" 182*1230fdc1SLionel Sambuc >XML_Parse</a></code></dt> 183*1230fdc1SLionel Sambuc <dd>Pass a buffer full of document to the parser</dd> 184*1230fdc1SLionel Sambuc</dl> 185*1230fdc1SLionel Sambuc 186*1230fdc1SLionel Sambuc<p>These functions and others are described in the <a 187*1230fdc1SLionel Sambuchref="#reference">reference</a> part of this document. The reference 188*1230fdc1SLionel Sambucsection also describes in detail the parameters passed to the 189*1230fdc1SLionel Sambucdifferent types of handlers.</p> 190*1230fdc1SLionel Sambuc 191*1230fdc1SLionel Sambuc<p>Let's look at a very simple example program that only uses 3 of the 192*1230fdc1SLionel Sambucabove functions (it doesn't need to set a character handler.) The 193*1230fdc1SLionel Sambucprogram <a href="../examples/outline.c">outline.c</a> prints an 194*1230fdc1SLionel Sambucelement outline, indenting child elements to distinguish them from the 195*1230fdc1SLionel Sambucparent element that contains them. The start handler does all the 196*1230fdc1SLionel Sambucwork. It prints two indenting spaces for every level of ancestor 197*1230fdc1SLionel Sambucelements, then it prints the element and attribute 198*1230fdc1SLionel Sambucinformation. Finally it increments the global <code>Depth</code> 199*1230fdc1SLionel Sambucvariable.</p> 200*1230fdc1SLionel Sambuc 201*1230fdc1SLionel Sambuc<pre class="eg"> 202*1230fdc1SLionel Sambucint Depth; 203*1230fdc1SLionel Sambuc 204*1230fdc1SLionel Sambucvoid XMLCALL 205*1230fdc1SLionel Sambucstart(void *data, const char *el, const char **attr) { 206*1230fdc1SLionel Sambuc int i; 207*1230fdc1SLionel Sambuc 208*1230fdc1SLionel Sambuc for (i = 0; i < Depth; i++) 209*1230fdc1SLionel Sambuc printf(" "); 210*1230fdc1SLionel Sambuc 211*1230fdc1SLionel Sambuc printf("%s", el); 212*1230fdc1SLionel Sambuc 213*1230fdc1SLionel Sambuc for (i = 0; attr[i]; i += 2) { 214*1230fdc1SLionel Sambuc printf(" %s='%s'", attr[i], attr[i + 1]); 215*1230fdc1SLionel Sambuc } 216*1230fdc1SLionel Sambuc 217*1230fdc1SLionel Sambuc printf("\n"); 218*1230fdc1SLionel Sambuc Depth++; 219*1230fdc1SLionel Sambuc} /* End of start handler */ 220*1230fdc1SLionel Sambuc</pre> 221*1230fdc1SLionel Sambuc 222*1230fdc1SLionel Sambuc<p>The end tag simply does the bookkeeping work of decrementing 223*1230fdc1SLionel Sambuc<code>Depth</code>.</p> 224*1230fdc1SLionel Sambuc<pre class="eg"> 225*1230fdc1SLionel Sambucvoid XMLCALL 226*1230fdc1SLionel Sambucend(void *data, const char *el) { 227*1230fdc1SLionel Sambuc Depth--; 228*1230fdc1SLionel Sambuc} /* End of end handler */ 229*1230fdc1SLionel Sambuc</pre> 230*1230fdc1SLionel Sambuc 231*1230fdc1SLionel Sambuc<p>Note the <code>XMLCALL</code> annotation used for the callbacks. 232*1230fdc1SLionel SambucThis is used to ensure that the Expat and the callbacks are using the 233*1230fdc1SLionel Sambucsame calling convention in case the compiler options used for Expat 234*1230fdc1SLionel Sambucitself and the client code are different. Expat tries not to care 235*1230fdc1SLionel Sambucwhat the default calling convention is, though it may require that it 236*1230fdc1SLionel Sambucbe compiled with a default convention of "cdecl" on some platforms. 237*1230fdc1SLionel SambucFor code which uses Expat, however, the calling convention is 238*1230fdc1SLionel Sambucspecified by the <code>XMLCALL</code> annotation on most platforms; 239*1230fdc1SLionel Sambuccallbacks should be defined using this annotation.</p> 240*1230fdc1SLionel Sambuc 241*1230fdc1SLionel Sambuc<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but 242*1230fdc1SLionel Sambucexisting working Expat applications don't need to add it (since they 243*1230fdc1SLionel Sambucare already using the "cdecl" calling convention, or they wouldn't be 244*1230fdc1SLionel Sambucworking). The annotation is only needed if the default calling 245*1230fdc1SLionel Sambucconvention may be something other than "cdecl". To use the annotation 246*1230fdc1SLionel Sambucsafely with older versions of Expat, you can conditionally define it 247*1230fdc1SLionel Sambuc<em>after</em> including Expat's header file:</p> 248*1230fdc1SLionel Sambuc 249*1230fdc1SLionel Sambuc<pre class="eg"> 250*1230fdc1SLionel Sambuc#include <expat.h> 251*1230fdc1SLionel Sambuc 252*1230fdc1SLionel Sambuc#ifndef XMLCALL 253*1230fdc1SLionel Sambuc#if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) && !defined(__CYGWIN__) 254*1230fdc1SLionel Sambuc#define XMLCALL __cdecl 255*1230fdc1SLionel Sambuc#elif defined(__GNUC__) 256*1230fdc1SLionel Sambuc#define XMLCALL __attribute__((cdecl)) 257*1230fdc1SLionel Sambuc#else 258*1230fdc1SLionel Sambuc#define XMLCALL 259*1230fdc1SLionel Sambuc#endif 260*1230fdc1SLionel Sambuc#endif 261*1230fdc1SLionel Sambuc</pre> 262*1230fdc1SLionel Sambuc 263*1230fdc1SLionel Sambuc<p>After creating the parser, the main program just has the job of 264*1230fdc1SLionel Sambucshoveling the document to the parser so that it can do its work.</p> 265*1230fdc1SLionel Sambuc 266*1230fdc1SLionel Sambuc<hr /> 267*1230fdc1SLionel Sambuc<h2><a name="building">Building and Installing Expat</a></h2> 268*1230fdc1SLionel Sambuc 269*1230fdc1SLionel Sambuc<p>The Expat distribution comes as a compressed (with GNU gzip) tar 270*1230fdc1SLionel Sambucfile. You may download the latest version from <a href= 271*1230fdc1SLionel Sambuc"http://sourceforge.net/projects/expat/" >Source Forge</a>. After 272*1230fdc1SLionel Sambucunpacking this, cd into the directory. Then follow either the Win32 273*1230fdc1SLionel Sambucdirections or Unix directions below.</p> 274*1230fdc1SLionel Sambuc 275*1230fdc1SLionel Sambuc<h3>Building under Win32</h3> 276*1230fdc1SLionel Sambuc 277*1230fdc1SLionel Sambuc<p>If you're using the GNU compiler under cygwin, follow the Unix 278*1230fdc1SLionel Sambucdirections in the next section. Otherwise if you have Microsoft's 279*1230fdc1SLionel SambucDeveloper Studio installed, then from Windows Explorer double-click on 280*1230fdc1SLionel Sambuc"expat.dsp" in the lib directory and build and install in the usual 281*1230fdc1SLionel Sambucmanner.</p> 282*1230fdc1SLionel Sambuc 283*1230fdc1SLionel Sambuc<p>Alternatively, you may download the Win32 binary package that 284*1230fdc1SLionel Sambuccontains the "expat.h" include file and a pre-built DLL.</p> 285*1230fdc1SLionel Sambuc 286*1230fdc1SLionel Sambuc<h3>Building under Unix (or GNU)</h3> 287*1230fdc1SLionel Sambuc 288*1230fdc1SLionel Sambuc<p>First you'll need to run the configure shell script in order to 289*1230fdc1SLionel Sambucconfigure the Makefiles and headers for your system.</p> 290*1230fdc1SLionel Sambuc 291*1230fdc1SLionel Sambuc<p>If you're happy with all the defaults that configure picks for you, 292*1230fdc1SLionel Sambucand you have permission on your system to install into /usr/local, you 293*1230fdc1SLionel Sambuccan install Expat with this sequence of commands:</p> 294*1230fdc1SLionel Sambuc 295*1230fdc1SLionel Sambuc<pre class="eg"> 296*1230fdc1SLionel Sambuc./configure 297*1230fdc1SLionel Sambucmake 298*1230fdc1SLionel Sambucmake install 299*1230fdc1SLionel Sambuc</pre> 300*1230fdc1SLionel Sambuc 301*1230fdc1SLionel Sambuc<p>There are some options that you can provide to this script, but the 302*1230fdc1SLionel Sambuconly one we'll mention here is the <code>--prefix</code> option. You 303*1230fdc1SLionel Sambuccan find out all the options available by running configure with just 304*1230fdc1SLionel Sambucthe <code>--help</code> option.</p> 305*1230fdc1SLionel Sambuc 306*1230fdc1SLionel Sambuc<p>By default, the configure script sets things up so that the library 307*1230fdc1SLionel Sambucgets installed in <code>/usr/local/lib</code> and the associated 308*1230fdc1SLionel Sambucheader file in <code>/usr/local/include</code>. But if you were to 309*1230fdc1SLionel Sambucgive the option, <code>--prefix=/home/me/mystuff</code>, then the 310*1230fdc1SLionel Sambuclibrary and header would get installed in 311*1230fdc1SLionel Sambuc<code>/home/me/mystuff/lib</code> and 312*1230fdc1SLionel Sambuc<code>/home/me/mystuff/include</code> respectively.</p> 313*1230fdc1SLionel Sambuc 314*1230fdc1SLionel Sambuc<h3>Configuring Expat Using the Pre-Processor</h3> 315*1230fdc1SLionel Sambuc 316*1230fdc1SLionel Sambuc<p>Expat's feature set can be configured using a small number of 317*1230fdc1SLionel Sambucpre-processor definitions. The definition of this symbols does not 318*1230fdc1SLionel Sambucaffect the set of entry points for Expat, only the behavior of the API 319*1230fdc1SLionel Sambucand the definition of character types in the case of 320*1230fdc1SLionel Sambuc<code>XML_UNICODE_WCHAR_T</code>. The symbols are:</p> 321*1230fdc1SLionel Sambuc 322*1230fdc1SLionel Sambuc<dl class="cpp-symbols"> 323*1230fdc1SLionel Sambuc<dt>XML_DTD</dt> 324*1230fdc1SLionel Sambuc<dd>Include support for using and reporting DTD-based content. If 325*1230fdc1SLionel Sambucthis is defined, default attribute values from an external DTD subset 326*1230fdc1SLionel Sambucare reported and attribute value normalization occurs based on the 327*1230fdc1SLionel Sambuctype of attributes defined in the external subset. Without 328*1230fdc1SLionel Sambucthis, Expat has a smaller memory footprint and can be faster, but will 329*1230fdc1SLionel Sambucnot load external entities or process conditional sections. This does 330*1230fdc1SLionel Sambucnot affect the set of functions available in the API.</dd> 331*1230fdc1SLionel Sambuc 332*1230fdc1SLionel Sambuc<dt>XML_NS</dt> 333*1230fdc1SLionel Sambuc<dd>When defined, support for the <cite><a href= 334*1230fdc1SLionel Sambuc"http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite> 335*1230fdc1SLionel Sambucspecification is included.</dd> 336*1230fdc1SLionel Sambuc 337*1230fdc1SLionel Sambuc<dt>XML_UNICODE</dt> 338*1230fdc1SLionel Sambuc<dd>When defined, character data reported to the application is 339*1230fdc1SLionel Sambucencoded in UTF-16 using wide characters of the type 340*1230fdc1SLionel Sambuc<code>XML_Char</code>. This is implied if 341*1230fdc1SLionel Sambuc<code>XML_UNICODE_WCHAR_T</code> is defined.</dd> 342*1230fdc1SLionel Sambuc 343*1230fdc1SLionel Sambuc<dt>XML_UNICODE_WCHAR_T</dt> 344*1230fdc1SLionel Sambuc<dd>If defined, causes the <code>XML_Char</code> character type to be 345*1230fdc1SLionel Sambucdefined using the <code>wchar_t</code> type; otherwise, <code>unsigned 346*1230fdc1SLionel Sambucshort</code> is used. Defining this implies 347*1230fdc1SLionel Sambuc<code>XML_UNICODE</code>.</dd> 348*1230fdc1SLionel Sambuc 349*1230fdc1SLionel Sambuc<dt>XML_LARGE_SIZE</dt> 350*1230fdc1SLionel Sambuc<dd>If defined, causes the <code>XML_Size</code> and <code>XML_Index</code> 351*1230fdc1SLionel Sambucinteger types to be at least 64 bits in size. This is intended to support 352*1230fdc1SLionel Sambucprocessing of very large input streams, where the return values of 353*1230fdc1SLionel Sambuc<code><a href="#XML_GetCurrentByteIndex" >XML_GetCurrentByteIndex</a></code>, 354*1230fdc1SLionel Sambuc<code><a href="#XML_GetCurrentLineNumber" >XML_GetCurrentLineNumber</a></code> and 355*1230fdc1SLionel Sambuc<code><a href="#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code> 356*1230fdc1SLionel Sambuccould overflow. It may not be supported by all compilers, and is turned 357*1230fdc1SLionel Sambucoff by default.</dd> 358*1230fdc1SLionel Sambuc 359*1230fdc1SLionel Sambuc<dt>XML_CONTEXT_BYTES</dt> 360*1230fdc1SLionel Sambuc<dd>The number of input bytes of markup context which the parser will 361*1230fdc1SLionel Sambucensure are available for reporting via <code><a href= 362*1230fdc1SLionel Sambuc"#XML_GetInputContext" >XML_GetInputContext</a></code>. This is 363*1230fdc1SLionel Sambucnormally set to 1024, and must be set to a positive interger. If this 364*1230fdc1SLionel Sambucis not defined, the input context will not be available and <code><a 365*1230fdc1SLionel Sambuchref= "#XML_GetInputContext" >XML_GetInputContext</a></code> will 366*1230fdc1SLionel Sambucalways report NULL. Without this, Expat has a smaller memory 367*1230fdc1SLionel Sambucfootprint and can be faster.</dd> 368*1230fdc1SLionel Sambuc 369*1230fdc1SLionel Sambuc<dt>XML_STATIC</dt> 370*1230fdc1SLionel Sambuc<dd>On Windows, this should be set if Expat is going to be linked 371*1230fdc1SLionel Sambucstatically with the code that calls it; this is required to get all 372*1230fdc1SLionel Sambucthe right MSVC magic annotations correct. This is ignored on other 373*1230fdc1SLionel Sambucplatforms.</dd> 374*1230fdc1SLionel Sambuc 375*1230fdc1SLionel Sambuc<dt>XML_ATTR_INFO</dt> 376*1230fdc1SLionel Sambuc<dd>If defined, makes the the additional function <code><a href= 377*1230fdc1SLionel Sambuc"#XML_GetAttributeInfo" >XML_GetAttributeInfo</a></code> available 378*1230fdc1SLionel Sambucfor reporting attribute byte offsets.</dd> 379*1230fdc1SLionel Sambuc</dl> 380*1230fdc1SLionel Sambuc 381*1230fdc1SLionel Sambuc<hr /> 382*1230fdc1SLionel Sambuc<h2><a name="using">Using Expat</a></h2> 383*1230fdc1SLionel Sambuc 384*1230fdc1SLionel Sambuc<h3>Compiling and Linking Against Expat</h3> 385*1230fdc1SLionel Sambuc 386*1230fdc1SLionel Sambuc<p>Unless you installed Expat in a location not expected by your 387*1230fdc1SLionel Sambuccompiler and linker, all you have to do to use Expat in your programs 388*1230fdc1SLionel Sambucis to include the Expat header (<code>#include <expat.h></code>) 389*1230fdc1SLionel Sambucin your files that make calls to it and to tell the linker that it 390*1230fdc1SLionel Sambucneeds to link against the Expat library. On Unix systems, this would 391*1230fdc1SLionel Sambucusually be done with the <code>-lexpat</code> argument. Otherwise, 392*1230fdc1SLionel Sambucyou'll need to tell the compiler where to look for the Expat header 393*1230fdc1SLionel Sambucand the linker where to find the Expat library. You may also need to 394*1230fdc1SLionel Sambuctake steps to tell the operating system where to find this library at 395*1230fdc1SLionel Sambucrun time.</p> 396*1230fdc1SLionel Sambuc 397*1230fdc1SLionel Sambuc<p>On a Unix-based system, here's what a Makefile might look like when 398*1230fdc1SLionel SambucExpat is installed in a standard location:</p> 399*1230fdc1SLionel Sambuc 400*1230fdc1SLionel Sambuc<pre class="eg"> 401*1230fdc1SLionel SambucCC=cc 402*1230fdc1SLionel SambucLDFLAGS= 403*1230fdc1SLionel SambucLIBS= -lexpat 404*1230fdc1SLionel Sambucxmlapp: xmlapp.o 405*1230fdc1SLionel Sambuc $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 406*1230fdc1SLionel Sambuc</pre> 407*1230fdc1SLionel Sambuc 408*1230fdc1SLionel Sambuc<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then 409*1230fdc1SLionel Sambucthe Makefile would look like this:</p> 410*1230fdc1SLionel Sambuc 411*1230fdc1SLionel Sambuc<pre class="eg"> 412*1230fdc1SLionel SambucCC=cc 413*1230fdc1SLionel SambucCFLAGS= -I/home/me/mystuff/include 414*1230fdc1SLionel SambucLDFLAGS= 415*1230fdc1SLionel SambucLIBS= -L/home/me/mystuff/lib -lexpat 416*1230fdc1SLionel Sambucxmlapp: xmlapp.o 417*1230fdc1SLionel Sambuc $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 418*1230fdc1SLionel Sambuc</pre> 419*1230fdc1SLionel Sambuc 420*1230fdc1SLionel Sambuc<p>You'd also have to set the environment variable 421*1230fdc1SLionel Sambuc<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or 422*1230fdc1SLionel Sambucto <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if 423*1230fdc1SLionel SambucLD_LIBRARY_PATH already has some directories in it) in order to run 424*1230fdc1SLionel Sambucyour application.</p> 425*1230fdc1SLionel Sambuc 426*1230fdc1SLionel Sambuc<h3>Expat Basics</h3> 427*1230fdc1SLionel Sambuc 428*1230fdc1SLionel Sambuc<p>As we saw in the example in the overview, the first step in parsing 429*1230fdc1SLionel Sambucan XML document with Expat is to create a parser object. There are <a 430*1230fdc1SLionel Sambuchref="#creation">three functions</a> in the Expat API for creating a 431*1230fdc1SLionel Sambucparser object. However, only two of these (<code><a href= 432*1230fdc1SLionel Sambuc"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href= 433*1230fdc1SLionel Sambuc"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for 434*1230fdc1SLionel Sambucconstructing a parser for a top-level document. The object returned 435*1230fdc1SLionel Sambucby these functions is an opaque pointer (i.e. "expat.h" declares it as 436*1230fdc1SLionel Sambucvoid *) to data with further internal structure. In order to free the 437*1230fdc1SLionel Sambucmemory associated with this object you must call <code><a href= 438*1230fdc1SLionel Sambuc"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have 439*1230fdc1SLionel Sambucprovided any <a href="#userdata">user data</a> that gets stored in the 440*1230fdc1SLionel Sambucparser, then your application is responsible for freeing it prior to 441*1230fdc1SLionel Sambuccalling <code>XML_ParserFree</code>.</p> 442*1230fdc1SLionel Sambuc 443*1230fdc1SLionel Sambuc<p>The objects returned by the parser creation functions are good for 444*1230fdc1SLionel Sambucparsing only one XML document or external parsed entity. If your 445*1230fdc1SLionel Sambucapplication needs to parse many XML documents, then it needs to create 446*1230fdc1SLionel Sambuca parser object for each one. The best way to deal with this is to 447*1230fdc1SLionel Sambuccreate a higher level object that contains all the default 448*1230fdc1SLionel Sambucinitialization you want for your parser objects.</p> 449*1230fdc1SLionel Sambuc 450*1230fdc1SLionel Sambuc<p>Walking through a document hierarchy with a stream oriented parser 451*1230fdc1SLionel Sambucwill require a good stack mechanism in order to keep track of current 452*1230fdc1SLionel Sambuccontext. For instance, to answer the simple question, "What element 453*1230fdc1SLionel Sambucdoes this text belong to?" requires a stack, since the parser may have 454*1230fdc1SLionel Sambucdescended into other elements that are children of the current one and 455*1230fdc1SLionel Sambuchas encountered this text on the way out.</p> 456*1230fdc1SLionel Sambuc 457*1230fdc1SLionel Sambuc<p>The things you're likely to want to keep on a stack are the 458*1230fdc1SLionel Sambuccurrently opened element and it's attributes. You push this 459*1230fdc1SLionel Sambucinformation onto the stack in the start handler and you pop it off in 460*1230fdc1SLionel Sambucthe end handler.</p> 461*1230fdc1SLionel Sambuc 462*1230fdc1SLionel Sambuc<p>For some tasks, it is sufficient to just keep information on what 463*1230fdc1SLionel Sambucthe depth of the stack is (or would be if you had one.) The outline 464*1230fdc1SLionel Sambucprogram shown above presents one example. Another such task would be 465*1230fdc1SLionel Sambucskipping over a complete element. When you see the start tag for the 466*1230fdc1SLionel Sambucelement you want to skip, you set a skip flag and record the depth at 467*1230fdc1SLionel Sambucwhich the element started. When the end tag handler encounters the 468*1230fdc1SLionel Sambucsame depth, the skipped element has ended and the flag may be 469*1230fdc1SLionel Sambuccleared. If you follow the convention that the root element starts at 470*1230fdc1SLionel Sambuc1, then you can use the same variable for skip flag and skip 471*1230fdc1SLionel Sambucdepth.</p> 472*1230fdc1SLionel Sambuc 473*1230fdc1SLionel Sambuc<pre class="eg"> 474*1230fdc1SLionel Sambucvoid 475*1230fdc1SLionel Sambucinit_info(Parseinfo *info) { 476*1230fdc1SLionel Sambuc info->skip = 0; 477*1230fdc1SLionel Sambuc info->depth = 1; 478*1230fdc1SLionel Sambuc /* Other initializations here */ 479*1230fdc1SLionel Sambuc} /* End of init_info */ 480*1230fdc1SLionel Sambuc 481*1230fdc1SLionel Sambucvoid XMLCALL 482*1230fdc1SLionel Sambucrawstart(void *data, const char *el, const char **attr) { 483*1230fdc1SLionel Sambuc Parseinfo *inf = (Parseinfo *) data; 484*1230fdc1SLionel Sambuc 485*1230fdc1SLionel Sambuc if (! inf->skip) { 486*1230fdc1SLionel Sambuc if (should_skip(inf, el, attr)) { 487*1230fdc1SLionel Sambuc inf->skip = inf->depth; 488*1230fdc1SLionel Sambuc } 489*1230fdc1SLionel Sambuc else 490*1230fdc1SLionel Sambuc start(inf, el, attr); /* This does rest of start handling */ 491*1230fdc1SLionel Sambuc } 492*1230fdc1SLionel Sambuc 493*1230fdc1SLionel Sambuc inf->depth++; 494*1230fdc1SLionel Sambuc} /* End of rawstart */ 495*1230fdc1SLionel Sambuc 496*1230fdc1SLionel Sambucvoid XMLCALL 497*1230fdc1SLionel Sambucrawend(void *data, const char *el) { 498*1230fdc1SLionel Sambuc Parseinfo *inf = (Parseinfo *) data; 499*1230fdc1SLionel Sambuc 500*1230fdc1SLionel Sambuc inf->depth--; 501*1230fdc1SLionel Sambuc 502*1230fdc1SLionel Sambuc if (! inf->skip) 503*1230fdc1SLionel Sambuc end(inf, el); /* This does rest of end handling */ 504*1230fdc1SLionel Sambuc 505*1230fdc1SLionel Sambuc if (inf->skip == inf->depth) 506*1230fdc1SLionel Sambuc inf->skip = 0; 507*1230fdc1SLionel Sambuc} /* End rawend */ 508*1230fdc1SLionel Sambuc</pre> 509*1230fdc1SLionel Sambuc 510*1230fdc1SLionel Sambuc<p>Notice in the above example the difference in how depth is 511*1230fdc1SLionel Sambucmanipulated in the start and end handlers. The end tag handler should 512*1230fdc1SLionel Sambucbe the mirror image of the start tag handler. This is necessary to 513*1230fdc1SLionel Sambucproperly model containment. Since, in the start tag handler, we 514*1230fdc1SLionel Sambucincremented depth <em>after</em> the main body of start tag code, then 515*1230fdc1SLionel Sambucin the end handler, we need to manipulate it <em>before</em> the main 516*1230fdc1SLionel Sambucbody. If we'd decided to increment it first thing in the start 517*1230fdc1SLionel Sambuchandler, then we'd have had to decrement it last thing in the end 518*1230fdc1SLionel Sambuchandler.</p> 519*1230fdc1SLionel Sambuc 520*1230fdc1SLionel Sambuc<h3 id="userdata">Communicating between handlers</h3> 521*1230fdc1SLionel Sambuc 522*1230fdc1SLionel Sambuc<p>In order to be able to pass information between different handlers 523*1230fdc1SLionel Sambucwithout using globals, you'll need to define a data structure to hold 524*1230fdc1SLionel Sambucthe shared variables. You can then tell Expat (with the <code><a href= 525*1230fdc1SLionel Sambuc"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a 526*1230fdc1SLionel Sambucpointer to this structure to the handlers. This is the first 527*1230fdc1SLionel Sambucargument received by most handlers. In the <a href="#reference" 528*1230fdc1SLionel Sambuc>reference section</a>, an argument to a callback function is named 529*1230fdc1SLionel Sambuc<code>userData</code> and have type <code>void *</code> if the user 530*1230fdc1SLionel Sambucdata is passed; it will have the type <code>XML_Parser</code> if the 531*1230fdc1SLionel Sambucparser itself is passed. When the parser is passed, the user data may 532*1230fdc1SLionel Sambucbe retrieved using <code><a href="#XML_GetUserData" 533*1230fdc1SLionel Sambuc>XML_GetUserData</a></code>.</p> 534*1230fdc1SLionel Sambuc 535*1230fdc1SLionel Sambuc<p>One common case where multiple calls to a single handler may need 536*1230fdc1SLionel Sambucto communicate using an application data structure is the case when 537*1230fdc1SLionel Sambuccontent passed to the character data handler (set by <code><a href= 538*1230fdc1SLionel Sambuc"#XML_SetCharacterDataHandler" 539*1230fdc1SLionel Sambuc>XML_SetCharacterDataHandler</a></code>) needs to be accumulated. A 540*1230fdc1SLionel Sambuccommon first-time mistake with any of the event-oriented interfaces to 541*1230fdc1SLionel Sambucan XML parser is to expect all the text contained in an element to be 542*1230fdc1SLionel Sambucreported by a single call to the character data handler. Expat, like 543*1230fdc1SLionel Sambucmany other XML parsers, reports such data as a sequence of calls; 544*1230fdc1SLionel Sambucthere's no way to know when the end of the sequence is reached until a 545*1230fdc1SLionel Sambucdifferent callback is made. A buffer referenced by the user data 546*1230fdc1SLionel Sambucstructure proves both an effective and convenient place to accumulate 547*1230fdc1SLionel Sambuccharacter data.</p> 548*1230fdc1SLionel Sambuc 549*1230fdc1SLionel Sambuc<!-- XXX example needed here --> 550*1230fdc1SLionel Sambuc 551*1230fdc1SLionel Sambuc 552*1230fdc1SLionel Sambuc<h3>XML Version</h3> 553*1230fdc1SLionel Sambuc 554*1230fdc1SLionel Sambuc<p>Expat is an XML 1.0 parser, and as such never complains based on 555*1230fdc1SLionel Sambucthe value of the <code>version</code> pseudo-attribute in the XML 556*1230fdc1SLionel Sambucdeclaration, if present.</p> 557*1230fdc1SLionel Sambuc 558*1230fdc1SLionel Sambuc<p>If an application needs to check the version number (to support 559*1230fdc1SLionel Sambucalternate processing), it should use the <code><a href= 560*1230fdc1SLionel Sambuc"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to 561*1230fdc1SLionel Sambucset a handler that uses the information in the XML declaration to 562*1230fdc1SLionel Sambucdetermine what to do. This example shows how to check that only a 563*1230fdc1SLionel Sambucversion number of <code>"1.0"</code> is accepted:</p> 564*1230fdc1SLionel Sambuc 565*1230fdc1SLionel Sambuc<pre class="eg"> 566*1230fdc1SLionel Sambucstatic int wrong_version; 567*1230fdc1SLionel Sambucstatic XML_Parser parser; 568*1230fdc1SLionel Sambuc 569*1230fdc1SLionel Sambucstatic void XMLCALL 570*1230fdc1SLionel Sambucxmldecl_handler(void *userData, 571*1230fdc1SLionel Sambuc const XML_Char *version, 572*1230fdc1SLionel Sambuc const XML_Char *encoding, 573*1230fdc1SLionel Sambuc int standalone) 574*1230fdc1SLionel Sambuc{ 575*1230fdc1SLionel Sambuc static const XML_Char Version_1_0[] = {'1', '.', '0', 0}; 576*1230fdc1SLionel Sambuc 577*1230fdc1SLionel Sambuc int i; 578*1230fdc1SLionel Sambuc 579*1230fdc1SLionel Sambuc for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) { 580*1230fdc1SLionel Sambuc if (version[i] != Version_1_0[i]) { 581*1230fdc1SLionel Sambuc wrong_version = 1; 582*1230fdc1SLionel Sambuc /* also clear all other handlers: */ 583*1230fdc1SLionel Sambuc XML_SetCharacterDataHandler(parser, NULL); 584*1230fdc1SLionel Sambuc ... 585*1230fdc1SLionel Sambuc return; 586*1230fdc1SLionel Sambuc } 587*1230fdc1SLionel Sambuc } 588*1230fdc1SLionel Sambuc ... 589*1230fdc1SLionel Sambuc} 590*1230fdc1SLionel Sambuc</pre> 591*1230fdc1SLionel Sambuc 592*1230fdc1SLionel Sambuc<h3>Namespace Processing</h3> 593*1230fdc1SLionel Sambuc 594*1230fdc1SLionel Sambuc<p>When the parser is created using the <code><a href= 595*1230fdc1SLionel Sambuc"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat 596*1230fdc1SLionel Sambucperforms namespace processing. Under namespace processing, Expat 597*1230fdc1SLionel Sambucconsumes <code>xmlns</code> and <code>xmlns:...</code> attributes, 598*1230fdc1SLionel Sambucwhich declare namespaces for the scope of the element in which they 599*1230fdc1SLionel Sambucoccur. This means that your start handler will not see these 600*1230fdc1SLionel Sambucattributes. Your application can still be informed of these 601*1230fdc1SLionel Sambucdeclarations by setting namespace declaration handlers with <a href= 602*1230fdc1SLionel Sambuc"#XML_SetNamespaceDeclHandler" 603*1230fdc1SLionel Sambuc><code>XML_SetNamespaceDeclHandler</code></a>.</p> 604*1230fdc1SLionel Sambuc 605*1230fdc1SLionel Sambuc<p>Element type and attribute names that belong to a given namespace 606*1230fdc1SLionel Sambucare passed to the appropriate handler in expanded form. By default 607*1230fdc1SLionel Sambucthis expanded form is a concatenation of the namespace URI, the 608*1230fdc1SLionel Sambucseparator character (which is the 2nd argument to <code><a href= 609*1230fdc1SLionel Sambuc"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local 610*1230fdc1SLionel Sambucname (i.e. the part after the colon). Names with undeclared prefixes 611*1230fdc1SLionel Sambucare not well-formed when namespace processing is enabled, and will 612*1230fdc1SLionel Sambuctrigger an error. Unprefixed attribute names are never expanded, 613*1230fdc1SLionel Sambucand unprefixed element names are only expanded when they are in the 614*1230fdc1SLionel Sambucscope of a default namespace.</p> 615*1230fdc1SLionel Sambuc 616*1230fdc1SLionel Sambuc<p>However if <code><a href= "#XML_SetReturnNSTriplet" 617*1230fdc1SLionel Sambuc>XML_SetReturnNSTriplet</a></code> has been called with a non-zero 618*1230fdc1SLionel Sambuc<code>do_nst</code> parameter, then the expanded form for names with 619*1230fdc1SLionel Sambucan explicit prefix is a concatenation of: URI, separator, local name, 620*1230fdc1SLionel Sambucseparator, prefix.</p> 621*1230fdc1SLionel Sambuc 622*1230fdc1SLionel Sambuc<p>You can set handlers for the start of a namespace declaration and 623*1230fdc1SLionel Sambucfor the end of a scope of a declaration with the <code><a href= 624*1230fdc1SLionel Sambuc"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code> 625*1230fdc1SLionel Sambucfunction. The StartNamespaceDeclHandler is called prior to the start 626*1230fdc1SLionel Sambuctag handler and the EndNamespaceDeclHandler is called after the 627*1230fdc1SLionel Sambuccorresponding end tag that ends the namespace's scope. The namespace 628*1230fdc1SLionel Sambucstart handler gets passed the prefix and URI for the namespace. For a 629*1230fdc1SLionel Sambucdefault namespace declaration (xmlns='...'), the prefix will be null. 630*1230fdc1SLionel SambucThe URI will be null for the case where the default namespace is being 631*1230fdc1SLionel Sambucunset. The namespace end handler just gets the prefix for the closing 632*1230fdc1SLionel Sambucscope.</p> 633*1230fdc1SLionel Sambuc 634*1230fdc1SLionel Sambuc<p>These handlers are called for each declaration. So if, for 635*1230fdc1SLionel Sambucinstance, a start tag had three namespace declarations, then the 636*1230fdc1SLionel SambucStartNamespaceDeclHandler would be called three times before the start 637*1230fdc1SLionel Sambuctag handler is called, once for each declaration.</p> 638*1230fdc1SLionel Sambuc 639*1230fdc1SLionel Sambuc<h3>Character Encodings</h3> 640*1230fdc1SLionel Sambuc 641*1230fdc1SLionel Sambuc<p>While XML is based on Unicode, and every XML processor is required 642*1230fdc1SLionel Sambucto recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), 643*1230fdc1SLionel Sambucother encodings may be declared in XML documents or entities. For the 644*1230fdc1SLionel Sambucmain document, an XML declaration may contain an encoding 645*1230fdc1SLionel Sambucdeclaration:</p> 646*1230fdc1SLionel Sambuc<pre> 647*1230fdc1SLionel Sambuc<?xml version="1.0" encoding="ISO-8859-2"?> 648*1230fdc1SLionel Sambuc</pre> 649*1230fdc1SLionel Sambuc 650*1230fdc1SLionel Sambuc<p>External parsed entities may begin with a text declaration, which 651*1230fdc1SLionel Sambuclooks like an XML declaration with just an encoding declaration:</p> 652*1230fdc1SLionel Sambuc<pre> 653*1230fdc1SLionel Sambuc<?xml encoding="Big5"?> 654*1230fdc1SLionel Sambuc</pre> 655*1230fdc1SLionel Sambuc 656*1230fdc1SLionel Sambuc<p>With Expat, you may also specify an encoding at the time of 657*1230fdc1SLionel Sambuccreating a parser. This is useful when the encoding information may 658*1230fdc1SLionel Sambuccome from a source outside the document itself (like a higher level 659*1230fdc1SLionel Sambucprotocol.)</p> 660*1230fdc1SLionel Sambuc 661*1230fdc1SLionel Sambuc<p><a name="builtin_encodings"></a>There are four built-in encodings 662*1230fdc1SLionel Sambucin Expat:</p> 663*1230fdc1SLionel Sambuc<ul> 664*1230fdc1SLionel Sambuc<li>UTF-8</li> 665*1230fdc1SLionel Sambuc<li>UTF-16</li> 666*1230fdc1SLionel Sambuc<li>ISO-8859-1</li> 667*1230fdc1SLionel Sambuc<li>US-ASCII</li> 668*1230fdc1SLionel Sambuc</ul> 669*1230fdc1SLionel Sambuc 670*1230fdc1SLionel Sambuc<p>Anything else discovered in an encoding declaration or in the 671*1230fdc1SLionel Sambucprotocol encoding specified in the parser constructor, triggers a call 672*1230fdc1SLionel Sambucto the <code>UnknownEncodingHandler</code>. This handler gets passed 673*1230fdc1SLionel Sambucthe encoding name and a pointer to an <code>XML_Encoding</code> data 674*1230fdc1SLionel Sambucstructure. Your handler must fill in this structure and return 675*1230fdc1SLionel Sambuc<code>XML_STATUS_OK</code> if it knows how to deal with the 676*1230fdc1SLionel Sambucencoding. Otherwise the handler should return 677*1230fdc1SLionel Sambuc<code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer 678*1230fdc1SLionel Sambucto an optional application data structure that you may indicate when 679*1230fdc1SLionel Sambucyou set the handler.</p> 680*1230fdc1SLionel Sambuc 681*1230fdc1SLionel Sambuc<p>Expat places restrictions on character encodings that it can 682*1230fdc1SLionel Sambucsupport by filling in the <code>XML_Encoding</code> structure. 683*1230fdc1SLionel Sambucinclude file:</p> 684*1230fdc1SLionel Sambuc<ol> 685*1230fdc1SLionel Sambuc<li>Every ASCII character that can appear in a well-formed XML document 686*1230fdc1SLionel Sambucmust be represented by a single byte, and that byte must correspond to 687*1230fdc1SLionel Sambucit's ASCII encoding (except for the characters $@\^'{}~)</li> 688*1230fdc1SLionel Sambuc<li>Characters must be encoded in 4 bytes or less.</li> 689*1230fdc1SLionel Sambuc<li>All characters encoded must have Unicode scalar values less than or 690*1230fdc1SLionel Sambucequal to 65535 (0xFFFF)<em>This does not apply to the built-in support 691*1230fdc1SLionel Sambucfor UTF-16 and UTF-8</em></li> 692*1230fdc1SLionel Sambuc<li>No character may be encoded by more that one distinct sequence of 693*1230fdc1SLionel Sambucbytes</li> 694*1230fdc1SLionel Sambuc</ol> 695*1230fdc1SLionel Sambuc 696*1230fdc1SLionel Sambuc<p><code>XML_Encoding</code> contains an array of integers that 697*1230fdc1SLionel Sambuccorrespond to the 1st byte of an encoding sequence. If the value in 698*1230fdc1SLionel Sambucthe array for a byte is zero or positive, then the byte is a single 699*1230fdc1SLionel Sambucbyte encoding that encodes the Unicode scalar value contained in the 700*1230fdc1SLionel Sambucarray. A -1 in this array indicates a malformed byte. If the value is 701*1230fdc1SLionel Sambuc-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte 702*1230fdc1SLionel Sambucsequence respectively. Multi-byte sequences are sent to the convert 703*1230fdc1SLionel Sambucfunction pointed at in the <code>XML_Encoding</code> structure. This 704*1230fdc1SLionel Sambucfunction should return the Unicode scalar value for the sequence or -1 705*1230fdc1SLionel Sambucif the sequence is malformed.</p> 706*1230fdc1SLionel Sambuc 707*1230fdc1SLionel Sambuc<p>One pitfall that novice Expat users are likely to fall into is that 708*1230fdc1SLionel Sambucalthough Expat may accept input in various encodings, the strings that 709*1230fdc1SLionel Sambucit passes to the handlers are always encoded in UTF-8 or UTF-16 710*1230fdc1SLionel Sambuc(depending on how Expat was compiled). Your application is responsible 711*1230fdc1SLionel Sambucfor any translation of these strings into other encodings.</p> 712*1230fdc1SLionel Sambuc 713*1230fdc1SLionel Sambuc<h3>Handling External Entity References</h3> 714*1230fdc1SLionel Sambuc 715*1230fdc1SLionel Sambuc<p>Expat does not read or parse external entities directly. Note that 716*1230fdc1SLionel Sambucany external DTD is a special case of an external entity. If you've 717*1230fdc1SLionel Sambucset no <code>ExternalEntityRefHandler</code>, then external entity 718*1230fdc1SLionel Sambucreferences are silently ignored. Otherwise, it calls your handler with 719*1230fdc1SLionel Sambucthe information needed to read and parse the external entity.</p> 720*1230fdc1SLionel Sambuc 721*1230fdc1SLionel Sambuc<p>Your handler isn't actually responsible for parsing the entity, but 722*1230fdc1SLionel Sambucit is responsible for creating a subsidiary parser with <code><a href= 723*1230fdc1SLionel Sambuc"#XML_ExternalEntityParserCreate" 724*1230fdc1SLionel Sambuc>XML_ExternalEntityParserCreate</a></code> that will do the job. This 725*1230fdc1SLionel Sambucreturns an instance of <code>XML_Parser</code> that has handlers and 726*1230fdc1SLionel Sambucother data structures initialized from the parent parser. You may then 727*1230fdc1SLionel Sambucuse <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a 728*1230fdc1SLionel Sambuchref= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this 729*1230fdc1SLionel Sambucparser. Since external entities my refer to other external entities, 730*1230fdc1SLionel Sambucyour handler should be prepared to be called recursively.</p> 731*1230fdc1SLionel Sambuc 732*1230fdc1SLionel Sambuc<h3>Parsing DTDs</h3> 733*1230fdc1SLionel Sambuc 734*1230fdc1SLionel Sambuc<p>In order to parse parameter entities, before starting the parse, 735*1230fdc1SLionel Sambucyou must call <code><a href= "#XML_SetParamEntityParsing" 736*1230fdc1SLionel Sambuc>XML_SetParamEntityParsing</a></code> with one of the following 737*1230fdc1SLionel Sambucarguments:</p> 738*1230fdc1SLionel Sambuc<dl> 739*1230fdc1SLionel Sambuc<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt> 740*1230fdc1SLionel Sambuc<dd>Don't parse parameter entities or the external subset</dd> 741*1230fdc1SLionel Sambuc<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt> 742*1230fdc1SLionel Sambuc<dd>Parse parameter entites and the external subset unless 743*1230fdc1SLionel Sambuc<code>standalone</code> was set to "yes" in the XML declaration.</dd> 744*1230fdc1SLionel Sambuc<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt> 745*1230fdc1SLionel Sambuc<dd>Always parse parameter entities and the external subset</dd> 746*1230fdc1SLionel Sambuc</dl> 747*1230fdc1SLionel Sambuc 748*1230fdc1SLionel Sambuc<p>In order to read an external DTD, you also have to set an external 749*1230fdc1SLionel Sambucentity reference handler as described above.</p> 750*1230fdc1SLionel Sambuc 751*1230fdc1SLionel Sambuc<h3 id="stop-resume">Temporarily Stopping Parsing</h3> 752*1230fdc1SLionel Sambuc 753*1230fdc1SLionel Sambuc<p>Expat 1.95.8 introduces a new feature: its now possible to stop 754*1230fdc1SLionel Sambucparsing temporarily from within a handler function, even if more data 755*1230fdc1SLionel Sambuchas already been passed into the parser. Applications for this 756*1230fdc1SLionel Sambucinclude</p> 757*1230fdc1SLionel Sambuc 758*1230fdc1SLionel Sambuc<ul> 759*1230fdc1SLionel Sambuc <li>Supporting the <a href= "http://www.w3.org/TR/xinclude/" 760*1230fdc1SLionel Sambuc >XInclude</a> specification.</li> 761*1230fdc1SLionel Sambuc 762*1230fdc1SLionel Sambuc <li>Delaying further processing until additional information is 763*1230fdc1SLionel Sambuc available from some other source.</li> 764*1230fdc1SLionel Sambuc 765*1230fdc1SLionel Sambuc <li>Adjusting processor load as task priorities shift within an 766*1230fdc1SLionel Sambuc application.</li> 767*1230fdc1SLionel Sambuc 768*1230fdc1SLionel Sambuc <li>Stopping parsing completely (simply free or reset the parser 769*1230fdc1SLionel Sambuc instead of resuming in the outer parsing loop). This can be useful 770*1230fdc1SLionel Sambuc if a application-domain error is found in the XML being parsed or if 771*1230fdc1SLionel Sambuc the result of the parse is determined not to be useful after 772*1230fdc1SLionel Sambuc all.</li> 773*1230fdc1SLionel Sambuc</ul> 774*1230fdc1SLionel Sambuc 775*1230fdc1SLionel Sambuc<p>To take advantage of this feature, the main parsing loop of an 776*1230fdc1SLionel Sambucapplication needs to support this specifically. It cannot be 777*1230fdc1SLionel Sambucsupported with a parsing loop compatible with Expat 1.95.7 or 778*1230fdc1SLionel Sambucearlier (though existing loops will continue to work without 779*1230fdc1SLionel Sambucsupporting the stop/resume feature).</p> 780*1230fdc1SLionel Sambuc 781*1230fdc1SLionel Sambuc<p>An application that uses this feature for a single parser will have 782*1230fdc1SLionel Sambucthe rough structure (in pseudo-code):</p> 783*1230fdc1SLionel Sambuc 784*1230fdc1SLionel Sambuc<pre class="pseudocode"> 785*1230fdc1SLionel Sambucfd = open_input() 786*1230fdc1SLionel Sambucp = create_parser() 787*1230fdc1SLionel Sambuc 788*1230fdc1SLionel Sambucif parse_xml(p, fd) { 789*1230fdc1SLionel Sambuc /* suspended */ 790*1230fdc1SLionel Sambuc 791*1230fdc1SLionel Sambuc int suspended = 1; 792*1230fdc1SLionel Sambuc 793*1230fdc1SLionel Sambuc while (suspended) { 794*1230fdc1SLionel Sambuc do_something_else() 795*1230fdc1SLionel Sambuc if ready_to_resume() { 796*1230fdc1SLionel Sambuc suspended = continue_parsing(p, fd); 797*1230fdc1SLionel Sambuc } 798*1230fdc1SLionel Sambuc } 799*1230fdc1SLionel Sambuc} 800*1230fdc1SLionel Sambuc</pre> 801*1230fdc1SLionel Sambuc 802*1230fdc1SLionel Sambuc<p>An application that may resume any of several parsers based on 803*1230fdc1SLionel Sambucinput (either from the XML being parsed or some other source) will 804*1230fdc1SLionel Sambuccertainly have more interesting control structures.</p> 805*1230fdc1SLionel Sambuc 806*1230fdc1SLionel Sambuc<p>This C function could be used for the <code>parse_xml</code> 807*1230fdc1SLionel Sambucfunction mentioned in the pseudo-code above:</p> 808*1230fdc1SLionel Sambuc 809*1230fdc1SLionel Sambuc<pre class="eg"> 810*1230fdc1SLionel Sambuc#define BUFF_SIZE 10240 811*1230fdc1SLionel Sambuc 812*1230fdc1SLionel Sambuc/* Parse a document from the open file descriptor 'fd' until the parse 813*1230fdc1SLionel Sambuc is complete (the document has been completely parsed, or there's 814*1230fdc1SLionel Sambuc been an error), or the parse is stopped. Return non-zero when 815*1230fdc1SLionel Sambuc the parse is merely suspended. 816*1230fdc1SLionel Sambuc*/ 817*1230fdc1SLionel Sambucint 818*1230fdc1SLionel Sambucparse_xml(XML_Parser p, int fd) 819*1230fdc1SLionel Sambuc{ 820*1230fdc1SLionel Sambuc for (;;) { 821*1230fdc1SLionel Sambuc int last_chunk; 822*1230fdc1SLionel Sambuc int bytes_read; 823*1230fdc1SLionel Sambuc enum XML_Status status; 824*1230fdc1SLionel Sambuc 825*1230fdc1SLionel Sambuc void *buff = XML_GetBuffer(p, BUFF_SIZE); 826*1230fdc1SLionel Sambuc if (buff == NULL) { 827*1230fdc1SLionel Sambuc /* handle error... */ 828*1230fdc1SLionel Sambuc return 0; 829*1230fdc1SLionel Sambuc } 830*1230fdc1SLionel Sambuc bytes_read = read(fd, buff, BUFF_SIZE); 831*1230fdc1SLionel Sambuc if (bytes_read < 0) { 832*1230fdc1SLionel Sambuc /* handle error... */ 833*1230fdc1SLionel Sambuc return 0; 834*1230fdc1SLionel Sambuc } 835*1230fdc1SLionel Sambuc status = XML_ParseBuffer(p, bytes_read, bytes_read == 0); 836*1230fdc1SLionel Sambuc switch (status) { 837*1230fdc1SLionel Sambuc case XML_STATUS_ERROR: 838*1230fdc1SLionel Sambuc /* handle error... */ 839*1230fdc1SLionel Sambuc return 0; 840*1230fdc1SLionel Sambuc case XML_STATUS_SUSPENDED: 841*1230fdc1SLionel Sambuc return 1; 842*1230fdc1SLionel Sambuc } 843*1230fdc1SLionel Sambuc if (bytes_read == 0) 844*1230fdc1SLionel Sambuc return 0; 845*1230fdc1SLionel Sambuc } 846*1230fdc1SLionel Sambuc} 847*1230fdc1SLionel Sambuc</pre> 848*1230fdc1SLionel Sambuc 849*1230fdc1SLionel Sambuc<p>The corresponding <code>continue_parsing</code> function is 850*1230fdc1SLionel Sambucsomewhat simpler, since it only need deal with the return code from 851*1230fdc1SLionel Sambuc<code><a href= "#XML_ResumeParser">XML_ResumeParser</a></code>; it can 852*1230fdc1SLionel Sambucdelegate the input handling to the <code>parse_xml</code> 853*1230fdc1SLionel Sambucfunction:</p> 854*1230fdc1SLionel Sambuc 855*1230fdc1SLionel Sambuc<pre class="eg"> 856*1230fdc1SLionel Sambuc/* Continue parsing a document which had been suspended. The 'p' and 857*1230fdc1SLionel Sambuc 'fd' arguments are the same as passed to parse_xml(). Return 858*1230fdc1SLionel Sambuc non-zero when the parse is suspended. 859*1230fdc1SLionel Sambuc*/ 860*1230fdc1SLionel Sambucint 861*1230fdc1SLionel Sambuccontinue_parsing(XML_Parser p, int fd) 862*1230fdc1SLionel Sambuc{ 863*1230fdc1SLionel Sambuc enum XML_Status status = XML_ResumeParser(p); 864*1230fdc1SLionel Sambuc switch (status) { 865*1230fdc1SLionel Sambuc case XML_STATUS_ERROR: 866*1230fdc1SLionel Sambuc /* handle error... */ 867*1230fdc1SLionel Sambuc return 0; 868*1230fdc1SLionel Sambuc case XML_ERROR_NOT_SUSPENDED: 869*1230fdc1SLionel Sambuc /* handle error... */ 870*1230fdc1SLionel Sambuc return 0;. 871*1230fdc1SLionel Sambuc case XML_STATUS_SUSPENDED: 872*1230fdc1SLionel Sambuc return 1; 873*1230fdc1SLionel Sambuc } 874*1230fdc1SLionel Sambuc return parse_xml(p, fd); 875*1230fdc1SLionel Sambuc} 876*1230fdc1SLionel Sambuc</pre> 877*1230fdc1SLionel Sambuc 878*1230fdc1SLionel Sambuc<p>Now that we've seen what a mess the top-level parsing loop can 879*1230fdc1SLionel Sambucbecome, what have we gained? Very simply, we can now use the <code><a 880*1230fdc1SLionel Sambuchref= "#XML_StopParser" >XML_StopParser</a></code> function to stop 881*1230fdc1SLionel Sambucparsing, without having to go to great lengths to avoid additional 882*1230fdc1SLionel Sambucprocessing that we're expecting to ignore. As a bonus, we get to stop 883*1230fdc1SLionel Sambucparsing <em>temporarily</em>, and come back to it when we're 884*1230fdc1SLionel Sambucready.</p> 885*1230fdc1SLionel Sambuc 886*1230fdc1SLionel Sambuc<p>To stop parsing from a handler function, use the <code><a href= 887*1230fdc1SLionel Sambuc"#XML_StopParser" >XML_StopParser</a></code> function. This function 888*1230fdc1SLionel Sambuctakes two arguments; the parser being stopped and a flag indicating 889*1230fdc1SLionel Sambucwhether the parse can be resumed in the future.</p> 890*1230fdc1SLionel Sambuc 891*1230fdc1SLionel Sambuc<!-- XXX really need more here --> 892*1230fdc1SLionel Sambuc 893*1230fdc1SLionel Sambuc 894*1230fdc1SLionel Sambuc<hr /> 895*1230fdc1SLionel Sambuc<!-- ================================================================ --> 896*1230fdc1SLionel Sambuc 897*1230fdc1SLionel Sambuc<h2><a name="reference">Expat Reference</a></h2> 898*1230fdc1SLionel Sambuc 899*1230fdc1SLionel Sambuc<h3><a name="creation">Parser Creation</a></h3> 900*1230fdc1SLionel Sambuc 901*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParserCreate"> 902*1230fdc1SLionel SambucXML_Parser XMLCALL 903*1230fdc1SLionel SambucXML_ParserCreate(const XML_Char *encoding); 904*1230fdc1SLionel Sambuc</pre> 905*1230fdc1SLionel Sambuc<div class="fcndef"> 906*1230fdc1SLionel SambucConstruct a new parser. If encoding is non-null, it specifies a 907*1230fdc1SLionel Sambuccharacter encoding to use for the document. This overrides the document 908*1230fdc1SLionel Sambucencoding declaration. There are four built-in encodings: 909*1230fdc1SLionel Sambuc<ul> 910*1230fdc1SLionel Sambuc<li>US-ASCII</li> 911*1230fdc1SLionel Sambuc<li>UTF-8</li> 912*1230fdc1SLionel Sambuc<li>UTF-16</li> 913*1230fdc1SLionel Sambuc<li>ISO-8859-1</li> 914*1230fdc1SLionel Sambuc</ul> 915*1230fdc1SLionel SambucAny other value will invoke a call to the UnknownEncodingHandler. 916*1230fdc1SLionel Sambuc</div> 917*1230fdc1SLionel Sambuc 918*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParserCreateNS"> 919*1230fdc1SLionel SambucXML_Parser XMLCALL 920*1230fdc1SLionel SambucXML_ParserCreateNS(const XML_Char *encoding, 921*1230fdc1SLionel Sambuc XML_Char sep); 922*1230fdc1SLionel Sambuc</pre> 923*1230fdc1SLionel Sambuc<div class="fcndef"> 924*1230fdc1SLionel SambucConstructs a new parser that has namespace processing in effect. Namespace 925*1230fdc1SLionel Sambucexpanded element names and attribute names are returned as a concatenation 926*1230fdc1SLionel Sambucof the namespace URI, <em>sep</em>, and the local part of the name. This 927*1230fdc1SLionel Sambucmeans that you should pick a character for <em>sep</em> that can't be part 928*1230fdc1SLionel Sambucof an URI. Since Expat does not check namespace URIs for conformance, the 929*1230fdc1SLionel Sambuconly safe choice for a namespace separator is a character that is illegal 930*1230fdc1SLionel Sambucin XML. For instance, <code>'\xFF'</code> is not legal in UTF-8, and 931*1230fdc1SLionel Sambuc<code>'\xFFFF'</code> is not legal in UTF-16. There is a special case when 932*1230fdc1SLionel Sambuc<em>sep</em> is the null character <code>'\0'</code>: the namespace URI and 933*1230fdc1SLionel Sambucthe local part will be concatenated without any separator - this is intended 934*1230fdc1SLionel Sambucto support RDF processors. It is a programming error to use the null separator 935*1230fdc1SLionel Sambucwith <a href= "#XML_SetReturnNSTriplet">namespace triplets</a>.</div> 936*1230fdc1SLionel Sambuc 937*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParserCreate_MM"> 938*1230fdc1SLionel SambucXML_Parser XMLCALL 939*1230fdc1SLionel SambucXML_ParserCreate_MM(const XML_Char *encoding, 940*1230fdc1SLionel Sambuc const XML_Memory_Handling_Suite *ms, 941*1230fdc1SLionel Sambuc const XML_Char *sep); 942*1230fdc1SLionel Sambuc</pre> 943*1230fdc1SLionel Sambuc<pre class="signature"> 944*1230fdc1SLionel Sambuctypedef struct { 945*1230fdc1SLionel Sambuc void *(XMLCALL *malloc_fcn)(size_t size); 946*1230fdc1SLionel Sambuc void *(XMLCALL *realloc_fcn)(void *ptr, size_t size); 947*1230fdc1SLionel Sambuc void (XMLCALL *free_fcn)(void *ptr); 948*1230fdc1SLionel Sambuc} XML_Memory_Handling_Suite; 949*1230fdc1SLionel Sambuc</pre> 950*1230fdc1SLionel Sambuc<div class="fcndef"> 951*1230fdc1SLionel Sambuc<p>Construct a new parser using the suite of memory handling functions 952*1230fdc1SLionel Sambucspecified in <code>ms</code>. If <code>ms</code> is NULL, then use the 953*1230fdc1SLionel Sambucstandard set of memory management functions. If <code>sep</code> is 954*1230fdc1SLionel Sambucnon NULL, then namespace processing is enabled in the created parser 955*1230fdc1SLionel Sambucand the character pointed at by sep is used as the separator between 956*1230fdc1SLionel Sambucthe namespace URI and the local part of the name.</p> 957*1230fdc1SLionel Sambuc</div> 958*1230fdc1SLionel Sambuc 959*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ExternalEntityParserCreate"> 960*1230fdc1SLionel SambucXML_Parser XMLCALL 961*1230fdc1SLionel SambucXML_ExternalEntityParserCreate(XML_Parser p, 962*1230fdc1SLionel Sambuc const XML_Char *context, 963*1230fdc1SLionel Sambuc const XML_Char *encoding); 964*1230fdc1SLionel Sambuc</pre> 965*1230fdc1SLionel Sambuc<div class="fcndef"> 966*1230fdc1SLionel SambucConstruct a new <code>XML_Parser</code> object for parsing an external 967*1230fdc1SLionel Sambucgeneral entity. Context is the context argument passed in a call to a 968*1230fdc1SLionel SambucExternalEntityRefHandler. Other state information such as handlers, 969*1230fdc1SLionel Sambucuser data, namespace processing is inherited from the parser passed as 970*1230fdc1SLionel Sambucthe 1st argument. So you shouldn't need to call any of the behavior 971*1230fdc1SLionel Sambucchanging functions on this parser (unless you want it to act 972*1230fdc1SLionel Sambucdifferently than the parent parser). 973*1230fdc1SLionel Sambuc</div> 974*1230fdc1SLionel Sambuc 975*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParserFree"> 976*1230fdc1SLionel Sambucvoid XMLCALL 977*1230fdc1SLionel SambucXML_ParserFree(XML_Parser p); 978*1230fdc1SLionel Sambuc</pre> 979*1230fdc1SLionel Sambuc<div class="fcndef"> 980*1230fdc1SLionel SambucFree memory used by the parser. Your application is responsible for 981*1230fdc1SLionel Sambucfreeing any memory associated with <a href="#userdata">user data</a>. 982*1230fdc1SLionel Sambuc</div> 983*1230fdc1SLionel Sambuc 984*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParserReset"> 985*1230fdc1SLionel SambucXML_Bool XMLCALL 986*1230fdc1SLionel SambucXML_ParserReset(XML_Parser p, 987*1230fdc1SLionel Sambuc const XML_Char *encoding); 988*1230fdc1SLionel Sambuc</pre> 989*1230fdc1SLionel Sambuc<div class="fcndef"> 990*1230fdc1SLionel SambucClean up the memory structures maintained by the parser so that it may 991*1230fdc1SLionel Sambucbe used again. After this has been called, <code>parser</code> is 992*1230fdc1SLionel Sambucready to start parsing a new document. All handlers are cleared from 993*1230fdc1SLionel Sambucthe parser, except for the unknownEncodingHandler. The parser's external 994*1230fdc1SLionel Sambucstate is re-initialized except for the values of ns and ns_triplets. 995*1230fdc1SLionel SambucThis function may not be used on a parser created using <code><a href= 996*1230fdc1SLionel Sambuc"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a 997*1230fdc1SLionel Sambuc></code>; it will return <code>XML_FALSE</code> in that case. Returns 998*1230fdc1SLionel Sambuc<code>XML_TRUE</code> on success. Your application is responsible for 999*1230fdc1SLionel Sambucdealing with any memory associated with <a href="#userdata">user data</a>. 1000*1230fdc1SLionel Sambuc</div> 1001*1230fdc1SLionel Sambuc 1002*1230fdc1SLionel Sambuc<h3><a name="parsing">Parsing</a></h3> 1003*1230fdc1SLionel Sambuc 1004*1230fdc1SLionel Sambuc<p>To state the obvious: the three parsing functions <code><a href= 1005*1230fdc1SLionel Sambuc"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer"> 1006*1230fdc1SLionel SambucXML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer"> 1007*1230fdc1SLionel SambucXML_GetBuffer</a></code> must not be called from within a handler 1008*1230fdc1SLionel Sambucunless they operate on a separate parser instance, that is, one that 1009*1230fdc1SLionel Sambucdid not call the handler. For example, it is OK to call the parsing 1010*1230fdc1SLionel Sambucfunctions from within an <code>XML_ExternalEntityRefHandler</code>, 1011*1230fdc1SLionel Sambucif they apply to the parser created by 1012*1230fdc1SLionel Sambuc<code><a href= "#XML_ExternalEntityParserCreate" 1013*1230fdc1SLionel Sambuc>XML_ExternalEntityParserCreate</a></code>.</p> 1014*1230fdc1SLionel Sambuc 1015*1230fdc1SLionel Sambuc<p>Note: the <code>len</code> argument passed to these functions 1016*1230fdc1SLionel Sambucshould be considerably less than the maximum value for an integer, 1017*1230fdc1SLionel Sambucas it could create an integer overflow situation if the added 1018*1230fdc1SLionel Sambuclengths of a buffer and the unprocessed portion of the previous buffer 1019*1230fdc1SLionel Sambucexceed the maximum integer value. Input data at the end of a buffer 1020*1230fdc1SLionel Sambucwill remain unprocessed if it is part of an XML token for which the 1021*1230fdc1SLionel Sambucend is not part of that buffer.</p> 1022*1230fdc1SLionel Sambuc 1023*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_Parse"> 1024*1230fdc1SLionel Sambucenum XML_Status XMLCALL 1025*1230fdc1SLionel SambucXML_Parse(XML_Parser p, 1026*1230fdc1SLionel Sambuc const char *s, 1027*1230fdc1SLionel Sambuc int len, 1028*1230fdc1SLionel Sambuc int isFinal); 1029*1230fdc1SLionel Sambuc</pre> 1030*1230fdc1SLionel Sambuc<pre class="signature"> 1031*1230fdc1SLionel Sambucenum XML_Status { 1032*1230fdc1SLionel Sambuc XML_STATUS_ERROR = 0, 1033*1230fdc1SLionel Sambuc XML_STATUS_OK = 1 1034*1230fdc1SLionel Sambuc}; 1035*1230fdc1SLionel Sambuc</pre> 1036*1230fdc1SLionel Sambuc<div class="fcndef"> 1037*1230fdc1SLionel SambucParse some more of the document. The string <code>s</code> is a buffer 1038*1230fdc1SLionel Sambuccontaining part (or perhaps all) of the document. The number of bytes of s 1039*1230fdc1SLionel Sambucthat are part of the document is indicated by <code>len</code>. This means 1040*1230fdc1SLionel Sambucthat <code>s</code> doesn't have to be null terminated. It also means that 1041*1230fdc1SLionel Sambucif <code>len</code> is larger than the number of bytes in the block of 1042*1230fdc1SLionel Sambucmemory that <code>s</code> points at, then a memory fault is likely. The 1043*1230fdc1SLionel Sambuc<code>isFinal</code> parameter informs the parser that this is the last 1044*1230fdc1SLionel Sambucpiece of the document. Frequently, the last piece is empty (i.e. 1045*1230fdc1SLionel Sambuc<code>len</code> is zero.) 1046*1230fdc1SLionel SambucIf a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. 1047*1230fdc1SLionel SambucOtherwise it returns <code>XML_STATUS_OK</code> value. 1048*1230fdc1SLionel Sambuc</div> 1049*1230fdc1SLionel Sambuc 1050*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ParseBuffer"> 1051*1230fdc1SLionel Sambucenum XML_Status XMLCALL 1052*1230fdc1SLionel SambucXML_ParseBuffer(XML_Parser p, 1053*1230fdc1SLionel Sambuc int len, 1054*1230fdc1SLionel Sambuc int isFinal); 1055*1230fdc1SLionel Sambuc</pre> 1056*1230fdc1SLionel Sambuc<div class="fcndef"> 1057*1230fdc1SLionel SambucThis is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>, 1058*1230fdc1SLionel Sambucexcept in this case Expat provides the buffer. By obtaining the 1059*1230fdc1SLionel Sambucbuffer from Expat with the <code><a href= "#XML_GetBuffer" 1060*1230fdc1SLionel Sambuc>XML_GetBuffer</a></code> function, the application can avoid double 1061*1230fdc1SLionel Sambuccopying of the input. 1062*1230fdc1SLionel Sambuc</div> 1063*1230fdc1SLionel Sambuc 1064*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetBuffer"> 1065*1230fdc1SLionel Sambucvoid * XMLCALL 1066*1230fdc1SLionel SambucXML_GetBuffer(XML_Parser p, 1067*1230fdc1SLionel Sambuc int len); 1068*1230fdc1SLionel Sambuc</pre> 1069*1230fdc1SLionel Sambuc<div class="fcndef"> 1070*1230fdc1SLionel SambucObtain a buffer of size <code>len</code> to read a piece of the document 1071*1230fdc1SLionel Sambucinto. A NULL value is returned if Expat can't allocate enough memory for 1072*1230fdc1SLionel Sambucthis buffer. This has to be called prior to every call to 1073*1230fdc1SLionel Sambuc<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A 1074*1230fdc1SLionel Sambuctypical use would look like this: 1075*1230fdc1SLionel Sambuc 1076*1230fdc1SLionel Sambuc<pre class="eg"> 1077*1230fdc1SLionel Sambucfor (;;) { 1078*1230fdc1SLionel Sambuc int bytes_read; 1079*1230fdc1SLionel Sambuc void *buff = XML_GetBuffer(p, BUFF_SIZE); 1080*1230fdc1SLionel Sambuc if (buff == NULL) { 1081*1230fdc1SLionel Sambuc /* handle error */ 1082*1230fdc1SLionel Sambuc } 1083*1230fdc1SLionel Sambuc 1084*1230fdc1SLionel Sambuc bytes_read = read(docfd, buff, BUFF_SIZE); 1085*1230fdc1SLionel Sambuc if (bytes_read < 0) { 1086*1230fdc1SLionel Sambuc /* handle error */ 1087*1230fdc1SLionel Sambuc } 1088*1230fdc1SLionel Sambuc 1089*1230fdc1SLionel Sambuc if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) { 1090*1230fdc1SLionel Sambuc /* handle parse error */ 1091*1230fdc1SLionel Sambuc } 1092*1230fdc1SLionel Sambuc 1093*1230fdc1SLionel Sambuc if (bytes_read == 0) 1094*1230fdc1SLionel Sambuc break; 1095*1230fdc1SLionel Sambuc} 1096*1230fdc1SLionel Sambuc</pre> 1097*1230fdc1SLionel Sambuc</div> 1098*1230fdc1SLionel Sambuc 1099*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_StopParser"> 1100*1230fdc1SLionel Sambucenum XML_Status XMLCALL 1101*1230fdc1SLionel SambucXML_StopParser(XML_Parser p, 1102*1230fdc1SLionel Sambuc XML_Bool resumable); 1103*1230fdc1SLionel Sambuc</pre> 1104*1230fdc1SLionel Sambuc<div class="fcndef"> 1105*1230fdc1SLionel Sambuc 1106*1230fdc1SLionel Sambuc<p>Stops parsing, causing <code><a href= "#XML_Parse" 1107*1230fdc1SLionel Sambuc>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 1108*1230fdc1SLionel Sambuc>XML_ParseBuffer</a></code> to return. Must be called from within a 1109*1230fdc1SLionel Sambuccall-back handler, except when aborting (when <code>resumable</code> 1110*1230fdc1SLionel Sambucis <code>XML_FALSE</code>) an already suspended parser. Some 1111*1230fdc1SLionel Sambuccall-backs may still follow because they would otherwise get 1112*1230fdc1SLionel Sambuclost, including 1113*1230fdc1SLionel Sambuc<ul> 1114*1230fdc1SLionel Sambuc <li> the end element handler for empty elements when stopped in the 1115*1230fdc1SLionel Sambuc start element handler,</li> 1116*1230fdc1SLionel Sambuc <li> the end namespace declaration handler when stopped in the end 1117*1230fdc1SLionel Sambuc element handler,</li> 1118*1230fdc1SLionel Sambuc <li> the character data handler when stopped in the character data handler 1119*1230fdc1SLionel Sambuc while making multiple call-backs on a contiguous chunk of characters,</li> 1120*1230fdc1SLionel Sambuc</ul> 1121*1230fdc1SLionel Sambucand possibly others.</p> 1122*1230fdc1SLionel Sambuc 1123*1230fdc1SLionel Sambuc<p>This can be called from most handlers, including DTD related 1124*1230fdc1SLionel Sambuccall-backs, except when parsing an external parameter entity and 1125*1230fdc1SLionel Sambuc<code>resumable</code> is <code>XML_TRUE</code>. Returns 1126*1230fdc1SLionel Sambuc<code>XML_STATUS_OK</code> when successful, 1127*1230fdc1SLionel Sambuc<code>XML_STATUS_ERROR</code> otherwise. The possible error codes 1128*1230fdc1SLionel Sambucare:</p> 1129*1230fdc1SLionel Sambuc<dl> 1130*1230fdc1SLionel Sambuc <dt><code>XML_ERROR_SUSPENDED</code></dt> 1131*1230fdc1SLionel Sambuc <dd>when suspending an already suspended parser.</dd> 1132*1230fdc1SLionel Sambuc <dt><code>XML_ERROR_FINISHED</code></dt> 1133*1230fdc1SLionel Sambuc <dd>when the parser has already finished.</dd> 1134*1230fdc1SLionel Sambuc <dt><code>XML_ERROR_SUSPEND_PE</code></dt> 1135*1230fdc1SLionel Sambuc <dd>when suspending while parsing an external PE.</dd> 1136*1230fdc1SLionel Sambuc</dl> 1137*1230fdc1SLionel Sambuc 1138*1230fdc1SLionel Sambuc<p>Since the stop/resume feature requires application support in the 1139*1230fdc1SLionel Sambucouter parsing loop, it is an error to call this function for a parser 1140*1230fdc1SLionel Sambucnot being handled appropriately; see <a href= "#stop-resume" 1141*1230fdc1SLionel Sambuc>Temporarily Stopping Parsing</a> for more information.</p> 1142*1230fdc1SLionel Sambuc 1143*1230fdc1SLionel Sambuc<p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing 1144*1230fdc1SLionel Sambucis <em>suspended</em>, that is, <code><a href= "#XML_Parse" 1145*1230fdc1SLionel Sambuc>XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer" 1146*1230fdc1SLionel Sambuc>XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>. 1147*1230fdc1SLionel SambucOtherwise, parsing is <em>aborted</em>, that is, <code><a href= 1148*1230fdc1SLionel Sambuc"#XML_Parse" >XML_Parse</a></code> and <code><a href= 1149*1230fdc1SLionel Sambuc"#XML_ParseBuffer" >XML_ParseBuffer</a></code> return 1150*1230fdc1SLionel Sambuc<code>XML_STATUS_ERROR</code> with error code 1151*1230fdc1SLionel Sambuc<code>XML_ERROR_ABORTED</code>.</p> 1152*1230fdc1SLionel Sambuc 1153*1230fdc1SLionel Sambuc<p><strong>Note:</strong> 1154*1230fdc1SLionel SambucThis will be applied to the current parser instance only, that is, if 1155*1230fdc1SLionel Sambucthere is a parent parser then it will continue parsing when the 1156*1230fdc1SLionel Sambucexternal entity reference handler returns. It is up to the 1157*1230fdc1SLionel Sambucimplementation of that handler to call <code><a href= 1158*1230fdc1SLionel Sambuc"#XML_StopParser" >XML_StopParser</a></code> on the parent parser 1159*1230fdc1SLionel Sambuc(recursively), if one wants to stop parsing altogether.</p> 1160*1230fdc1SLionel Sambuc 1161*1230fdc1SLionel Sambuc<p>When suspended, parsing can be resumed by calling <code><a href= 1162*1230fdc1SLionel Sambuc"#XML_ResumeParser" >XML_ResumeParser</a></code>.</p> 1163*1230fdc1SLionel Sambuc 1164*1230fdc1SLionel Sambuc<p>New in Expat 1.95.8.</p> 1165*1230fdc1SLionel Sambuc</div> 1166*1230fdc1SLionel Sambuc 1167*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ResumeParser"> 1168*1230fdc1SLionel Sambucenum XML_Status XMLCALL 1169*1230fdc1SLionel SambucXML_ResumeParser(XML_Parser p); 1170*1230fdc1SLionel Sambuc</pre> 1171*1230fdc1SLionel Sambuc<div class="fcndef"> 1172*1230fdc1SLionel Sambuc<p>Resumes parsing after it has been suspended with <code><a href= 1173*1230fdc1SLionel Sambuc"#XML_StopParser" >XML_StopParser</a></code>. Must not be called from 1174*1230fdc1SLionel Sambucwithin a handler call-back. Returns same status codes as <code><a 1175*1230fdc1SLionel Sambuchref= "#XML_Parse">XML_Parse</a></code> or <code><a href= 1176*1230fdc1SLionel Sambuc"#XML_ParseBuffer" >XML_ParseBuffer</a></code>. An additional error 1177*1230fdc1SLionel Sambuccode, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the 1178*1230fdc1SLionel Sambucparser was not currently suspended.</p> 1179*1230fdc1SLionel Sambuc 1180*1230fdc1SLionel Sambuc<p><strong>Note:</strong> 1181*1230fdc1SLionel SambucThis must be called on the most deeply nested child parser instance 1182*1230fdc1SLionel Sambucfirst, and on its parent parser only after the child parser has 1183*1230fdc1SLionel Sambucfinished, to be applied recursively until the document entity's parser 1184*1230fdc1SLionel Sambucis restarted. That is, the parent parser will not resume by itself 1185*1230fdc1SLionel Sambucand it is up to the application to call <code><a href= 1186*1230fdc1SLionel Sambuc"#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the 1187*1230fdc1SLionel Sambucappropriate moment.</p> 1188*1230fdc1SLionel Sambuc 1189*1230fdc1SLionel Sambuc<p>New in Expat 1.95.8.</p> 1190*1230fdc1SLionel Sambuc</div> 1191*1230fdc1SLionel Sambuc 1192*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetParsingStatus"> 1193*1230fdc1SLionel Sambucvoid XMLCALL 1194*1230fdc1SLionel SambucXML_GetParsingStatus(XML_Parser p, 1195*1230fdc1SLionel Sambuc XML_ParsingStatus *status); 1196*1230fdc1SLionel Sambuc</pre> 1197*1230fdc1SLionel Sambuc<pre class="signature"> 1198*1230fdc1SLionel Sambucenum XML_Parsing { 1199*1230fdc1SLionel Sambuc XML_INITIALIZED, 1200*1230fdc1SLionel Sambuc XML_PARSING, 1201*1230fdc1SLionel Sambuc XML_FINISHED, 1202*1230fdc1SLionel Sambuc XML_SUSPENDED 1203*1230fdc1SLionel Sambuc}; 1204*1230fdc1SLionel Sambuc 1205*1230fdc1SLionel Sambuctypedef struct { 1206*1230fdc1SLionel Sambuc enum XML_Parsing parsing; 1207*1230fdc1SLionel Sambuc XML_Bool finalBuffer; 1208*1230fdc1SLionel Sambuc} XML_ParsingStatus; 1209*1230fdc1SLionel Sambuc</pre> 1210*1230fdc1SLionel Sambuc<div class="fcndef"> 1211*1230fdc1SLionel Sambuc<p>Returns status of parser with respect to being initialized, 1212*1230fdc1SLionel Sambucparsing, finished, or suspended, and whether the final buffer is being 1213*1230fdc1SLionel Sambucprocessed. The <code>status</code> parameter <em>must not</em> be 1214*1230fdc1SLionel SambucNULL.</p> 1215*1230fdc1SLionel Sambuc 1216*1230fdc1SLionel Sambuc<p>New in Expat 1.95.8.</p> 1217*1230fdc1SLionel Sambuc</div> 1218*1230fdc1SLionel Sambuc 1219*1230fdc1SLionel Sambuc 1220*1230fdc1SLionel Sambuc<h3><a name="setting">Handler Setting</a></h3> 1221*1230fdc1SLionel Sambuc 1222*1230fdc1SLionel Sambuc<p>Although handlers are typically set prior to parsing and left alone, an 1223*1230fdc1SLionel Sambucapplication may choose to set or change the handler for a parsing event 1224*1230fdc1SLionel Sambucwhile the parse is in progress. For instance, your application may choose 1225*1230fdc1SLionel Sambucto ignore all text not descended from a <code>para</code> element. One 1226*1230fdc1SLionel Sambucway it could do this is to set the character handler when a para start tag 1227*1230fdc1SLionel Sambucis seen, and unset it for the corresponding end tag.</p> 1228*1230fdc1SLionel Sambuc 1229*1230fdc1SLionel Sambuc<p>A handler may be <em>unset</em> by providing a NULL pointer to the 1230*1230fdc1SLionel Sambucappropriate handler setter. None of the handler setting functions have 1231*1230fdc1SLionel Sambuca return value.</p> 1232*1230fdc1SLionel Sambuc 1233*1230fdc1SLionel Sambuc<p>Your handlers will be receiving strings in arrays of type 1234*1230fdc1SLionel Sambuc<code>XML_Char</code>. This type is conditionally defined in expat.h as 1235*1230fdc1SLionel Sambuceither <code>char</code>, <code>wchar_t</code> or <code>unsigned short</code>. 1236*1230fdc1SLionel SambucThe former implies UTF-8 encoding, the latter two imply UTF-16 encoding. 1237*1230fdc1SLionel SambucNote that you'll receive them in this form independent of the original 1238*1230fdc1SLionel Sambucencoding of the document.</p> 1239*1230fdc1SLionel Sambuc 1240*1230fdc1SLionel Sambuc<div class="handler"> 1241*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetStartElementHandler"> 1242*1230fdc1SLionel Sambucvoid XMLCALL 1243*1230fdc1SLionel SambucXML_SetStartElementHandler(XML_Parser p, 1244*1230fdc1SLionel Sambuc XML_StartElementHandler start); 1245*1230fdc1SLionel Sambuc</pre> 1246*1230fdc1SLionel Sambuc<pre class="signature"> 1247*1230fdc1SLionel Sambuctypedef void 1248*1230fdc1SLionel Sambuc(XMLCALL *XML_StartElementHandler)(void *userData, 1249*1230fdc1SLionel Sambuc const XML_Char *name, 1250*1230fdc1SLionel Sambuc const XML_Char **atts); 1251*1230fdc1SLionel Sambuc</pre> 1252*1230fdc1SLionel Sambuc<p>Set handler for start (and empty) tags. Attributes are passed to the start 1253*1230fdc1SLionel Sambuchandler as a pointer to a vector of char pointers. Each attribute seen in 1254*1230fdc1SLionel Sambuca start (or empty) tag occupies 2 consecutive places in this vector: the 1255*1230fdc1SLionel Sambucattribute name followed by the attribute value. These pairs are terminated 1256*1230fdc1SLionel Sambucby a null pointer.</p> 1257*1230fdc1SLionel Sambuc<p>Note that an empty tag generates a call to both start and end handlers 1258*1230fdc1SLionel Sambuc(in that order).</p> 1259*1230fdc1SLionel Sambuc</div> 1260*1230fdc1SLionel Sambuc 1261*1230fdc1SLionel Sambuc<div class="handler"> 1262*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetEndElementHandler"> 1263*1230fdc1SLionel Sambucvoid XMLCALL 1264*1230fdc1SLionel SambucXML_SetEndElementHandler(XML_Parser p, 1265*1230fdc1SLionel Sambuc XML_EndElementHandler); 1266*1230fdc1SLionel Sambuc</pre> 1267*1230fdc1SLionel Sambuc<pre class="signature"> 1268*1230fdc1SLionel Sambuctypedef void 1269*1230fdc1SLionel Sambuc(XMLCALL *XML_EndElementHandler)(void *userData, 1270*1230fdc1SLionel Sambuc const XML_Char *name); 1271*1230fdc1SLionel Sambuc</pre> 1272*1230fdc1SLionel Sambuc<p>Set handler for end (and empty) tags. As noted above, an empty tag 1273*1230fdc1SLionel Sambucgenerates a call to both start and end handlers.</p> 1274*1230fdc1SLionel Sambuc</div> 1275*1230fdc1SLionel Sambuc 1276*1230fdc1SLionel Sambuc<div class="handler"> 1277*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetElementHandler"> 1278*1230fdc1SLionel Sambucvoid XMLCALL 1279*1230fdc1SLionel SambucXML_SetElementHandler(XML_Parser p, 1280*1230fdc1SLionel Sambuc XML_StartElementHandler start, 1281*1230fdc1SLionel Sambuc XML_EndElementHandler end); 1282*1230fdc1SLionel Sambuc</pre> 1283*1230fdc1SLionel Sambuc<p>Set handlers for start and end tags with one call.</p> 1284*1230fdc1SLionel Sambuc</div> 1285*1230fdc1SLionel Sambuc 1286*1230fdc1SLionel Sambuc<div class="handler"> 1287*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetCharacterDataHandler"> 1288*1230fdc1SLionel Sambucvoid XMLCALL 1289*1230fdc1SLionel SambucXML_SetCharacterDataHandler(XML_Parser p, 1290*1230fdc1SLionel Sambuc XML_CharacterDataHandler charhndl) 1291*1230fdc1SLionel Sambuc</pre> 1292*1230fdc1SLionel Sambuc<pre class="signature"> 1293*1230fdc1SLionel Sambuctypedef void 1294*1230fdc1SLionel Sambuc(XMLCALL *XML_CharacterDataHandler)(void *userData, 1295*1230fdc1SLionel Sambuc const XML_Char *s, 1296*1230fdc1SLionel Sambuc int len); 1297*1230fdc1SLionel Sambuc</pre> 1298*1230fdc1SLionel Sambuc<p>Set a text handler. The string your handler receives 1299*1230fdc1SLionel Sambucis <em>NOT nul-terminated</em>. You have to use the length argument 1300*1230fdc1SLionel Sambucto deal with the end of the string. A single block of contiguous text 1301*1230fdc1SLionel Sambucfree of markup may still result in a sequence of calls to this handler. 1302*1230fdc1SLionel SambucIn other words, if you're searching for a pattern in the text, it may 1303*1230fdc1SLionel Sambucbe split across calls to this handler. Note: Setting this handler to NULL 1304*1230fdc1SLionel Sambucmay <em>NOT immediately</em> terminate call-backs if the parser is currently 1305*1230fdc1SLionel Sambucprocessing such a single block of contiguous markup-free text, as the parser 1306*1230fdc1SLionel Sambucwill continue calling back until the end of the block is reached.</p> 1307*1230fdc1SLionel Sambuc</div> 1308*1230fdc1SLionel Sambuc 1309*1230fdc1SLionel Sambuc<div class="handler"> 1310*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetProcessingInstructionHandler"> 1311*1230fdc1SLionel Sambucvoid XMLCALL 1312*1230fdc1SLionel SambucXML_SetProcessingInstructionHandler(XML_Parser p, 1313*1230fdc1SLionel Sambuc XML_ProcessingInstructionHandler proc) 1314*1230fdc1SLionel Sambuc</pre> 1315*1230fdc1SLionel Sambuc<pre class="signature"> 1316*1230fdc1SLionel Sambuctypedef void 1317*1230fdc1SLionel Sambuc(XMLCALL *XML_ProcessingInstructionHandler)(void *userData, 1318*1230fdc1SLionel Sambuc const XML_Char *target, 1319*1230fdc1SLionel Sambuc const XML_Char *data); 1320*1230fdc1SLionel Sambuc 1321*1230fdc1SLionel Sambuc</pre> 1322*1230fdc1SLionel Sambuc<p>Set a handler for processing instructions. The target is the first word 1323*1230fdc1SLionel Sambucin the processing instruction. The data is the rest of the characters in 1324*1230fdc1SLionel Sambucit after skipping all whitespace after the initial word.</p> 1325*1230fdc1SLionel Sambuc</div> 1326*1230fdc1SLionel Sambuc 1327*1230fdc1SLionel Sambuc<div class="handler"> 1328*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetCommentHandler"> 1329*1230fdc1SLionel Sambucvoid XMLCALL 1330*1230fdc1SLionel SambucXML_SetCommentHandler(XML_Parser p, 1331*1230fdc1SLionel Sambuc XML_CommentHandler cmnt) 1332*1230fdc1SLionel Sambuc</pre> 1333*1230fdc1SLionel Sambuc<pre class="signature"> 1334*1230fdc1SLionel Sambuctypedef void 1335*1230fdc1SLionel Sambuc(XMLCALL *XML_CommentHandler)(void *userData, 1336*1230fdc1SLionel Sambuc const XML_Char *data); 1337*1230fdc1SLionel Sambuc</pre> 1338*1230fdc1SLionel Sambuc<p>Set a handler for comments. The data is all text inside the comment 1339*1230fdc1SLionel Sambucdelimiters.</p> 1340*1230fdc1SLionel Sambuc</div> 1341*1230fdc1SLionel Sambuc 1342*1230fdc1SLionel Sambuc<div class="handler"> 1343*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetStartCdataSectionHandler"> 1344*1230fdc1SLionel Sambucvoid XMLCALL 1345*1230fdc1SLionel SambucXML_SetStartCdataSectionHandler(XML_Parser p, 1346*1230fdc1SLionel Sambuc XML_StartCdataSectionHandler start); 1347*1230fdc1SLionel Sambuc</pre> 1348*1230fdc1SLionel Sambuc<pre class="signature"> 1349*1230fdc1SLionel Sambuctypedef void 1350*1230fdc1SLionel Sambuc(XMLCALL *XML_StartCdataSectionHandler)(void *userData); 1351*1230fdc1SLionel Sambuc</pre> 1352*1230fdc1SLionel Sambuc<p>Set a handler that gets called at the beginning of a CDATA section.</p> 1353*1230fdc1SLionel Sambuc</div> 1354*1230fdc1SLionel Sambuc 1355*1230fdc1SLionel Sambuc<div class="handler"> 1356*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetEndCdataSectionHandler"> 1357*1230fdc1SLionel Sambucvoid XMLCALL 1358*1230fdc1SLionel SambucXML_SetEndCdataSectionHandler(XML_Parser p, 1359*1230fdc1SLionel Sambuc XML_EndCdataSectionHandler end); 1360*1230fdc1SLionel Sambuc</pre> 1361*1230fdc1SLionel Sambuc<pre class="signature"> 1362*1230fdc1SLionel Sambuctypedef void 1363*1230fdc1SLionel Sambuc(XMLCALL *XML_EndCdataSectionHandler)(void *userData); 1364*1230fdc1SLionel Sambuc</pre> 1365*1230fdc1SLionel Sambuc<p>Set a handler that gets called at the end of a CDATA section.</p> 1366*1230fdc1SLionel Sambuc</div> 1367*1230fdc1SLionel Sambuc 1368*1230fdc1SLionel Sambuc<div class="handler"> 1369*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetCdataSectionHandler"> 1370*1230fdc1SLionel Sambucvoid XMLCALL 1371*1230fdc1SLionel SambucXML_SetCdataSectionHandler(XML_Parser p, 1372*1230fdc1SLionel Sambuc XML_StartCdataSectionHandler start, 1373*1230fdc1SLionel Sambuc XML_EndCdataSectionHandler end) 1374*1230fdc1SLionel Sambuc</pre> 1375*1230fdc1SLionel Sambuc<p>Sets both CDATA section handlers with one call.</p> 1376*1230fdc1SLionel Sambuc</div> 1377*1230fdc1SLionel Sambuc 1378*1230fdc1SLionel Sambuc<div class="handler"> 1379*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetDefaultHandler"> 1380*1230fdc1SLionel Sambucvoid XMLCALL 1381*1230fdc1SLionel SambucXML_SetDefaultHandler(XML_Parser p, 1382*1230fdc1SLionel Sambuc XML_DefaultHandler hndl) 1383*1230fdc1SLionel Sambuc</pre> 1384*1230fdc1SLionel Sambuc<pre class="signature"> 1385*1230fdc1SLionel Sambuctypedef void 1386*1230fdc1SLionel Sambuc(XMLCALL *XML_DefaultHandler)(void *userData, 1387*1230fdc1SLionel Sambuc const XML_Char *s, 1388*1230fdc1SLionel Sambuc int len); 1389*1230fdc1SLionel Sambuc</pre> 1390*1230fdc1SLionel Sambuc 1391*1230fdc1SLionel Sambuc<p>Sets a handler for any characters in the document which wouldn't 1392*1230fdc1SLionel Sambucotherwise be handled. This includes both data for which no handlers 1393*1230fdc1SLionel Sambuccan be set (like some kinds of DTD declarations) and data which could 1394*1230fdc1SLionel Sambucbe reported but which currently has no handler set. The characters 1395*1230fdc1SLionel Sambucare passed exactly as they were present in the XML document except 1396*1230fdc1SLionel Sambucthat they will be encoded in UTF-8 or UTF-16. Line boundaries are not 1397*1230fdc1SLionel Sambucnormalized. Note that a byte order mark character is not passed to the 1398*1230fdc1SLionel Sambucdefault handler. There are no guarantees about how characters are 1399*1230fdc1SLionel Sambucdivided between calls to the default handler: for example, a comment 1400*1230fdc1SLionel Sambucmight be split between multiple calls. Setting the handler with 1401*1230fdc1SLionel Sambucthis call has the side effect of turning off expansion of references 1402*1230fdc1SLionel Sambucto internally defined general entities. Instead these references are 1403*1230fdc1SLionel Sambucpassed to the default handler.</p> 1404*1230fdc1SLionel Sambuc 1405*1230fdc1SLionel Sambuc<p>See also <code><a 1406*1230fdc1SLionel Sambuchref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 1407*1230fdc1SLionel Sambuc</div> 1408*1230fdc1SLionel Sambuc 1409*1230fdc1SLionel Sambuc<div class="handler"> 1410*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetDefaultHandlerExpand"> 1411*1230fdc1SLionel Sambucvoid XMLCALL 1412*1230fdc1SLionel SambucXML_SetDefaultHandlerExpand(XML_Parser p, 1413*1230fdc1SLionel Sambuc XML_DefaultHandler hndl) 1414*1230fdc1SLionel Sambuc</pre> 1415*1230fdc1SLionel Sambuc<pre class="signature"> 1416*1230fdc1SLionel Sambuctypedef void 1417*1230fdc1SLionel Sambuc(XMLCALL *XML_DefaultHandler)(void *userData, 1418*1230fdc1SLionel Sambuc const XML_Char *s, 1419*1230fdc1SLionel Sambuc int len); 1420*1230fdc1SLionel Sambuc</pre> 1421*1230fdc1SLionel Sambuc<p>This sets a default handler, but doesn't inhibit the expansion of 1422*1230fdc1SLionel Sambucinternal entity references. The entity reference will not be passed 1423*1230fdc1SLionel Sambucto the default handler.</p> 1424*1230fdc1SLionel Sambuc 1425*1230fdc1SLionel Sambuc<p>See also <code><a 1426*1230fdc1SLionel Sambuchref="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 1427*1230fdc1SLionel Sambuc</div> 1428*1230fdc1SLionel Sambuc 1429*1230fdc1SLionel Sambuc<div class="handler"> 1430*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetExternalEntityRefHandler"> 1431*1230fdc1SLionel Sambucvoid XMLCALL 1432*1230fdc1SLionel SambucXML_SetExternalEntityRefHandler(XML_Parser p, 1433*1230fdc1SLionel Sambuc XML_ExternalEntityRefHandler hndl) 1434*1230fdc1SLionel Sambuc</pre> 1435*1230fdc1SLionel Sambuc<pre class="signature"> 1436*1230fdc1SLionel Sambuctypedef int 1437*1230fdc1SLionel Sambuc(XMLCALL *XML_ExternalEntityRefHandler)(XML_Parser p, 1438*1230fdc1SLionel Sambuc const XML_Char *context, 1439*1230fdc1SLionel Sambuc const XML_Char *base, 1440*1230fdc1SLionel Sambuc const XML_Char *systemId, 1441*1230fdc1SLionel Sambuc const XML_Char *publicId); 1442*1230fdc1SLionel Sambuc</pre> 1443*1230fdc1SLionel Sambuc<p>Set an external entity reference handler. This handler is also 1444*1230fdc1SLionel Sambuccalled for processing an external DTD subset if parameter entity parsing 1445*1230fdc1SLionel Sambucis in effect. (See <a href="#XML_SetParamEntityParsing"> 1446*1230fdc1SLionel Sambuc<code>XML_SetParamEntityParsing</code></a>.)</p> 1447*1230fdc1SLionel Sambuc 1448*1230fdc1SLionel Sambuc<p>The <code>context</code> parameter specifies the parsing context in 1449*1230fdc1SLionel Sambucthe format expected by the <code>context</code> argument to <code><a 1450*1230fdc1SLionel Sambuchref="#XML_ExternalEntityParserCreate" 1451*1230fdc1SLionel Sambuc>XML_ExternalEntityParserCreate</a></code>. <code>code</code> is 1452*1230fdc1SLionel Sambucvalid only until the handler returns, so if the referenced entity is 1453*1230fdc1SLionel Sambucto be parsed later, it must be copied. <code>context</code> is NULL 1454*1230fdc1SLionel Sambuconly when the entity is a parameter entity, which is how one can 1455*1230fdc1SLionel Sambucdifferentiate between general and parameter entities.</p> 1456*1230fdc1SLionel Sambuc 1457*1230fdc1SLionel Sambuc<p>The <code>base</code> parameter is the base to use for relative 1458*1230fdc1SLionel Sambucsystem identifiers. It is set by <code><a 1459*1230fdc1SLionel Sambuchref="#XML_SetBase">XML_SetBase</a></code> and may be NULL. The 1460*1230fdc1SLionel Sambuc<code>publicId</code> parameter is the public id given in the entity 1461*1230fdc1SLionel Sambucdeclaration and may be NULL. <code>systemId</code> is the system 1462*1230fdc1SLionel Sambucidentifier specified in the entity declaration and is never NULL.</p> 1463*1230fdc1SLionel Sambuc 1464*1230fdc1SLionel Sambuc<p>There are a couple of ways in which this handler differs from 1465*1230fdc1SLionel Sambucothers. First, this handler returns a status indicator (an 1466*1230fdc1SLionel Sambucinteger). <code>XML_STATUS_OK</code> should be returned for successful 1467*1230fdc1SLionel Sambuchandling of the external entity reference. Returning 1468*1230fdc1SLionel Sambuc<code>XML_STATUS_ERROR</code> indicates failure, and causes the 1469*1230fdc1SLionel Sambuccalling parser to return an 1470*1230fdc1SLionel Sambuc<code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p> 1471*1230fdc1SLionel Sambuc 1472*1230fdc1SLionel Sambuc<p>Second, instead of having the user data as its first argument, it 1473*1230fdc1SLionel Sambucreceives the parser that encountered the entity reference. This, along 1474*1230fdc1SLionel Sambucwith the context parameter, may be used as arguments to a call to 1475*1230fdc1SLionel Sambuc<code><a href= "#XML_ExternalEntityParserCreate" 1476*1230fdc1SLionel Sambuc>XML_ExternalEntityParserCreate</a></code>. Using the returned 1477*1230fdc1SLionel Sambucparser, the body of the external entity can be recursively parsed.</p> 1478*1230fdc1SLionel Sambuc 1479*1230fdc1SLionel Sambuc<p>Since this handler may be called recursively, it should not be saving 1480*1230fdc1SLionel Sambucinformation into global or static variables.</p> 1481*1230fdc1SLionel Sambuc</div> 1482*1230fdc1SLionel Sambuc 1483*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg"> 1484*1230fdc1SLionel Sambucvoid XMLCALL 1485*1230fdc1SLionel SambucXML_SetExternalEntityRefHandlerArg(XML_Parser p, 1486*1230fdc1SLionel Sambuc void *arg) 1487*1230fdc1SLionel Sambuc</pre> 1488*1230fdc1SLionel Sambuc<div class="fcndef"> 1489*1230fdc1SLionel Sambuc<p>Set the argument passed to the ExternalEntityRefHandler. If 1490*1230fdc1SLionel Sambuc<code>arg</code> is not NULL, it is the new value passed to the 1491*1230fdc1SLionel Sambuchandler set using <code><a href="#XML_SetExternalEntityRefHandler" 1492*1230fdc1SLionel Sambuc>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is 1493*1230fdc1SLionel SambucNULL, the argument passed to the handler function will be the parser 1494*1230fdc1SLionel Sambucobject itself.</p> 1495*1230fdc1SLionel Sambuc 1496*1230fdc1SLionel Sambuc<p><strong>Note:</strong> 1497*1230fdc1SLionel SambucThe type of <code>arg</code> and the type of the first argument to the 1498*1230fdc1SLionel SambucExternalEntityRefHandler do not match. This function takes a 1499*1230fdc1SLionel Sambuc<code>void *</code> to be passed to the handler, while the handler 1500*1230fdc1SLionel Sambucaccepts an <code>XML_Parser</code>. This is a historical accident, 1501*1230fdc1SLionel Sambucbut will not be corrected before Expat 2.0 (at the earliest) to avoid 1502*1230fdc1SLionel Sambuccausing compiler warnings for code that's known to work with this 1503*1230fdc1SLionel SambucAPI. It is the responsibility of the application code to know the 1504*1230fdc1SLionel Sambucactual type of the argument passed to the handler and to manage it 1505*1230fdc1SLionel Sambucproperly.</p> 1506*1230fdc1SLionel Sambuc</div> 1507*1230fdc1SLionel Sambuc 1508*1230fdc1SLionel Sambuc<div class="handler"> 1509*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetSkippedEntityHandler"> 1510*1230fdc1SLionel Sambucvoid XMLCALL 1511*1230fdc1SLionel SambucXML_SetSkippedEntityHandler(XML_Parser p, 1512*1230fdc1SLionel Sambuc XML_SkippedEntityHandler handler) 1513*1230fdc1SLionel Sambuc</pre> 1514*1230fdc1SLionel Sambuc<pre class="signature"> 1515*1230fdc1SLionel Sambuctypedef void 1516*1230fdc1SLionel Sambuc(XMLCALL *XML_SkippedEntityHandler)(void *userData, 1517*1230fdc1SLionel Sambuc const XML_Char *entityName, 1518*1230fdc1SLionel Sambuc int is_parameter_entity); 1519*1230fdc1SLionel Sambuc</pre> 1520*1230fdc1SLionel Sambuc<p>Set a skipped entity handler. This is called in two situations:</p> 1521*1230fdc1SLionel Sambuc<ol> 1522*1230fdc1SLionel Sambuc <li>An entity reference is encountered for which no declaration 1523*1230fdc1SLionel Sambuc has been read <em>and</em> this is not an error.</li> 1524*1230fdc1SLionel Sambuc <li>An internal entity reference is read, but not expanded, because 1525*1230fdc1SLionel Sambuc <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> 1526*1230fdc1SLionel Sambuc has been called.</li> 1527*1230fdc1SLionel Sambuc</ol> 1528*1230fdc1SLionel Sambuc<p>The <code>is_parameter_entity</code> argument will be non-zero for 1529*1230fdc1SLionel Sambuca parameter entity and zero for a general entity.</p> <p>Note: skipped 1530*1230fdc1SLionel Sambucparameter entities in declarations and skipped general entities in 1531*1230fdc1SLionel Sambucattribute values cannot be reported, because the event would be out of 1532*1230fdc1SLionel Sambucsync with the reporting of the declarations or attribute values</p> 1533*1230fdc1SLionel Sambuc</div> 1534*1230fdc1SLionel Sambuc 1535*1230fdc1SLionel Sambuc<div class="handler"> 1536*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetUnknownEncodingHandler"> 1537*1230fdc1SLionel Sambucvoid XMLCALL 1538*1230fdc1SLionel SambucXML_SetUnknownEncodingHandler(XML_Parser p, 1539*1230fdc1SLionel Sambuc XML_UnknownEncodingHandler enchandler, 1540*1230fdc1SLionel Sambuc void *encodingHandlerData) 1541*1230fdc1SLionel Sambuc</pre> 1542*1230fdc1SLionel Sambuc<pre class="signature"> 1543*1230fdc1SLionel Sambuctypedef int 1544*1230fdc1SLionel Sambuc(XMLCALL *XML_UnknownEncodingHandler)(void *encodingHandlerData, 1545*1230fdc1SLionel Sambuc const XML_Char *name, 1546*1230fdc1SLionel Sambuc XML_Encoding *info); 1547*1230fdc1SLionel Sambuc 1548*1230fdc1SLionel Sambuctypedef struct { 1549*1230fdc1SLionel Sambuc int map[256]; 1550*1230fdc1SLionel Sambuc void *data; 1551*1230fdc1SLionel Sambuc int (XMLCALL *convert)(void *data, const char *s); 1552*1230fdc1SLionel Sambuc void (XMLCALL *release)(void *data); 1553*1230fdc1SLionel Sambuc} XML_Encoding; 1554*1230fdc1SLionel Sambuc</pre> 1555*1230fdc1SLionel Sambuc<p>Set a handler to deal with encodings other than the <a 1556*1230fdc1SLionel Sambuchref="#builtin_encodings">built in set</a>. This should be done before 1557*1230fdc1SLionel Sambuc<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href= 1558*1230fdc1SLionel Sambuc"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the 1559*1230fdc1SLionel Sambucgiven parser.</p> <p>If the handler knows how to deal with an encoding 1560*1230fdc1SLionel Sambucwith the given name, it should fill in the <code>info</code> data 1561*1230fdc1SLionel Sambucstructure and return <code>XML_STATUS_OK</code>. Otherwise it 1562*1230fdc1SLionel Sambucshould return <code>XML_STATUS_ERROR</code>. The handler will be called 1563*1230fdc1SLionel Sambucat most once per parsed (external) entity. The optional application 1564*1230fdc1SLionel Sambucdata pointer <code>encodingHandlerData</code> will be passed back to 1565*1230fdc1SLionel Sambucthe handler.</p> 1566*1230fdc1SLionel Sambuc 1567*1230fdc1SLionel Sambuc<p>The map array contains information for every possible possible leading 1568*1230fdc1SLionel Sambucbyte in a byte sequence. If the corresponding value is >= 0, then it's 1569*1230fdc1SLionel Sambuca single byte sequence and the byte encodes that Unicode value. If the 1570*1230fdc1SLionel Sambucvalue is -1, then that byte is invalid as the initial byte in a sequence. 1571*1230fdc1SLionel SambucIf the value is -n, where n is an integer > 1, then n is the number of 1572*1230fdc1SLionel Sambucbytes in the sequence and the actual conversion is accomplished by a 1573*1230fdc1SLionel Sambuccall to the function pointed at by convert. This function may return -1 1574*1230fdc1SLionel Sambucif the sequence itself is invalid. The convert pointer may be null if 1575*1230fdc1SLionel Sambucthere are only single byte codes. The data parameter passed to the convert 1576*1230fdc1SLionel Sambucfunction is the data pointer from <code>XML_Encoding</code>. The 1577*1230fdc1SLionel Sambucstring s is <em>NOT</em> nul-terminated and points at the sequence of 1578*1230fdc1SLionel Sambucbytes to be converted.</p> 1579*1230fdc1SLionel Sambuc 1580*1230fdc1SLionel Sambuc<p>The function pointed at by <code>release</code> is called by the 1581*1230fdc1SLionel Sambucparser when it is finished with the encoding. It may be NULL.</p> 1582*1230fdc1SLionel Sambuc</div> 1583*1230fdc1SLionel Sambuc 1584*1230fdc1SLionel Sambuc<div class="handler"> 1585*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetStartNamespaceDeclHandler"> 1586*1230fdc1SLionel Sambucvoid XMLCALL 1587*1230fdc1SLionel SambucXML_SetStartNamespaceDeclHandler(XML_Parser p, 1588*1230fdc1SLionel Sambuc XML_StartNamespaceDeclHandler start); 1589*1230fdc1SLionel Sambuc</pre> 1590*1230fdc1SLionel Sambuc<pre class="signature"> 1591*1230fdc1SLionel Sambuctypedef void 1592*1230fdc1SLionel Sambuc(XMLCALL *XML_StartNamespaceDeclHandler)(void *userData, 1593*1230fdc1SLionel Sambuc const XML_Char *prefix, 1594*1230fdc1SLionel Sambuc const XML_Char *uri); 1595*1230fdc1SLionel Sambuc</pre> 1596*1230fdc1SLionel Sambuc<p>Set a handler to be called when a namespace is declared. Namespace 1597*1230fdc1SLionel Sambucdeclarations occur inside start tags. But the namespace declaration start 1598*1230fdc1SLionel Sambuchandler is called before the start tag handler for each namespace declared 1599*1230fdc1SLionel Sambucin that start tag.</p> 1600*1230fdc1SLionel Sambuc</div> 1601*1230fdc1SLionel Sambuc 1602*1230fdc1SLionel Sambuc<div class="handler"> 1603*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetEndNamespaceDeclHandler"> 1604*1230fdc1SLionel Sambucvoid XMLCALL 1605*1230fdc1SLionel SambucXML_SetEndNamespaceDeclHandler(XML_Parser p, 1606*1230fdc1SLionel Sambuc XML_EndNamespaceDeclHandler end); 1607*1230fdc1SLionel Sambuc</pre> 1608*1230fdc1SLionel Sambuc<pre class="signature"> 1609*1230fdc1SLionel Sambuctypedef void 1610*1230fdc1SLionel Sambuc(XMLCALL *XML_EndNamespaceDeclHandler)(void *userData, 1611*1230fdc1SLionel Sambuc const XML_Char *prefix); 1612*1230fdc1SLionel Sambuc</pre> 1613*1230fdc1SLionel Sambuc<p>Set a handler to be called when leaving the scope of a namespace 1614*1230fdc1SLionel Sambucdeclaration. This will be called, for each namespace declaration, 1615*1230fdc1SLionel Sambucafter the handler for the end tag of the element in which the 1616*1230fdc1SLionel Sambucnamespace was declared.</p> 1617*1230fdc1SLionel Sambuc</div> 1618*1230fdc1SLionel Sambuc 1619*1230fdc1SLionel Sambuc<div class="handler"> 1620*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetNamespaceDeclHandler"> 1621*1230fdc1SLionel Sambucvoid XMLCALL 1622*1230fdc1SLionel SambucXML_SetNamespaceDeclHandler(XML_Parser p, 1623*1230fdc1SLionel Sambuc XML_StartNamespaceDeclHandler start, 1624*1230fdc1SLionel Sambuc XML_EndNamespaceDeclHandler end) 1625*1230fdc1SLionel Sambuc</pre> 1626*1230fdc1SLionel Sambuc<p>Sets both namespace declaration handlers with a single call.</p> 1627*1230fdc1SLionel Sambuc</div> 1628*1230fdc1SLionel Sambuc 1629*1230fdc1SLionel Sambuc<div class="handler"> 1630*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetXmlDeclHandler"> 1631*1230fdc1SLionel Sambucvoid XMLCALL 1632*1230fdc1SLionel SambucXML_SetXmlDeclHandler(XML_Parser p, 1633*1230fdc1SLionel Sambuc XML_XmlDeclHandler xmldecl); 1634*1230fdc1SLionel Sambuc</pre> 1635*1230fdc1SLionel Sambuc<pre class="signature"> 1636*1230fdc1SLionel Sambuctypedef void 1637*1230fdc1SLionel Sambuc(XMLCALL *XML_XmlDeclHandler)(void *userData, 1638*1230fdc1SLionel Sambuc const XML_Char *version, 1639*1230fdc1SLionel Sambuc const XML_Char *encoding, 1640*1230fdc1SLionel Sambuc int standalone); 1641*1230fdc1SLionel Sambuc</pre> 1642*1230fdc1SLionel Sambuc<p>Sets a handler that is called for XML declarations and also for 1643*1230fdc1SLionel Sambuctext declarations discovered in external entities. The way to 1644*1230fdc1SLionel Sambucdistinguish is that the <code>version</code> parameter will be NULL 1645*1230fdc1SLionel Sambucfor text declarations. The <code>encoding</code> parameter may be NULL 1646*1230fdc1SLionel Sambucfor an XML declaration. The <code>standalone</code> argument will 1647*1230fdc1SLionel Sambuccontain -1, 0, or 1 indicating respectively that there was no 1648*1230fdc1SLionel Sambucstandalone parameter in the declaration, that it was given as no, or 1649*1230fdc1SLionel Sambucthat it was given as yes.</p> 1650*1230fdc1SLionel Sambuc</div> 1651*1230fdc1SLionel Sambuc 1652*1230fdc1SLionel Sambuc<div class="handler"> 1653*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetStartDoctypeDeclHandler"> 1654*1230fdc1SLionel Sambucvoid XMLCALL 1655*1230fdc1SLionel SambucXML_SetStartDoctypeDeclHandler(XML_Parser p, 1656*1230fdc1SLionel Sambuc XML_StartDoctypeDeclHandler start); 1657*1230fdc1SLionel Sambuc</pre> 1658*1230fdc1SLionel Sambuc<pre class="signature"> 1659*1230fdc1SLionel Sambuctypedef void 1660*1230fdc1SLionel Sambuc(XMLCALL *XML_StartDoctypeDeclHandler)(void *userData, 1661*1230fdc1SLionel Sambuc const XML_Char *doctypeName, 1662*1230fdc1SLionel Sambuc const XML_Char *sysid, 1663*1230fdc1SLionel Sambuc const XML_Char *pubid, 1664*1230fdc1SLionel Sambuc int has_internal_subset); 1665*1230fdc1SLionel Sambuc</pre> 1666*1230fdc1SLionel Sambuc<p>Set a handler that is called at the start of a DOCTYPE declaration, 1667*1230fdc1SLionel Sambucbefore any external or internal subset is parsed. Both <code>sysid</code> 1668*1230fdc1SLionel Sambucand <code>pubid</code> may be NULL. The <code>has_internal_subset</code> 1669*1230fdc1SLionel Sambucwill be non-zero if the DOCTYPE declaration has an internal subset.</p> 1670*1230fdc1SLionel Sambuc</div> 1671*1230fdc1SLionel Sambuc 1672*1230fdc1SLionel Sambuc<div class="handler"> 1673*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetEndDoctypeDeclHandler"> 1674*1230fdc1SLionel Sambucvoid XMLCALL 1675*1230fdc1SLionel SambucXML_SetEndDoctypeDeclHandler(XML_Parser p, 1676*1230fdc1SLionel Sambuc XML_EndDoctypeDeclHandler end); 1677*1230fdc1SLionel Sambuc</pre> 1678*1230fdc1SLionel Sambuc<pre class="signature"> 1679*1230fdc1SLionel Sambuctypedef void 1680*1230fdc1SLionel Sambuc(XMLCALL *XML_EndDoctypeDeclHandler)(void *userData); 1681*1230fdc1SLionel Sambuc</pre> 1682*1230fdc1SLionel Sambuc<p>Set a handler that is called at the end of a DOCTYPE declaration, 1683*1230fdc1SLionel Sambucafter parsing any external subset.</p> 1684*1230fdc1SLionel Sambuc</div> 1685*1230fdc1SLionel Sambuc 1686*1230fdc1SLionel Sambuc<div class="handler"> 1687*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetDoctypeDeclHandler"> 1688*1230fdc1SLionel Sambucvoid XMLCALL 1689*1230fdc1SLionel SambucXML_SetDoctypeDeclHandler(XML_Parser p, 1690*1230fdc1SLionel Sambuc XML_StartDoctypeDeclHandler start, 1691*1230fdc1SLionel Sambuc XML_EndDoctypeDeclHandler end); 1692*1230fdc1SLionel Sambuc</pre> 1693*1230fdc1SLionel Sambuc<p>Set both doctype handlers with one call.</p> 1694*1230fdc1SLionel Sambuc</div> 1695*1230fdc1SLionel Sambuc 1696*1230fdc1SLionel Sambuc<div class="handler"> 1697*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetElementDeclHandler"> 1698*1230fdc1SLionel Sambucvoid XMLCALL 1699*1230fdc1SLionel SambucXML_SetElementDeclHandler(XML_Parser p, 1700*1230fdc1SLionel Sambuc XML_ElementDeclHandler eldecl); 1701*1230fdc1SLionel Sambuc</pre> 1702*1230fdc1SLionel Sambuc<pre class="signature"> 1703*1230fdc1SLionel Sambuctypedef void 1704*1230fdc1SLionel Sambuc(XMLCALL *XML_ElementDeclHandler)(void *userData, 1705*1230fdc1SLionel Sambuc const XML_Char *name, 1706*1230fdc1SLionel Sambuc XML_Content *model); 1707*1230fdc1SLionel Sambuc</pre> 1708*1230fdc1SLionel Sambuc<pre class="signature"> 1709*1230fdc1SLionel Sambucenum XML_Content_Type { 1710*1230fdc1SLionel Sambuc XML_CTYPE_EMPTY = 1, 1711*1230fdc1SLionel Sambuc XML_CTYPE_ANY, 1712*1230fdc1SLionel Sambuc XML_CTYPE_MIXED, 1713*1230fdc1SLionel Sambuc XML_CTYPE_NAME, 1714*1230fdc1SLionel Sambuc XML_CTYPE_CHOICE, 1715*1230fdc1SLionel Sambuc XML_CTYPE_SEQ 1716*1230fdc1SLionel Sambuc}; 1717*1230fdc1SLionel Sambuc 1718*1230fdc1SLionel Sambucenum XML_Content_Quant { 1719*1230fdc1SLionel Sambuc XML_CQUANT_NONE, 1720*1230fdc1SLionel Sambuc XML_CQUANT_OPT, 1721*1230fdc1SLionel Sambuc XML_CQUANT_REP, 1722*1230fdc1SLionel Sambuc XML_CQUANT_PLUS 1723*1230fdc1SLionel Sambuc}; 1724*1230fdc1SLionel Sambuc 1725*1230fdc1SLionel Sambuctypedef struct XML_cp XML_Content; 1726*1230fdc1SLionel Sambuc 1727*1230fdc1SLionel Sambucstruct XML_cp { 1728*1230fdc1SLionel Sambuc enum XML_Content_Type type; 1729*1230fdc1SLionel Sambuc enum XML_Content_Quant quant; 1730*1230fdc1SLionel Sambuc const XML_Char * name; 1731*1230fdc1SLionel Sambuc unsigned int numchildren; 1732*1230fdc1SLionel Sambuc XML_Content * children; 1733*1230fdc1SLionel Sambuc}; 1734*1230fdc1SLionel Sambuc</pre> 1735*1230fdc1SLionel Sambuc<p>Sets a handler for element declarations in a DTD. The handler gets 1736*1230fdc1SLionel Sambuccalled with the name of the element in the declaration and a pointer 1737*1230fdc1SLionel Sambucto a structure that contains the element model. It is the 1738*1230fdc1SLionel Sambucapplication's responsibility to free this data structure using 1739*1230fdc1SLionel Sambuc<code><a href="#XML_FreeContentModel" 1740*1230fdc1SLionel Sambuc>XML_FreeContentModel</a></code>.</p> 1741*1230fdc1SLionel Sambuc 1742*1230fdc1SLionel Sambuc<p>The <code>model</code> argument is the root of a tree of 1743*1230fdc1SLionel Sambuc<code>XML_Content</code> nodes. If <code>type</code> equals 1744*1230fdc1SLionel Sambuc<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then 1745*1230fdc1SLionel Sambuc<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other 1746*1230fdc1SLionel Sambucfields will be zero or NULL. If <code>type</code> is 1747*1230fdc1SLionel Sambuc<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be 1748*1230fdc1SLionel Sambuc<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and 1749*1230fdc1SLionel Sambuc<code>numchildren</code> will contain the number of elements that are 1750*1230fdc1SLionel Sambucallowed to be mixed in and <code>children</code> points to an array of 1751*1230fdc1SLionel Sambuc<code>XML_Content</code> structures that will all have type 1752*1230fdc1SLionel SambucXML_CTYPE_NAME with no quantification. Only the root node can be type 1753*1230fdc1SLionel Sambuc<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or 1754*1230fdc1SLionel Sambuc<code>XML_CTYPE_MIXED</code>.</p> 1755*1230fdc1SLionel Sambuc 1756*1230fdc1SLionel Sambuc<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field 1757*1230fdc1SLionel Sambucpoints to the name and the <code>numchildren</code> and 1758*1230fdc1SLionel Sambuc<code>children</code> fields will be zero and NULL. The 1759*1230fdc1SLionel Sambuc<code>quant</code> field will indicate any quantifiers placed on the 1760*1230fdc1SLionel Sambucname.</p> 1761*1230fdc1SLionel Sambuc 1762*1230fdc1SLionel Sambuc<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> 1763*1230fdc1SLionel Sambucindicate a choice or sequence respectively. The 1764*1230fdc1SLionel Sambuc<code>numchildren</code> field indicates how many nodes in the choice 1765*1230fdc1SLionel Sambucor sequence and <code>children</code> points to the nodes.</p> 1766*1230fdc1SLionel Sambuc</div> 1767*1230fdc1SLionel Sambuc 1768*1230fdc1SLionel Sambuc<div class="handler"> 1769*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetAttlistDeclHandler"> 1770*1230fdc1SLionel Sambucvoid XMLCALL 1771*1230fdc1SLionel SambucXML_SetAttlistDeclHandler(XML_Parser p, 1772*1230fdc1SLionel Sambuc XML_AttlistDeclHandler attdecl); 1773*1230fdc1SLionel Sambuc</pre> 1774*1230fdc1SLionel Sambuc<pre class="signature"> 1775*1230fdc1SLionel Sambuctypedef void 1776*1230fdc1SLionel Sambuc(XMLCALL *XML_AttlistDeclHandler)(void *userData, 1777*1230fdc1SLionel Sambuc const XML_Char *elname, 1778*1230fdc1SLionel Sambuc const XML_Char *attname, 1779*1230fdc1SLionel Sambuc const XML_Char *att_type, 1780*1230fdc1SLionel Sambuc const XML_Char *dflt, 1781*1230fdc1SLionel Sambuc int isrequired); 1782*1230fdc1SLionel Sambuc</pre> 1783*1230fdc1SLionel Sambuc<p>Set a handler for attlist declarations in the DTD. This handler is 1784*1230fdc1SLionel Sambuccalled for <em>each</em> attribute. So a single attlist declaration 1785*1230fdc1SLionel Sambucwith multiple attributes declared will generate multiple calls to this 1786*1230fdc1SLionel Sambuchandler. The <code>elname</code> parameter returns the name of the 1787*1230fdc1SLionel Sambucelement for which the attribute is being declared. The attribute name 1788*1230fdc1SLionel Sambucis in the <code>attname</code> parameter. The attribute type is in the 1789*1230fdc1SLionel Sambuc<code>att_type</code> parameter. It is the string representing the 1790*1230fdc1SLionel Sambuctype in the declaration with whitespace removed.</p> 1791*1230fdc1SLionel Sambuc 1792*1230fdc1SLionel Sambuc<p>The <code>dflt</code> parameter holds the default value. It will be 1793*1230fdc1SLionel SambucNULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can 1794*1230fdc1SLionel Sambucdistinguish these two cases by checking the <code>isrequired</code> 1795*1230fdc1SLionel Sambucparameter, which will be true in the case of "#REQUIRED" attributes. 1796*1230fdc1SLionel SambucAttributes which are "#FIXED" will have also have a true 1797*1230fdc1SLionel Sambuc<code>isrequired</code>, but they will have the non-NULL fixed value 1798*1230fdc1SLionel Sambucin the <code>dflt</code> parameter.</p> 1799*1230fdc1SLionel Sambuc</div> 1800*1230fdc1SLionel Sambuc 1801*1230fdc1SLionel Sambuc<div class="handler"> 1802*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetEntityDeclHandler"> 1803*1230fdc1SLionel Sambucvoid XMLCALL 1804*1230fdc1SLionel SambucXML_SetEntityDeclHandler(XML_Parser p, 1805*1230fdc1SLionel Sambuc XML_EntityDeclHandler handler); 1806*1230fdc1SLionel Sambuc</pre> 1807*1230fdc1SLionel Sambuc<pre class="signature"> 1808*1230fdc1SLionel Sambuctypedef void 1809*1230fdc1SLionel Sambuc(XMLCALL *XML_EntityDeclHandler)(void *userData, 1810*1230fdc1SLionel Sambuc const XML_Char *entityName, 1811*1230fdc1SLionel Sambuc int is_parameter_entity, 1812*1230fdc1SLionel Sambuc const XML_Char *value, 1813*1230fdc1SLionel Sambuc int value_length, 1814*1230fdc1SLionel Sambuc const XML_Char *base, 1815*1230fdc1SLionel Sambuc const XML_Char *systemId, 1816*1230fdc1SLionel Sambuc const XML_Char *publicId, 1817*1230fdc1SLionel Sambuc const XML_Char *notationName); 1818*1230fdc1SLionel Sambuc</pre> 1819*1230fdc1SLionel Sambuc<p>Sets a handler that will be called for all entity declarations. 1820*1230fdc1SLionel SambucThe <code>is_parameter_entity</code> argument will be non-zero in the 1821*1230fdc1SLionel Sambuccase of parameter entities and zero otherwise.</p> 1822*1230fdc1SLionel Sambuc 1823*1230fdc1SLionel Sambuc<p>For internal entities (<code><!ENTITY foo "bar"></code>), 1824*1230fdc1SLionel Sambuc<code>value</code> will be non-NULL and <code>systemId</code>, 1825*1230fdc1SLionel Sambuc<code>publicId</code>, and <code>notationName</code> will all be NULL. 1826*1230fdc1SLionel SambucThe value string is <em>not</em> NULL terminated; the length is 1827*1230fdc1SLionel Sambucprovided in the <code>value_length</code> parameter. Do not use 1828*1230fdc1SLionel Sambuc<code>value_length</code> to test for internal entities, since it is 1829*1230fdc1SLionel Sambuclegal to have zero-length values. Instead check for whether or not 1830*1230fdc1SLionel Sambuc<code>value</code> is NULL.</p> <p>The <code>notationName</code> 1831*1230fdc1SLionel Sambucargument will have a non-NULL value only for unparsed entity 1832*1230fdc1SLionel Sambucdeclarations.</p> 1833*1230fdc1SLionel Sambuc</div> 1834*1230fdc1SLionel Sambuc 1835*1230fdc1SLionel Sambuc<div class="handler"> 1836*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetUnparsedEntityDeclHandler"> 1837*1230fdc1SLionel Sambucvoid XMLCALL 1838*1230fdc1SLionel SambucXML_SetUnparsedEntityDeclHandler(XML_Parser p, 1839*1230fdc1SLionel Sambuc XML_UnparsedEntityDeclHandler h) 1840*1230fdc1SLionel Sambuc</pre> 1841*1230fdc1SLionel Sambuc<pre class="signature"> 1842*1230fdc1SLionel Sambuctypedef void 1843*1230fdc1SLionel Sambuc(XMLCALL *XML_UnparsedEntityDeclHandler)(void *userData, 1844*1230fdc1SLionel Sambuc const XML_Char *entityName, 1845*1230fdc1SLionel Sambuc const XML_Char *base, 1846*1230fdc1SLionel Sambuc const XML_Char *systemId, 1847*1230fdc1SLionel Sambuc const XML_Char *publicId, 1848*1230fdc1SLionel Sambuc const XML_Char *notationName); 1849*1230fdc1SLionel Sambuc</pre> 1850*1230fdc1SLionel Sambuc<p>Set a handler that receives declarations of unparsed entities. These 1851*1230fdc1SLionel Sambucare entity declarations that have a notation (NDATA) field:</p> 1852*1230fdc1SLionel Sambuc 1853*1230fdc1SLionel Sambuc<div id="eg"><pre> 1854*1230fdc1SLionel Sambuc<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif> 1855*1230fdc1SLionel Sambuc</pre></div> 1856*1230fdc1SLionel Sambuc<p>This handler is obsolete and is provided for backwards 1857*1230fdc1SLionel Sambuccompatibility. Use instead <a href= "#XML_SetEntityDeclHandler" 1858*1230fdc1SLionel Sambuc>XML_SetEntityDeclHandler</a>.</p> 1859*1230fdc1SLionel Sambuc</div> 1860*1230fdc1SLionel Sambuc 1861*1230fdc1SLionel Sambuc<div class="handler"> 1862*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetNotationDeclHandler"> 1863*1230fdc1SLionel Sambucvoid XMLCALL 1864*1230fdc1SLionel SambucXML_SetNotationDeclHandler(XML_Parser p, 1865*1230fdc1SLionel Sambuc XML_NotationDeclHandler h) 1866*1230fdc1SLionel Sambuc</pre> 1867*1230fdc1SLionel Sambuc<pre class="signature"> 1868*1230fdc1SLionel Sambuctypedef void 1869*1230fdc1SLionel Sambuc(XMLCALL *XML_NotationDeclHandler)(void *userData, 1870*1230fdc1SLionel Sambuc const XML_Char *notationName, 1871*1230fdc1SLionel Sambuc const XML_Char *base, 1872*1230fdc1SLionel Sambuc const XML_Char *systemId, 1873*1230fdc1SLionel Sambuc const XML_Char *publicId); 1874*1230fdc1SLionel Sambuc</pre> 1875*1230fdc1SLionel Sambuc<p>Set a handler that receives notation declarations.</p> 1876*1230fdc1SLionel Sambuc</div> 1877*1230fdc1SLionel Sambuc 1878*1230fdc1SLionel Sambuc<div class="handler"> 1879*1230fdc1SLionel Sambuc<pre class="setter" id="XML_SetNotStandaloneHandler"> 1880*1230fdc1SLionel Sambucvoid XMLCALL 1881*1230fdc1SLionel SambucXML_SetNotStandaloneHandler(XML_Parser p, 1882*1230fdc1SLionel Sambuc XML_NotStandaloneHandler h) 1883*1230fdc1SLionel Sambuc</pre> 1884*1230fdc1SLionel Sambuc<pre class="signature"> 1885*1230fdc1SLionel Sambuctypedef int 1886*1230fdc1SLionel Sambuc(XMLCALL *XML_NotStandaloneHandler)(void *userData); 1887*1230fdc1SLionel Sambuc</pre> 1888*1230fdc1SLionel Sambuc<p>Set a handler that is called if the document is not "standalone". 1889*1230fdc1SLionel SambucThis happens when there is an external subset or a reference to a 1890*1230fdc1SLionel Sambucparameter entity, but does not have standalone set to "yes" in an XML 1891*1230fdc1SLionel Sambucdeclaration. If this handler returns <code>XML_STATUS_ERROR</code>, 1892*1230fdc1SLionel Sambucthen the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code> 1893*1230fdc1SLionel Sambucerror.</p> 1894*1230fdc1SLionel Sambuc</div> 1895*1230fdc1SLionel Sambuc 1896*1230fdc1SLionel Sambuc<h3><a name="position">Parse position and error reporting functions</a></h3> 1897*1230fdc1SLionel Sambuc 1898*1230fdc1SLionel Sambuc<p>These are the functions you'll want to call when the parse 1899*1230fdc1SLionel Sambucfunctions return <code>XML_STATUS_ERROR</code> (a parse error has 1900*1230fdc1SLionel Sambucoccurred), although the position reporting functions are useful outside 1901*1230fdc1SLionel Sambucof errors. The position reported is the byte position (in the original 1902*1230fdc1SLionel Sambucdocument or entity encoding) of the first of the sequence of 1903*1230fdc1SLionel Sambuccharacters that generated the current event (or the error that caused 1904*1230fdc1SLionel Sambucthe parse functions to return <code>XML_STATUS_ERROR</code>.) The 1905*1230fdc1SLionel Sambucexceptions are callbacks trigged by declarations in the document 1906*1230fdc1SLionel Sambucprologue, in which case they exact position reported is somewhere in the 1907*1230fdc1SLionel Sambucrelevant markup, but not necessarily as meaningful as for other 1908*1230fdc1SLionel Sambucevents.</p> 1909*1230fdc1SLionel Sambuc 1910*1230fdc1SLionel Sambuc<p>The position reporting functions are accurate only outside of the 1911*1230fdc1SLionel SambucDTD. In other words, they usually return bogus information when 1912*1230fdc1SLionel Sambuccalled from within a DTD declaration handler.</p> 1913*1230fdc1SLionel Sambuc 1914*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetErrorCode"> 1915*1230fdc1SLionel Sambucenum XML_Error XMLCALL 1916*1230fdc1SLionel SambucXML_GetErrorCode(XML_Parser p); 1917*1230fdc1SLionel Sambuc</pre> 1918*1230fdc1SLionel Sambuc<div class="fcndef"> 1919*1230fdc1SLionel SambucReturn what type of error has occurred. 1920*1230fdc1SLionel Sambuc</div> 1921*1230fdc1SLionel Sambuc 1922*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ErrorString"> 1923*1230fdc1SLionel Sambucconst XML_LChar * XMLCALL 1924*1230fdc1SLionel SambucXML_ErrorString(enum XML_Error code); 1925*1230fdc1SLionel Sambuc</pre> 1926*1230fdc1SLionel Sambuc<div class="fcndef"> 1927*1230fdc1SLionel SambucReturn a string describing the error corresponding to code. 1928*1230fdc1SLionel SambucThe code should be one of the enums that can be returned from 1929*1230fdc1SLionel Sambuc<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>. 1930*1230fdc1SLionel Sambuc</div> 1931*1230fdc1SLionel Sambuc 1932*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetCurrentByteIndex"> 1933*1230fdc1SLionel SambucXML_Index XMLCALL 1934*1230fdc1SLionel SambucXML_GetCurrentByteIndex(XML_Parser p); 1935*1230fdc1SLionel Sambuc</pre> 1936*1230fdc1SLionel Sambuc<div class="fcndef"> 1937*1230fdc1SLionel SambucReturn the byte offset of the position. This always corresponds to 1938*1230fdc1SLionel Sambucthe values returned by <code><a href= "#XML_GetCurrentLineNumber" 1939*1230fdc1SLionel Sambuc>XML_GetCurrentLineNumber</a></code> and <code><a href= 1940*1230fdc1SLionel Sambuc"#XML_GetCurrentColumnNumber" >XML_GetCurrentColumnNumber</a></code>. 1941*1230fdc1SLionel Sambuc</div> 1942*1230fdc1SLionel Sambuc 1943*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetCurrentLineNumber"> 1944*1230fdc1SLionel SambucXML_Size XMLCALL 1945*1230fdc1SLionel SambucXML_GetCurrentLineNumber(XML_Parser p); 1946*1230fdc1SLionel Sambuc</pre> 1947*1230fdc1SLionel Sambuc<div class="fcndef"> 1948*1230fdc1SLionel SambucReturn the line number of the position. The first line is reported as 1949*1230fdc1SLionel Sambuc<code>1</code>. 1950*1230fdc1SLionel Sambuc</div> 1951*1230fdc1SLionel Sambuc 1952*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetCurrentColumnNumber"> 1953*1230fdc1SLionel SambucXML_Size XMLCALL 1954*1230fdc1SLionel SambucXML_GetCurrentColumnNumber(XML_Parser p); 1955*1230fdc1SLionel Sambuc</pre> 1956*1230fdc1SLionel Sambuc<div class="fcndef"> 1957*1230fdc1SLionel SambucReturn the offset, from the beginning of the current line, of 1958*1230fdc1SLionel Sambucthe position. 1959*1230fdc1SLionel Sambuc</div> 1960*1230fdc1SLionel Sambuc 1961*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetCurrentByteCount"> 1962*1230fdc1SLionel Sambucint XMLCALL 1963*1230fdc1SLionel SambucXML_GetCurrentByteCount(XML_Parser p); 1964*1230fdc1SLionel Sambuc</pre> 1965*1230fdc1SLionel Sambuc<div class="fcndef"> 1966*1230fdc1SLionel SambucReturn the number of bytes in the current event. Returns 1967*1230fdc1SLionel Sambuc<code>0</code> if the event is inside a reference to an internal 1968*1230fdc1SLionel Sambucentity and for the end-tag event for empty element tags (the later can 1969*1230fdc1SLionel Sambucbe used to distinguish empty-element tags from empty elements using 1970*1230fdc1SLionel Sambucseparate start and end tags). 1971*1230fdc1SLionel Sambuc</div> 1972*1230fdc1SLionel Sambuc 1973*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetInputContext"> 1974*1230fdc1SLionel Sambucconst char * XMLCALL 1975*1230fdc1SLionel SambucXML_GetInputContext(XML_Parser p, 1976*1230fdc1SLionel Sambuc int *offset, 1977*1230fdc1SLionel Sambuc int *size); 1978*1230fdc1SLionel Sambuc</pre> 1979*1230fdc1SLionel Sambuc<div class="fcndef"> 1980*1230fdc1SLionel Sambuc 1981*1230fdc1SLionel Sambuc<p>Returns the parser's input buffer, sets the integer pointed at by 1982*1230fdc1SLionel Sambuc<code>offset</code> to the offset within this buffer of the current 1983*1230fdc1SLionel Sambucparse position, and set the integer pointed at by <code>size</code> to 1984*1230fdc1SLionel Sambucthe size of the returned buffer.</p> 1985*1230fdc1SLionel Sambuc 1986*1230fdc1SLionel Sambuc<p>This should only be called from within a handler during an active 1987*1230fdc1SLionel Sambucparse and the returned buffer should only be referred to from within 1988*1230fdc1SLionel Sambucthe handler that made the call. This input buffer contains the 1989*1230fdc1SLionel Sambucuntranslated bytes of the input.</p> 1990*1230fdc1SLionel Sambuc 1991*1230fdc1SLionel Sambuc<p>Only a limited amount of context is kept, so if the event 1992*1230fdc1SLionel Sambuctriggering a call spans over a very large amount of input, the actual 1993*1230fdc1SLionel Sambucparse position may be before the beginning of the buffer.</p> 1994*1230fdc1SLionel Sambuc 1995*1230fdc1SLionel Sambuc<p>If <code>XML_CONTEXT_BYTES</code> is not defined, this will always 1996*1230fdc1SLionel Sambucreturn NULL.</p> 1997*1230fdc1SLionel Sambuc</div> 1998*1230fdc1SLionel Sambuc 1999*1230fdc1SLionel Sambuc<h3><a name="miscellaneous">Miscellaneous functions</a></h3> 2000*1230fdc1SLionel Sambuc 2001*1230fdc1SLionel Sambuc<p>The functions in this section either obtain state information from 2002*1230fdc1SLionel Sambucthe parser or can be used to dynamicly set parser options.</p> 2003*1230fdc1SLionel Sambuc 2004*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetUserData"> 2005*1230fdc1SLionel Sambucvoid XMLCALL 2006*1230fdc1SLionel SambucXML_SetUserData(XML_Parser p, 2007*1230fdc1SLionel Sambuc void *userData); 2008*1230fdc1SLionel Sambuc</pre> 2009*1230fdc1SLionel Sambuc<div class="fcndef"> 2010*1230fdc1SLionel SambucThis sets the user data pointer that gets passed to handlers. It 2011*1230fdc1SLionel Sambucoverwrites any previous value for this pointer. Note that the 2012*1230fdc1SLionel Sambucapplication is responsible for freeing the memory associated with 2013*1230fdc1SLionel Sambuc<code>userData</code> when it is finished with the parser. So if you 2014*1230fdc1SLionel Sambuccall this when there's already a pointer there, and you haven't freed 2015*1230fdc1SLionel Sambucthe memory associated with it, then you've probably just leaked 2016*1230fdc1SLionel Sambucmemory. 2017*1230fdc1SLionel Sambuc</div> 2018*1230fdc1SLionel Sambuc 2019*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetUserData"> 2020*1230fdc1SLionel Sambucvoid * XMLCALL 2021*1230fdc1SLionel SambucXML_GetUserData(XML_Parser p); 2022*1230fdc1SLionel Sambuc</pre> 2023*1230fdc1SLionel Sambuc<div class="fcndef"> 2024*1230fdc1SLionel SambucThis returns the user data pointer that gets passed to handlers. 2025*1230fdc1SLionel SambucIt is actually implemented as a macro. 2026*1230fdc1SLionel Sambuc</div> 2027*1230fdc1SLionel Sambuc 2028*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_UseParserAsHandlerArg"> 2029*1230fdc1SLionel Sambucvoid XMLCALL 2030*1230fdc1SLionel SambucXML_UseParserAsHandlerArg(XML_Parser p); 2031*1230fdc1SLionel Sambuc</pre> 2032*1230fdc1SLionel Sambuc<div class="fcndef"> 2033*1230fdc1SLionel SambucAfter this is called, handlers receive the parser in their 2034*1230fdc1SLionel Sambuc<code>userData</code> arguments. The user data can still be obtained 2035*1230fdc1SLionel Sambucusing the <code><a href= "#XML_GetUserData" 2036*1230fdc1SLionel Sambuc>XML_GetUserData</a></code> function. 2037*1230fdc1SLionel Sambuc</div> 2038*1230fdc1SLionel Sambuc 2039*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetBase"> 2040*1230fdc1SLionel Sambucenum XML_Status XMLCALL 2041*1230fdc1SLionel SambucXML_SetBase(XML_Parser p, 2042*1230fdc1SLionel Sambuc const XML_Char *base); 2043*1230fdc1SLionel Sambuc</pre> 2044*1230fdc1SLionel Sambuc<div class="fcndef"> 2045*1230fdc1SLionel SambucSet the base to be used for resolving relative URIs in system 2046*1230fdc1SLionel Sambucidentifiers. The return value is <code>XML_STATUS_ERROR</code> if 2047*1230fdc1SLionel Sambucthere's no memory to store base, otherwise it's 2048*1230fdc1SLionel Sambuc<code>XML_STATUS_OK</code>. 2049*1230fdc1SLionel Sambuc</div> 2050*1230fdc1SLionel Sambuc 2051*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetBase"> 2052*1230fdc1SLionel Sambucconst XML_Char * XMLCALL 2053*1230fdc1SLionel SambucXML_GetBase(XML_Parser p); 2054*1230fdc1SLionel Sambuc</pre> 2055*1230fdc1SLionel Sambuc<div class="fcndef"> 2056*1230fdc1SLionel SambucReturn the base for resolving relative URIs. 2057*1230fdc1SLionel Sambuc</div> 2058*1230fdc1SLionel Sambuc 2059*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetSpecifiedAttributeCount"> 2060*1230fdc1SLionel Sambucint XMLCALL 2061*1230fdc1SLionel SambucXML_GetSpecifiedAttributeCount(XML_Parser p); 2062*1230fdc1SLionel Sambuc</pre> 2063*1230fdc1SLionel Sambuc<div class="fcndef"> 2064*1230fdc1SLionel SambucWhen attributes are reported to the start handler in the atts vector, 2065*1230fdc1SLionel Sambucattributes that were explicitly set in the element occur before any 2066*1230fdc1SLionel Sambucattributes that receive their value from default information in an 2067*1230fdc1SLionel SambucATTLIST declaration. This function returns the number of attributes 2068*1230fdc1SLionel Sambucthat were explicitly set times two, thus giving the offset in the 2069*1230fdc1SLionel Sambuc<code>atts</code> array passed to the start tag handler of the first 2070*1230fdc1SLionel Sambucattribute set due to defaults. It supplies information for the last 2071*1230fdc1SLionel Sambuccall to a start handler. If called inside a start handler, then that 2072*1230fdc1SLionel Sambucmeans the current call. 2073*1230fdc1SLionel Sambuc</div> 2074*1230fdc1SLionel Sambuc 2075*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetIdAttributeIndex"> 2076*1230fdc1SLionel Sambucint XMLCALL 2077*1230fdc1SLionel SambucXML_GetIdAttributeIndex(XML_Parser p); 2078*1230fdc1SLionel Sambuc</pre> 2079*1230fdc1SLionel Sambuc<div class="fcndef"> 2080*1230fdc1SLionel SambucReturns the index of the ID attribute passed in the atts array in the 2081*1230fdc1SLionel Sambuclast call to <code><a href= "#XML_StartElementHandler" 2082*1230fdc1SLionel Sambuc>XML_StartElementHandler</a></code>, or -1 if there is no ID 2083*1230fdc1SLionel Sambucattribute. If called inside a start handler, then that means the 2084*1230fdc1SLionel Sambuccurrent call. 2085*1230fdc1SLionel Sambuc</div> 2086*1230fdc1SLionel Sambuc 2087*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetAttributeInfo"> 2088*1230fdc1SLionel Sambucconst XML_AttrInfo * XMLCALL 2089*1230fdc1SLionel SambucXML_GetAttributeInfo(XML_Parser parser); 2090*1230fdc1SLionel Sambuc</pre> 2091*1230fdc1SLionel Sambuc<pre class="signature"> 2092*1230fdc1SLionel Sambuctypedef struct { 2093*1230fdc1SLionel Sambuc XML_Index nameStart; /* Offset to beginning of the attribute name. */ 2094*1230fdc1SLionel Sambuc XML_Index nameEnd; /* Offset after the attribute name's last byte. */ 2095*1230fdc1SLionel Sambuc XML_Index valueStart; /* Offset to beginning of the attribute value. */ 2096*1230fdc1SLionel Sambuc XML_Index valueEnd; /* Offset after the attribute value's last byte. */ 2097*1230fdc1SLionel Sambuc} XML_AttrInfo; 2098*1230fdc1SLionel Sambuc</pre> 2099*1230fdc1SLionel Sambuc<div class="fcndef"> 2100*1230fdc1SLionel SambucReturns an array of <code>XML_AttrInfo</code> structures for the 2101*1230fdc1SLionel Sambucattribute/value pairs passed in the last call to the 2102*1230fdc1SLionel Sambuc<code>XML_StartElementHandler</code> that were specified 2103*1230fdc1SLionel Sambucin the start-tag rather than defaulted. Each attribute/value pair counts 2104*1230fdc1SLionel Sambucas 1; thus the number of entries in the array is 2105*1230fdc1SLionel Sambuc<code>XML_GetSpecifiedAttributeCount(parser) / 2</code>. 2106*1230fdc1SLionel Sambuc</div> 2107*1230fdc1SLionel Sambuc 2108*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetEncoding"> 2109*1230fdc1SLionel Sambucenum XML_Status XMLCALL 2110*1230fdc1SLionel SambucXML_SetEncoding(XML_Parser p, 2111*1230fdc1SLionel Sambuc const XML_Char *encoding); 2112*1230fdc1SLionel Sambuc</pre> 2113*1230fdc1SLionel Sambuc<div class="fcndef"> 2114*1230fdc1SLionel SambucSet the encoding to be used by the parser. It is equivalent to 2115*1230fdc1SLionel Sambucpassing a non-null encoding argument to the parser creation functions. 2116*1230fdc1SLionel SambucIt must not be called after <code><a href= "#XML_Parse" 2117*1230fdc1SLionel Sambuc>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 2118*1230fdc1SLionel Sambuc>XML_ParseBuffer</a></code> have been called on the given parser. 2119*1230fdc1SLionel SambucReturns <code>XML_STATUS_OK</code> on success or 2120*1230fdc1SLionel Sambuc<code>XML_STATUS_ERROR</code> on error. 2121*1230fdc1SLionel Sambuc</div> 2122*1230fdc1SLionel Sambuc 2123*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetParamEntityParsing"> 2124*1230fdc1SLionel Sambucint XMLCALL 2125*1230fdc1SLionel SambucXML_SetParamEntityParsing(XML_Parser p, 2126*1230fdc1SLionel Sambuc enum XML_ParamEntityParsing code); 2127*1230fdc1SLionel Sambuc</pre> 2128*1230fdc1SLionel Sambuc<div class="fcndef"> 2129*1230fdc1SLionel SambucThis enables parsing of parameter entities, including the external 2130*1230fdc1SLionel Sambucparameter entity that is the external DTD subset, according to 2131*1230fdc1SLionel Sambuc<code>code</code>. 2132*1230fdc1SLionel SambucThe choices for <code>code</code> are: 2133*1230fdc1SLionel Sambuc<ul> 2134*1230fdc1SLionel Sambuc<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li> 2135*1230fdc1SLionel Sambuc<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li> 2136*1230fdc1SLionel Sambuc<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li> 2137*1230fdc1SLionel Sambuc</ul> 2138*1230fdc1SLionel Sambuc<b>Note:</b> If <code>XML_SetParamEntityParsing</code> is called after 2139*1230fdc1SLionel Sambuc<code>XML_Parse</code> or <code>XML_ParseBuffer</code>, then it has 2140*1230fdc1SLionel Sambucno effect and will always return 0. 2141*1230fdc1SLionel Sambuc</div> 2142*1230fdc1SLionel Sambuc 2143*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetHashSalt"> 2144*1230fdc1SLionel Sambucint XMLCALL 2145*1230fdc1SLionel SambucXML_SetHashSalt(XML_Parser p, 2146*1230fdc1SLionel Sambuc unsigned long hash_salt); 2147*1230fdc1SLionel Sambuc</pre> 2148*1230fdc1SLionel Sambuc<div class="fcndef"> 2149*1230fdc1SLionel SambucSets the hash salt to use for internal hash calculations. 2150*1230fdc1SLionel SambucHelps in preventing DoS attacks based on predicting hash 2151*1230fdc1SLionel Sambucfunction behavior. In order to have an effect this must be called 2152*1230fdc1SLionel Sambucbefore parsing has started. Returns 1 if successful, 0 when called 2153*1230fdc1SLionel Sambucafter <code>XML_Parse</code> or <code>XML_ParseBuffer</code>. 2154*1230fdc1SLionel Sambuc<p><b>Note:</b> This call is optional, as the parser will auto-generate a new 2155*1230fdc1SLionel Sambucrandom salt value if no value has been set at the start of parsing.</p> 2156*1230fdc1SLionel Sambuc</div> 2157*1230fdc1SLionel Sambuc 2158*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_UseForeignDTD"> 2159*1230fdc1SLionel Sambucenum XML_Error XMLCALL 2160*1230fdc1SLionel SambucXML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); 2161*1230fdc1SLionel Sambuc</pre> 2162*1230fdc1SLionel Sambuc<div class="fcndef"> 2163*1230fdc1SLionel Sambuc<p>This function allows an application to provide an external subset 2164*1230fdc1SLionel Sambucfor the document type declaration for documents which do not specify 2165*1230fdc1SLionel Sambucan external subset of their own. For documents which specify an 2166*1230fdc1SLionel Sambucexternal subset in their DOCTYPE declaration, the application-provided 2167*1230fdc1SLionel Sambucsubset will be ignored. If the document does not contain a DOCTYPE 2168*1230fdc1SLionel Sambucdeclaration at all and <code>useDTD</code> is true, the 2169*1230fdc1SLionel Sambucapplication-provided subset will be parsed, but the 2170*1230fdc1SLionel Sambuc<code>startDoctypeDeclHandler</code> and 2171*1230fdc1SLionel Sambuc<code>endDoctypeDeclHandler</code> functions, if set, will not be 2172*1230fdc1SLionel Sambuccalled. The setting of parameter entity parsing, controlled using 2173*1230fdc1SLionel Sambuc<code><a href= "#XML_SetParamEntityParsing" 2174*1230fdc1SLionel Sambuc>XML_SetParamEntityParsing</a></code>, will be honored.</p> 2175*1230fdc1SLionel Sambuc 2176*1230fdc1SLionel Sambuc<p>The application-provided external subset is read by calling the 2177*1230fdc1SLionel Sambucexternal entity reference handler set via <code><a href= 2178*1230fdc1SLionel Sambuc"#XML_SetExternalEntityRefHandler" 2179*1230fdc1SLionel Sambuc>XML_SetExternalEntityRefHandler</a></code> with both 2180*1230fdc1SLionel Sambuc<code>publicId</code> and <code>systemId</code> set to NULL.</p> 2181*1230fdc1SLionel Sambuc 2182*1230fdc1SLionel Sambuc<p>If this function is called after parsing has begun, it returns 2183*1230fdc1SLionel Sambuc<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores 2184*1230fdc1SLionel Sambuc<code>useDTD</code>. If called when Expat has been compiled without 2185*1230fdc1SLionel SambucDTD support, it returns 2186*1230fdc1SLionel Sambuc<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise, it 2187*1230fdc1SLionel Sambucreturns <code>XML_ERROR_NONE</code>.</p> 2188*1230fdc1SLionel Sambuc 2189*1230fdc1SLionel Sambuc<p><b>Note:</b> For the purpose of checking WFC: Entity Declared, passing 2190*1230fdc1SLionel Sambuc<code>useDTD == XML_TRUE</code> will make the parser behave as if 2191*1230fdc1SLionel Sambucthe document had a DTD with an external subset. This holds true even if 2192*1230fdc1SLionel Sambucthe external entity reference handler returns without action.</p> 2193*1230fdc1SLionel Sambuc</div> 2194*1230fdc1SLionel Sambuc 2195*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_SetReturnNSTriplet"> 2196*1230fdc1SLionel Sambucvoid XMLCALL 2197*1230fdc1SLionel SambucXML_SetReturnNSTriplet(XML_Parser parser, 2198*1230fdc1SLionel Sambuc int do_nst); 2199*1230fdc1SLionel Sambuc</pre> 2200*1230fdc1SLionel Sambuc<div class="fcndef"> 2201*1230fdc1SLionel Sambuc<p> 2202*1230fdc1SLionel SambucThis function only has an effect when using a parser created with 2203*1230fdc1SLionel Sambuc<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, 2204*1230fdc1SLionel Sambuci.e. when namespace processing is in effect. The <code>do_nst</code> 2205*1230fdc1SLionel Sambucsets whether or not prefixes are returned with names qualified with a 2206*1230fdc1SLionel Sambucnamespace prefix. If this function is called with <code>do_nst</code> 2207*1230fdc1SLionel Sambucnon-zero, then afterwards namespace qualified names (that is qualified 2208*1230fdc1SLionel Sambucwith a prefix as opposed to belonging to a default namespace) are 2209*1230fdc1SLionel Sambucreturned as a triplet with the three parts separated by the namespace 2210*1230fdc1SLionel Sambucseparator specified when the parser was created. The order of 2211*1230fdc1SLionel Sambucreturned parts is URI, local name, and prefix.</p> <p>If 2212*1230fdc1SLionel Sambuc<code>do_nst</code> is zero, then namespaces are reported in the 2213*1230fdc1SLionel Sambucdefault manner, URI then local_name separated by the namespace 2214*1230fdc1SLionel Sambucseparator.</p> 2215*1230fdc1SLionel Sambuc</div> 2216*1230fdc1SLionel Sambuc 2217*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_DefaultCurrent"> 2218*1230fdc1SLionel Sambucvoid XMLCALL 2219*1230fdc1SLionel SambucXML_DefaultCurrent(XML_Parser parser); 2220*1230fdc1SLionel Sambuc</pre> 2221*1230fdc1SLionel Sambuc<div class="fcndef"> 2222*1230fdc1SLionel SambucThis can be called within a handler for a start element, end element, 2223*1230fdc1SLionel Sambucprocessing instruction or character data. It causes the corresponding 2224*1230fdc1SLionel Sambucmarkup to be passed to the default handler set by <code><a 2225*1230fdc1SLionel Sambuchref="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or 2226*1230fdc1SLionel Sambuc<code><a href="#XML_SetDefaultHandlerExpand" 2227*1230fdc1SLionel Sambuc>XML_SetDefaultHandlerExpand</a></code>. It does nothing if there is 2228*1230fdc1SLionel Sambucnot a default handler. 2229*1230fdc1SLionel Sambuc</div> 2230*1230fdc1SLionel Sambuc 2231*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ExpatVersion"> 2232*1230fdc1SLionel SambucXML_LChar * XMLCALL 2233*1230fdc1SLionel SambucXML_ExpatVersion(); 2234*1230fdc1SLionel Sambuc</pre> 2235*1230fdc1SLionel Sambuc<div class="fcndef"> 2236*1230fdc1SLionel SambucReturn the library version as a string (e.g. <code>"expat_1.95.1"</code>). 2237*1230fdc1SLionel Sambuc</div> 2238*1230fdc1SLionel Sambuc 2239*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_ExpatVersionInfo"> 2240*1230fdc1SLionel Sambucstruct XML_Expat_Version XMLCALL 2241*1230fdc1SLionel SambucXML_ExpatVersionInfo(); 2242*1230fdc1SLionel Sambuc</pre> 2243*1230fdc1SLionel Sambuc<pre class="signature"> 2244*1230fdc1SLionel Sambuctypedef struct { 2245*1230fdc1SLionel Sambuc int major; 2246*1230fdc1SLionel Sambuc int minor; 2247*1230fdc1SLionel Sambuc int micro; 2248*1230fdc1SLionel Sambuc} XML_Expat_Version; 2249*1230fdc1SLionel Sambuc</pre> 2250*1230fdc1SLionel Sambuc<div class="fcndef"> 2251*1230fdc1SLionel SambucReturn the library version information as a structure. 2252*1230fdc1SLionel SambucSome macros are also defined that support compile-time tests of the 2253*1230fdc1SLionel Sambuclibrary version: 2254*1230fdc1SLionel Sambuc<ul> 2255*1230fdc1SLionel Sambuc<li><code>XML_MAJOR_VERSION</code></li> 2256*1230fdc1SLionel Sambuc<li><code>XML_MINOR_VERSION</code></li> 2257*1230fdc1SLionel Sambuc<li><code>XML_MICRO_VERSION</code></li> 2258*1230fdc1SLionel Sambuc</ul> 2259*1230fdc1SLionel SambucTesting these constants is currently the best way to determine if 2260*1230fdc1SLionel Sambucparticular parts of the Expat API are available. 2261*1230fdc1SLionel Sambuc</div> 2262*1230fdc1SLionel Sambuc 2263*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_GetFeatureList"> 2264*1230fdc1SLionel Sambucconst XML_Feature * XMLCALL 2265*1230fdc1SLionel SambucXML_GetFeatureList(); 2266*1230fdc1SLionel Sambuc</pre> 2267*1230fdc1SLionel Sambuc<pre class="signature"> 2268*1230fdc1SLionel Sambucenum XML_FeatureEnum { 2269*1230fdc1SLionel Sambuc XML_FEATURE_END = 0, 2270*1230fdc1SLionel Sambuc XML_FEATURE_UNICODE, 2271*1230fdc1SLionel Sambuc XML_FEATURE_UNICODE_WCHAR_T, 2272*1230fdc1SLionel Sambuc XML_FEATURE_DTD, 2273*1230fdc1SLionel Sambuc XML_FEATURE_CONTEXT_BYTES, 2274*1230fdc1SLionel Sambuc XML_FEATURE_MIN_SIZE, 2275*1230fdc1SLionel Sambuc XML_FEATURE_SIZEOF_XML_CHAR, 2276*1230fdc1SLionel Sambuc XML_FEATURE_SIZEOF_XML_LCHAR, 2277*1230fdc1SLionel Sambuc XML_FEATURE_NS, 2278*1230fdc1SLionel Sambuc XML_FEATURE_LARGE_SIZE 2279*1230fdc1SLionel Sambuc}; 2280*1230fdc1SLionel Sambuc 2281*1230fdc1SLionel Sambuctypedef struct { 2282*1230fdc1SLionel Sambuc enum XML_FeatureEnum feature; 2283*1230fdc1SLionel Sambuc XML_LChar *name; 2284*1230fdc1SLionel Sambuc long int value; 2285*1230fdc1SLionel Sambuc} XML_Feature; 2286*1230fdc1SLionel Sambuc</pre> 2287*1230fdc1SLionel Sambuc<div class="fcndef"> 2288*1230fdc1SLionel Sambuc<p>Returns a list of "feature" records, providing details on how 2289*1230fdc1SLionel SambucExpat was configured at compile time. Most applications should not 2290*1230fdc1SLionel Sambucneed to worry about this, but this information is otherwise not 2291*1230fdc1SLionel Sambucavailable from Expat. This function allows code that does need to 2292*1230fdc1SLionel Sambuccheck these features to do so at runtime.</p> 2293*1230fdc1SLionel Sambuc 2294*1230fdc1SLionel Sambuc<p>The return value is an array of <code>XML_Feature</code>, 2295*1230fdc1SLionel Sambucterminated by a record with a <code>feature</code> of 2296*1230fdc1SLionel Sambuc<code>XML_FEATURE_END</code> and <code>name</code> of NULL, 2297*1230fdc1SLionel Sambucidentifying the feature-test macros Expat was compiled with. Since an 2298*1230fdc1SLionel Sambucapplication that requires this kind of information needs to determine 2299*1230fdc1SLionel Sambucthe type of character the <code>name</code> points to, records for the 2300*1230fdc1SLionel Sambuc<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and 2301*1230fdc1SLionel Sambuc<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the 2302*1230fdc1SLionel Sambucbeginning of the list, followed by <code>XML_FEATURE_UNICODE</code> 2303*1230fdc1SLionel Sambucand <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at 2304*1230fdc1SLionel Sambucall.</p> 2305*1230fdc1SLionel Sambuc 2306*1230fdc1SLionel Sambuc<p>Some features have an associated value. If there isn't an 2307*1230fdc1SLionel Sambucassociated value, the <code>value</code> field is set to 0. At this 2308*1230fdc1SLionel Sambuctime, the following features have been defined to have values:</p> 2309*1230fdc1SLionel Sambuc 2310*1230fdc1SLionel Sambuc<dl> 2311*1230fdc1SLionel Sambuc <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt> 2312*1230fdc1SLionel Sambuc <dd>The number of bytes occupied by one <code>XML_Char</code> 2313*1230fdc1SLionel Sambuc character.</dd> 2314*1230fdc1SLionel Sambuc <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt> 2315*1230fdc1SLionel Sambuc <dd>The number of bytes occupied by one <code>XML_LChar</code> 2316*1230fdc1SLionel Sambuc character.</dd> 2317*1230fdc1SLionel Sambuc <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt> 2318*1230fdc1SLionel Sambuc <dd>The maximum number of characters of context which can be 2319*1230fdc1SLionel Sambuc reported by <code><a href= "#XML_GetInputContext" 2320*1230fdc1SLionel Sambuc >XML_GetInputContext</a></code>.</dd> 2321*1230fdc1SLionel Sambuc</dl> 2322*1230fdc1SLionel Sambuc</div> 2323*1230fdc1SLionel Sambuc 2324*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_FreeContentModel"> 2325*1230fdc1SLionel Sambucvoid XMLCALL 2326*1230fdc1SLionel SambucXML_FreeContentModel(XML_Parser parser, XML_Content *model); 2327*1230fdc1SLionel Sambuc</pre> 2328*1230fdc1SLionel Sambuc<div class="fcndef"> 2329*1230fdc1SLionel SambucFunction to deallocate the <code>model</code> argument passed to the 2330*1230fdc1SLionel Sambuc<code>XML_ElementDeclHandler</code> callback set using <code><a 2331*1230fdc1SLionel Sambuchref="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>. 2332*1230fdc1SLionel SambucThis function should not be used for any other purpose. 2333*1230fdc1SLionel Sambuc</div> 2334*1230fdc1SLionel Sambuc 2335*1230fdc1SLionel Sambuc<p>The following functions allow external code to share the memory 2336*1230fdc1SLionel Sambucallocator an <code>XML_Parser</code> has been configured to use. This 2337*1230fdc1SLionel Sambucis especially useful for third-party libraries that interact with a 2338*1230fdc1SLionel Sambucparser object created by application code, or heavily layered 2339*1230fdc1SLionel Sambucapplications. This can be essential when using dynamically loaded 2340*1230fdc1SLionel Sambuclibraries which use different C standard libraries (this can happen on 2341*1230fdc1SLionel SambucWindows, at least).</p> 2342*1230fdc1SLionel Sambuc 2343*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_MemMalloc"> 2344*1230fdc1SLionel Sambucvoid * XMLCALL 2345*1230fdc1SLionel SambucXML_MemMalloc(XML_Parser parser, size_t size); 2346*1230fdc1SLionel Sambuc</pre> 2347*1230fdc1SLionel Sambuc<div class="fcndef"> 2348*1230fdc1SLionel SambucAllocate <code>size</code> bytes of memory using the allocator the 2349*1230fdc1SLionel Sambuc<code>parser</code> object has been configured to use. Returns a 2350*1230fdc1SLionel Sambucpointer to the memory or NULL on failure. Memory allocated in this 2351*1230fdc1SLionel Sambucway must be freed using <code><a href="#XML_MemFree" 2352*1230fdc1SLionel Sambuc>XML_MemFree</a></code>. 2353*1230fdc1SLionel Sambuc</div> 2354*1230fdc1SLionel Sambuc 2355*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_MemRealloc"> 2356*1230fdc1SLionel Sambucvoid * XMLCALL 2357*1230fdc1SLionel SambucXML_MemRealloc(XML_Parser parser, void *ptr, size_t size); 2358*1230fdc1SLionel Sambuc</pre> 2359*1230fdc1SLionel Sambuc<div class="fcndef"> 2360*1230fdc1SLionel SambucAllocate <code>size</code> bytes of memory using the allocator the 2361*1230fdc1SLionel Sambuc<code>parser</code> object has been configured to use. 2362*1230fdc1SLionel Sambuc<code>ptr</code> must point to a block of memory allocated by <code><a 2363*1230fdc1SLionel Sambuchref="#XML_MemMalloc" >XML_MemMalloc</a></code> or 2364*1230fdc1SLionel Sambuc<code>XML_MemRealloc</code>, or be NULL. This function tries to 2365*1230fdc1SLionel Sambucexpand the block pointed to by <code>ptr</code> if possible. Returns 2366*1230fdc1SLionel Sambuca pointer to the memory or NULL on failure. On success, the original 2367*1230fdc1SLionel Sambucblock has either been expanded or freed. On failure, the original 2368*1230fdc1SLionel Sambucblock has not been freed; the caller is responsible for freeing the 2369*1230fdc1SLionel Sambucoriginal block. Memory allocated in this way must be freed using 2370*1230fdc1SLionel Sambuc<code><a href="#XML_MemFree" 2371*1230fdc1SLionel Sambuc>XML_MemFree</a></code>. 2372*1230fdc1SLionel Sambuc</div> 2373*1230fdc1SLionel Sambuc 2374*1230fdc1SLionel Sambuc<pre class="fcndec" id="XML_MemFree"> 2375*1230fdc1SLionel Sambucvoid XMLCALL 2376*1230fdc1SLionel SambucXML_MemFree(XML_Parser parser, void *ptr); 2377*1230fdc1SLionel Sambuc</pre> 2378*1230fdc1SLionel Sambuc<div class="fcndef"> 2379*1230fdc1SLionel SambucFree a block of memory pointed to by <code>ptr</code>. The block must 2380*1230fdc1SLionel Sambuchave been allocated by <code><a href="#XML_MemMalloc" 2381*1230fdc1SLionel Sambuc>XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be NULL. 2382*1230fdc1SLionel Sambuc</div> 2383*1230fdc1SLionel Sambuc 2384*1230fdc1SLionel Sambuc<hr /> 2385*1230fdc1SLionel Sambuc<p><a href="http://validator.w3.org/check/referer"><img 2386*1230fdc1SLionel Sambuc src="valid-xhtml10.png" alt="Valid XHTML 1.0!" 2387*1230fdc1SLionel Sambuc height="31" width="88" class="noborder" /></a></p> 2388*1230fdc1SLionel Sambuc</div> 2389*1230fdc1SLionel Sambuc</body> 2390*1230fdc1SLionel Sambuc</html> 2391
