| Microsoft XML SDK 2.6 - XML Reference |  |
| Microsoft XML SDK 2.6 - XML Reference | |
Represents the top level of the XML source. Includes methods and properties used to obtain or create all other XML objects.
This interface inherits from IXMLDOMNode.
| abort* | Aborts an asynchronous download in progress. |
| async* | Indicates whether asynchronous download is permitted. |
| createAttribute | Creates a new attribute with the specified name. |
| createCDATASection | Creates a CDATA section node that contains the supplied data. |
| createComment | Creates a comment node that contains the supplied data. |
| createDocumentFragment | Creates an empty DocumentFragment object. |
| createElement | Creates an element node using the specified name. |
| createEntityReference | Creates a new EntityReference object. |
| createNode* | Creates a node using the supplied type, name, and namespace. |
| createProcessingInstruction | Creates a processing instruction node that contains the supplied target and data. |
| createTextNode | Creates a text node that contains the supplied data. |
| doctype | Contains the document type node that specifies the DTD for this document. |
| documentElement | Contains the root element of the document. |
| getElementsByTagName | Returns a collection of elements that have the specified name. |
| implementation | Contains a pointer to the XMLDOMImplementation object for this document. |
| load* | Loads an XML document from the specified location. |
| loadXML* | Loads an XML document using the supplied string. |
| nodeFromID* | Returns the node whose ID attribute matches the supplied value. |
| ondataavailable* | Property that specifies the event handler for the ondataavailable event. |
| ondataavailable* | Event that fires when data is available for processing. |
| onreadystatechange* | Property that specifies the event handler to be run when the readyState property changes. |
| onreadystatechange* | Event handler run when the readyState property changes. |
| ontransformnode* | Property that specifies the event handler to be run when transformNode is called. |
| ontransformnode* | Event handler run before each node of the XSL style sheet is applied to each node of the XML data source. |
| parseError* | Returns an XMLDOMParseError object that contains information about the last parsing error. |
| preserveWhiteSpace* | Indicates whether to preserve all white space in the XML document. |
| readyState* | Indicates the current state of the XML document. |
| resolveExternals* | Indicates that external definitions (resolvable namespaces, DTD external subsets, and external entity references) are to be resolved at parse time. |
| save* | Saves the XML document to the specified location. |
| url* | Returns the canonicalized URL for the last loaded XML document. |
| validateOnParse* | Indicates whether the parser should validate this document. |
* denotes an extension to the W3C DOM.
This object represents the top node in the tree. It implements all of the base DOM document methods and provides additional methods and properties that support XSL and XML transformations.
You can create the DOMDocument object and query for the other interfaces as follows:
HRESULT hr;
IXMLDOMDocument * pXMLDoc;
IXMLDOMNode * pXDN;
//...
hr = CoInitialize(NULL); // Check the return value, hr...
hr = CoCreateInstance(CLSID_DOMDocument, NULL, CLSCTX_INPROC_SERVER,
IID_IXMLDOMDocument, (void**)&pXMLDoc); // Check the return value, hr...
hr = pXMLDoc->QueryInterface(IID_IXMLDOMNode, (void **)&pXDN); // Check the return value.
Although there are many interfaces, only one object is created: the document. All other interfaces are accessed or created from the document.
The document can be created using either a free-threaded or a rental-threaded model. The behavior of the two models is identical; rental-threaded documents exhibit better performance because the parser doesn't need to manage concurrent access among threads. Note that you cannot combine nodes or documents that are created using differing threading models. The document threading model is determined by the following settings:
| Setting | Rental-threaded model | Free-threaded model |
|---|---|---|
| Version-independent ProgID | Msxml2.DOMDocument | Msxml2.FreeThreadedDOMDocument |
| Version-independent ClassID | f6d90f11-9c73-11d3-b32e-00c04f990bb4 | f6d90f12-9c73-11d3-b32e-00c04f990bb4 |
| Version-dependent ProgID | Msxml2.DOMDocument.2.6 | Msxml2.FreeThreadedDOMDocument.2.6 |
| Version-dependent ClassID | f5078f1b-c551-11d3-89b9-0000f81fe221 | f5078f1c-c551-11d3-89b9-0000f81fe221 |
| VB Class Name | Msxml.DOMDocument26 | Msxml.FreeThreadedDOMDocument26 |
In addition to the DOM interfaces, IXMLDOMDocument implements a number of standard COM interfaces. You can call the QueryInterface method on IXMLDOMDocument to get the following interfaces:
| Interface | Usage |
|---|---|
| IUnknown | DOMDocument is a wrapper object and each query for DOMDocument returns a new wrapper. You should only compare IUnknown interface pointers. |
| IconnectionPointContainer | Supports outgoing events ondataavailable and onreadystatechange through IPropertyNotifySink::OnChanged and IDispatch::Invoke. |
| IDispatch | Interface used by Visual Basic. |
| IDispatchEx | Interface used by dynamic late-bound scripting languages such as VBScript and JScript. This is not fully implemented. The following methods always return E_NOTIMPL: DeleteMemberByName or DeleteMemberByDispID, GetMemberProperties, GetMemberName, GetNextDispID, and GetNameSpaceParent. |
| IMarshal | Can be used to get a FreeThreadedMarshaler for a free-threaded DOM document. This allows the free-threaded DOM document to be used in ASP shared Session and Application states for sharing XML documents across multiple clients in memory. |
| IObjectSafety | When the SetInterfaceSafetyOptions method is called with nonzero safety options, the Microsoft XML Parser (MSXML) will apply security rules before fetching XML data. |
| IObjectWithSite | Enables a host application to provide extra contextual information, such the base URL. |
| IOleCommandTarget | Used by an COM container to send an OLECMDID_STOP command to stop an asynchronous download. |
| IPersistMoniker | Provides control over how to bind the XML document to persistent data. Both synchronous and asynchronous loading are supported using BindToStorage on the given IMoniker. Save is not called; therefore the BindToStorage, IsDirty, and SaveCompleted methods return E_NOTIMPL. |
| IPersistStream | Used to save and load the XML document to and from an IStream. |
| IPersistStreamInit | Updated version of IPersistStream. |
| IProvideClassInfo | Provides an easy way to get ITypeInfo for the DOMDocument. |
| IStream | You can read and write directly to the document via the IStream that is returned. You cannot Seek during a Write operation, and the following methods are not implemented on this stream: SetSize, CopyTo, Commit, Revert, LockRegion, UnlockRegion, and Clone. This allows you to build an XML document efficiently by providing chunks of XML and calling Write on the stream. You can also use this to test the persistence of your current DOM document by calling "xmldoc1.save(xmldoc2)." The Save method uses this IStream interface. |
When the object-creation methods (such as createElement) are used on the document, nodes are created in the context of the document (the ownerDocument property of the node points to the document), but the node is not part of the document tree. The node is only part of the document tree when it is explicitly added to the tree by calling insertBefore, replaceChild, or appendChild (or for attributes, setAttributeNode).
Implementation: Msxml.dll
Header and IDL files: Msxml.h, Xmldom.idl
IXMLDOMNode Interface | XML DOM Persistence