getProperty Method

MSXML 5.0 SDK

Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - SAX2 Reference

getProperty Method

Returns a property's value (as a string), for any qualified Uniform Resource Identifier (URI).

[Visual Basic]

Usage Syntax

varValue = oSAXXMLReader.getProperty(strName)

Parameters

varValue
The corresponding data type of the property.

Return Values

The following table shows the return values for the getProperty method.

Property Returns
declaration-handler lexical-handler
max-xml-size
schemas
schema-declaration-handler
Current value
charset
dom-node

xmldecl-encoding
xmldecl-version
xmldecl-standalone
xml-string
Either the current value (when parsing) or a trappable error (when not parsing).
Other properties Trappable error.

[C/C++]

Returns the value of a property. The property name is any qualified Uniform Resource Identifier (URI).

It is possible for a reader to recognize a property name but not be able to return its state. Although a core set of properties is defined, a reader is not required to recognize specific property names. Some property values may be available only in a specific context, such as before, during, or after a parse.

Syntax

HRESULT getProperty(
   [in] const wchar_t * pwchName,
   [out, retval] VARIANT * pvarValue);

Parameters

pwchName [in]
The property's name (zero-terminated Unicode string).
pvarValue [out, retval]
The corresponding data type for the property.

Return Values

The following table lists the return values for the getProperty method.

Property Returns
declaration-handler
lexical-handler
max-xml-size
schemas
schema-declaration-handler
S_OK — The current value is returned.
charset
dom-node

xmldecl-encoding
xmldecl-version
xmldecl-standalone
xml-string
S_OK — The current value is returned.

E_FAIL — Not parsing.

Other properties E_INVALIDARG — The property is not recognized.

Remarks

The ISAXXMLReader interface recognizes the following properties:

"charset"
Externally defined encoding to use with an XML document. An example is the one used in the MIME-header. This setting takes priority over the default encoding, which is implicitly UTF-16, or over the encoding specified in the byte order mark (BOM) of the XML document header.
This property only affects documents that are parsed using the parse method. For any documents that are parsed using the parseURL method, this property is ignored. This property can be set at any time, but it only affects documents that are opened after it is set. For example, if it is set in the resolveEntity method (which is available when you implement a SAX entity resolver), it affects the external entity to be opened, but does not affect the main document, which is currently being parsed.
Datatype — BSTR* (The string value must be a recognized description of a character set that is valid for use with XML. For example, "US-ASCII", "UTF-8", etc.)
Default — Empty (uses either the BOM in XML header or the default encoding)
Access — Read/write.
"http://xml.org/sax/properties/lexical-handler"
This is an optional extension handler for lexical events like comments.
Datatype — ISAXXMLLexicalHandler.
Access — Read/write.
"http://xml.org/sax/properties/declaration-handler"
This is an optional extension handler for declaration events.
Datatype — ISAXXMLDeclHandler.
Access — Read/write.
"http://xml.org/sax/properties/dom-node"
Source DOM node for current SAX event. Only available when using parse method and SAX events are generated from an IXMLDOMNode object. Not available when using parseURL method for SAX parsing of a file.
Datatype — IXMLDOMNode.
Access — Read-only.
"http://xml.org/sax/properties/xml-string"
The literal string of characters in the XML source for the current SAX event.
Datatype — String (Visual Basic) / w_chart* (C/C++)
Access — Read-only.
"max-xml-size"
Sets the maximum size limit for XML documents that the SAX reader will parse. A positive integer value can be used to indicate the number of blocks of 1024 characters (i.e. for kilobytes for ASCII) that equal the maximum size to allow for an XML document. This property is equivalent of DOM property, MaxXMLSize. It has the same range of valid values, i.e. 0..(222-1). Notice, that this is size of the physically read data, so entities will contribute to this size only once, even if used many times. If an attempt to read an XML document larger than the specified limit occurs, the method used (either parse or parseURL) will return an error code of 0XC00CEE01.
Datatype — VARIANT/INT(VT_I4), 0 means unlimited, negative values are error.
Default — 0 (unlimited)
Access — Read/Write.
"schemas"
An option for registering schemas with the SAX reader.
Datatype — XMLSchemaCache.
Access — (parsing) Read-only; (not parsing) Read/Write.
"schema-declaration-handler"
An option for registering a schema-based declaration handler with the SAX reader.
Datatype — Event handler that implements the IMXSchemaDeclHandler interface.
Access — Read/write.
"xmldecl-encoding"
Encoding declared in the XML header of the currently parsed document. This data is unavailable until the reader parses the XML header.
Datatype — BSTR*.
Default — Empty (if there is no XML declaration or if a property is not found).
Access — (parsing) Read: (not parsing) None.
"xmldecl-version"
Version declared in the XML header of currently parsed document. This data is unavailable until the reader parses the XML header.
Datatype — BSTR*.
Default — Empty (if there is no XML declaration).
Access — (parsing) Read; (not parsing) None.
"xmldecl-standalone"
Declared in the XML header of currently parsed document. This data is unavailable until the reader parses the XML header.
Datatype — BSTR* ("yes" or "no").
Default — Empty (if there is no XML declaration or if a property is not found).
Access — (parsing) Read; (not parsing) None.
Note   The "xmldecl-encoding", "xmldecl-version", and "xmldecl-standalone" properties provide information about the presence and content of the XML header. However, XML header information was designed for low-level reader and parser use, not for applications.

To view reference information for Visual Basic or C/C++ only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

putProperty Method

Applies to: ISAXXMLReader Interface