Microsoft XML 2.5 SDK

IXMLDOMElement::getElementsByTagName Method

[This is preliminary documentation and subject to change.]

Returns a list of all descendant elements that match the supplied name.

Visual Basic Syntax

Set objXMLDOMNodeList = oXMLDOMElement.getElementsByTagName(tagName)

C/C++ Syntax

HRESULT getElementsByTagName(

    BSTR tagName,

    IXMLDOMNodeList **resultList);

Parameters

tagName

[in]
Name of the element to find. The string "*" matches all descendant elements of this element.

resultList

[out]
DOMNodeList object containing all elements that match the supplied name.

C/C++ Return Value

Returns S_OK if successful, or an error code otherwise.

Remarks

Elements appear in the order encountered in a preorder traversal of this element's tree.

Note that the IXMLDOMNodeList object is returned even if there are no matches. In such a case, the length of the list will be set to zero.

The IXMLDOMNodeList interface is live and immediately reflects changes to the nodes that appear in the list.

C/C++ Example

BOOL DOMElementGetElementsBytagName()
{
   BOOL bResult = FALSE;
   wstring strFindText (_T("AUTHOR"));
   IXMLDOMElement *pIXMLDOMElement = NULL;
   IXMLDOMNodeList *pIDOMNodeList = NULL;
   IXMLDOMNode *pIDOMNode = NULL;
IXMLDOMDocument *pIXMLDOMDocument = NULL;
HRESULT hr;
   long value;
   BSTR bstrItemText;
   
   try
   {
      // create an instance of DOMDocument and initialize pIXMLDOMDocument
      // load/create an XML fragment
      hr = pIXMLDOMDocument->get_documentElement(&pIXMLDOMElement);
      SUCCEEDED(hr) ? 0 : throw hr;

if(pIXMLDOMElement)
{
hr = pIXMLDOMElement->getElementsByTagName ((TCHAR*)strFindText.data(), &pIDOMNodeList);
      SUCCEEDED(hr) ? 0 : throw hr;
      
      if(pIDOMNodeList)
{      
bResult = TRUE;
      hr = pIDOMNodeList->get_length(&value);
      if(SUCCEEDED(hr))
      {
         for(int ii = 0; ii < value; ii++)
         {
            pIDOMNodeList->get_item(ii, &pIDOMNode);
            pIDOMNode->get_text(&bstrItemText);
            ::MessageBox(NULL, bstrItemText,strFindText.data(), MB_OK);
            ::SysFreeString(bstrItemText);
            pIDOMNode->Release();
            pIDOMNode = NULL;
         }
      }
pIDOMNodeList->Release();
pIDOMNodeList = NULL;
   }
         pIXMLDOMElement->Release();
}
   }
   catch(...)
   {
      if(pIXMLDOMElement)
         pIXMLDOMElement->Release();
   if(pIXMLDOMElement)
         pIXMLDOMElement->Release();
      if(pIDOMNode)
         pIDOMNode->Release();
      DisplayErrorToUser();
   }
   return bResult;
}