📄 reference.html
字号:
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- Copyright 1999,2000 Clark Cooper <coopercc@netheaven.com>
All rights reserved.
This is free software. You may distribute or modify according to
the terms of the MIT/X License -->
<title>Expat XML Parser</title>
<meta name="author" content="Clark Cooper, coopercc@netheaven.com" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table cellspacing="0" cellpadding="0" width="100%">
<tr>
<td class="corner"><img src="expat.png" alt="(Expat logo)" /></td>
<td class="banner"><h1>The Expat XML Parser</h1></td>
</tr>
<tr>
<td class="releaseno">Release 1.95.8</td>
<td></td>
</tr>
</table>
<div class="content">
<p>Expat is a library, written in C, for parsing XML documents. It's
the underlying XML parser for the open source Mozilla project, Perl's
<code>XML::Parser</code>, Python's <code>xml.parsers.expat</code>, and
other open-source XML parsers.</p>
<p>This library is the creation of James Clark, who's also given us
groff (an nroff look-alike), Jade (an implemention of ISO's DSSSL
stylesheet language for SGML), XP (a Java XML parser package), XT (a
Java XSL engine). James was also the technical lead on the XML
Working Group at W3C that produced the XML specification.</p>
<p>This is free software, licensed under the <a
href="../COPYING">MIT/X Consortium license</a>. You may download it
from <a href="http://www.libexpat.org/">the Expat home page</a>.
</p>
<p>The bulk of this document was originally commissioned as an article
by <a href="http://www.xml.com/">XML.com</a>. They graciously allowed
Clark Cooper to retain copyright and to distribute it with Expat.
This version has been substantially extended to include documentation
on features which have been added since the original article was
published, and additional information on using the original
interface.</p>
<hr />
<h2>Table of Contents</h2>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#building">Building and Installing</a></li>
<li><a href="#using">Using Expat</a></li>
<li><a href="#reference">Reference</a>
<ul>
<li><a href="#creation">Parser Creation Functions</a>
<ul>
<li><a href="#XML_ParserCreate">XML_ParserCreate</a></li>
<li><a href="#XML_ParserCreateNS">XML_ParserCreateNS</a></li>
<li><a href="#XML_ParserCreate_MM">XML_ParserCreate_MM</a></li>
<li><a href="#XML_ExternalEntityParserCreate">XML_ExternalEntityParserCreate</a></li>
<li><a href="#XML_ParserFree">XML_ParserFree</a></li>
<li><a href="#XML_ParserReset">XML_ParserReset</a></li>
</ul>
</li>
<li><a href="#parsing">Parsing Functions</a>
<ul>
<li><a href="#XML_Parse">XML_Parse</a></li>
<li><a href="#XML_ParseBuffer">XML_ParseBuffer</a></li>
<li><a href="#XML_GetBuffer">XML_GetBuffer</a></li>
<li><a href="#XML_StopParser">XML_StopParser</a></li>
<li><a href="#XML_ResumeParser">XML_ResumeParser</a></li>
<li><a href="#XML_GetParsingStatus">XML_GetParsingStatus</a></li>
</ul>
</li>
<li><a href="#setting">Handler Setting Functions</a>
<ul>
<li><a href="#XML_SetStartElementHandler">XML_SetStartElementHandler</a></li>
<li><a href="#XML_SetEndElementHandler">XML_SetEndElementHandler</a></li>
<li><a href="#XML_SetElementHandler">XML_SetElementHandler</a></li>
<li><a href="#XML_SetCharacterDataHandler">XML_SetCharacterDataHandler</a></li>
<li><a href="#XML_SetProcessingInstructionHandler">XML_SetProcessingInstructionHandler</a></li>
<li><a href="#XML_SetCommentHandler">XML_SetCommentHandler</a></li>
<li><a href="#XML_SetStartCdataSectionHandler">XML_SetStartCdataSectionHandler</a></li>
<li><a href="#XML_SetEndCdataSectionHandler">XML_SetEndCdataSectionHandler</a></li>
<li><a href="#XML_SetCdataSectionHandler">XML_SetCdataSectionHandler</a></li>
<li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li>
<li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li>
<li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li>
<li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li>
<li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li>
<li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li>
<li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li>
<li><a href="#XML_SetEndNamespaceDeclHandler">XML_SetEndNamespaceDeclHandler</a></li>
<li><a href="#XML_SetNamespaceDeclHandler">XML_SetNamespaceDeclHandler</a></li>
<li><a href="#XML_SetXmlDeclHandler">XML_SetXmlDeclHandler</a></li>
<li><a href="#XML_SetStartDoctypeDeclHandler">XML_SetStartDoctypeDeclHandler</a></li>
<li><a href="#XML_SetEndDoctypeDeclHandler">XML_SetEndDoctypeDeclHandler</a></li>
<li><a href="#XML_SetDoctypeDeclHandler">XML_SetDoctypeDeclHandler</a></li>
<li><a href="#XML_SetElementDeclHandler">XML_SetElementDeclHandler</a></li>
<li><a href="#XML_SetAttlistDeclHandler">XML_SetAttlistDeclHandler</a></li>
<li><a href="#XML_SetEntityDeclHandler">XML_SetEntityDeclHandler</a></li>
<li><a href="#XML_SetUnparsedEntityDeclHandler">XML_SetUnparsedEntityDeclHandler</a></li>
<li><a href="#XML_SetNotationDeclHandler">XML_SetNotationDeclHandler</a></li>
<li><a href="#XML_SetNotStandaloneHandler">XML_SetNotStandaloneHandler</a></li>
</ul>
</li>
<li><a href="#position">Parse Position and Error Reporting Functions</a>
<ul>
<li><a href="#XML_GetErrorCode">XML_GetErrorCode</a></li>
<li><a href="#XML_ErrorString">XML_ErrorString</a></li>
<li><a href="#XML_GetCurrentByteIndex">XML_GetCurrentByteIndex</a></li>
<li><a href="#XML_GetCurrentLineNumber">XML_GetCurrentLineNumber</a></li>
<li><a href="#XML_GetCurrentColumnNumber">XML_GetCurrentColumnNumber</a></li>
<li><a href="#XML_GetCurrentByteCount">XML_GetCurrentByteCount</a></li>
<li><a href="#XML_GetInputContext">XML_GetInputContext</a></li>
</ul>
</li>
<li><a href="#miscellaneous">Miscellaneous Functions</a>
<ul>
<li><a href="#XML_SetUserData">XML_SetUserData</a></li>
<li><a href="#XML_GetUserData">XML_GetUserData</a></li>
<li><a href="#XML_UseParserAsHandlerArg">XML_UseParserAsHandlerArg</a></li>
<li><a href="#XML_SetBase">XML_SetBase</a></li>
<li><a href="#XML_GetBase">XML_GetBase</a></li>
<li><a href="#XML_GetSpecifiedAttributeCount">XML_GetSpecifiedAttributeCount</a></li>
<li><a href="#XML_GetIdAttributeIndex">XML_GetIdAttributeIndex</a></li>
<li><a href="#XML_SetEncoding">XML_SetEncoding</a></li>
<li><a href="#XML_SetParamEntityParsing">XML_SetParamEntityParsing</a></li>
<li><a href="#XML_UseForeignDTD">XML_UseForeignDTD</a></li>
<li><a href="#XML_SetReturnNSTriplet">XML_SetReturnNSTriplet</a></li>
<li><a href="#XML_DefaultCurrent">XML_DefaultCurrent</a></li>
<li><a href="#XML_ExpatVersion">XML_ExpatVersion</a></li>
<li><a href="#XML_ExpatVersionInfo">XML_ExpatVersionInfo</a></li>
<li><a href="#XML_GetFeatureList">XML_GetFeatureList</a></li>
<li><a href="#XML_FreeContentModel">XML_FreeContentModel</a></li>
<li><a href="#XML_MemMalloc">XML_MemMalloc</a></li>
<li><a href="#XML_MemRealloc">XML_MemRealloc</a></li>
<li><a href="#XML_MemFree">XML_MemFree</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<hr />
<h2><a name="overview">Overview</a></h2>
<p>Expat is a stream-oriented parser. You register callback (or
handler) functions with the parser and then start feeding it the
document. As the parser recognizes parts of the document, it will
call the appropriate handler for that part (if you've registered one.)
The document is fed to the parser in pieces, so you can start parsing
before you have all the document. This also allows you to parse really
huge documents that won't fit into memory.</p>
<p>Expat can be intimidating due to the many kinds of handlers and
options you can set. But you only need to learn four functions in
order to do 90% of what you'll want to do with it:</p>
<dl>
<dt><code><a href= "#XML_ParserCreate"
>XML_ParserCreate</a></code></dt>
<dd>Create a new parser object.</dd>
<dt><code><a href= "#XML_SetElementHandler"
>XML_SetElementHandler</a></code></dt>
<dd>Set handlers for start and end tags.</dd>
<dt><code><a href= "#XML_SetCharacterDataHandler"
>XML_SetCharacterDataHandler</a></code></dt>
<dd>Set handler for text.</dd>
<dt><code><a href= "#XML_Parse"
>XML_Parse</a></code></dt>
<dd>Pass a buffer full of document to the parser</dd>
</dl>
<p>These functions and others are described in the <a
href="#reference">reference</a> part of this document. The reference
section also describes in detail the parameters passed to the
different types of handlers.</p>
<p>Let's look at a very simple example program that only uses 3 of the
above functions (it doesn't need to set a character handler.) The
program <a href="../examples/outline.c">outline.c</a> prints an
element outline, indenting child elements to distinguish them from the
parent element that contains them. The start handler does all the
work. It prints two indenting spaces for every level of ancestor
elements, then it prints the element and attribute
information. Finally it increments the global <code>Depth</code>
variable.</p>
<pre class="eg">
int Depth;
void XMLCALL
start(void *data, const char *el, const char **attr) {
int i;
for (i = 0; i < Depth; i++)
printf(" ");
printf("%s", el);
for (i = 0; attr[i]; i += 2) {
printf(" %s='%s'", attr[i], attr[i + 1]);
}
printf("\n");
Depth++;
} /* End of start handler */
</pre>
<p>The end tag simply does the bookkeeping work of decrementing
<code>Depth</code>.</p>
<pre class="eg">
void XMLCALL
end(void *data, const char *el) {
Depth--;
} /* End of end handler */
</pre>
<p>Note the <code>XMLCALL</code> annotation used for the callbacks.
This is used to ensure that the Expat and the callbacks are using the
same calling convention in case the compiler options used for Expat
itself and the client code are different. Expat tries not to care
what the default calling convention is, though it may require that it
be compiled with a default convention of "cdecl" on some platforms.
For code which uses Expat, however, the calling convention is
specified by the <code>XMLCALL</code> annotation on most platforms;
callbacks should be defined using this annotation.</p>
<p>The <code>XMLCALL</code> annotation was added in Expat 1.95.7, but
existing working Expat applications don't need to add it (since they
are already using the "cdecl" calling convention, or they wouldn't be
working). The annotation is only needed if the default calling
convention may be something other than "cdecl". To use the annotation
safely with older versions of Expat, you can conditionally define it
<em>after</em> including Expat's header file:</p>
<pre class="eg">
#include <expat.h>
#ifndef XMLCALL
#if defined(_MSC_EXTENSIONS) && !defined(__BEOS__) && !defined(__CYGWIN__)
#define XMLCALL __cdecl
#elif defined(__GNUC__)
#define XMLCALL __attribute__((cdecl))
#else
#define XMLCALL
#endif
#endif
</pre>
<p>After creating the parser, the main program just has the job of
shoveling the document to the parser so that it can do its work.</p>
<hr />
<h2><a name="building">Building and Installing Expat</a></h2>
<p>The Expat distribution comes as a compressed (with GNU gzip) tar
file. You may download the latest version from <a href=
"http://sourceforge.net/projects/expat/" >Source Forge</a>. After
unpacking this, cd into the directory. Then follow either the Win32
directions or Unix directions below.</p>
<h3>Building under Win32</h3>
<p>If you're using the GNU compiler under cygwin, follow the Unix
directions in the next section. Otherwise if you have Microsoft's
Developer Studio installed, then from Windows Explorer double-click on
"expat.dsp" in the lib directory and build and install in the usual
manner.</p>
<p>Alternatively, you may download the Win32 binary package that
contains the "expat.h" include file and a pre-built DLL.</p>
<h3>Building under Unix (or GNU)</h3>
<p>First you'll need to run the configure shell script in order to
configure the Makefiles and headers for your system.</p>
<p>If you're happy with all the defaults that configure picks for you,
and you have permission on your system to install into /usr/local, you
can install Expat with this sequence of commands:</p>
<pre class="eg">
./configure
make
make install
</pre>
<p>There are some options that you can provide to this script, but the
only one we'll mention here is the <code>--prefix</code> option. You
can find out all the options available by running configure with just
the <code>--help</code> option.</p>
<p>By default, the configure script sets things up so that the library
gets installed in <code>/usr/local/lib</code> and the associated
header file in <code>/usr/local/include</code>. But if you were to
give the option, <code>--prefix=/home/me/mystuff</code>, then the
library and header would get installed in
<code>/home/me/mystuff/lib</code> and
<code>/home/me/mystuff/include</code> respectively.</p>
<h3>Configuring Expat Using the Pre-Processor</h3>
<p>Expat's feature set can be configured using a small number of
pre-processor definitions. The definition of this symbols does not
affect the set of entry points for Expat, only the behavior of the API
and the definition of character types in the case of
<code>XML_UNICODE_WCHAR_T</code>. The symbols are:</p>
<dl class="cpp-symbols">
<dt>XML_DTD</dt>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -