parse Method1

  • Article

 

Parses an XML document or a DOMDocument object.

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.

Visual Basic 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.

By default, when the baseURL Property (Visual Basic) is NULL, URLs will be resolved relative to the directory from which the program executed. The property will be NULL by default when parsing a BSTR, a safe array, an IStream, or an ISequentialStream.

C/C++ 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

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.

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.

By default, when the baseURL property is NULL (see getBaseURL Method (C-C++)), URLs will be resolved relative to the directory from which the program executed. The property will be NULL by default when parsing a BSTR, a safe array, an IStream, or an ISequentialStream.

Versioning

Implemented in: MSXML 3.0 and later

Applies to

ISAXXMLReader Interface

See Also

Convert DOM to SAX
IXMLDOMDocument-DOMDocument
ISAXErrorHandler Interface
contentHandler Property (Visual Basic)
dtdHandler Property (Visual Basic)
entityResolver Property (Visual Basic)
errorHandler Property (Visual Basic)
putContentHandler Method (C-C++)
putDTDHandler Method (C-C++)
putEntityResolver Method (C-C++)
putErrorHandler Method (C-C++)