1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 4<html> 5<head> 6<!-- Copyright 1999,2000 Clark Cooper <coopercc@netheaven.com> 7 All rights reserved. 8 This is free software. You may distribute or modify according to 9 the terms of the MIT/X License --> 10 <title>Expat XML Parser</title> 11 <meta name="author" content="Clark Cooper, coopercc@netheaven.com" /> 12 <meta http-equiv="Content-Style-Type" content="text/css" /> 13 <link href="style.css" rel="stylesheet" type="text/css" /> 14</head> 15<body> 16<h1>Expat XML Parser</h1> 17 18<p>Expat is a library, written in C, for parsing XML documents. It's 19the underlying XML parser for the open source Mozilla project, Perl's 20<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and 21other open-source XML parsers.</p> 22 23<p>This library is the creation of James Clark, who's also given us 24groff (an nroff look-alike), Jade (an implemention of ISO's DSSSL 25stylesheet language for SGML), XP (a Java XML parser package), XT (a 26Java XSL engine). James was also the technical lead on the XML 27Working Group at W3C that produced the XML specification.</p> 28 29<p>This is free software, licensed under the <a 30href="../COPYING">MIT/X Consortium license</a>. You may download it 31from <a href="http://www.libexpat.org/">the Expat home page</a>. 32</p> 33 34<p>The bulk of this document was originally commissioned as an article by 35<a href="http://www.xml.com/">XML.com</a>. They graciously allowed 36Clark Cooper to retain copyright and to distribute it with Expat.</p> 37 38<hr /> 39<h2>Table of Contents</h2> 40<ul> 41 <li><a href="#overview">Overview</a></li> 42 <li><a href="#building">Building and Installing</a></li> 43 <li><a href="#using">Using Expat</a></li> 44 <li><a href="#reference">Reference</a> 45 <ul> 46 <li><a href="#creation">Parser Creation Functions</a> 47 <ul> 48 <li><a href="#XML_ParserCreate">XML_ParserCreate</a></li> 49 <li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li> 50 <li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li> 51 <li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li> 52 <li><a href="#XML_ParserFree">XML_ParserFree</a></li> 53 <li><a href="#XML_ParserReset">XML_ParserReset</a></li> 54 </ul> 55 </li> 56 <li><a href="#parsing">Parsing Functions</a> 57 <ul> 58 <li><a href="#XML_Parse">XML_Parse</a></li> 59 <li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li> 60 <li><a href="#XML_GetBuffer">XML_GetBuffer</a></li> 61 </ul> 62 </li> 63 <li><a href="#setting">Handler Setting Functions</a> 64 <ul> 65 <li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li> 66 <li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li> 67 <li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li> 68 <li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li> 69 <li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li> 70 <li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li> 71 <li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li> 72 <li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li> 73 <li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li> 74 <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li> 75 <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li> 76 <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li> 77 <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li> 78 <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li> 79 <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li> 80 <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li> 81 <li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li> 82 <li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li> 83 <li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li> 84 <li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li> 85 <li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li> 86 <li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li> 87 <li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li> 88 <li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li> 89 <li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li> 90 <li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li> 91 <li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li> 92 <li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li> 93 </ul> 94 </li> 95 <li><a href="#position">Parse Position and Error Reporting Functions</a> 96 <ul> 97 <li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li> 98 <li><a href="#XML_ErrorString">XML_ErrorString</a></li> 99 <li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li> 100 <li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li> 101 <li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li> 102 <li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li> 103 <li><a href="#XML_GetInputContext">XML_GetInputContext</a></li> 104 </ul> 105 </li> 106 <li><a href="#miscellaneous">Miscellaneous Functions</a> 107 <ul> 108 <li><a href="#XML_SetUserData">XML_SetUserData</a></li> 109 <li><a href="#XML_GetUserData">XML_GetUserData</a></li> 110 <li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li> 111 <li><a href="#XML_SetBase">XML_SetBase</a></li> 112 <li><a href="#XML_GetBase">XML_GetBase</a></li> 113 <li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li> 114 <li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li> 115 <li><a href="#XML_SetEncoding">XML_SetEncoding</a></li> 116 <li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li> 117 <li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li> 118 <li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li> 119 <li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li> 120 <li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li> 121 <li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li> 122 <li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li> 123 <li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li> 124 <li><a href="#XML_MemMalloc">XML_MemMalloc</a></li> 125 <li><a href="#XML_MemRealloc">XML_MemRealloc</a></li> 126 <li><a href="#XML_MemFree">XML_MemFree</a></li> 127 </ul> 128 </li> 129 </ul> 130 </li> 131</ul> 132 133<hr /> 134<h2><a name="overview">Overview</a></h2> 135 136<p>Expat is a stream-oriented parser. You register callback (or 137handler) functions with the parser and then start feeding it the 138document. As the parser recognizes parts of the document, it will 139call the appropriate handler for that part (if you've registered one.) 140The document is fed to the parser in pieces, so you can start parsing 141before you have all the document. This also allows you to parse really 142huge documents that won't fit into memory.</p> 143 144<p>Expat can be intimidating due to the many kinds of handlers and 145options you can set. But you only need to learn four functions in 146order to do 90% of what you'll want to do with it:</p> 147 148<dl> 149 150<dt><code><a href= "#XML_ParserCreate" 151 >XML_ParserCreate</a></code></dt> 152 <dd>Create a new parser object.</dd> 153 154<dt><code><a href= "#XML_SetElementHandler" 155 >XML_SetElementHandler</a></code></dt> 156 <dd>Set handlers for start and end tags.</dd> 157 158<dt><code><a href= "#XML_SetCharacterDataHandler" 159 >XML_SetCharacterDataHandler</a></code></dt> 160 <dd>Set handler for text.</dd> 161 162<dt><code><a href= "#XML_Parse" 163 >XML_Parse</a></code></dt> 164 <dd>Pass a buffer full of document to the parser</dd> 165</dl> 166 167<p>These functions and others are described in the <a 168href="#reference">reference</a> part of this document. The reference 169section also describes in detail the parameters passed to the 170different types of handlers.</p> 171 172<p>Let's look at a very simple example program that only uses 3 of the 173above functions (it doesn't need to set a character handler.) The 174program <a href="../examples/outline.c">outline.c</a> prints an 175element outline, indenting child elements to distinguish them from the 176parent element that contains them. The start handler does all the 177work. It prints two indenting spaces for every level of ancestor 178elements, then it prints the element and attribute 179information. Finally it increments the global <code>Depth</code> 180variable.</p> 181 182<pre class="eg"> 183int Depth; 184 185void 186start(void *data, const char *el, const char **attr) { 187 int i; 188 189 for (i = 0; i < Depth; i++) 190 printf(" "); 191 192 printf("%s", el); 193 194 for (i = 0; attr[i]; i += 2) { 195 printf(" %s='%s'", attr[i], attr[i + 1]); 196 } 197 198 printf("\n"); 199 Depth++; 200} /* End of start handler */ 201</pre> 202 203<p>The end tag simply does the bookkeeping work of decrementing 204<code>Depth</code>.</p> 205<pre class="eg"> 206void 207end(void *data, const char *el) { 208 Depth--; 209} /* End of end handler */ 210</pre> 211 212<p>After creating the parser, the main program just has the job of 213shoveling the document to the parser so that it can do its work.</p> 214 215<hr /> 216<h2><a name="building">Building and Installing Expat</a></h2> 217 218<p>The Expat distribution comes as a compressed (with GNU gzip) tar 219file. You may download the latest version from <a href= 220"http://sourceforge.net/projects/expat/" >Source Forge</a>. After 221unpacking this, cd into the directory. Then follow either the Win32 222directions or Unix directions below.</p> 223 224<h3>Building under Win32</h3> 225 226<p>If you're using the GNU compiler under cygwin, follow the Unix 227directions in the next section. Otherwise if you have Microsoft's 228Developer Studio installed, then from Windows Explorer double-click on 229"expat.dsp" in the lib directory and build and install in the usual 230manner.</p> 231 232<p>Alternatively, you may download the Win32 binary package that 233contains the "expat.h" include file and a pre-built DLL.</p> 234 235<h3>Building under Unix (or GNU)</h3> 236 237<p>First you'll need to run the configure shell script in order to 238configure the Makefiles and headers for your system.</p> 239 240<p>If you're happy with all the defaults that configure picks for you, 241and you have permission on your system to install into /usr/local, you 242can install Expat with this sequence of commands:</p> 243 244<pre class="eg"> 245 ./configure 246 make 247 make install 248</pre> 249 250<p>There are some options that you can provide to this script, but the 251only one we'll mention here is the <code>--prefix</code> option. You 252can find out all the options available by running configure with just 253the <code>--help</code> option.</p> 254 255<p>By default, the configure script sets things up so that the library 256gets installed in <code>/usr/local/lib</code> and the associated 257header file in <code>/usr/local/include</code>. But if you were to 258give the option, <code>--prefix=/home/me/mystuff</code>, then the 259library and header would get installed in 260<code>/home/me/mystuff/lib</code> and 261<code>/home/me/mystuff/include</code> respectively.</p> 262 263<hr /> 264<h2><a name="using">Using Expat</a></h2> 265 266<h3>Compiling and Linking Against Expat</h3> 267 268<p>Unless you installed Expat in a location not expected by your 269compiler and linker, all you have to do to use Expat in your programs 270is to include the Expat header (<code>#include <expat.h></code>) 271in your files that make calls to it and to tell the linker that it 272needs to link against the Expat library. On Unix systems, this would 273usually be done with the <code>-lexpat</code> argument. Otherwise, 274you'll need to tell the compiler where to look for the Expat header 275and the linker where to find the Expat library. You may also need to 276take steps to tell the operating system where to find this libary at 277run time.</p> 278 279<p>On a Unix-based system, here's what a Makefile might look like when 280Expat is installed in a standard location:</p> 281 282<pre class="eg"> 283CC=cc 284LDFLAGS= 285LIBS= -lexpat 286xmlapp: xmlapp.o 287 $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 288</pre> 289 290<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then 291the Makefile would look like this:</p> 292 293<pre class="eg"> 294CC=cc 295CFLAGS= -I/home/me/mystuff/include 296LDFLAGS= 297LIBS= -L/home/me/mystuff/lib -lexpat 298xmlapp: xmlapp.o 299 $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS) 300</pre> 301 302<p>You'd also have to set the environment variable 303<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or 304to <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if 305LD_LIBRARY_PATH already has some directories in it) in order to run 306your application.</p> 307 308<h3>Expat Basics</h3> 309 310<p>As we saw in the example in the overview, the first step in parsing 311an XML document with Expat is to create a parser object. There are <a 312href="#creation">three functions</a> in the Expat API for creating a 313parser object. However, only two of these (<code><a href= 314"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href= 315"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for 316constructing a parser for a top-level document. The object returned 317by these functions is an opaque pointer (i.e. "expat.h" declares it as 318void *) to data with further internal structure. In order to free the 319memory associated with this object you must call <code><a href= 320"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have 321provided any <a href="userdata">user data</a> that gets stored in the 322parser, then your application is responsible for freeing it prior to 323calling <code>XML_ParserFree</code>.</p> 324 325<p>The objects returned by the parser creation functions are good for 326parsing only one XML document or external parsed entity. If your 327application needs to parse many XML documents, then it needs to create 328a parser object for each one. The best way to deal with this is to 329create a higher level object that contains all the default 330initialization you want for your parser objects.</p> 331 332<p>Walking through a document hierarchy with a stream oriented parser 333will require a good stack mechanism in order to keep track of current 334context. For instance, to answer the simple question, "What element 335does this text belong to?" requires a stack, since the parser may have 336descended into other elements that are children of the current one and 337has encountered this text on the way out.</p> 338 339<p>The things you're likely to want to keep on a stack are the 340currently opened element and it's attributes. You push this 341information onto the stack in the start handler and you pop it off in 342the end handler.</p> 343 344<p>For some tasks, it is sufficient to just keep information on what 345the depth of the stack is (or would be if you had one.) The outline 346program shown above presents one example. Another such task would be 347skipping over a complete element. When you see the start tag for the 348element you want to skip, you set a skip flag and record the depth at 349which the element started. When the end tag handler encounters the 350same depth, the skipped element has ended and the flag may be 351cleared. If you follow the convention that the root element starts at 3521, then you can use the same variable for skip flag and skip 353depth.</p> 354 355<pre class="eg"> 356void 357init_info(Parseinfo *info) { 358 info->skip = 0; 359 info->depth = 1; 360 /* Other initializations here */ 361} /* End of init_info */ 362 363void 364rawstart(void *data, const char *el, const char **attr) { 365 Parseinfo *inf = (Parseinfo *) data; 366 367 if (! inf->skip) { 368 if (should_skip(inf, el, attr)) { 369 inf->skip = inf->depth; 370 } 371 else 372 start(inf, el, attr); /* This does rest of start handling */ 373 } 374 375 inf->depth++; 376} /* End of rawstart */ 377 378void 379rawend(void *data, const char *el) { 380 Parseinfo *inf = (Parseinfo *) data; 381 382 inf->depth--; 383 384 if (! inf->skip) 385 end(inf, el); /* This does rest of end handling */ 386 387 if (inf->skip == inf->depth) 388 inf->skip = 0; 389} /* End rawend */ 390</pre> 391 392<p>Notice in the above example the difference in how depth is 393manipulated in the start and end handlers. The end tag handler should 394be the mirror image of the start tag handler. This is necessary to 395properly model containment. Since, in the start tag handler, we 396incremented depth <em>after</em> the main body of start tag code, then 397in the end handler, we need to manipulate it <em>before</em> the main 398body. If we'd decided to increment it first thing in the start 399handler, then we'd have had to decrement it last thing in the end 400handler.</p> 401 402<h3 id="userdata">Communicating between handlers</h3> 403 404<p>In order to be able to pass information between different handlers 405without using globals, you'll need to define a data structure to hold 406the shared variables. You can then tell Expat (with the <code><a href= 407"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a 408pointer to this structure to the handlers. This is typically the first 409argument received by most handlers.</p> 410 411<h3>XML Version</h3> 412 413<p>Expat is an XML 1.0 parser, and as such never complains based on 414the value of the <code>version</code> pseudo-attribute in the XML 415declaration, if present.</p> 416 417<p>If an application needs to check the version number (to support 418alternate processing), it should use the <code><a href= 419"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to 420set a handler that uses the information in the XML declaration to 421determine what to do. This example shows how to check that only a 422version number of <code>"1.0"</code> is accepted:</p> 423 424<pre class="eg"> 425static int wrong_version; 426static XML_Parser parser; 427 428static void 429xmldecl_handler(void *userData, 430 const XML_Char *version, 431 const XML_Char *encoding, 432 int standalone) 433{ 434 static const XML_Char Version_1_0[] = {'1', '.', '0', 0}; 435 436 int i; 437 438 for (i = 0; i < (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) { 439 if (version[i] != Version_1_0[i]) { 440 wrong_version = 1; 441 /* also clear all other handlers: */ 442 XML_SetCharacterDataHandler(parser, NULL); 443 ... 444 return; 445 } 446 } 447 ... 448} 449</pre> 450 451<h3>Namespace Processing</h3> 452 453<p>When the parser is created using the <code><a href= 454"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat 455performs namespace processing. Under namespace processing, Expat 456consumes <code>xmlns</code> and <code>xmlns:...</code> attributes, 457which declare namespaces for the scope of the element in which they 458occur. This means that your start handler will not see these 459attributes. Your application can still be informed of these 460declarations by setting namespace declaration handlers with <a href= 461"#XML_SetNamespaceDeclHandler" 462><code>XML_SetNamespaceDeclHandler</code></a>.</p> 463 464<p>Element type and attribute names that belong to a given namespace 465are passed to the appropriate handler in expanded form. By default 466this expanded form is a concatenation of the namespace URI, the 467separator character (which is the 2nd argument to <code><a href= 468"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local 469name (i.e. the part after the colon). Names with undeclared prefixes 470are passed through to the handlers unchanged, with the prefix and 471colon still attached. Unprefixed attribute names are never expanded, 472and unprefixed element names are only expanded when they are in the 473scope of a default namespace.</p> 474 475<p>However if <code><a href= "XML_SetReturnNSTriplet" 476>XML_SetReturnNSTriplet</a></code> has been called with a non-zero 477<code>do_nst</code> parameter, then the expanded form for names with 478an explicit prefix is a concatenation of: URI, separator, local name, 479separator, prefix.</p> 480 481<p>You can set handlers for the start of a namespace declaration and 482for the end of a scope of a declaration with the <code><a href= 483"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code> 484function. The StartNamespaceDeclHandler is called prior to the start 485tag handler and the EndNamespaceDeclHandler is called before the 486corresponding end tag that ends the namespace's scope. The namespace 487start handler gets passed the prefix and URI for the namespace. For a 488default namespace declaration (xmlns='...'), the prefix will be null. 489The URI will be null for the case where the default namespace is being 490unset. The namespace end handler just gets the prefix for the closing 491scope.</p> 492 493<p>These handlers are called for each declaration. So if, for 494instance, a start tag had three namespace declarations, then the 495StartNamespaceDeclHandler would be called three times before the start 496tag handler is called, once for each declaration.</p> 497 498<h3>Character Encodings</h3> 499 500<p>While XML is based on Unicode, and every XML processor is required 501to recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode), 502other encodings may be declared in XML documents or entities. For the 503main document, an XML declaration may contain an encoding 504declaration:</p> 505<pre> 506<?xml version="1.0" encoding="ISO-8859-2"?> 507</pre> 508 509<p>External parsed entities may begin with a text declaration, which 510looks like an XML declaration with just an encoding declaration:</p> 511<pre> 512<?xml encoding="Big5"?> 513</pre> 514 515<p>With Expat, you may also specify an encoding at the time of 516creating a parser. This is useful when the encoding information may 517come from a source outside the document itself (like a higher level 518protocol.)</p> 519 520<p><a name="builtin_encodings"></a>There are four built-in encodings 521in Expat:</p> 522<ul> 523<li>UTF-8</li> 524<li>UTF-16</li> 525<li>ISO-8859-1</li> 526<li>US-ASCII</li> 527</ul> 528 529<p>Anything else discovered in an encoding declaration or in the 530protocol encoding specified in the parser constructor, triggers a call 531to the <code>UnknownEncodingHandler</code>. This handler gets passed 532the encoding name and a pointer to an <code>XML_Encoding</code> data 533structure. Your handler must fill in this structure and return 534<code>XML_STATUS_OK</code> if it knows how to deal with the 535encoding. Otherwise the handler should return 536<code>XML_STATUS_ERROR</code>. The handler also gets passed a pointer 537to an optional application data structure that you may indicate when 538you set the handler.</p> 539 540<p>Expat places restrictions on character encodings that it can 541support by filling in the <code>XML_Encoding</code> structure. 542include file:</p> 543<ol> 544<li>Every ASCII character that can appear in a well-formed XML document 545must be represented by a single byte, and that byte must correspond to 546it's ASCII encoding (except for the characters $@\^'{}~)</li> 547<li>Characters must be encoded in 4 bytes or less.</li> 548<li>All characters encoded must have Unicode scalar values less than or 549equal to 65535 (0xFFFF)<em>This does not apply to the built-in support 550for UTF-16 and UTF-8</em></li> 551<li>No character may be encoded by more that one distinct sequence of 552bytes</li> 553</ol> 554 555<p><code>XML_Encoding</code> contains an array of integers that 556correspond to the 1st byte of an encoding sequence. If the value in 557the array for a byte is zero or positive, then the byte is a single 558byte encoding that encodes the Unicode scalar value contained in the 559array. A -1 in this array indicates a malformed byte. If the value is 560-2, -3, or -4, then the byte is the beginning of a 2, 3, or 4 byte 561sequence respectively. Multi-byte sequences are sent to the convert 562function pointed at in the <code>XML_Encoding</code> structure. This 563function should return the Unicode scalar value for the sequence or -1 564if the sequence is malformed.</p> 565 566<p>One pitfall that novice Expat users are likely to fall into is that 567although Expat may accept input in various encodings, the strings that 568it passes to the handlers are always encoded in UTF-8 or UTF-16 569(depending on how Expat was compiled). Your application is responsible 570for any translation of these strings into other encodings.</p> 571 572<h3>Handling External Entity References</h3> 573 574<p>Expat does not read or parse external entities directly. Note that 575any external DTD is a special case of an external entity. If you've 576set no <code>ExternalEntityRefHandler</code>, then external entity 577references are silently ignored. Otherwise, it calls your handler with 578the information needed to read and parse the external entity.</p> 579 580<p>Your handler isn't actually responsible for parsing the entity, but 581it is responsible for creating a subsidiary parser with <code><a href= 582"#XML_ExternalEntityParserCreate" 583>XML_ExternalEntityParserCreate</a></code> that will do the job. This 584returns an instance of <code>XML_Parser</code> that has handlers and 585other data structures initialized from the parent parser. You may then 586use <code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a 587href= "#XML_ParseBuffer">XML_ParseBuffer</a></code> calls against this 588parser. Since external entities my refer to other external entities, 589your handler should be prepared to be called recursively.</p> 590 591<h3>Parsing DTDs</h3> 592 593<p>In order to parse parameter entities, before starting the parse, 594you must call <code><a href= "#XML_SetParamEntityParsing" 595>XML_SetParamEntityParsing</a></code> with one of the following 596arguments:</p> 597<dl> 598<dt><code>XML_PARAM_ENTITY_PARSING_NEVER</code></dt> 599<dd>Don't parse parameter entities or the external subset</dd> 600<dt><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></dt> 601<dd>Parse parameter entites and the external subset unless 602<code>standalone</code> was set to "yes" in the XML declaration.</dd> 603<dt><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></dt> 604<dd>Always parse parameter entities and the external subset</dd> 605</dl> 606 607<p>In order to read an external DTD, you also have to set an external 608entity reference handler as described above.</p> 609 610<hr /> 611<!-- ================================================================ --> 612 613<h2><a name="reference">Expat Reference</a></h2> 614 615<h3><a name="creation">Parser Creation</a></h3> 616 617<pre class="fcndec" id="XML_ParserCreate"> 618XML_Parser 619XML_ParserCreate(const XML_Char *encoding); 620</pre> 621<div class="fcndef"> 622Construct a new parser. If encoding is non-null, it specifies a 623character encoding to use for the document. This overrides the document 624encoding declaration. There are four built-in encodings: 625<ul> 626<li>US-ASCII</li> 627<li>UTF-8</li> 628<li>UTF-16</li> 629<li>ISO-8859-1</li> 630</ul> 631Any other value will invoke a call to the UnknownEncodingHandler. 632</div> 633 634<pre class="fcndec" id="XML_ParserCreateNS"> 635XML_Parser 636XML_ParserCreateNS(const XML_Char *encoding, 637 XML_Char sep); 638</pre> 639<div class="fcndef"> 640Constructs a new parser that has namespace processing in effect. Namespace 641expanded element names and attribute names are returned as a concatenation 642of the namespace URI, <em>sep</em>, and the local part of the name. This 643means that you should pick a character for <em>sep</em> that can't be 644part of a legal URI.</div> 645 646<pre class="fcndec" id="XML_ParserCreate_MM"> 647XML_Parser 648XML_ParserCreate_MM(const XML_Char *encoding, 649 const XML_Memory_Handling_Suite *ms, 650 const XML_Char *sep); 651</pre> 652<pre class="signature"> 653typedef struct { 654 void *(*malloc_fcn)(size_t size); 655 void *(*realloc_fcn)(void *ptr, size_t size); 656 void (*free_fcn)(void *ptr); 657} XML_Memory_Handling_Suite; 658</pre> 659<div class="fcndef"> 660<p>Construct a new parser using the suite of memory handling functions 661specified in <code>ms</code>. If <code>ms</code> is NULL, then use the 662standard set of memory management functions. If <code>sep</code> is 663non NULL, then namespace processing is enabled in the created parser 664and the character pointed at by sep is used as the separator between 665the namespace URI and the local part of the name.</p> 666</div> 667 668<pre class="fcndec" id="XML_ExternalEntityParserCreate"> 669XML_Parser 670XML_ExternalEntityParserCreate(XML_Parser p, 671 const XML_Char *context, 672 const XML_Char *encoding); 673</pre> 674<div class="fcndef"> 675Construct a new <code>XML_Parser</code> object for parsing an external 676general entity. Context is the context argument passed in a call to a 677ExternalEntityRefHandler. Other state information such as handlers, 678user data, namespace processing is inherited from the parser passed as 679the 1st argument. So you shouldn't need to call any of the behavior 680changing functions on this parser (unless you want it to act 681differently than the parent parser). 682</div> 683 684<pre class="fcndec" id="XML_ParserFree"> 685void 686XML_ParserFree(XML_Parser p); 687</pre> 688<div class="fcndef"> 689Free memory used by the parser. Your application is responsible for 690freeing any memory associated with <a href="#userdata">user data</a>. 691</div> 692 693<pre class="fcndec" id="XML_ParserReset"> 694XML_Bool 695XML_ParserReset(XML_Parser p); 696</pre> 697<div class="fcndef"> 698Clean up the memory structures maintained by the parser so that it may 699be used again. After this has been called, <code>parser</code> is 700ready to start parsing a new document. This function may not be used 701on a parser created using <code><a href= 702"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a 703></code>; it will return <code>XML_FALSE</code> in that case. Returns 704<code>XML_TRUE</code> on success. Your application is responsible for 705dealing with any memory associated with <a href="#userdata">user data</a>. 706</div> 707 708<h3><a name="parsing">Parsing</a></h3> 709 710<p>To state the obvious: the three parsing functions <code><a href= 711"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer" 712>XML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer" 713>>XML_GetBuffer</a></code> must not be 714called from within a handler unless they operate on a separate parser 715instance, that is, one that did not call the handler. For example, it 716is OK to call the parsing functions from within an 717<code>XML_ExternalEntityRefHandler</code>, if they apply to the parser 718created by <code><a href= "#XML_ExternalEntityParserCreate" 719>XML_ExternalEntityParserCreate</a></code>.</p> 720 721<pre class="fcndec" id="XML_Parse"> 722XML_Status 723XML_Parse(XML_Parser p, 724 const char *s, 725 int len, 726 int isFinal); 727</pre> 728<pre class="signature"> 729enum XML_Status { 730 XML_STATUS_ERROR = 0, 731 XML_STATUS_OK = 1 732}; 733</pre> 734<div class="fcndef"> 735Parse some more of the document. The string <code>s</code> is a buffer 736containing part (or perhaps all) of the document. The number of bytes of s 737that are part of the document is indicated by <code>len</code>. This means 738that <code>s</code> doesn't have to be null terminated. It also means that 739if <code>len</code> is larger than the number of bytes in the block of 740memory that <code>s</code> points at, then a memory fault is likely. The 741<code>isFinal</code> parameter informs the parser that this is the last 742piece of the document. Frequently, the last piece is empty (i.e. 743<code>len</code> is zero.) 744If a parse error occurred, it returns <code>XML_STATUS_ERROR</code>. 745Otherwise it returns <code>XML_STATUS_OK</code> value. 746</div> 747 748<pre class="fcndec" id="XML_ParseBuffer"> 749XML_Status 750XML_ParseBuffer(XML_Parser p, 751 int len, 752 int isFinal); 753</pre> 754<div class="fcndef"> 755This is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>, 756except in this case Expat provides the buffer. By obtaining the 757buffer from Expat with the <code><a href= "#XML_GetBuffer" 758>XML_GetBuffer</a></code> function, the application can avoid double 759copying of the input. 760</div> 761 762<pre class="fcndec" id="XML_GetBuffer"> 763void * 764XML_GetBuffer(XML_Parser p, 765 int len); 766</pre> 767<div class="fcndef"> 768Obtain a buffer of size <code>len</code> to read a piece of the document 769into. A NULL value is returned if Expat can't allocate enough memory for 770this buffer. This has to be called prior to every call to 771<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A 772typical use would look like this: 773 774<pre class="eg"> 775for (;;) { 776 int bytes_read; 777 void *buff = XML_GetBuffer(p, BUFF_SIZE); 778 if (buff == NULL) { 779 /* handle error */ 780 } 781 782 bytes_read = read(docfd, buff, BUFF_SIZE); 783 if (bytes_read < 0) { 784 /* handle error */ 785 } 786 787 if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) { 788 /* handle parse error */ 789 } 790 791 if (bytes_read == 0) 792 break; 793} 794</pre> 795</div> 796 797<h3><a name="setting">Handler Setting</a></h3> 798 799<p>Although handlers are typically set prior to parsing and left alone, an 800application may choose to set or change the handler for a parsing event 801while the parse is in progress. For instance, your application may choose 802to ignore all text not descended from a <code>para</code> element. One 803way it could do this is to set the character handler when a para start tag 804is seen, and unset it for the corresponding end tag.</p> 805 806<p>A handler may be <em>unset</em> by providing a NULL pointer to the 807appropriate handler setter. None of the handler setting functions have 808a return value.</p> 809 810<p>Your handlers will be receiving strings in arrays of type 811<code>XML_Char</code>. This type is defined in expat.h as <code>char 812*</code> and contains bytes encoding UTF-8. Note that you'll receive 813them in this form independent of the original encoding of the 814document.</p> 815 816<div class="handler"> 817<pre class="setter" id="XML_SetStartElementHandler"> 818XML_SetStartElementHandler(XML_Parser p, 819 XML_StartElementHandler start); 820</pre> 821<pre class="signature"> 822typedef void 823(*XML_StartElementHandler)(void *userData, 824 const XML_Char *name, 825 const XML_Char **atts); 826</pre> 827<p>Set handler for start (and empty) tags. Attributes are passed to the start 828handler as a pointer to a vector of char pointers. Each attribute seen in 829a start (or empty) tag occupies 2 consecutive places in this vector: the 830attribute name followed by the attribute value. These pairs are terminated 831by a null pointer.</p> 832<p>Note that an empty tag generates a call to both start and end handlers 833(in that order).</p> 834</div> 835 836<div class="handler"> 837<pre class="setter" id="XML_SetEndElementHandler"> 838XML_SetEndElementHandler(XML_Parser p, 839 XML_EndElementHandler); 840</pre> 841<pre class="signature"> 842typedef void 843(*XML_EndElementHandler)(void *userData, 844 const XML_Char *name); 845</pre> 846<p>Set handler for end (and empty) tags. As noted above, an empty tag 847generates a call to both start and end handlers.</p> 848</div> 849 850<div class="handler"> 851<pre class="setter" id="XML_SetElementHandler"> 852XML_SetElementHandler(XML_Parser p, 853 XML_StartElementHandler start, 854 XML_EndElementHandler end); 855</pre> 856<p>Set handlers for start and end tags with one call.</p> 857</div> 858 859<div class="handler"> 860<pre class="setter" id="XML_SetCharacterDataHandler"> 861XML_SetCharacterDataHandler(XML_Parser p, 862 XML_CharacterDataHandler charhndl) 863</pre> 864<pre class="signature"> 865typedef void 866(*XML_CharacterDataHandler)(void *userData, 867 const XML_Char *s, 868 int len); 869</pre> 870<p>Set a text handler. The string your handler receives 871is <em>NOT nul-terminated</em>. You have to use the length argument 872to deal with the end of the string. A single block of contiguous text 873free of markup may still result in a sequence of calls to this handler. 874In other words, if you're searching for a pattern in the text, it may 875be split across calls to this handler.</p> 876</div> 877 878<div class="handler"> 879<pre class="setter" id="XML_SetProcessingInstructionHandler"> 880XML_SetProcessingInstructionHandler(XML_Parser p, 881 XML_ProcessingInstructionHandler proc) 882</pre> 883<pre class="signature"> 884typedef void 885(*XML_ProcessingInstructionHandler)(void *userData, 886 const XML_Char *target, 887 const XML_Char *data); 888 889</pre> 890<p>Set a handler for processing instructions. The target is the first word 891in the processing instruction. The data is the rest of the characters in 892it after skipping all whitespace after the initial word.</p> 893</div> 894 895<div class="handler"> 896<pre class="setter" id="XML_SetCommentHandler"> 897XML_SetCommentHandler(XML_Parser p, 898 XML_CommentHandler cmnt) 899</pre> 900<pre class="signature"> 901typedef void 902(*XML_CommentHandler)(void *userData, 903 const XML_Char *data); 904</pre> 905<p>Set a handler for comments. The data is all text inside the comment 906delimiters.</p> 907</div> 908 909<div class="handler"> 910<pre class="setter" id="XML_SetStartCdataSectionHandler"> 911XML_SetStartCdataSectionHandler(XML_Parser p, 912 XML_StartCdataSectionHandler start); 913</pre> 914<pre class="signature"> 915typedef void 916(*XML_StartCdataSectionHandler)(void *userData); 917</pre> 918<p>Set a handler that gets called at the beginning of a CDATA section.</p> 919</div> 920 921<div class="handler"> 922<pre class="setter" id="XML_SetEndCdataSectionHandler"> 923XML_SetEndCdataSectionHandler(XML_Parser p, 924 XML_EndCdataSectionHandler end); 925</pre> 926<pre class="signature"> 927typedef void 928(*XML_EndCdataSectionHandler)(void *userData); 929</pre> 930<p>Set a handler that gets called at the end of a CDATA section.</p> 931</div> 932 933<div class="handler"> 934<pre class="setter" id="XML_SetCdataSectionHandler"> 935XML_SetCdataSectionHandler(XML_Parser p, 936 XML_StartCdataSectionHandler start, 937 XML_EndCdataSectionHandler end) 938</pre> 939<p>Sets both CDATA section handlers with one call.</p> 940</div> 941 942<div class="handler"> 943<pre class="setter" id="XML_SetDefaultHandler"> 944XML_SetDefaultHandler(XML_Parser p, 945 XML_DefaultHandler hndl) 946</pre> 947<pre class="signature"> 948typedef void 949(*XML_DefaultHandler)(void *userData, 950 const XML_Char *s, 951 int len); 952</pre> 953 954<p>Sets a handler for any characters in the document which wouldn't 955otherwise be handled. This includes both data for which no handlers 956can be set (like some kinds of DTD declarations) and data which could 957be reported but which currently has no handler set. The characters 958are passed exactly as they were present in the XML document except 959that they will be encoded in UTF-8 or UTF-16. Line boundaries are not 960normalized. Note that a byte order mark character is not passed to the 961default handler. There are no guarantees about how characters are 962divided between calls to the default handler: for example, a comment 963might be split between multiple calls. Setting the handler with 964this call has the side effect of turning off expansion of references 965to internally defined general entities. Instead these references are 966passed to the default handler.</p> 967 968<p>See also <code><a 969href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 970</div> 971 972<div class="handler"> 973<pre class="setter" id="XML_SetDefaultHandlerExpand"> 974XML_SetDefaultHandlerExpand(XML_Parser p, 975 XML_DefaultHandler hndl) 976</pre> 977<pre class="signature"> 978typedef void 979(*XML_DefaultHandler)(void *userData, 980 const XML_Char *s, 981 int len); 982</pre> 983<p>This sets a default handler, but doesn't inhibit the expansion of 984internal entity references. The entity reference will not be passed 985to the default handler.</p> 986 987<p>See also <code><a 988href="#XML_DefaultCurrent">XML_DefaultCurrent</a></code>.</p> 989</div> 990 991<div class="handler"> 992<pre class="setter" id="XML_SetExternalEntityRefHandler"> 993XML_SetExternalEntityRefHandler(XML_Parser p, 994 XML_ExternalEntityRefHandler hndl) 995</pre> 996<pre class="signature"> 997typedef int 998(*XML_ExternalEntityRefHandler)(XML_Parser p, 999 const XML_Char *context, 1000 const XML_Char *base, 1001 const XML_Char *systemId, 1002 const XML_Char *publicId); 1003</pre> 1004<p>Set an external entity reference handler. This handler is also 1005called for processing an external DTD subset if parameter entity parsing 1006is in effect. (See <a href="#XML_SetParamEntityParsing"> 1007<code>XML_SetParamEntityParsing</code></a>.)</p> 1008 1009<p>The <code>context</code> parameter specifies the parsing context in 1010the format expected by the <code>context</code> argument to <code><a 1011href="#XML_ExternalEntityParserCreate" 1012>XML_ExternalEntityParserCreate</a></code>. <code>code</code> is 1013valid only until the handler returns, so if the referenced entity is 1014to be parsed later, it must be copied. <code>context</code> is NULL 1015only when the entity is a parameter entity, which is how one can 1016differentiate between general and parameter entities.</p> 1017 1018<p>The <code>base</code> parameter is the base to use for relative 1019system identifiers. It is set by <code><a 1020href="#XML_SetBase">XML_SetBase</a></code> and may be NULL. The 1021<code>publicId</code> parameter is the public id given in the entity 1022declaration and may be NULL. <code>systemId</code> is the system 1023identifier specified in the entity declaration and is never NULL.</p> 1024 1025<p>There are a couple of ways in which this handler differs from 1026others. First, this handler returns a status indicator (an 1027integer). <code>XML_STATUS_OK</code> should be returned for successful 1028handling of the external entity reference. Returning 1029<code>XML_STATUS_ERROR</code> indicates failure, and causes the 1030calling parser to return an 1031<code>XML_ERROR_EXTERNAL_ENTITY_HANDLING</code> error.</p> 1032 1033<p>Second, instead of having the user data as its first argument, it 1034receives the parser that encountered the entity reference. This, along 1035with the context parameter, may be used as arguments to a call to 1036<code><a href= "#XML_ExternalEntityParserCreate" 1037>XML_ExternalEntityParserCreate</a></code>. Using the returned 1038parser, the body of the external entity can be recursively parsed.</p> 1039 1040<p>Since this handler may be called recursively, it should not be saving 1041information into global or static variables.</p> 1042</div> 1043 1044<pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg"> 1045XML_SetExternalEntityRefHandlerArg(XML_Parser p, 1046 void *arg) 1047</pre> 1048<div class="fcndef"> 1049<p>Set the argument passed to the ExternalEntityRefHandler. If 1050<code>arg</code> is not NULL, it is the new value passed to the 1051handler set using <code><a href="#XML_SetExternalEntityRefHandler" 1052>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is 1053NULL, the argument passed to the handler function will be the parser 1054object itself.</p> 1055 1056<p><strong>Note:</strong> 1057The type of <code>arg</code> and the type of the first argument to the 1058ExternalEntityRefHandler do not match. This function takes a 1059<code>void *</code> to be passed to the handler, while the handler 1060accepts an <code>XML_Parser</code>. This is a historical accident, 1061but will not be corrected before Expat 2.0 (at the earliest) to avoid 1062causing compiler warnings for code that's known to work with this 1063API. It is the responsibility of the application code to know the 1064actual type of the argument passed to the handler and to manage it 1065properly.</p> 1066</div> 1067 1068<div class="handler"> 1069<pre class="setter" id="XML_SetSkippedEntityHandler"> 1070XML_SetSkippedEntityHandler(XML_Parser p, 1071 XML_SkippedEntityHandler handler) 1072</pre> 1073<pre class="signature"> 1074typedef void 1075(*XML_SkippedEntityHandler)(void *userData, 1076 const XML_Char *entityName, 1077 int is_parameter_entity); 1078</pre> 1079<p>Set a skipped entity handler. This is called in two situations:</p> 1080<ol> 1081 <li>An entity reference is encountered for which no declaration 1082 has been read <em>and</em> this is not an error.</li> 1083 <li>An internal entity reference is read, but not expanded, because 1084 <a href="#XML_SetDefaultHandler"><code>XML_SetDefaultHandler</code></a> 1085 has been called.</li> 1086</ol> 1087<p>The <code>is_parameter_entity</code> argument will be non-zero for 1088a parameter entity and zero for a general entity.</p> <p>Note: skipped 1089parameter entities in declarations and skipped general entities in 1090attribute values cannot be reported, because the event would be out of 1091sync with the reporting of the declarations or attribute values</p> 1092</div> 1093 1094<div class="handler"> 1095<pre class="setter" id="XML_SetUnknownEncodingHandler"> 1096XML_SetUnknownEncodingHandler(XML_Parser p, 1097 XML_UnknownEncodingHandler enchandler, 1098 void *encodingHandlerData) 1099</pre> 1100<pre class="signature"> 1101typedef int 1102(*XML_UnknownEncodingHandler)(void *encodingHandlerData, 1103 const XML_Char *name, 1104 XML_Encoding *info); 1105 1106typedef struct { 1107 int map[256]; 1108 void *data; 1109 int (*convert)(void *data, const char *s); 1110 void (*release)(void *data); 1111} XML_Encoding; 1112</pre> 1113<p>Set a handler to deal with encodings other than the <a 1114href="#builtin_encodings">built in set</a>. This should be done before 1115<code><a href= "#XML_Parse" >XML_Parse</a></code> or <code><a href= 1116"#XML_ParseBuffer" >XML_ParseBuffer</a></code> have been called on the 1117given parser.</p> <p>If the handler knows how to deal with an encoding 1118with the given name, it should fill in the <code>info</code> data 1119structure and return <code>XML_STATUS_ERROR</code>. Otherwise it 1120should return <code>XML_STATUS_OK</code>. The handler will be called 1121at most once per parsed (external) entity. The optional application 1122data pointer <code>encodingHandlerData</code> will be passed back to 1123the handler.</p> 1124 1125<p>The map array contains information for every possible possible leading 1126byte in a byte sequence. If the corresponding value is >= 0, then it's 1127a single byte sequence and the byte encodes that Unicode value. If the 1128value is -1, then that byte is invalid as the initial byte in a sequence. 1129If the value is -n, where n is an integer > 1, then n is the number of 1130bytes in the sequence and the actual conversion is accomplished by a 1131call to the function pointed at by convert. This function may return -1 1132if the sequence itself is invalid. The convert pointer may be null if 1133there are only single byte codes. The data parameter passed to the convert 1134function is the data pointer from <code>XML_Encoding</code>. The 1135string s is <em>NOT</em> nul-terminated and points at the sequence of 1136bytes to be converted.</p> 1137 1138<p>The function pointed at by <code>release</code> is called by the 1139parser when it is finished with the encoding. It may be NULL.</p> 1140</div> 1141 1142<div class="handler"> 1143<pre class="setter" id="XML_SetStartNamespaceDeclHandler"> 1144XML_SetStartNamespaceDeclHandler(XML_Parser p, 1145 XML_StartNamespaceDeclHandler start); 1146</pre> 1147<pre class="signature"> 1148typedef void 1149(*XML_StartNamespaceDeclHandler)(void *userData, 1150 const XML_Char *prefix, 1151 const XML_Char *uri); 1152</pre> 1153<p>Set a handler to be called when a namespace is declared. Namespace 1154declarations occur inside start tags. But the namespace declaration start 1155handler is called before the start tag handler for each namespace declared 1156in that start tag.</p> 1157 1158<p><strong>Note:</strong> 1159Due to limitations of the implementation, the 1160StartNamespaceDeclHandler is not called unless the StartElementHandler 1161is also set. The specific value of the StartElementHandler is allowed 1162to change freely, so long as it is not NULL.</p> 1163</div> 1164 1165<div class="handler"> 1166<pre class="setter" id="XML_SetEndNamespaceDeclHandler"> 1167XML_SetEndNamespaceDeclHandler(XML_Parser p, 1168 XML_EndNamespaceDeclHandler end); 1169</pre> 1170<pre class="signature"> 1171typedef void 1172(*XML_EndNamespaceDeclHandler)(void *userData, 1173 const XML_Char *prefix); 1174</pre> 1175<p>Set a handler to be called when leaving the scope of a namespace 1176declaration. This will be called, for each namespace declaration, 1177after the handler for the end tag of the element in which the 1178namespace was declared.</p> 1179 1180<p><strong>Note:</strong> 1181Due to limitations of the implementation, the EndNamespaceDeclHandler 1182is not called unless the StartElementHandler is also set. The 1183specific value of the StartElementHandler is allowed to change freely, 1184so long as it is not NULL.</p> 1185</div> 1186 1187<div class="handler"> 1188<pre class="setter" id="XML_SetNamespaceDeclHandler"> 1189XML_SetNamespaceDeclHandler(XML_Parser p, 1190 XML_StartNamespaceDeclHandler start, 1191 XML_EndNamespaceDeclHandler end) 1192</pre> 1193<p>Sets both namespace declaration handlers with a single call.</p> 1194 1195<p><strong>Note:</strong> 1196Due to limitations of the implementation, the 1197StartNamespaceDeclHandler and EndNamespaceDeclHandler are not called 1198unless the StartElementHandler is also set. The specific value of the 1199StartElementHandler is allowed to change freely, so long as it is not 1200NULL.</p> 1201</div> 1202 1203<div class="handler"> 1204<pre class="setter" id="XML_SetXmlDeclHandler"> 1205XML_SetXmlDeclHandler(XML_Parser p, 1206 XML_XmlDeclHandler xmldecl); 1207</pre> 1208<pre class="signature"> 1209typedef void 1210(*XML_XmlDeclHandler) (void *userData, 1211 const XML_Char *version, 1212 const XML_Char *encoding, 1213 int standalone); 1214</pre> 1215<p>Sets a handler that is called for XML declarations and also for 1216text declarations discovered in external entities. The way to 1217distinguish is that the <code>version</code> parameter will be NULL 1218for text declarations. The <code>encoding</code> parameter may be NULL 1219for an XML declaration. The <code>standalone</code> argument will 1220contain -1, 0, or 1 indicating respectively that there was no 1221standalone parameter in the declaration, that it was given as no, or 1222that it was given as yes.</p> 1223</div> 1224 1225<div class="handler"> 1226<pre class="setter" id="XML_SetStartDoctypeDeclHandler"> 1227XML_SetStartDoctypeDeclHandler(XML_Parser p, 1228 XML_StartDoctypeDeclHandler start); 1229</pre> 1230<pre class="signature"> 1231typedef void 1232(*XML_StartDoctypeDeclHandler)(void *userData, 1233 const XML_Char *doctypeName, 1234 const XML_Char *sysid, 1235 const XML_Char *pubid, 1236 int has_internal_subset); 1237</pre> 1238<p>Set a handler that is called at the start of a DOCTYPE declaration, 1239before any external or internal subset is parsed. Both <code>sysid</code> 1240and <code>pubid</code> may be NULL. The <code>has_internal_subset</code> 1241will be non-zero if the DOCTYPE declaration has an internal subset.</p> 1242</div> 1243 1244<div class="handler"> 1245<pre class="setter" id="XML_SetEndDoctypeDeclHandler"> 1246XML_SetEndDoctypeDeclHandler(XML_Parser p, 1247 XML_EndDoctypeDeclHandler end); 1248</pre> 1249<pre class="signature"> 1250typedef void 1251(*XML_EndDoctypeDeclHandler)(void *userData); 1252</pre> 1253<p>Set a handler that is called at the end of a DOCTYPE declaration, 1254after parsing any external subset.</p> 1255</div> 1256 1257<div class="handler"> 1258<pre class="setter" id="XML_SetDoctypeDeclHandler"> 1259XML_SetDoctypeDeclHandler(XML_Parser p, 1260 XML_StartDoctypeDeclHandler start, 1261 XML_EndDoctypeDeclHandler end); 1262</pre> 1263<p>Set both doctype handlers with one call.</p> 1264</div> 1265 1266<div class="handler"> 1267<pre class="setter" id="XML_SetElementDeclHandler"> 1268XML_SetElementDeclHandler(XML_Parser p, 1269 XML_ElementDeclHandler eldecl); 1270</pre> 1271<pre class="signature"> 1272typedef void 1273(*XML_ElementDeclHandler)(void *userData, 1274 const XML_Char *name, 1275 XML_Content *model); 1276</pre> 1277<pre class="signature"> 1278enum XML_Content_Type { 1279 XML_CTYPE_EMPTY = 1, 1280 XML_CTYPE_ANY, 1281 XML_CTYPE_MIXED, 1282 XML_CTYPE_NAME, 1283 XML_CTYPE_CHOICE, 1284 XML_CTYPE_SEQ 1285}; 1286 1287enum XML_Content_Quant { 1288 XML_CQUANT_NONE, 1289 XML_CQUANT_OPT, 1290 XML_CQUANT_REP, 1291 XML_CQUANT_PLUS 1292}; 1293 1294typedef struct XML_cp XML_Content; 1295 1296struct XML_cp { 1297 enum XML_Content_Type type; 1298 enum XML_Content_Quant quant; 1299 const XML_Char * name; 1300 unsigned int numchildren; 1301 XML_Content * children; 1302}; 1303</pre> 1304<p>Sets a handler for element declarations in a DTD. The handler gets 1305called with the name of the element in the declaration and a pointer 1306to a structure that contains the element model. It is the 1307application's responsibility to free this data structure using 1308<code><a href="#XML_FreeContentModel" 1309>XML_FreeContentModel</a></code>.</p> 1310 1311<p>The <code>model</code> argument is the root of a tree of 1312<code>XML_Content</code> nodes. If <code>type</code> equals 1313<code>XML_CTYPE_EMPTY</code> or <code>XML_CTYPE_ANY</code>, then 1314<code>quant</code> will be <code>XML_CQUANT_NONE</code>, and the other 1315fields will be zero or NULL. If <code>type</code> is 1316<code>XML_CTYPE_MIXED</code>, then <code>quant</code> will be 1317<code>XML_CQUANT_NONE</code> or <code>XML_CQUANT_REP</code> and 1318<code>numchildren</code> will contain the number of elements that are 1319allowed to be mixed in and <code>children</code> points to an array of 1320<code>XML_Content</code> structures that will all have type 1321XML_CTYPE_NAME with no quantification. Only the root node can be type 1322<code>XML_CTYPE_EMPTY</code>, <code>XML_CTYPE_ANY</code>, or 1323<code>XML_CTYPE_MIXED</code>.</p> 1324 1325<p>For type <code>XML_CTYPE_NAME</code>, the <code>name</code> field 1326points to the name and the <code>numchildren</code> and 1327<code>children</code> fields will be zero and NULL. The 1328<code>quant</code> field will indicate any quantifiers placed on the 1329name.</p> 1330 1331<p>Types <code>XML_CTYPE_CHOICE</code> and <code>XML_CTYPE_SEQ</code> 1332indicate a choice or sequence respectively. The 1333<code>numchildren</code> field indicates how many nodes in the choice 1334or sequence and <code>children</code> points to the nodes.</p> 1335</div> 1336 1337<div class="handler"> 1338<pre class="setter" id="XML_SetAttlistDeclHandler"> 1339XML_SetAttlistDeclHandler(XML_Parser p, 1340 XML_AttlistDeclHandler attdecl); 1341</pre> 1342<pre class="signature"> 1343typedef void 1344(*XML_AttlistDeclHandler) (void *userData, 1345 const XML_Char *elname, 1346 const XML_Char *attname, 1347 const XML_Char *att_type, 1348 const XML_Char *dflt, 1349 int isrequired); 1350</pre> 1351<p>Set a handler for attlist declarations in the DTD. This handler is 1352called for <em>each</em> attribute. So a single attlist declaration 1353with multiple attributes declared will generate multiple calls to this 1354handler. The <code>elname</code> parameter returns the name of the 1355element for which the attribute is being declared. The attribute name 1356is in the <code>attname</code> parameter. The attribute type is in the 1357<code>att_type</code> parameter. It is the string representing the 1358type in the declaration with whitespace removed.</p> 1359 1360<p>The <code>dflt</code> parameter holds the default value. It will be 1361NULL in the case of "#IMPLIED" or "#REQUIRED" attributes. You can 1362distinguish these two cases by checking the <code>isrequired</code> 1363parameter, which will be true in the case of "#REQUIRED" attributes. 1364Attributes which are "#FIXED" will have also have a true 1365<code>isrequired</code>, but they will have the non-NULL fixed value 1366in the <code>dflt</code> parameter.</p> 1367</div> 1368 1369<div class="handler"> 1370<pre class="setter" id="XML_SetEntityDeclHandler"> 1371XML_SetEntityDeclHandler(XML_Parser p, 1372 XML_EntityDeclHandler handler); 1373</pre> 1374<pre class="signature"> 1375typedef void 1376(*XML_EntityDeclHandler) (void *userData, 1377 const XML_Char *entityName, 1378 int is_parameter_entity, 1379 const XML_Char *value, 1380 int value_length, 1381 const XML_Char *base, 1382 const XML_Char *systemId, 1383 const XML_Char *publicId, 1384 const XML_Char *notationName); 1385</pre> 1386<p>Sets a handler that will be called for all entity declarations. 1387The <code>is_parameter_entity</code> argument will be non-zero in the 1388case of parameter entities and zero otherwise.</p> 1389 1390<p>For internal entities (<code><!ENTITY foo "bar"></code>), 1391<code>value</code> will be non-NULL and <code>systemId</code>, 1392<code>publicId</code>, and <code>notationName</code> will all be NULL. 1393The value string is <em>not</em> NULL terminated; the length is 1394provided in the <code>value_length</code> parameter. Do not use 1395<code>value_length</code> to test for internal entities, since it is 1396legal to have zero-length values. Instead check for whether or not 1397<code>value</code> is NULL.</p> <p>The <code>notationName</code> 1398argument will have a non-NULL value only for unparsed entity 1399declarations.</p> 1400</div> 1401 1402<div class="handler"> 1403<pre class="setter" id="XML_SetUnparsedEntityDeclHandler"> 1404XML_SetUnparsedEntityDeclHandler(XML_Parser p, 1405 XML_UnparsedEntityDeclHandler h) 1406</pre> 1407<pre class="signature"> 1408typedef void 1409(*XML_UnparsedEntityDeclHandler)(void *userData, 1410 const XML_Char *entityName, 1411 const XML_Char *base, 1412 const XML_Char *systemId, 1413 const XML_Char *publicId, 1414 const XML_Char *notationName); 1415</pre> 1416<p>Set a handler that receives declarations of unparsed entities. These 1417are entity declarations that have a notation (NDATA) field:</p> 1418 1419<div id="eg"><pre> 1420<!ENTITY logo SYSTEM "images/logo.gif" NDATA gif> 1421</pre></div> 1422<p>This handler is obsolete and is provided for backwards 1423compatibility. Use instead <a href= "#XML_SetEntityDeclHandler" 1424>XML_SetEntityDeclHandler</a>.</p> 1425</div> 1426 1427<div class="handler"> 1428<pre class="setter" id="XML_SetNotationDeclHandler"> 1429XML_SetNotationDeclHandler(XML_Parser p, 1430 XML_NotationDeclHandler h) 1431</pre> 1432<pre class="signature"> 1433typedef void 1434(*XML_NotationDeclHandler)(void *userData, 1435 const XML_Char *notationName, 1436 const XML_Char *base, 1437 const XML_Char *systemId, 1438 const XML_Char *publicId); 1439</pre> 1440<p>Set a handler that receives notation declarations.</p> 1441</div> 1442 1443<div class="handler"> 1444<pre class="setter" id="XML_SetNotStandaloneHandler"> 1445XML_SetNotStandaloneHandler(XML_Parser p, 1446 XML_NotStandaloneHandler h) 1447</pre> 1448<pre class="signature"> 1449typedef int 1450(*XML_NotStandaloneHandler)(void *userData); 1451</pre> 1452<p>Set a handler that is called if the document is not "standalone". 1453This happens when there is an external subset or a reference to a 1454parameter entity, but does not have standalone set to "yes" in an XML 1455declaration. If this handler returns <code>XML_STATUS_ERROR</code>, 1456then the parser will throw an <code>XML_ERROR_NOT_STANDALONE</code> 1457error.</p> 1458</div> 1459 1460<h3><a name="position">Parse position and error reporting functions</a></h3> 1461 1462<p>These are the functions you'll want to call when the parse 1463functions return <code>XML_STATUS_ERROR</code> (a parse error has 1464ocurred), although the position reporting functions are useful outside 1465of errors. The position reported is the byte position (in the original 1466document or entity encoding) of the first of the sequence of 1467characters that generated the current event (or the error that caused 1468the parse functions to return <code>XML_STATUS_ERROR</code>.)</p> 1469 1470<p>The position reporting functions are accurate only outside of the 1471DTD. In other words, they usually return bogus information when 1472called from within a DTD declaration handler.</p> 1473 1474<pre class="fcndec" id="XML_GetErrorCode"> 1475enum XML_Error 1476XML_GetErrorCode(XML_Parser p); 1477</pre> 1478<div class="fcndef"> 1479Return what type of error has occurred. 1480</div> 1481 1482<pre class="fcndec" id="XML_ErrorString"> 1483const XML_LChar * 1484XML_ErrorString(int code); 1485</pre> 1486<div class="fcndef"> 1487Return a string describing the error corresponding to code. 1488The code should be one of the enums that can be returned from 1489<code><a href= "#XML_GetErrorCode" >XML_GetErrorCode</a></code>. 1490</div> 1491 1492<pre class="fcndec" id="XML_GetCurrentByteIndex"> 1493long 1494XML_GetCurrentByteIndex(XML_Parser p); 1495</pre> 1496<div class="fcndef"> 1497Return the byte offset of the position. 1498</div> 1499 1500<pre class="fcndec" id="XML_GetCurrentLineNumber"> 1501int 1502XML_GetCurrentLineNumber(XML_Parser p); 1503</pre> 1504<div class="fcndef"> 1505Return the line number of the position. 1506</div> 1507 1508<pre class="fcndec" id="XML_GetCurrentColumnNumber"> 1509int 1510XML_GetCurrentColumnNumber(XML_Parser p); 1511</pre> 1512<div class="fcndef"> 1513Return the offset, from the beginning of the current line, of 1514the position. 1515</div> 1516 1517<pre class="fcndec" id="XML_GetCurrentByteCount"> 1518int 1519XML_GetCurrentByteCount(XML_Parser p); 1520</pre> 1521<div class="fcndef"> 1522Return the number of bytes in the current event. Returns 1523<code>0</code> if the event is inside a reference to an internal 1524entity and for the end-tag event for empty element tags (the later can 1525be used to distinguish empty-element tags from empty elements using 1526separate start and end tags). 1527</div> 1528 1529<pre class="fcndec" id="XML_GetInputContext"> 1530const char * 1531XML_GetInputContext(XML_Parser p, 1532 int *offset, 1533 int *size); 1534</pre> 1535<div class="fcndef"> 1536 1537<p>Returns the parser's input buffer, sets the integer pointed at by 1538<code>offset</code> to the offset within this buffer of the current 1539parse position, and set the integer pointed at by <code>size</code> to 1540the size of the returned buffer.</p> 1541 1542<p>This should only be called from within a handler during an active 1543parse and the returned buffer should only be referred to from within 1544the handler that made the call. This input buffer contains the 1545untranslated bytes of the input.</p> 1546 1547<p>Only a limited amount of context is kept, so if the event 1548triggering a call spans over a very large amount of input, the actual 1549parse position may be before the beginning of the buffer.</p> 1550</div> 1551 1552<h3><a name="miscellaneous">Miscellaneous functions</a></h3> 1553 1554<p>The functions in this section either obtain state information from 1555the parser or can be used to dynamicly set parser options.</p> 1556 1557<pre class="fcndec" id="XML_SetUserData"> 1558void 1559XML_SetUserData(XML_Parser p, 1560 void *userData); 1561</pre> 1562<div class="fcndef"> 1563This sets the user data pointer that gets passed to handlers. It 1564overwrites any previous value for this pointer. Note that the 1565application is responsible for freeing the memory associated with 1566<code>userData</code> when it is finished with the parser. So if you 1567call this when there's already a pointer there, and you haven't freed 1568the memory associated with it, then you've probably just leaked 1569memory. 1570</div> 1571 1572<pre class="fcndec" id="XML_GetUserData"> 1573void * 1574XML_GetUserData(XML_Parser p); 1575</pre> 1576<div class="fcndef"> 1577This returns the user data pointer that gets passed to handlers. 1578It is actually implemented as a macro. 1579</div> 1580 1581<pre class="fcndec" id="XML_UseParserAsHandlerArg"> 1582void 1583XML_UseParserAsHandlerArg(XML_Parser p); 1584</pre> 1585<div class="fcndef"> 1586After this is called, handlers receive the parser in their 1587<code>userData</code> arguments. The user data can still be obtained 1588using the <code><a href= "#XML_GetUserData" 1589>XML_GetUserData</a></code> function. 1590</div> 1591 1592<pre class="fcndec" id="XML_SetBase"> 1593enum XML_Status 1594XML_SetBase(XML_Parser p, 1595 const XML_Char *base); 1596</pre> 1597<div class="fcndef"> 1598Set the base to be used for resolving relative URIs in system 1599identifiers. The return value is <code>XML_STATUS_ERROR</code> if 1600there's no memory to store base, otherwise it's 1601<code>XML_STATUS_OK</code>. 1602</div> 1603 1604<pre class="fcndec" id="XML_GetBase"> 1605const XML_Char * 1606XML_GetBase(XML_Parser p); 1607</pre> 1608<div class="fcndef"> 1609Return the base for resolving relative URIs. 1610</div> 1611 1612<pre class="fcndec" id="XML_GetSpecifiedAttributeCount"> 1613int 1614XML_GetSpecifiedAttributeCount(XML_Parser p); 1615</pre> 1616<div class="fcndef"> 1617When attributes are reported to the start handler in the atts vector, 1618attributes that were explicitly set in the element occur before any 1619attributes that receive their value from default information in an 1620ATTLIST declaration. This function returns the number of attributes 1621that were explicitly set times two, thus giving the offset in the 1622<code>atts</code> array passed to the start tag handler of the first 1623attribute set due to defaults. It supplies information for the last 1624call to a start handler. If called inside a start handler, then that 1625means the current call. 1626</div> 1627 1628<pre class="fcndec" id="XML_GetIdAttributeIndex"> 1629int 1630XML_GetIdAttributeIndex(XML_Parser p); 1631</pre> 1632<div class="fcndef"> 1633Returns the index of the ID attribute passed in the atts array in the 1634last call to <code><a href= "#XML_StartElementHandler" 1635>XML_StartElementHandler</a></code>, or -1 if there is no ID 1636attribute. If called inside a start handler, then that means the 1637current call. 1638</div> 1639 1640<pre class="fcndec" id="XML_SetEncoding"> 1641enum XML_Status 1642XML_SetEncoding(XML_Parser p, 1643 const XML_Char *encoding); 1644</pre> 1645<div class="fcndef"> 1646Set the encoding to be used by the parser. It is equivalent to 1647passing a non-null encoding argument to the parser creation functions. 1648It must not be called after <code><a href= "#XML_Parse" 1649>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer" 1650>XML_ParseBuffer</a></code> have been called on the given parser. 1651Returns <code>XML_STATUS_OK</code> on success or 1652<code>XML_STATUS_ERROR</code> on error. 1653</div> 1654 1655<pre class="fcndec" id="XML_SetParamEntityParsing"> 1656int 1657XML_SetParamEntityParsing(XML_Parser p, 1658 enum XML_ParamEntityParsing code); 1659</pre> 1660<div class="fcndef"> 1661This enables parsing of parameter entities, including the external 1662parameter entity that is the external DTD subset, according to 1663<code>code</code>. 1664The choices for <code>code</code> are: 1665<ul> 1666<li><code>XML_PARAM_ENTITY_PARSING_NEVER</code></li> 1667<li><code>XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE</code></li> 1668<li><code>XML_PARAM_ENTITY_PARSING_ALWAYS</code></li> 1669</ul> 1670</div> 1671 1672<pre class="fcndec" id="XML_UseForeignDTD"> 1673enum XML_Error 1674XML_UseForeignDTD(XML_Parser parser, XML_Bool useDTD); 1675</pre> 1676<div class="fcndef"> 1677<p>This function allows an application to provide an external subset 1678for the document type declaration for documents which do not specify 1679an external subset of their own. For documents which specify an 1680external subset in their DOCTYPE declaration, the application-provided 1681subset will be ignored. If the document does not contain a DOCTYPE 1682declaration at all and <code>useDTD</code> is true, the 1683application-provided subset will be parsed, but the 1684<code>startDoctypeDeclHandler</code> and 1685<code>endDoctypeDeclHandler</code> functions, if set, will not be 1686called. The setting of parameter entity parsing, controlled using 1687<code><a href= "#XML_SetParamEntityParsing" 1688>XML_SetParamEntityParsing</a></code>, will be honored.</p> 1689 1690<p>The application-provided external subset is read by calling the 1691external entity reference handler set via <code><a href= 1692"#XML_SetExternalEntityRefHandler" 1693>XML_SetExternalEntityRefHandler</a></code> with both 1694<code>publicId</code> and <code>systemId</code> set to NULL.</p> 1695 1696<p>If this function is called after parsing has begun, it returns 1697<code>XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING</code> and ignores 1698<code>useDTD</code>. If called when Expat has been compiled without 1699DTD support, it returns 1700<code>XML_ERROR_FEATURE_REQUIRES_XML_DTD</code>. Otherwise, it 1701returns <code>XML_ERROR_NONE</code>.</p> 1702</div> 1703 1704<pre class="fcndec" id="XML_SetReturnNSTriplet"> 1705void 1706XML_SetReturnNSTriplet(XML_Parser parser, 1707 int do_nst); 1708</pre> 1709<div class="fcndef"> 1710<p> 1711This function only has an effect when using a parser created with 1712<code><a href= "#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, 1713i.e. when namespace processing is in effect. The <code>do_nst</code> 1714sets whether or not prefixes are returned with names qualified with a 1715namespace prefix. If this function is called with <code>do_nst</code> 1716non-zero, then afterwards namespace qualified names (that is qualified 1717with a prefix as opposed to belonging to a default namespace) are 1718returned as a triplet with the three parts separated by the namespace 1719separator specified when the parser was created. The order of 1720returned parts is URI, local name, and prefix.</p> <p>If 1721<code>do_nst</code> is zero, then namespaces are reported in the 1722default manner, URI then local_name separated by the namespace 1723separator.</p> 1724</div> 1725 1726<pre class="fcndec" id="XML_DefaultCurrent"> 1727void 1728XML_DefaultCurrent(XML_Parser parser); 1729</pre> 1730<div class="fcndef"> 1731This can be called within a handler for a start element, end element, 1732processing instruction or character data. It causes the corresponding 1733markup to be passed to the default handler set by <code><a 1734href="#XML_SetDefaultHandler" >XML_SetDefaultHandler</a></code> or 1735<code><a href="#XML_SetDefaultHandlerExpand" 1736>XML_SetDefaultHandlerExpand</a></code>. It does nothing if there is 1737not a default handler. 1738</div> 1739 1740<pre class="fcndec" id="XML_ExpatVersion"> 1741XML_LChar * 1742XML_ExpatVersion(); 1743</pre> 1744<div class="fcndef"> 1745Return the library version as a string (e.g. <code>"expat_1.95.1"</code>). 1746</div> 1747 1748<pre class="fcndec" id="XML_ExpatVersionInfo"> 1749struct XML_Expat_Version 1750XML_ExpatVersionInfo(); 1751</pre> 1752<pre class="signature"> 1753typedef struct { 1754 int major; 1755 int minor; 1756 int micro; 1757} XML_Expat_Version; 1758</pre> 1759<div class="fcndef"> 1760Return the library version information as a structure. 1761Some macros are also defined that support compile-time tests of the 1762library version: 1763<ul> 1764<li><code>XML_MAJOR_VERSION</code></li> 1765<li><code>XML_MINOR_VERSION</code></li> 1766<li><code>XML_MICRO_VERSION</code></li> 1767</ul> 1768Testing these constants is currently the best way to determine if 1769particular parts of the Expat API are available. 1770</div> 1771 1772<pre class="fcndec" id="XML_GetFeatureList"> 1773const XML_Feature * 1774XML_GetFeatureList(); 1775</pre> 1776<pre class="signature"> 1777enum XML_FeatureEnum { 1778 XML_FEATURE_END = 0, 1779 XML_FEATURE_UNICODE, 1780 XML_FEATURE_UNICODE_WCHAR_T, 1781 XML_FEATURE_DTD, 1782 XML_FEATURE_CONTEXT_BYTES, 1783 XML_FEATURE_MIN_SIZE, 1784 XML_FEATURE_SIZEOF_XML_CHAR, 1785 XML_FEATURE_SIZEOF_XML_LCHAR 1786}; 1787 1788typedef struct { 1789 enum XML_FeatureEnum feature; 1790 XML_LChar *name; 1791 long int value; 1792} XML_Feature; 1793</pre> 1794<div class="fcndef"> 1795<p>Returns a list of "feature" records, providing details on how 1796Expat was configured at compile time. Most applications should not 1797need to worry about this, but this information is otherwise not 1798available from Expat. This function allows code that does need to 1799check these features to do so at runtime.</p> 1800 1801<p>The return value is an array of <code>XML_Feature</code>, 1802terminated by a record with a <code>feature</code> of 1803<code>XML_FEATURE_END</code> and <code>name</code> of NULL, 1804identifying the feature-test macros Expat was compiled with. Since an 1805application that requires this kind of information needs to determine 1806the type of character the <code>name</code> points to, records for the 1807<code>XML_FEATURE_SIZEOF_XML_CHAR</code> and 1808<code>XML_FEATURE_SIZEOF_XML_LCHAR</code> will be located at the 1809beginning of the list, followed by <code>XML_FEATURE_UNICODE</code> 1810and <code>XML_FEATURE_UNICODE_WCHAR_T</code>, if they are present at 1811all.</p> 1812 1813<p>Some features have an associated value. If there isn't an 1814associated value, the <code>value</code> field is set to 0. At this 1815time, the following features have been defined to have values:</p> 1816 1817<dl> 1818 <dt><code>XML_FEATURE_SIZEOF_XML_CHAR</code></dt> 1819 <dd>The number of bytes occupied by one <code>XML_Char</code> 1820 character.</dd> 1821 <dt><code>XML_FEATURE_SIZEOF_XML_LCHAR</code></dt> 1822 <dd>The number of bytes occupied by one <code>XML_LChar</code> 1823 character.</dd> 1824 <dt><code>XML_FEATURE_CONTEXT_BYTES</code></dt> 1825 <dd>The maximum number of characters of context which can be 1826 reported by <code><a href= "#XML_GetInputContext" 1827 >XML_GetInputContext</a></code>.</dd> 1828</dl> 1829</div> 1830 1831<pre class="fcndec" id="XML_FreeContentModel"> 1832void 1833XML_FreeContentModel(XML_Parser parser, XML_Content *model); 1834</pre> 1835<div class="fcndef"> 1836Function to deallocate the <code>model</code> argument passed to the 1837<code>XML_ElementDeclHandler</code> callback set using <code><a 1838href="#XML_SetElementDeclHandler" >XML_ElementDeclHandler</a></code>. 1839This function should not be used for any other purpose. 1840</div> 1841 1842<p>The following functions allow external code to share the memory 1843allocator an <code>XML_Parser</code> has been configured to use. This 1844is especially useful for third-party libraries that interact with a 1845parser object created by application code, or heavily layered 1846applications. This can be essential when using dynamically loaded 1847libraries which use different C standard libraries (this can happen on 1848Windows, at least).</p> 1849 1850<pre class="fcndec" id="XML_MemMalloc"> 1851void * 1852XML_MemMalloc(XML_Parser parser, size_t size); 1853</pre> 1854<div class="fcndef"> 1855Allocate <code>size</code> bytes of memory using the allocator the 1856<code>parser</code> object has been configured to use. Returns a 1857pointer to the memory or NULL on failure. Memory allocated in this 1858way must be freed using <code><a href="#XML_MemFree" 1859>XML_MemFree</a></code>. 1860</div> 1861 1862<pre class="fcndec" id="XML_MemRealloc"> 1863void * 1864XML_MemRealloc(XML_Parser parser, void *ptr, size_t size); 1865</pre> 1866<div class="fcndef"> 1867Allocate <code>size</code> bytes of memory using the allocator the 1868<code>parser</code> object has been configured to use. 1869<code>ptr</code> must point to a block of memory allocated by <code><a 1870href="#XML_MemMalloc" >XML_MemMalloc</a></code> or 1871<code>XML_MemRealloc</code>, or be NULL. This function tries to 1872expand the block pointed to by <code>ptr</code> if possible. Returns 1873a pointer to the memory or NULL on failure. On success, the original 1874block has either been expanded or freed. On failure, the original 1875block has not been freed; the caller is responsible for freeing the 1876original block. Memory allocated in this way must be freed using 1877<code><a href="#XML_MemFree" 1878>XML_MemFree</a></code>. 1879</div> 1880 1881<pre class="fcndec" id="XML_MemFree"> 1882void 1883XML_MemFree(XML_Parser parser, void *ptr); 1884</pre> 1885<div class="fcndef"> 1886Free a block of memory pointed to by <code>ptr</code>. The block must 1887have been allocated by <code><a href="#XML_MemMalloc" 1888>XML_MemMalloc</a></code> or <code>XML_MemRealloc</code>, or be NULL. 1889</div> 1890 1891<hr /> 1892<p><a href="http://validator.w3.org/check/referer"><img 1893 src="valid-xhtml10.png" alt="Valid XHTML 1.0!" 1894 height="31" width="88" class="noborder" /></a></p> 1895</body> 1896</html> 1897