A custom property page provider adds new property pages or replaces default property pages for a specific device or class. A provider can be a separate DLL or it can be combined with the class installer or the control panel applet for the device. If combined with the installer, the provider must be distinct from any properties handling provided by the ClassInstall function of the installer.
Every property page provider exports the property page enumeration function, usually named EnumPropPages. The Device Manager dynamicly links and calls this function just before displaying the default property sheet to give the provider a chance to add pages or replace the default pages.
A provider must export dialog procedures to support the property pages it adds to the default property sheet. The dialog procedures process initialize values and process user input for the property pages when the Device Manager displays the property sheet. The Device Manager uses the PropertySheet function to display the properties sheet, so the dialog procedures for the individual pages must be prepared to process the messages and notifications associated with this function.
When the Device Manager calls EnumPropPages, it passes three arguments: the address of a DEVICE_INFO structure, the address of a AddPropSheetPageProc function, and a 32-bit value. The DEVICE_INFO structure identifies the device or class that the user has requested properties for. The 32-bit value is used by the Device Manager to keep track of internal processing and must not be changed.
You use the AddPropSheetPageProc function to add property pages to the default property sheet. The function requires two parameters: a handle of a valid property sheet page and the supplied 32-bit value. You create a valid property sheet page and retrieve its handle by using the CreatePropertySheetPage function. The AddPropSheetPageProc function returns TRUE if it added the page, FALSE otherwise.
To replace one or both default property pages, you add the replacement pages using AddPropSheetPageProc, then set one or both of these values in the Flags member of the DEVICE_INFO structure:
DI_GENERALPAGE_ADDED | Replaces the default general property page. |
DI_RESOURCEPAGE_ADDED | Replaces the default resources property page. |
If you replace a default page, your replacement page must provide all the basic functions provided by that default page. If you do not replace a default page, the Device Manager uses the default page for the class or device as appropriate.
The EnumPropPages function returns TRUE to direct the Device Manager to display the property sheet or FALSE to prevent display.
Property page dialog procedures support property pages added by a provider. The procedures must adhere to the guidelines given for property sheets in the Microsoft Win32 Programmer's Reference. In particular, a dialog procedure must process any WM_NOTIFY messages appropriately.
A property page dialog procedure should also save the address of the DEVICE_INFO structure sent as the lParam parameter with the WM_INITDIALOG message. The Device Manager sends this structure to help the dialog procedure determine the device or class. Dialog procedures typically use the SetWindowLong to store this value in the DWL_USER portion of the window handle, then retrieve the address using the GetWindowLong function on subsequent messages.
If a reboot or restart is necessary due to the settings provided by the user, a dialog procedure show always set an appropriate value in the Flags member of the DEVICE_INFO structure. It must not send a PSN_GUISTART or PSN_REBOOT notification to the property sheet dialog procedure.