reference.html

这是symbian下的实现XML解析的源代码。里面包括解析器和解析例子代码。

<dd>Include support for using and reporting DTD-based content.  If
this is defined, default attribute values from an external DTD subset
are reported and attribute value normalization occurs based on the
type of attributes defined in the external subset.  Without
this, Expat has a smaller memory footprint and can be faster, but will
not load external entities or process conditional sections.  This does
not affect the set of functions available in the API.</dd>

<dt>XML_NS</dt>
<dd>When defined, support for the <cite><a href=
"http://www.w3.org/TR/REC-xml-names/" >Namespaces in XML</a></cite>
specification is included.</dd>

<dt>XML_UNICODE</dt>
<dd>When defined, character data reported to the application is
encoded in UTF-16 using wide characters of the type
<code>XML_Char</code>.  This is implied if
<code>XML_UNICODE_WCHAR_T</code> is defined.</dd>

<dt>XML_UNICODE_WCHAR_T</dt>
<dd>If defined, causes the <code>XML_Char</code> character type to be
defined using the <code>wchar_t</code> type; otherwise, <code>unsigned
short</code> is used.  Defining this implies
<code>XML_UNICODE</code>.</dd>

<dt>XML_CONTEXT_BYTES</dt>
<dd>The number of input bytes of markup context which the parser will
ensure are available for reporting via <code><a href=
"#XML_GetInputContext" >XML_GetInputContext</a></code>.  This is
normally set to 1024, and must be set to a positive interger.  If this
is not defined, the input context will not be available and <code><a
href= "#XML_GetInputContext" >XML_GetInputContext</a></code> will
always report NULL.  Without this, Expat has a smaller memory
footprint and can be faster.</dd>

<dt>XML_STATIC</dt>
<dd>On Windows, this should be set if Expat is going to be linked
statically with the code that calls it; this is required to get all
the right MSVC magic annotations correct.  This is ignored on other
platforms.</dd>
</dl>

<hr />
<h2><a name="using">Using Expat</a></h2>

<h3>Compiling and Linking Against Expat</h3>

<p>Unless you installed Expat in a location not expected by your
compiler and linker, all you have to do to use Expat in your programs
is to include the Expat header (<code>#include &lt;expat.h&gt;</code>)
in your files that make calls to it and to tell the linker that it
needs to link against the Expat library.  On Unix systems, this would
usually be done with the <code>-lexpat</code> argument.  Otherwise,
you'll need to tell the compiler where to look for the Expat header
and the linker where to find the Expat library.  You may also need to
take steps to tell the operating system where to find this libary at
run time.</p>

<p>On a Unix-based system, here's what a Makefile might look like when
Expat is installed in a standard location:</p>

<pre class="eg">
CC=cc
LDFLAGS=
LIBS= -lexpat
xmlapp: xmlapp.o
        $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
</pre>

<p>If you installed Expat in, say, <code>/home/me/mystuff</code>, then
the Makefile would look like this:</p>

<pre class="eg">
CC=cc
CFLAGS= -I/home/me/mystuff/include
LDFLAGS=
LIBS= -L/home/me/mystuff/lib -lexpat
xmlapp: xmlapp.o
        $(CC) $(LDFLAGS) -o xmlapp xmlapp.o $(LIBS)
</pre>

<p>You'd also have to set the environment variable
<code>LD_LIBRARY_PATH</code> to <code>/home/me/mystuff/lib</code> (or
to <code>${LD_LIBRARY_PATH}:/home/me/mystuff/lib</code> if
LD_LIBRARY_PATH already has some directories in it) in order to run
your application.</p>

<h3>Expat Basics</h3>

<p>As we saw in the example in the overview, the first step in parsing
an XML document with Expat is to create a parser object. There are <a
href="#creation">three functions</a> in the Expat API for creating a
parser object.  However, only two of these (<code><a href=
"#XML_ParserCreate" >XML_ParserCreate</a></code> and <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>) can be used for
constructing a parser for a top-level document.  The object returned
by these functions is an opaque pointer (i.e. "expat.h" declares it as
void *) to data with further internal structure. In order to free the
memory associated with this object you must call <code><a href=
"#XML_ParserFree" >XML_ParserFree</a></code>. Note that if you have
provided any <a href="userdata">user data</a> that gets stored in the
parser, then your application is responsible for freeing it prior to
calling <code>XML_ParserFree</code>.</p>

<p>The objects returned by the parser creation functions are good for
parsing only one XML document or external parsed entity. If your
application needs to parse many XML documents, then it needs to create
a parser object for each one. The best way to deal with this is to
create a higher level object that contains all the default
initialization you want for your parser objects.</p>

<p>Walking through a document hierarchy with a stream oriented parser
will require a good stack mechanism in order to keep track of current
context.  For instance, to answer the simple question, "What element
does this text belong to?" requires a stack, since the parser may have
descended into other elements that are children of the current one and
has encountered this text on the way out.</p>

<p>The things you're likely to want to keep on a stack are the
currently opened element and it's attributes. You push this
information onto the stack in the start handler and you pop it off in
the end handler.</p>

<p>For some tasks, it is sufficient to just keep information on what
the depth of the stack is (or would be if you had one.) The outline
program shown above presents one example. Another such task would be
skipping over a complete element. When you see the start tag for the
element you want to skip, you set a skip flag and record the depth at
which the element started.  When the end tag handler encounters the
same depth, the skipped element has ended and the flag may be
cleared. If you follow the convention that the root element starts at
1, then you can use the same variable for skip flag and skip
depth.</p>

<pre class="eg">
void
init_info(Parseinfo *info) {
  info->skip = 0;
  info->depth = 1;
  /* Other initializations here */
}  /* End of init_info */

void XMLCALL
rawstart(void *data, const char *el, const char **attr) {
  Parseinfo *inf = (Parseinfo *) data;

  if (! inf->skip) {
    if (should_skip(inf, el, attr)) {
      inf->skip = inf->depth;
    }
    else
      start(inf, el, attr);     /* This does rest of start handling */
  }

  inf->depth++;
}  /* End of rawstart */

void XMLCALL
rawend(void *data, const char *el) {
  Parseinfo *inf = (Parseinfo *) data;

  inf->depth--;

  if (! inf->skip)
    end(inf, el);              /* This does rest of end handling */

  if (inf->skip == inf->depth)
    inf->skip = 0;
}  /* End rawend */
</pre>

<p>Notice in the above example the difference in how depth is
manipulated in the start and end handlers. The end tag handler should
be the mirror image of the start tag handler. This is necessary to
properly model containment. Since, in the start tag handler, we
incremented depth <em>after</em> the main body of start tag code, then
in the end handler, we need to manipulate it <em>before</em> the main
body.  If we'd decided to increment it first thing in the start
handler, then we'd have had to decrement it last thing in the end
handler.</p>

<h3 id="userdata">Communicating between handlers</h3>

<p>In order to be able to pass information between different handlers
without using globals, you'll need to define a data structure to hold
the shared variables. You can then tell Expat (with the <code><a href=
"#XML_SetUserData" >XML_SetUserData</a></code> function) to pass a
pointer to this structure to the handlers.  This is the first
argument received by most handlers.  In the <a href="#reference"
>reference section</a>, an argument to a callback function is named
<code>userData</code> and have type <code>void *</code> if the user
data is passed; it will have the type <code>XML_Parser</code> if the
parser itself is passed.  When the parser is passed, the user data may
be retrieved using <code><a href="#XML_GetUserData"
>XML_GetUserData</a></code>.</p>

<p>One common case where multiple calls to a single handler may need
to communicate using an application data structure is the case when
content passed to the character data handler (set by <code><a href=
"#XML_SetCharacterDataHandler"
>XML_SetCharacterDataHandler</a></code>) needs to be accumulated.  A
common first-time mistake with any of the event-oriented interfaces to
an XML parser is to expect all the text contained in an element to be
reported by a single call to the character data handler.  Expat, like
many other XML parsers, reports such data as a sequence of calls;
there's no way to know when the end of the sequence is reached until a
different callback is made.  A buffer referenced by the user data
structure proves both an effective and convenient place to accumulate
character data.</p>

<!-- XXX example needed here -->


<h3>XML Version</h3>

<p>Expat is an XML 1.0 parser, and as such never complains based on
the value of the <code>version</code> pseudo-attribute in the XML
declaration, if present.</p>

<p>If an application needs to check the version number (to support
alternate processing), it should use the <code><a href=
"#XML_SetXmlDeclHandler" >XML_SetXmlDeclHandler</a></code> function to
set a handler that uses the information in the XML declaration to
determine what to do.  This example shows how to check that only a
version number of <code>"1.0"</code> is accepted:</p>

<pre class="eg">
static int wrong_version;
static XML_Parser parser;

static void XMLCALL
xmldecl_handler(void            *userData,
                const XML_Char  *version,
                const XML_Char  *encoding,
                int              standalone)
{
  static const XML_Char Version_1_0[] = {'1', '.', '0', 0};

  int i;

  for (i = 0; i &lt; (sizeof(Version_1_0) / sizeof(Version_1_0[0])); ++i) {
    if (version[i] != Version_1_0[i]) {
      wrong_version = 1;
      /* also clear all other handlers: */
      XML_SetCharacterDataHandler(parser, NULL);
      ...
      return;
    }
  }
  ...
}
</pre>

<h3>Namespace Processing</h3>

<p>When the parser is created using the <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>, function, Expat
performs namespace processing. Under namespace processing, Expat
consumes <code>xmlns</code> and <code>xmlns:...</code> attributes,
which declare namespaces for the scope of the element in which they
occur. This means that your start handler will not see these
attributes.  Your application can still be informed of these
declarations by setting namespace declaration handlers with <a href=
"#XML_SetNamespaceDeclHandler"
><code>XML_SetNamespaceDeclHandler</code></a>.</p>

<p>Element type and attribute names that belong to a given namespace
are passed to the appropriate handler in expanded form. By default
this expanded form is a concatenation of the namespace URI, the
separator character (which is the 2nd argument to <code><a href=
"#XML_ParserCreateNS" >XML_ParserCreateNS</a></code>), and the local
name (i.e. the part after the colon). Names with undeclared prefixes
are passed through to the handlers unchanged, with the prefix and
colon still attached. Unprefixed attribute names are never expanded,
and unprefixed element names are only expanded when they are in the
scope of a default namespace.</p>

<p>However if <code><a href= "XML_SetReturnNSTriplet"
>XML_SetReturnNSTriplet</a></code> has been called with a non-zero
<code>do_nst</code> parameter, then the expanded form for names with
an explicit prefix is a concatenation of: URI, separator, local name,
separator, prefix.</p>

<p>You can set handlers for the start of a namespace declaration and
for the end of a scope of a declaration with the <code><a href=
"#XML_SetNamespaceDeclHandler" >XML_SetNamespaceDeclHandler</a></code>
function.  The StartNamespaceDeclHandler is called prior to the start
tag handler and the EndNamespaceDeclHandler is called before the
corresponding end tag that ends the namespace's scope.  The namespace
start handler gets passed the prefix and URI for the namespace.  For a
default namespace declaration (xmlns='...'), the prefix will be null.
The URI will be null for the case where the default namespace is being
unset.  The namespace end handler just gets the prefix for the closing
scope.</p>

<p>These handlers are called for each declaration. So if, for
instance, a start tag had three namespace declarations, then the
StartNamespaceDeclHandler would be called three times before the start
tag handler is called, once for each declaration.</p>

<h3>Character Encodings</h3>

<p>While XML is based on Unicode, and every XML processor is required
to recognized UTF-8 and UTF-16 (1 and 2 byte encodings of Unicode),
other encodings may be declared in XML documents or entities. For the
main document, an XML declaration may contain an encoding
declaration:</p>
<pre>
&lt;?xml version="1.0" encoding="ISO-8859-2"?&gt;
</pre>

<p>External parsed entities may begin with a text declaration, which
looks like an XML declaration with just an encoding declaration:</p>
<pre>
&lt;?xml encoding="Big5"?&gt;
</pre>

<p>With Expat, you may also specify an encoding at the time of
creating a parser. This is useful when the encoding information may
come from a source outside the document itself (like a higher level
protocol.)</p>