IXMLDOMEntity

MSXML 5.0 SDK

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

IXMLDOMEntity

Represents a parsed or unparsed entity in the XML document.

[C/C++]

Example

BOOL DOMEntityNotationName()
{
   BOOL bResult = FALSE;
   IXMLDOMEntity *pIXMLDOMEntity = NULL;
   BSTR bstrName ;
   HRESULT hr;

   try
   {
      pIXMLDOMEntity = GetFirstEntity();

      if(pIXMLDOMEntity)
      {
         hr =   pIXMLDOMEntity->get_notationName(&bstrName);
         ::MessageBox(NULL, bstrName, _T("Notation name"), MB_OK);
         bResult = TRUE;
         ::SysFreeString(bstrName);
         pIXMLDOMEntity->Release();
      }
   }
   catch(...)
   {
      if(pIXMLDOMEntity)
         pIXMLDOMEntity->Release();
      DisplayErrorToUser();
   }
   return bResult;
}
IXMLDOMEntity* GetFirstEntity()
{
   IXMLDOMNamedNodeMap *pIXMLDOMNamedNodeMapEntities = NULL;
   IXMLDOMEntity *pIXMLDOMEntity = NULL;
   IXMLDOMNode *pIXMLDOMNode = NULL;
   IXMLDOMDocument *pIXMLDOMDocument = NULL;
   HRESULT hr;

   try
   {
      // Create an instance of DOMDocument and initialize 
      // pIXMLDOMDocument.
      // Load/create an XML fragment.
      hr = pIXMLDOMDocument->get_doctype(&pIXMLDOMDocumentType);
      SUCCEEDED(hr) ? 0 : throw hr;

      if(pIXMLDOMDocumentType)
      {
         hr = pIXMLDOMDocumentType->get_entities 
            (&pIXMLDOMNamedNodeMapEntities);
         if(SUCCEEDED(hr) && pIXMLDOMNamedNodeMapEntities)
         {
            hr = pIXMLDOMNamedNodeMapEntities->nextNode(&pIXMLDOMNode);
            if(SUCCEEDED(hr) && pIXMLDOMNode)
            {
               hr = pIXMLDOMNode->QueryInterface(IID_IXMLDOMEntity, 
                  (void**)&pIXMLDOMEntity );
               SUCCEEDED(m_hr) ? 0 : throw m_hr;
               pIXMLDOMNode->Release();
            }
            pIXMLDOMNamedNodeMapEntities->Release();
         }
         pIXMLDOMDocumentType->Release();
      }
   }
   catch(...)
   {
      if(pIXMLDOMNode)
         pIXMLDOMNode->Release();
      if(m_pIXMLDOMNamedNodeMapEntities)
         m_pIXMLDOMNamedNodeMapEntities->Release();
      if(m_pIXMLDOMDocumentType)
         m_pIXMLDOMDocumentType->Release();
      DisplayErrorToUser();
   }
   // Release pIXMLDOMEntity when finished using it.
   // Release pIXMLDOMDocument when finished using it.
   return pIXMLDOMEntity;
}

Remarks

IXMLDOMEntity represents the entity itself rather than the entity declaration. The World Wide Web Consortium (W3C) Document Object Model (DOM) does not currently define an object that models the entity declaration.

According to the W3C DOM specification, an XML parser can completely expand entity references into entities before the structure model is passed to the DOM. When these entity references are expanded, the document tree does not contain any entity references.

When Microsoft® XML Core Services (MSXML) 5.0 for Microsoft Office validates the XML document, it expands external entities (except binary entities). The nodes representing the expanded entity are available as read-only children of the entity reference. The Microsoft implementation does not expand these entities when it is not validating.

The nodeName property contains the name of the entity.

The structure of the entity child list is exactly the same as the structure of the child list for the IXMLDOMEntityReference object with the same nodeName value.

Level 1 of the W3C DOM application programming interface (API) does not define a way to change entity nodes. (All IXMLDOMEntity object properties are read-only.)

Versioning

MSXML 2.0 and later

Requirements

Implementation: msxml5.dll, msxml2.lib

[C/C++]

Header and IDL files: msxml2.h, msxml2.idl

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

nodeName Property | IXMLDOMEntityReference | IXMLDOMEntity Members | DOMDocument