reference.html

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

</pre>
<div class="fcndef">
Clean up the memory structures maintained by the parser so that it may
be used again.  After this has been called, <code>parser</code> is
ready to start parsing a new document.  This function may not be used
on a parser created using <code><a href=
"#XML_ExternalEntityParserCreate" >XML_ExternalEntityParserCreate</a
></code>; it will return <code>XML_FALSE</code> in that case.  Returns
<code>XML_TRUE</code> on success.  Your application is responsible for
dealing with any memory associated with <a href="#userdata">user data</a>.
</div>

<h3><a name="parsing">Parsing</a></h3>

<p>To state the obvious: the three parsing functions <code><a href=
"#XML_Parse" >XML_Parse</a></code>, <code><a href= "#XML_ParseBuffer">
XML_ParseBuffer</a></code> and <code><a href= "#XML_GetBuffer">
XML_GetBuffer</a></code> must not be
called from within a handler unless they operate on a separate parser
instance, that is, one that did not call the handler. For example, it
is OK to call the parsing functions from within an
<code>XML_ExternalEntityRefHandler</code>, if they apply to the parser
created by <code><a href= "#XML_ExternalEntityParserCreate"
>XML_ExternalEntityParserCreate</a></code>.</p>

<pre class="fcndec" id="XML_Parse">
enum XML_Status XMLCALL
XML_Parse(XML_Parser p,
          const char *s,
          int len,
          int isFinal);
</pre>
<pre class="signature">
enum XML_Status {
  XML_STATUS_ERROR = 0,
  XML_STATUS_OK = 1
};
</pre>
<div class="fcndef">
Parse some more of the document. The string <code>s</code> is a buffer
containing part (or perhaps all) of the document. The number of bytes of s
that are part of the document is indicated by <code>len</code>. This means
that <code>s</code> doesn't have to be null terminated. It also means that
if <code>len</code> is larger than the number of bytes in the block of
memory that <code>s</code> points at, then a memory fault is likely. The
<code>isFinal</code> parameter informs the parser that this is the last
piece of the document. Frequently, the last piece is empty (i.e.
<code>len</code> is zero.)
If a parse error occurred, it returns <code>XML_STATUS_ERROR</code>.
Otherwise it returns <code>XML_STATUS_OK</code> value.
</div>

<pre class="fcndec" id="XML_ParseBuffer">
enum XML_Status XMLCALL
XML_ParseBuffer(XML_Parser p,
                int len,
                int isFinal);
</pre>
<div class="fcndef">
This is just like <code><a href= "#XML_Parse" >XML_Parse</a></code>,
except in this case Expat provides the buffer.  By obtaining the
buffer from Expat with the <code><a href= "#XML_GetBuffer"
>XML_GetBuffer</a></code> function, the application can avoid double
copying of the input.
</div>

<pre class="fcndec" id="XML_GetBuffer">
void * XMLCALL
XML_GetBuffer(XML_Parser p,
              int len);
</pre>
<div class="fcndef">
Obtain a buffer of size <code>len</code> to read a piece of the document
into. A NULL value is returned if Expat can't allocate enough memory for
this buffer. This has to be called prior to every call to
<code><a href= "#XML_ParseBuffer" >XML_ParseBuffer</a></code>. A
typical use would look like this:

<pre class="eg">
for (;;) {
  int bytes_read;
  void *buff = XML_GetBuffer(p, BUFF_SIZE);
  if (buff == NULL) {
    /* handle error */
  }

  bytes_read = read(docfd, buff, BUFF_SIZE);
  if (bytes_read &lt; 0) {
    /* handle error */
  }

  if (! XML_ParseBuffer(p, bytes_read, bytes_read == 0)) {
    /* handle parse error */
  }

  if (bytes_read == 0)
    break;
}
</pre>
</div>

<pre class="fcndec" id="XML_StopParser">
enum XML_Status XMLCALL
XML_StopParser(XML_Parser p,
               XML_Bool resumable);
</pre>
<div class="fcndef">

<p>Stops parsing, causing <code><a href= "#XML_Parse"
>XML_Parse</a></code> or <code><a href= "#XML_ParseBuffer"
>XML_ParseBuffer</a></code> to return.  Must be called from within a
call-back handler, except when aborting (when <code>resumable</code>
is <code>XML_FALSE</code>) an already suspended parser.  Some
call-backs may still follow because they would otherwise get
lost, including
<ul>
  <li> the end element handler for empty elements when stopped in the
       start element handler,</li>
  <li> end namespace declaration handler when stopped in the end
       element handler,</li>
</ul>
and possibly others.</p>

<p>This can be called from most handlers, including DTD related
call-backs, except when parsing an external parameter entity and
<code>resumable</code> is <code>XML_TRUE</code>.  Returns
<code>XML_STATUS_OK</code> when successful,
<code>XML_STATUS_ERROR</code> otherwise.  The possible error codes
are:</p>
<dl>
  <dt><code>XML_ERROR_SUSPENDED</code></dt>
  <dd>when suspending an already suspended parser.</dd>
  <dt><code>XML_ERROR_FINISHED</code></dt>
  <dd>when the parser has already finished.</dd>
  <dt><code>XML_ERROR_SUSPEND_PE</code></dt>
  <dd>when suspending while parsing an external PE.</dd>
</dl>

<p>Since the stop/resume feature requires application support in the
outer parsing loop, it is an error to call this function for a parser
not being handled appropriately; see <a href= "#stop-resume"
>Temporarily Stopping Parsing</a> for more information.</p>

<p>When <code>resumable</code> is <code>XML_TRUE</code> then parsing
is <em>suspended</em>, that is, <code><a href= "#XML_Parse"
>XML_Parse</a></code> and <code><a href= "#XML_ParseBuffer"
>XML_ParseBuffer</a></code> return <code>XML_STATUS_SUSPENDED</code>.
Otherwise, parsing is <em>aborted</em>, that is, <code><a href=
"#XML_Parse" >XML_Parse</a></code> and <code><a href=
"#XML_ParseBuffer" >XML_ParseBuffer</a></code> return
<code>XML_STATUS_ERROR</code> with error code
<code>XML_ERROR_ABORTED</code>.</p>

<p><strong>Note:</strong>
This will be applied to the current parser instance only, that is, if
there is a parent parser then it will continue parsing when the
external entity reference handler returns.  It is up to the
implementation of that handler to call <code><a href=
"#XML_StopParser" >XML_StopParser</a></code> on the parent parser
(recursively), if one wants to stop parsing altogether.</p>

<p>When suspended, parsing can be resumed by calling <code><a href=
"#XML_ResumeParser" >XML_ResumeParser</a></code>.</p>

<p>New in Expat 1.95.8.</p>
</div>

<pre class="fcndec" id="XML_ResumeParser">
enum XML_Status XMLCALL
XML_ResumeParser(XML_Parser p);
</pre>
<div class="fcndef">
<p>Resumes parsing after it has been suspended with <code><a href=
"#XML_StopParser" >XML_StopParser</a></code>.  Must not be called from
within a handler call-back.  Returns same status codes as <code><a
href= "#XML_Parse">XML_Parse</a></code> or <code><a href=
"#XML_ParseBuffer" >XML_ParseBuffer</a></code>.  An additional error
code, <code>XML_ERROR_NOT_SUSPENDED</code>, will be returned if the
parser was not currently suspended.</p>

<p><strong>Note:</strong>
This must be called on the most deeply nested child parser instance
first, and on its parent parser only after the child parser has
finished, to be applied recursively until the document entity's parser
is restarted.  That is, the parent parser will not resume by itself
and it is up to the application to call <code><a href=
"#XML_ResumeParser" >XML_ResumeParser</a></code> on it at the
appropriate moment.</p>

<p>New in Expat 1.95.8.</p>
</div>

<pre class="fcndec" id="XML_GetParsingStatus">
void XMLCALL
XML_GetParsingStatus(XML_Parser p,
                     XML_ParsingStatus *status);
</pre>
<pre class="signature">
enum XML_Parsing {
  XML_INITIALIZED,
  XML_PARSING,
  XML_FINISHED,
  XML_SUSPENDED
};

typedef struct {
  enum XML_Parsing parsing;
  XML_Bool finalBuffer;
} XML_ParsingStatus;
</pre>
<div class="fcndef">
<p>Returns status of parser with respect to being initialized,
parsing, finished, or suspended, and whether the final buffer is being
processed.  The <code>status</code> parameter <em>must not</em> be
NULL.</p>

<p>New in Expat 1.95.8.</p>
</div>


<h3><a name="setting">Handler Setting</a></h3>

<p>Although handlers are typically set prior to parsing and left alone, an
application may choose to set or change the handler for a parsing event
while the parse is in progress. For instance, your application may choose
to ignore all text not descended from a <code>para</code> element. One
way it could do this is to set the character handler when a para start tag
is seen, and unset it for the corresponding end tag.</p>

<p>A handler may be <em>unset</em> by providing a NULL pointer to the
appropriate handler setter. None of the handler setting functions have
a return value.</p>

<p>Your handlers will be receiving strings in arrays of type
<code>XML_Char</code>. This type is defined in expat.h as <code>char
*</code> and contains bytes encoding UTF-8.  Note that you'll receive
them in this form independent of the original encoding of the
document.</p>

<div class="handler">
<pre class="setter" id="XML_SetStartElementHandler">
void XMLCALL
XML_SetStartElementHandler(XML_Parser p,
                           XML_StartElementHandler start);
</pre>
<pre class="signature">
typedef void
(XMLCALL *XML_StartElementHandler)(void *userData,
                                   const XML_Char *name,
                                   const XML_Char **atts);
</pre>
<p>Set handler for start (and empty) tags. Attributes are passed to the start
handler as a pointer to a vector of char pointers. Each attribute seen in
a start (or empty) tag occupies 2 consecutive places in this vector: the
attribute name followed by the attribute value. These pairs are terminated
by a null pointer.</p>
<p>Note that an empty tag generates a call to both start and end handlers
(in that order).</p>
</div>

<div class="handler">
<pre class="setter" id="XML_SetEndElementHandler">
void XMLCALL
XML_SetEndElementHandler(XML_Parser p,
                         XML_EndElementHandler);
</pre>
<pre class="signature">
typedef void
(XMLCALL *XML_EndElementHandler)(void *userData,
                                 const XML_Char *name);
</pre>
<p>Set handler for end (and empty) tags. As noted above, an empty tag
generates a call to both start and end handlers.</p>
</div>

<div class="handler">
<pre class="setter" id="XML_SetElementHandler">
void XMLCALL
XML_SetElementHandler(XML_Parser p,
                      XML_StartElementHandler start,
                      XML_EndElementHandler end);
</pre>
<p>Set handlers for start and end tags with one call.</p>
</div>

<div class="handler">
<pre class="setter" id="XML_SetCharacterDataHandler">
void XMLCALL
XML_SetCharacterDataHandler(XML_Parser p,
                            XML_CharacterDataHandler charhndl)
</pre>
<pre class="signature">
typedef void
(XMLCALL *XML_CharacterDataHandler)(void *userData,
                                    const XML_Char *s,
                                    int len);
</pre>
<p>Set a text handler. The string your handler receives
is <em>NOT nul-terminated</em>. You have to use the length argument
to deal with the end of the string. A single block of contiguous text
free of markup may still result in a sequence of calls to this handler.
In other words, if you're searching for a pattern in the text, it may
be split across calls to this handler.</p>
</div>

<div class="handler">
<pre class="setter" id="XML_SetProcessingInstructionHandler">
void XMLCALL
XML_SetProcessingInstructionHandler(XML_Parser p,
                                    XML_ProcessingInstructionHandler proc)
</pre>
<pre class="signature">
typedef void
(XMLCALL *XML_ProcessingInstructionHandler)(void *userData,
                                            const XML_Char *target,
                                            const XML_Char *data);

</pre>
<p>Set a handler for processing instructions. The target is the first word
in the processing instruction. The data is the rest of the characters in
it after skipping all whitespace after the initial word.</p>