Replaces the specified old child node with the supplied new child node in the set of children of this node, and returns the old child node.
Visual Basic Syntax
Set objXMLDOMNode = oXMLDOMNode.replaceChild(newChild, oldChild)
C/C++ Syntax
HRESULT replaceChild(
IXMLDOMNode *newChild,
IXMLDOMNode *oldChild,
IXMLDOMNode **outOldChild);
Parameters
newChild
[in]
Address of the new child that is to replace the old child. If NULL, oldChild is removed without a replacement.
oldChild
[in]
Address of the old child that is to be replaced by the new child.
outOldChild
[out]
Old child that is replaced. If null, no object is created.
C/C++ Return Values
S_OK
Value returned if successful.
E_INVALIDARG
Value returned if the newChild node cannot be inserted as a child of this node, when the specified oldChild is not a child of this node, or if oldChild is null.
E_FAIL
Value returned if an error occurs.
Remarks
In the case where newChild has an existing parent, the node is automatically removed from that parent before being inserted into its new location.
When moving a node, it retains its namespace information. Moving a node doesn't create a namespace declaration, but declarations are added when retrieving the XML source (via the IXMLDOMDocument::save or IXMLDOMNode::get_xml methods) to ensure that all namespaces are properly declared.
When inserting a node tree under another node that has a different owner document, the ownerDocument property for each inserted node is changed to match the owner document of its new parent.
When moving a node tree to another document, the content of all entity reference nodes contained therein is updated to conform with the new document. So if the new document does not declare an entity that was moved into it, the entity reference will have no children, and the old content is removed. Existing references to nodes under the entity reference are still valid, but the node whose parent perviously was the entity reference now has a null parent.
This operation depends on the value of the nodeType property.
NODE_ATTRIBUTE
This operation depends on the value of the newChild parameter.
| NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_COMMENT, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ELEMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION | Returns an error. These node types cannot be children of an attribute. |
| NODE_DOCUMENT_FRAGMENT | Replaces oldChild with the children of the document fragment in newChild and returns oldChild. |
| NODE_ENTITY_REFERENCE, NODE_TEXT | Replaces the specified oldChild with the supplied newChild and returns oldChild. |
| NODE_CDATA_SECTION, NODE_COMMENT, NODE_ENTITY, NODE_NOTATION, NODE_PROCESSING_INSTRUCTION, NODE_TEXT | Returns an error. These node types either cannot have children or their children are read-only. |
NODE_DOCUMENT
This operation depends on the value of the newChild parameter.
| NODE_ATTRIBUTE, NODE_CDATA_SECTION, NODE_DOCUMENT, NODE_ENTITY, NODE_ENTITY_REFERENCE, NODE_NOTATION, NODE_TEXT | Returns an error. These nodes are not valid as children of a document node. |
| NODE_COMMENT, NODE_PROCESSING_INSTRUCTION | Replaces the specified oldChild with the supplied newChild and returns oldChild. |
| NODE_DOCUMENT_TYPE, NODE_ELEMENT | Replaces oldChild with newChild and returns oldChild. Note, however, that by definition an XML document (the Document node) can have only a single child. Therefore, an error is returned if the Document node already has a child. |
| NODE_DOCUMENT_FRAGMENT | Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. Note that the insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted. |
| NODE_DOCUMENT_TYPE | Returns an error. The document type is read-only. |
NODE_DOCUMENT_FRAGMENT
This operation depends on the value of the newChild parameter.
| NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE | Returns an error. These node types are not valid as children of a document fragment. |
| NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_PROCESSING_INSTRUCTION, NODE_TEXT | Replaces the specified oldChild with the supplied newChild and returns oldChild. |
| NODE_DOCUMENT_FRAGMENT | Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. Note that the insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted. |
| NODE_ENTITY, NODE_NOTATION | Returns an error. Entities and notations are read-only and cannot be inserted into a document. |
NODE_ELEMENT
This operation depends on the value of the newChild parameter.
| NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_PROCESSING_INSTRUCTION, NODE_TEXT | Replaces the specified oldChild with newChild and returns oldChild. |
| NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE, NODE_ENTITY, NODE_NOTATION | Returns an error. These node types cannot be children of an element node. |
| NODE_DOCUMENT_FRAGMENT | Replaces the specified oldChild with the children of the document fragment (newChild) and returns oldChild. Note that the insert operations are subject to the rules for child nodes and can fail if the document fragment children represent node types that cannot be inserted. |
| NODE_ENTITY_REFERENCE | Returns an error. Although the child nodes of an entity reference are the expanded entity, the children cannot be modified. |