Obtain the IXMLDOMDocument* from the Primary Snap-in's IDataObject

The extension snap-in you are developing receives context information from the Applications snap-in relayed through Microsoft Management Console (MMC). This is performed through data objects, which are passed to your extension when the user selects it from the Applications snap-in context menu or properties sheet. As discussed in the topic, Working with Extension Snap-ins, MMC does not restrict how data exchange that uses the IDataObject interface.

The Group Policy preference snap-in and its extensions, including the Applications snap-in, performs the data exchange through implementing the IDataObject::GetDataHere method in data objects requested by MMC and passed on to Group Policy preference extensions. The call to IDataObject::GetDataHere returns an interface pointer to an IXMLDOMDocument object. This XML document is key to the integration with the Applications snap-in.

The XML document contains:

• The GUID of the extended item (root element CLSID attribute).
• The GUID registered by the plug-in, as explained in the following section (root element extid attribute).
• All display information for the snap-in item (root element).
• All configuration information for the CSE (Properties element).
• All filter information for the CSE (Filters element).
• All Common tab parameterization (root element).

The extension snap-in has the ability to modify, delete, or add to any of these parameters. The document must follow the Group Policy preferences schema. For more information, see Preferences Policy Message Syntax.

Note

To ensure compliance with the schema, generate data using the Group Policy Management Editor select a preference extension user interface for a built-in item, and then copy this format within the Applications snap-in extension.

 

[!Warning]
Do not change clsid or extid attributes within the XML document. Changing the root element clsid and extid attributes could cause unexpected behavior and is not supported.

 

Code Example

The following code example shows how your extension must obtain a pointer to the IXMLDOMDocument* from the Primary Snap-in IDataObject. A call to IDataObject::GetDataHere( &formatetc, &stgmedium ) returns a 32-bit interface pointer to an IXMLDOMDocument object. At a minimum, this document is kept in scope for the life of the property sheet. The IXMLDOMDocument interface is reference-counted as the result of the IDataObject::GetDataHere query, and as such must be released when the property sheet extension is destroyed. Be aware that the life of a property sheet extension ends when the property sheet is closed. The IXMLDOMDocument object is then released by MMC.

The below code sample can be used without modification. For more information and a full code example see the AppExt.cpp included in, Applications Snap-in Extension Sample Code.

   CLIPFORMAT cfApmXMLDOM = (CLIPFORMAT) ::RegisterClipboardFormatW( CCF_AUTOPROF_XMLDOM );

   FORMATETC formatetc = { cfApmXMLDOM, NULL, DVASPECT_CONTENT, -1, 
      TYMED_HGLOBAL }; 

   STGMEDIUM stgmedium = { TYMED_HGLOBAL, NULL };

 stgmedium.hGlobal = GlobalAlloc( GMEM_SHARE, sizeof( m_pXmlDom ) );

   HRESULT hr = lpIDataObject->GetDataHere( &formatetc, &stgmedium );

   bool bHaveDom = false;
   bool bAddPage = false;
   
   if ( SUCCEEDED( hr ) )
   {
      LPBYTE pbNewData = 
      reinterpret_cast<LPBYTE>( ::GlobalLock( stgmedium.hGlobal ) );

      if ( pbNewData == NULL )
      {
         hr = E_UNEXPECTED;
      }
      else
      {
         ::CopyMemory( &amp;m_pXmlDom, pbNewData, sizeof( m_pXmlDom ) );

         if ( !::GlobalUnlock( stgmedium.hGlobal ) )
         {
            hr = HRESULT_FROM_WIN32( GetLastError() );
         }
         else
         {
            bHaveDom = true;
         }
      }
   }

   if ( stgmedium.hGlobal != NULL )
   {
      if ( ::GlobalFree( stgmedium.hGlobal ) != NULL )
      {
         hr = HRESULT_FROM_WIN32( GetLastError() );
      }
   }