Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - DOM Reference

getElementsByTagName Method (IXMLDOMElement)

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

[Script]

Script Syntax

var objXMLDOMNodeList = oXMLDOMElement.getElementsByTagName(tagName);

Parameters

tagName
A string specifying the name of the element to find. The tagName value "*" matches all descendant elements of this element.

Return Value

An object. Returns IXMLDOMNodeList object containing all elements that match the supplied name.

Example

var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.5.0");
var nodeBook, nodelistAuthor;
xmlDoc.async = false;
xmlDoc.load("books.xml");
if (xmlDoc.parseError.errorCode <> 0) {
   var myErr = xmlDoc.parseError;
   alert("You have error " + myErr.reason);
} else {
   nodeBook = xmlDoc.selectSingleNode("//book");
   nodelistAuthor = nodeBook.getElementsByTagName("author");
   alert(nodelistAuthor.length);
}
[Visual Basic]

Visual Basic Syntax

Set objXMLDOMNodeList = oXMLDOMElement.getElementsByTagName(tagName)

Parameters

tagName
A string specifying the name of the element to find. The tagName value "*" matches all descendant elements of this element.

Return Value

An object. Returns IXMLDOMNodeList object containing all elements that match the supplied name.

Example

Dim xmlDoc As New Msxml2.DOMDocument50
Dim nodeBook As IXMLDOMElement
Dim nodelistAuthor As IXMLDOMNodeList
xmlDoc.async = False
xmlDoc.Load "books.xml"
If (xmlDoc.parseError.errorCode <> 0) Then
   Dim myErr
   Set myErr = xmlDoc.parseError
   MsgBox("You have error " & myErr.reason)
Else
   Set nodeBook = xmlDoc.selectSingleNode("//book")
   Set nodelistAuthor = nodeBook.getElementsByTagName("author")
   MsgBox nodelistAuthor.length
End If
[C/C++]

C/C++ Syntax

HRESULT getElementsByTagName(
    BSTR tagName,
    IXMLDOMNodeList **resultList);

Parameters

tagName [in]
The name of the element to find. The tagName value "*" matches all descendant elements of this element.
resultList [out, retval]
An IXMLDOMNodeList object containing all elements that match the supplied name.

C/C++ Return Values

S_OK
The value returned if successful.

C/C++ Example

// Find all Nodes with a particular tag.
BOOL DOMDocFindNodesWithTag()
{
   BOOL bResult = FALSE;
   CString strFindText (_T("author"));
   IXMLDOMNodeList *pIDOMNodeList = NULL;
   IXMLDOMNode *pIDOMNode = NULL;
   long value = 0;
   BSTR bstrItemText = NULL;
   HRESULT hr;

   try
   {
      // Create the DOMDocument and initialise m_pIXMLDOMDocument2.
      // Find all "author" elements. 
      hr = m_pIXMLDOMDocument2->getElementsByTagName(
(TCHAR *)strFindText.GetBuffer(0), 
&pIDOMNodeList);
      SUCCEEDED(hr) ? 0 : throw hr;
      
      // Get the length of the list returned by the previous find.
      hr = pIDOMNodeList->get_length(&value);
      if(SUCCEEDED(hr))
      {
         pIDOMNodeList->reset();
      // Loop through the elements found and display the contents.
         for(int ii = 0; ii < value; ii++)
         {
            hr = pIDOMNodeList->get_item(ii, &pIDOMNode);
            SUCCEEDED(hr) ? 0 : throw hr;
            if(pIDOMNode)
            {
               hr = pIDOMNode->get_text(&bstrItemText);
               SUCCEEDED(hr) ? 0 : throw hr;
               if(bstrItemText)
               {
                     bResult = TRUE;
                     ::MessageBox(NULL, bstrItemText, strFindText, MB_OK);
                     ::SysFreeString(bstrItemText);
                     bstrItemText = NULL;
               }
               pIDOMNode->Release();
               pIDOMNode = NULL;
            }
         }
         pIDOMNodeList->Release();
         pIDOMNodeList = NULL;
      }
   }
   catch(...)
   {
      if(pIDOMNodeList)
         pIDOMNodeList->Release();
      if(pIDOMNode)
         pIDOMNode->Release();
      if(bstrItemText)
         ::SysFreeString(bstrItemText);
      bResult = FALSE;
      DisplayErrorToUser();
   }

   return bResult;
}

Remarks

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

The IXMLDOMNodeList object is returned even if there are no matches. In this case, the length of the list will be set to zero.

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

The getElementsByTagName method simulates the matching of the provided argument against the result of the tagName property of IXMLDOMElement. When executed, it does not recognize or support namespaces. Instead you should use the selectNodes method, which is faster in some cases and can support more complex searches.

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

IXMLDOMNodeList

Applies to: IXMLDOMElement