getElementsByTagName Method (IXMLDOMElement)

 

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

JScript 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.6.0");  
var nodeBook, nodelistAuthor;  
xmlDoc.async = false;  
xmlDoc.load("books.xml");  
if (xmlDoc.parseError.errorCode != 0) {  
   var myErr = xmlDoc.parseError;  
   WScript.Echo("You have error " + myErr.reason);  
} else {  
   nodeBook = xmlDoc.selectSingleNode("//book");  
   nodelistAuthor = nodeBook.getElementsByTagName("author");  
   WScript.Echo(nodelistAuthor.item(0).text);  
}  

Output

When used with the sample XML file (books.xml), this example returns the following message box output:

Gambardella, Matthew  

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.

Return Values

S_OK
The value returned if successful.

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.

Versioning

Implemented in: MSXML 3.0 and MSXML 6.0

Applies to

IXMLDOMElement

See Also

IXMLDOMNodeList