Windows Driver Kit: WDM Devices
Toaster Installation Package
Description
The Toaster Installation Package sample describes different approaches that end users take when adding new hardware to their computer and describes how to address these scenarios in a consistent, robust manner that works cooperatively with Plug and Play (PnP). This sample also outlines the mechanisms provided to facilitate additional vendor requirements such as the installation of value-added software. Theory of Operation
The installation of software to support an instance of a given device (known as "device installation" or "driver installation") is done in a device-centric fashion in the Microsoft Windows operating systems. A device INF file that matches up with one of the device's hardware or compatible IDs is used to identify the required driver files, registry modifications, and so on that are needed to make the device fully operational. This INF file, along with the files that are copied and a catalog that contains the digital signatures of the INF file and these other files, constitute what is known as a "driver package".
Because device installation is done for a specific instance of a device, the "natural" method of adding devices to a computer that is running a PnP operating system is by plugging in the device first, letting PnP find the device and automatically initiate an installation for that device. The device installation can then proceed by using a driver package that is supplied with the operating system, or a vendor driver package (which is supplied through a CD, the Internet, or some other distribution mechanism). When the device installation is initiated by the addition of hardware, this installation is termed a "hardware-first" device installation.
However, users can take an alternate approach to adding hardware to their computer. In this scenario, they first run a setup program (perhaps launched as an autorun application when the vendor-supplied CD is inserted). This setup program might perform installation activities and then prompt the user to insert their hardware. Upon the hardware's insertion, the vendor-supplied driver package (which was "pre-installed" by the setup program) is then found by PnP, and the installation proceeds as in the hardware-first scenario. When the device installation is initiated by running a setup program, this installation is termed a "software-first" device installation. This approach to adding new hardware is just as valid as the hardware-first scenario, and some vendors might even instruct their users (through documentation that is included with the hardware) that this method is the preferred method.
Vendors must support the hardware-first scenario (by providing a driver package that can be supplied to the Found New Hardware wizard with no "pre-configuration" performed by a setup program or other mechanism). Vendors can optionally also support the software-first scenario, but the actual installation of the device instance is done by PnP when the device arrives, as described above.
Vendors might also want to perform additional activities as part of the device installation. For example, the vendor might want to enable the user to optionally install one or more applications that are included with the device (for example, a scanner that ships with an image processing application). Such software is termed "value-added software". Value-added software is distinct from the files that make up the driver package because, unlike the core driver files, the device does not require value-added software to function properly. In the previous example of a scanner, for example, perhaps the user already has an image processing application that they prefer. The user should be given the option of whether or not they want to install any value-added software. Additional activities (such as enabling the user to select value-added software offerings) can be accomplished by using a vendor-supplied device-specific co-installer.
Implementation and Design
This sample contains inf, toastapp, toastcd, toastco, and toastva directories. The following summary describes the directories and key files.
inf
This directory contains the device INF file (toastpkg.inf) that is used in device installation of toaster devices that the toaster bus enumerator enumerates. It registers a device-specific co-installer (tostrco2.dll) that provides additional functionality during the installation. Also contained in this directory is the autorun.inf file that is placed in the root of the vendor's setup media (for example, CD-ROM). This INF file starts the toastva.exe application (described below) when the media is inserted in an autorun-capable drive, or when the user double-clicks the drive icon in Windows Explorer. Additionally, this INF file illustrates the [DeviceInstall] section that is a new feature introduced in Windows XP for autorun INF files:
[DeviceInstall]
DriverPath=\
The DriverPath entry in a [DeviceInstall] section indicates to the Found New Hardware and Update Driver wizards that Plug and Play (PnP) should search for device INF files in the specified directory only. This feature provides a performance improvement for media layouts that contain many subdirectories, because the default behavior is for PnP to recursively search the entire CD. Additionally, specifying no DriverPath entry in this section indicates that the CD contains no drivers, so PnP can quickly determine that it can ignore this media. Absence of the [DeviceInstall] section causes the media to be treated as it was in previous versions of Windows (for example, as in Windows Me and Windows 2000, the entire media is searched recursively for applicable INF files).
toastapp This directory contains the source code for the toastapp.exe program that is used as value-added software that the user can optionally install as part of device installation. This program is installed through the InstallShield setup program in the toastcd\ToastApp directory.
toastcd This directory contains the CD image that would be used by the vendor to distribute the toaster package. In the root of the image is the autorun.inf file that launches either the x86-based or Itanium-based version of toastva.exe (depending on the platform). Also in the root is the device INF file, toastpkg.inf, and the two associated catalogs, tostx86.cat and tostia64.cat, for the x86-based and Itanium-based platforms respectively. Finally, the root also contains the zero-length tag file (toastpkg.tag) that is used to identify the media in case it must be prompted for. This tagfile is referenced in the SourceDisksNames sections of toastpkg.inf: [SourceDisksNames.x86]
1 = %DiskId1%, toastpkg.tag,,\i386
[SourceDisksNames.ia64]
1 = %DiskId1%, toastpkg.tag,,\ia64
The i386 and ia64 subdirectories contain the driver files that, along with the INF and CAT files, constitute the driver package. These files are toaster.sys, tostrcls.dll, and tostrco2.dll. Their corresponding debug (.PDB) files are located there as well, although these are not installed. Additionally, as mentioned above, the toastva.exe program (and its .PDB file) is located here. Note that this program is not part of the driver package—it is merely used to facilitate software-first installation. Because this executable is not part of the driver package, you can modify it without affecting the digital signature of the package.
Finally, the ToastApp subdirectory contains the setup.exe program that installs the value-added software package, toastapp.exe. This setup.exe is a standalone package that contains the files it installs within this single binary. This portion is meant to represent an example of the kind of software that might be supplied to a vendor by an ISV for distribution with that vendor's hardware. While this particular setup program was authored with InstallShield, other installation methods are equally valid. For example, the setup program could have been written by using C/C++, directly leveraging the Microsoft Installer (MSI) application programming interfaces (API).
The tostrco2.dll module is constructed so that there is no requirement about how the value-added software is installed—it simply creates a process to initiate the setup program and then waits for that process to end before continuing. For the sample, the description of the value-added software offerings and details of starting the value-added setup application are hard-coded, but in a real-world scenario, the value-added software supplied might be listed in some sort of data file (perhaps an INF file) and the value-added software selection page would be completely data driven, by using the information that is contained in that data file. This scenario would be advantageous, for example, because a vendor could submit just their core driver package for Windows logo testing without any value-added software (and without this data file). The vendor could then construct setup media that contains the core driver package plus value-added software as they see fit. The contents of their setup media could be modified at any time by adding or removing value-added software, and no changes to the core driver package would be required (hence, no need to re-submit for Windows logo testing). This scenario works because the data file that contains details about the value-added software offerings is not a part of the driver package and thus can be changed without affecting that package. A co-installer DLL that is written to accommodate such a scheme could have default behavior that would not display the value-added software selection page in the absence of this data file.
toastco This directory contains the co-installer (tostrco2.dll), which is used during device installation of toaster devices that are enumerated by the toaster bus enumerator. This co-installer supplies a finish-install wizard page that enables the user to select the value-added software, if any, that they wish to install. It does not supply a finish-install wizard page if the user has previously responded to the wizard page (whether or not they opted to install value-added software) so that the user is not prompted multiple times in the case where they plug in multiple toasters (or the same toaster is plugged into multiple ports, which appears to Plug and Play (PnP) as different instances of that device). This DLL also supplies the same value-added software selection page for use by the toastva.exe setup program. This setup avoids code duplication and ensures a consistent user experience for the hardware-first and software-first scenarios.
Finally, this co-installer performs the same function as its version 1 counterpart (in the coinstaller directory under the main toaster directory). It provides a friendly name for the device that incorporates its serial number. However, this version retrieves the friendly name template from the INF file, and because the template is stored in the [Strings] section, it can be localized for other languages.
The reason this co-installer’s filename includes version number is to illustrate the technique that must be used when updating the driver for a device that might already have a previous version of the co-installer installed. If the name is not changed, the old co-installer is loaded early-on during the processing of DIF codes, and the updated version cannot “get in the loop” to perform its new actions when installing the device. Thus, co-installers should include a version number in their filename, so that the new version can be copied and can participate in the device installation.
toastva This directory contains the autorun installation application, toastva.exe, which is launched when the user inserts the vendor-provided CD. This application is used to "pre-install" the necessary INF and catalog files, along with any value-added software the user chooses. In addition, it uses the UpdateDriverForPlugAndPlayDevices API to update the existing installed drivers for any toasters that might already be present. Examples of scenarios where this would apply are: - The user previously plugged in a toaster, and there was no in-box support (that is, no supporting driver was included with the Windows operating systems) for it. The user did not supply a vendor provided driver package at that time (perhaps because they did not have the media), so no driver was installed for the device (this situation is sometimes referred to as a "null driver install").
- The user previously plugged in a toaster, and there was in-box support for it (perhaps using an older or reduced-functionality driver).
- The user previously plugged in a toaster, and at that time supplied an older version of the driver provided by the vendor.
In all the above cases, the UpdateDriverForPlugAndPlayDevices API searches for any toaster device instances that matches the specified hardware or compatible ID and determines whether the specified driver package is "better" (that is, lower rank or newer). If so, the device instance is updated with the specified driver package.
Pre-compiled Module Information
| Module | Instructions for use |
|---|
| INF | This directory contains the device INF (toastpkg.inf) that is used in device installation of toaster devices that the toaster bus enumerator enumerates. |
| toastapp | This directory contains the source code for the toastapp.exe program that is used as value-added software that might optionally be installed by the user as part of device installation. |
| toastcd | This directory contains the CD image that that the vendor could use to distribute the toaster package. |
| toastco | This directory contains the co-installer, tostrco2.dll, which is used during device installation of toaster devices that the toaster bus enumerator enumerates. |
| toastva | This directory contains the autorun installation application, toastva.exe, which is started when the user inserts the vendor-provided CD. |
Building the Sample
- To build the Toaster Installation Sample components, you must first set up the WDK environment on your host computer. The Installation and Release Notes topic in the WDK has a complete description about how to do this.
- Run the build –cZ command in the src\general\toaster\toastpkg directory to build tostrco2.dll, toastapp.exe, and toastva.exe. Run the build –cZ command in the classinstaller and func subdirectories of the main Toaster directory (parent of the toastpkg directory) to build tostrcls.dll and toaster.sys. The toastcd directory contains all these components already built with full debugging information. The reason is so that the sample could be digitally signed (thus exactly reproducing the ideal user experience).
To experiment with certain behaviors of this package (for example, toastva.exe started through CD autorun), you must copy the entire contents of the toastcd tree onto a writeable CD.
Testing
The sample can be run in two different ways, corresponding to the hardware-first and software-first scenarios.
Hardware-First Device Installation Walk-Through
Simulate the plugging in of a toaster by typing enum -p 1 at a command prompt (see the documentation for the toaster sample driver for more information about setting up the toaster bus enumerator and using the "enum" application to simulate plugging and unplugging of toaster devices).
Because there is no in-box driver for this device, the Found New Hardware wizard appears, prompting for a driver package. If you constructed the setup image on autorun-capable media (for example, writeable CD or DVD), you can insert that media in the drive, and Windows XP automatically initiates a driver search on that media. On Windows 2000, you must click Next to initiate the driver search on that media. If you constructed the setup image in a directory on your hard disk, you must select Install from a list or specific location (Advanced) and then click Next. On the next page, select Include this location in the search, and type the path to the directory. Clicking Next then initiates a driver search in the directory that you specified.
The install proceeds by using the toastpkg.inf file in the root of the install location. The co-installer, tostrco2.dll, assigns the device a friendly name during DIF_INSTALLDEVICE and supplies a value-add software selection wizard page in response to DIF_NEWDEVICEWIZARD_FINISHINSTALL. This page is supplied only if the user has not been given the option previously of selecting value-added software (of if they have since uninstalled the software). This enables subsequent toasters to be installed server-side, without any user interaction whatsoever (even if a non-admin user or no user is logged in).
Software-First Device Installation Walk-Through
If you constructed the setup image on auto-run capable media (for example, writeable CD or DVD), you can simply insert the media, and the toastva.exe program automatically starts. Note that toastva.exe suppresses itself when called while a device installation is in progress, which is why this application does not appear during the hardware-first scenario that is described above.
After the Welcome page, the wizard tries to update the driver for any existing toaster devices (through the UpdateDriverForPlugAndPlayDevices) API. If there are not any, it instead “pre-installs” the INF file by using the SetupCopyOEMInf API so that Plug and Play (PnP) automatically finds a match when the hardware is subsequently inserted. SetupCopyOEMInf also stores away information that enables PnP to know where the INF file came from, thus enabling the Found New Hardware wizard to prompt for media in the correct location if it ever needs to. In this scenario, it is presumed that the user will plug in their toaster upon completion of the wizard, when they are instructed to do so. As such, they should never actually be prompted to reinsert the CD, because they would not have removed it. However, if they had removed it, PnP would prompt them to reinsert it. It is possible to also “pre-install” all the driver files so that the user would never be prompted, even if they did remove the CD. The WDK has a discussion of this technique in the section titled “Writing a Device Installation Application” in the Device Installation section.
Next, the wizard displays the same value-add software selection page as the user would receive if they performed a hardware-first install, as described above. After clicking Next on this page, any selected applications are installed (the wizard is hidden while these setup processes run), and then the Finish wizard page appears. If the wizard did not find any devices during its call to UpdateDriverForPlugAndPlayDevices, it prompts the user to plug in their hardware now. When the user does plug in the hardware (that is, by typing enum –p 1), the install proceeds without requiring any user interaction.
Compatibility
OS
Windows Server 2008 Windows Vista Windows Server 2003 Windows XP
Build machine: CAPEBUILD