Finish-Install Wizard Pages

On Windows 2000 through Windows 7, a class installer or co-installer can supply finish-install wizard pages that Windows displays to the user after a device is installed but before Windows displays the standard Finish page. Windows supports finish-install wizard pages for PnP and non-PnP devices. The user interface for finish-install pages are displayed as wizard pages within the Found New Hardware Wizard.

Installers should supply finish-install pages only if the user must supply information before the device can operate correctly. If the information is optional, or if the information was previously supplied (for example, this is an upgrade for an existing device), an installer should not supply finish-install pages. If a device supports settings that can be set by a user after the device is installed, the installers should also supply one or more device property pages in response to DIF_ADDPROPERTYPAGE_ADVANCED.

An installer supplies finish-install wizard pages in response to a DIF_NEWDEVICEWIZARD_FINISHINSTALL request. Windows subsequently runs the finish-install wizard pages after all other installation operations are completed except for finish-install actions, and before it displays the standard Finish page. Windows runs finish-install wizard pages in the context of an administrator.

An installer supplies finish-install wizard pages by adding property sheet pages to the SP_NEWDEVICEWIZARD_DATA structure that is associated with a DIF_NEWDEVICEWIZARD_FINISHINSTALL request.

The following code example shows how an installer adds a custom page to the array of pages in the class install parameters:


// get the class install parameters by calling 
// SetupDiGetClassInstallParams 

// check whether NumDynamicPages has reached the max

// fill in the PROPSHEETPAGE structure

// add the page and increment the NumDynamicPages counter
NewDevWizardData.DynamicPages[NewDevWizardData.NumDynamicPages++] =
    CreatePropertySheetPage(&Page);

// apply the modified params by calling
// SetupDiSetClassInstallParams

For information about the CreatePropertySheetPage function, see the Microsoft Windows SDK.

If a finish-install wizard page collects settings from a user and the device has to be restarted to have the new settings take effect, the page dialog procedure calls SetupDiChangeState with a StateChange value of DICS_PROPCHANGE in the class installation parameters. This call to SetupDiChangeState directs the PnP manager to do the following:

  • Issue a query-remove request to determine whether the device can be removed without disrupting the system.

  • Remove the device.

  • Re-enumerate the parent of the device.

  • Rebuild the device stack of drivers.

  • Restart the device.

If an installer determines that the device cannot be dynamically removed and restarted, the installer can set the DI_NEEDREBOOT flag in the device install parameters instead of calling SetupDiChangeState. However, an installer should not force a system restart unless it is absolutely necessary.

Windows and the PnP manager attempt to install PnP devices in a trusted system context without requiring user response to dialog boxes. However, if an installer supplies finish-install wizard pages Windows is required to display those pages to the user. Windows terminates the trusted installation and performs an installation in the context of current user, if the user is an administrator, or in the context of the next administrator who logs on.

GUI-mode setup sends the DIF_NEWDEVICEWIZARD_FINISHINSTALL request for each device it installs, but GUI-mode setup cannot display installation wizard pages. If an installer supplies custom finish pages, GUI-mode setup marks the device so the user sees a New Hardware Found dialog box at first logon. The network configuration component of GUI-mode setup locates any network devices, such as ISDN boards, that have finish-install wizard pages, collects those pages, and incorporates them into the network setup wizard pages.

An installer should supply a Wizard 97 header title and a header subtitle in the PROPSHEETPAGE structure for a custom wizard page. An installer should not replace the system-supplied wizard title. See the Microsoft Windows SDK for documentation of the PROPSHEETPAGE structure and for more information about property pages.

Installers should supply finish-install wizard pages, regardless of the value of the DI_QUIETINSTALL flag. The sender of the DIF_NEWDEVICEWIZARD_FINISHINSTALL request determines whether to display the wizard pages and ensures that the pages are freed in either case.

An installer can use this DIF request to add custom wizard pages, but an installer cannot replace the system-supplied finish page.

By default, the Cancel button for finish-install wizard pages is disabled. If you want to allow the user to cancel out of your finish-install wizard pages, your installer must enable the Cancel button.

On Windows Vista and later versions, an installer can also supply finish-install actions that run in the context of an administrator after Windows runs finish-install wizard pages. Finish-install actions extend the capability that can be provided by finish-install pages.

For more information about DIF codes, see Handling DIF Codes.

 

 

Send comments about this topic to Microsoft

Show: