parse Method
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.
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
, orIXMLDOMDocument
.
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
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.
To view reference information for Visual Basic or C/C++ only, click the Language Filter button in the upper-left corner of the page.
See Also
Convert DOM to SAX | 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++)
Applies to: ISAXXMLReader Interface