Share via

Using IPropertySheetProvider Directly

  • Article

The IPropertySheetProvider interface allows snap-ins to display property sheets and wizards. Usually, snap-ins need not directly use IPropertySheetProvider to display a property sheet. Instead, snap-ins use the IPropertySheetCallback interface, which MMC supplies to them so that they can add their own property pages to the property sheet for a particular scope or result item.

The situations in which snap-ins must directly use the IPropertySheetProvider interface include:

For more information about that displays property sheets in response to the user activating the properties verb, see Adding Property Pages: Implementation Details. The rest of this section discusses how to use IPropertySheetProvider to display a property sheet independent of the properties verb.

Be aware that, regardless of whether or not a snap-in directly uses MMC's IPropertySheetProvider implementation, the IPropertySheetProvider methods call into the snap-in's IExtendPropertySheet implementation and supply an IPropertySheetCallback interface pointer so that the snap-in can add pages.

To use IPropertySheetProvider to display a property sheet

  1. Implement a procedure, say a function called InvokePropSheet, that is called when the user performs an action that causes the snap-in to invoke the wizard.

  2. Obtain an IPropertySheetProvider interface pointer by creating an instance of the MMC Node Manager. In the call to CoCreateInstance, set the rclsid parameter to CLSID_NodeManager, and the riid parameter to IID_IPropertySheetProvider.

  3. In InvokePropSheet, call the IPropertySheetProvider::CreatePropertySheet method to create a property sheet.

  4. In InvokePropSheet, call the IPropertySheetProvider::AddPrimaryPages method. The lpUnknown parameter in the method call specifies the IUnknown of the snap-in's IExtendPropertySheet implementation that is responsible for adding the property pages.

    • If the wizard sheet is for a scope item, set bScopePane to TRUE. Otherwise, set this parameter to FALSE.
    • If the snap-in should receive notifications via the MMCN_PROPERTY_CHANGE notification when the user changes any wizard properties, set the bCreateHandle parameter to TRUE.
    • If bCreateHandle is set to TRUE, the snap-in object that exposes IExtendPropertySheet to MMC must also expose either IComponent (if bScopePane == FALSE) or IComponentData (if bScopePane == TRUE) and handle the MMCN_PROPERTY_CHANGE notification in its IComponent::Notify (or IComponentData::Notify) implementation. The lpUnknown parameter should be a pointer to the IUnknown of this object. Be aware that non-namespace extension snap-ins need only implement IComponent::Notify (or IComponentData::Notify). The implementations of all other IComponent (or IComponentData) methods can return E_NOTIMPL.

    In MMC's AddPrimaryPages implementation, MMC calls back to the snap-in's IExtendPropertySheet2::CreatePropertyPages method.

  5. In InvokePropSheet, call the IPropertySheetProvider::AddExtensionPages method to allow extensions to add their own property pages to the property sheet.

  6. In InvokePropSheet, call IPropertySheetProvider::Show to display the wizard.

  7. Implement the IExtendPropertySheet2::CreatePropertyPages method.

    In the implementation of CreatePropertyPages:

    • If you set bCreateHandle to TRUE in the call to IPropertySheetProvider::AddPrimaryPages in Step 4., the handle parameter holds the handle value that the snap-in must specify in any future calls to MMCPropertyChangeNotify. The snap-in should cache this value for future use.
    • Define one or more wizard pages by filling the PROPSHEETPAGE structure for each of the pages with information about the page. Be aware that the standard size for a property page in an MMC console is 252 dialog units horizontally and 218 dialog units vertically.
    • For each PROPSHEETPAGE structure, call the API function CreatePropertySheetPage to create a page. The function returns a handle to the HPROPSHEETPAGE type that uniquely identifies the page.
    • Using the pointer to the IPropertySheetCallback interface passed to the snap-in in the call to the CreatePropertyPages method, call the IPropertySheetCallback::AddPage method to add each page to the wizard.

  8. Implement a dialog box procedure for each page. The pfnDlgProc member of each page's PROPSHEETPAGE structure should be set to the address of this procedure.

  9. The snap-in should call the MMCPropertyChangeNotify function if the user has changed any properties. As a result of this method call, an MMCN_PROPERTY_CHANGE notification is sent to the appropriate IComponent or IComponentData object. The snap-in should be prepared to handle this notification.

IPropertySheetProvider

Adding Wizard Pages

Adding Property Pages