IXMLDOMNode::insertBefore

  • Article

banner art

Previous Next

IXMLDOMNode::insertBefore

The insertBefore method inserts a child node before the specified node or at the end of the list.

Syntax

  HRESULT insertBefore(
 IXMLDOMNode* pNewChild, 
 VARIANT varRefChild, 
 IXMLDOMNode** ppOutNewChild
);

Parameters

pNewChild

[in] Pointer to an IXMLDOMNode interface that represents the address of the new node to be inserted.

varRefChild

[in] VARIANT containing the address of the reference node. If this parameter is NULL, pNewChild is inserted at the end of the child list.

ppOutNewChild

[out] Pointer to a pointer to an IXMLDOMNode interface containing the child node that was successfully inserted. This method calls AddRef internally. To avoid memory leaks, you must call Release when you are finished using the interface.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

When inserting a new child node into a list of existing nodes, the new child must be a valid child type for the existing parent node. The following tables list which child node types are valid and not valid for the parent node types specified.

The following table lists possible child node types for the parent node type NODE_ATTRIBUTE.

Child node type Description
NODE_ATTRIBUTE
NODE_COMMENT
NODE_ELEMENT		 Not valid. Returns an error. These node types cannot be children of an attribute.
NODE_PROCESSING_INSTRUCTION Not valid. Returns an error. This node type either cannot be a child of an attribute node or it is read-only.
NODE_TEXT Inserts pNewChild and returns pNewChild.

The following table lists possible child node types for the parent node type NODE_DOCUMENT.

Child node type Description
NODE_ATTRIBUTE
NODE_DOCUMENT
NODE_TEXT		 Not valid. Returns an error. These nodes cannot be children of a document node.
NODE_COMMENT
NODE_PROCESSING_INSTRUCTION		 Inserts pNewChild and returns pNewChild.
NODE_ELEMENT Inserts pNewChild and returns pNewChild. By definition, an XML document (the document node) can have only a single child element. Therefore, an error is returned if the document node already has a child element.

The following table lists possible child node types for the parent node type NODE_ELEMENT.

Child node type Description
NODE_ATTRIBUTE
NODE_DOCUMENT		 Not valid. Returns an error. These node types cannot be children of an element node.
NODE_COMMENT
NODE_ELEMENT
NODE_PROCESSING_INSTRUCTION
NODE_TEXT		 Inserts pNewChild and returns pNewChild.

The node supplied in varRefChild must be a child node of this node or NULL. The pNewChild is inserted before varRefChild in the child list. If varRefChild is NULL, pNewChild is inserted at the end of the child list. If varRefChild is not a child of this node, an error is returned.

Example Code

The following example retrieves a pointer to an IXMLDOMNode interface and inserts the node before the second child of the top-level node.

#include "wmsserver.h"
#include <atlbase.h> // Includes CComVariant and CComBSTR.

// Declare variables.
IWMSServer*         pServer;
IXMLDOMDocument*    pPlaylist;
IXMLDOMElement*     pXMLElement;
IXMLDOMNodeList*    pXMLNodeList;
IXMLDOMNode*        pXMLNodeNew;
IXMLDOMNode*        pXMLNodeRef;
IXMLDOMNode*        pXMLNodeCur;

HRESULT             hr;
VARIANT_BOOL        bIsSuccessful;
CComVariant         varFile;
CComVariant         varType;
CComVariant         varRef;
CComBSTR            bstrNamespace;
CComBSTR            bstrNamespaceURI;

// Initialize the COM library and retrieve a pointer
// to an IWMSServer interface.
hr = CoInitialize(NULL);
hr = CoCreateInstance(CLSID_WMSServer, NULL, CLSCTX_ALL, 
       IID_IWMSServer, (void**)&pServer);
if (FAILED(hr)) goto EXIT;

// Create the playlist object.
hr = pServer->CreatePlaylist(&pPlaylist);

// Load a sample playlist file.
varFile = "c:\\wmpub\\wmroot\\simple.wsx";
hr = pPlaylist->load(varFile, &bIsSuccessful);
if (FAILED(hr)) goto EXIT;

if (bIsSuccessful)
{
    // Retrieve a pointer to an IXMLDOMElement interface.
    hr = pPlaylist->get_documentElement(&pXMLElement);
    if (FAILED(hr)) goto EXIT;

    // Create a new node to insert.
    varType = NODE_ELEMENT;
    bstrNamespace = "seq";
    bstrNamespaceURI = "";
    hr = pPlaylist->createNode(varType, bstrNamespace,
                         bstrNamespaceURI, &pXMLNodeNew);
    if (FAILED(hr)) goto EXIT;

    // Retrieve a list of child nodes.
    hr = pXMLElement->get_childNodes(&pXMLNodeList);
    if (FAILED(hr)) goto EXIT;

    // Retrieve the second child node.
    hr = pXMLNodeList->get_item(1, &pXMLNodeRef);
    if (FAILED(hr)) goto EXIT;

    // Insert the new node before the second child node.
    varRef = pXMLNodeRef;
    hr = pXMLElement->insertBefore(pXMLNodeNew, varRef, &pXMLNodeCur);
    if (FAILED(hr)) goto EXIT;
    varRef.Clear();
}

EXIT:
    // TODO: Release temporary COM objects and uninitialize COM.

Requirements

Header: wmsserver.h.

Library: WMSServerTypeLib.dll.

Platform: Windows Server 2003 family, Windows Server 2008 family.

See Also

Previous Next