parse Method

[Visual Basic]

An application can use this method to instruct the reader to begin parsing a document from any valid input source, including a DOMDocument object, character stream, byte stream, or Uniform Resource Identifier (URI). An application cannot invoke this method while a parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Usage Syntax

oSAXXMLReader.parse(varInput)

Parameters

varInput

A variant (or a reference to one) containing the input source to parse from. The following VARIANT types are supported:

• VT_BSTR, which can contain a value of BSTR type.
• Either VT_ARRAY or VT_UI1, which can contain a value in the form of a safe array of bytes.
• VT_UNKNOWN or VT_DISPATCH, which can contain a value in the form of either an IStream, ISequentialStream, or IXMLDOMDocument.

When using references (VT_BYREF), more than one level of indirection is permitted.

An application cannot invoke this method while parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Remarks

During parsing, the reader provides information about the XML document through the registered event handlers. If an error occurs during parsing, the reader calls the appropriate method of the ErrorHandler. The ErrorHandler always returns the internal error code to the parse method, even if the ErrorHandler raises a user-defined error.

Example

The following example loads books.xml into a DOMDocument object, specifies the object as a parameter of the parse method, and then displays the result in a message box.

Sub Main()
'create the reader
Dim rdr As New SAXXMLReader50
'create the writer
Dim wrt As New MXXMLWriter50

On Error GoTo errorHandler

wrt.byteOrderMark = True
wrt.omitXMLDeclaration = False
wrt.indent = True

'set the writer to the content handler
Set rdr.contentHandler = wrt
Set rdr.dtdHandler = wrt
Set rdr.errorHandler = wrt
rdr.putProperty "http://xml.org/sax/properties/lexical-handler", wrt
rdr.putProperty "http://xml.org/sax/properties/declaration-handler", wrt

'parse the XML
rdr.parse "<catalog><book id='bk101'></book></catalog>"

'show the results in a message box
MsgBox wrt.output

Exit Sub

errorHandler:
    HandleErrors
End Sub

Private Function HandleErrors()
    MsgBox Err.Description
End Function

[C/C++]

The application can use this method to instruct the reader to begin parsing a document from a variety of sources. Supported VARIANT types are: VT_BSTR, which can contain a value of BSTR type; either VT_ARRAY or VT_UI1, which can contain a value in the form of a safe array of bytes; or VT_UNKNOWN, which can contain a value in the form of either an IStream, ISequentialStream or IXMLDOMDocument.

   VT_BYREF | VT_VARIANT -> VT_BSTR -> BSTR
   VT_BYREF | VT_VARIANT -> VT_UNKNOWN ->  VT_DISPATCH ->IStream |      ISequentialStream
   VT_BYREF | VT_VARIANT -> VT_UNKNOWN -> VT_DISPATCH -> IXMLDOMDocument
   VT_BYREF | VT_VARIANT -> VT_ARRAY | VT_UI1 -> SAFEARRAY

When using references (VT_BYREF). more than one level of indirection is permitted.

An application cannot invoke this method while parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Syntax

HRESULT parse (
   [in] VARIANT varInput);

Parameters

varInput [in]

Either a variant (VT_VARIANT) or a reference to one containing the input source to parse from. Supported VARIANT types and their data types for actual values are:

VT_BSTR (BSTR)

VT_ARRAY or VT_UI1 (SafeArray of bytes)

VT_UNKNOWN or VT_DISPATCH (IStream, ISequentialStream, or IXMLDOMDocument).

Return Values

S_OK

The value returned if parsing is successful.

E_INVALIDARG

The value returned if varInput is not a recognized input source.

Other

The parser error code or the code returned by the custom ErrorHandler.

Remarks

During parsing, the reader provides information about the XML document through the registered event handlers. If an error occurs during parsing, the reader calls the appropriate method of the ISAXErrorHandler interface. If the ErrorHandler returns anything but S_OK, parsing is aborted and the parse method returns the internal error that stopped the parser. The ErrorHandler always returns the internal error code, even if the ErrorHandler returns a user-defined HRESULT to the parse method. The reader can return a number of return codes, including, but not limited to: E_ACCESSDENIED, INET_E_OBJECT_NOT_FOUND, INET_E_DOWNLOAD_FAILURE, MSG_E_BADSTARTNAMECHAR, or MSG_E_MISSINGSEMICOLON.