Using IPropertySheetProvider Directly
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:
- Snap-ins that display wizards must directly use the IPropertySheetProvider interface to specify wizard sheets. For more information, see Adding Wizard Pages: Implementation Details.
- Snap-ins that display property sheets in response to user actions other than the activation of the properties verb must directly use the IPropertySheetProvider interface.
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
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.
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.
InvokePropSheet, call the IPropertySheetProvider::CreatePropertySheet method to create a property sheet.
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.
InvokePropSheet, call the IPropertySheetProvider::AddExtensionPages method to allow extensions to add their own property pages to the property sheet.
InvokePropSheet, call IPropertySheetProvider::Show to display the wizard.
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.
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.
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.