replaceChild Method

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

Replaces the specified old child node with the supplied new child node.

Script Syntax

var objXMLDOMNode = oXMLDOMNode.replaceChild(newChild, oldChild);

Remarks

Script Parameters

  • newChild
    Object. Address of the new child that is to replace the old child. If Null, oldChild is removed without a replacement.
  • oldChild
    Object. Address of the old child that is to be replaced by the new child.

Script Return Value

Object. Returns the old child that is replaced.

C/C++ Syntax

HRESULT replaceChild(
  IXMLDOMNode* newChild,
  IXMLDOMNode* oldChild,
  IXMLDOMNode** outOldChild
);

Remarks

C/C++ 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, retval] 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.

Requirements

Header msxml2.h, msxml2.idl
Library uuid.lib
Windows Embedded CE Windows CE .NET 4.0 and later

General Remarks

This operation depends on the value of the nodeType property.

NODE_ATTRIBUTE

This operation depends on the value of the newChild parameter:

Value Description

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.

Value Description

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

Value Description

NODE_ATTRIBUTE, NODE_DOCUMENT, NODE_DOCUMENT_TYPE

Returns an error. These nodes 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. 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.

Value Description

NODE_CDATA_SECTION, NODE_COMMENT, NODE_ELEMENT, NODE_ENTITY_REFERENCE, NODE_TEXT, NODE_PROCESSING_INSTRUCTION

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

This method applies to the following objects and interfaces:

IXMLDOMAttribute, IXMLDOMCDATASection, IXMLDOMCharacterData, IXMLDOMComment, DOMDocument, IXMLDOMDocumentFragment, IXMLDOMDocumentType, IXMLDOMElement, IXMLDOMEntity, IXMLDOMEntityReference, IXMLDOMNode, IXMLDOMNotation, IXMLDOMProcessingInstruction, IXMLDOMText, and IXTLRuntime.

See Also

Concepts

nodeType Property