IXMLElement::addChild


		Contents Index Topic Contents
	Previous Topic: IXMLElement::put_text Next Topic: IXMLElement::removeChild

IXMLElement::addChild
HRESULT IXMLElement::addChild(
    [in] IXMLElement *pChildElem, 
    long lIndex, 
    long lReserved)
Adds a child to this element.
Returns S_OK if successful. E_INVALIDARG is returned if the index is inappropriate.

pChildElem
Address of the new child element.
lIndex
Index of the child collection at which this child should be added. If this is zero, it is added at the first element of the collection. If this is less than zero, the element is simply added to the end of the child collection.
lReserved
Should always be -1.

All the children and descendants of this new child element remain attached as before. Any element can have only one parent element, so the previous parent will lose this child from its subtree. Any threads that have already traversed the tree and expect this element to have the old parent will fail unpredictably. Note that it is possible to use this method to break off a subtree from one XML document and attach it to another XML document. However, there are some stringent restrictions on when this can be done:
There can be no outstanding references on collections on the child element or any of its descendants.
There can be no reference on any of the descendant elements of this child.

If these are not adhered to, an error will be returned.
The results when using the IXMLElementCollection::get_newEnum method from a collection obtained from this element are undefined if the enumerator is not reset.
Finally, the implementation of breaking off a node that has many children and attaching it to a tree of another document is somewhat more expensive than breaking off a node and attaching it to another node of the same document.

Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.