]> git.saurik.com Git - wxWidgets.git/blame_incremental - src/expat/doc/reference.html
missing commit
[wxWidgets.git] / src / expat / doc / reference.html
... / ...
CommitLineData
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 &lt; 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 &lt;expat.h&gt;</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 &lt; (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&lt;?xml version="1.0" encoding="ISO-8859-2"?&gt;
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&lt;?xml encoding="Big5"?&gt;
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 &lt; 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 &gt;= 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 &gt; 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>&lt;!ENTITY foo "bar"&gt;</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&lt;!ENTITY logo SYSTEM "images/logo.gif" NDATA gif&gt;
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>