Device Installation Rules and Guidelines For Windows Vista

Device Installation Rules and
Guidelines for Windows Vista

WinHEC 2006 Version - May 9, 2006
Abstract
This paper provides preview information about device installation for Microsoft®
Windows Vista™. Manufacturers can use the information in this paper to anticipate
changes and to design driver installation programs for the release of Windows
Vista.
The rules that driver packages must follow to be installed successfully in Windows
Vista represent best practices for Microsoft Windows Server™ 2003, Microsoft
Windows XP, and earlier versions of Microsoft Windows®. Existing driver packages
that implement these best practices should require few if any changes to work for
Windows Vista. The guidelines in this paper for Windows Vista may become rules in
later Windows operating systems.
This information applies for the following operating systems:
Microsoft Windows 2000
Microsoft Windows XP
Microsoft Windows Server 2003
Microsoft Windows Vista
Future versions of this preview information will be provided in the Windows Driver
Kit.
The current version of this paper is maintained on the Web at:
http://www.microsoft.com/whdc/driver/install/default.mspx
Contents
Introduction.............................................................................................................................. 3
Device Installation in Windows Vista.......................................................................................4
Driver Store User Interface: Validating Trust and Licensing...............................................5
Driver Store: Placing Packages on the Local System.........................................................6
Update Install User Interface...............................................................................................7
Core Device Installation: Copying Files and Modifying the Registry...................................7
Finish-Install User Interface: Offering Optional User Interaction.........................................7
Device Installation Rules and Guidelines for Windows Vista...................................................8
Accessing and Modifying Registry Values..........................................................................9
Accessing and Modifying Device Properties.....................................................................15
Accessing and Modifying Files..........................................................................................16
Rules for Device Driver Information (.inf) Files.................................................................16
Calling Device Installation Functions................................................................................17
Software-First Installations................................................................................................18
General Rules for Class Installers and Co-Installers........................................................19
Checklist: Summary Actions for Driver Developers...............................................................21
Resources.............................................................................................................................. 21
Glossary............................................................................................................................ 21
References........................................................................................................................ 22
Device Installation Rules and Guidelines for Windows Vista - 2
Disclaimer
This is a preliminary document and may be changed substantially prior to final commercial release of the
software described herein.
The information contained in this document represents the current view of Microsoft Corporation on the
issues discussed as of the date of publication. Because Microsoft must respond to changing market
conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot
guarantee the accuracy of any information presented after the date of publication.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES,
EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights
under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval
system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property
rights covering subject matter in this document. Except as expressly provided in any written license
agreement from Microsoft, the furnishing of this document does not give you any license to these
patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, e-mail
addresses, logos, people, places and events depicted herein are fictitious, and no association with any
real company, organization, product, domain name, email address, logo, person, place or event is
intended or should be inferred.
© 2004-2006 Microsoft Corporation. All rights reserved.
Microsoft, Authenticode, Windows, Windows Server, and Windows Vista are either registered
trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.

Introduction
Microsoft® Windows Vista™ introduces an improved device installation architecture
that is more simple, user friendly, flexible, and secure than device installation for
earlier versions of Microsoft Windows®.
This paper provides preview information about device installation for Windows
Vista, including rules and guidelines for driver packages. Driver packages that do
not follow these rules and guidelines might not be installable on later versions of
Windows, beginning with Windows Vista.
For definitions of terms in this paper, see "Resources" at the end of this paper.
Solutions to problems with existing device installation. The Windows Vista
device installation architecture solves problems with existing device installation on
Windows XP and earlier versions of Windows. Issues addressed include:
 Server-side versus client-side installation. For current versions of
Windows, class installers and co-installers must follow different rules, including
different security rules, depending on whether installation occurred in the
context of the user (client-side installation) or in the context of the system
(server-side installation). In addition, presenting a user interface during server-
side installation can hang Plug and Play.
The Windows Vista device installation architecture eliminates client-side
installation. The same rules apply to class installers and co-installers at all
times, without exception.
 Files copied from the CD only when needed. Users of current versions of
Windows are prompted to insert product CDs to provide extra files that are
required after installation, which causes problems if the user cannot find the
CD.
For Windows Vista, all files in a driver package are copied into a driver store
and then loaded as they are required. To add functionality after initial
installation, the user does not need the CD.
 Digital signature issues. For current versions of Windows, the system
displays warnings for every unsigned driver installation, which troubles users
and causes them to unnecessarily lose confidence in drivers. Windows Vista
moves away from this user experience, although unsigned drivers still require
administrator authorization and display a warning.
For Windows Vista, all driver packages must be trusted to be installed. They
can be signed either by Microsoft through the Windows Logo Program or by
another trusted entity through Microsoft Authenticode® technology. On x86 and
IA64 versions of Windows Vista, unsigned drivers still cause user prompts.
However, administrators can trust unsigned drivers and stage them in the driver
store on users' local machines. This eliminates the need for users to elevate to
administrator privileges to install the driver and is useful in enterprise scenarios.
After a driver has been added to the store, it is considered to be trusted and can
be installed without prompts or administrator credentials.
On X64 versions of Windows, drivers must be signed and administrators cannot
install unsigned drivers. This ensures a more secure platform for X64 versions
of Windows.
For more information about the driver signing for x64 versions of Windows, see
the papers listed in "Resources" at the end of this paper.

 User rights. For current versions of Windows, the file system and registry
are protected with access control lists (ACLs). During client-side installation,
installation is subject to the ACLs of the file system, registry, and Plug and Play.
The user must be logged in as an administrator to install drivers.
For Windows Vista, the user is not required to be an administrator to install
drivers; instead, the installation rules engine checks the user's driver installation
policy to determine whether to permit installation. Domain administrators can
push drivers to many client systems at one time.
New device installation features. In addition to solving current problems, new

features planned for Windows Vista include the ability to:
 Install a specific driver on a specific device by using the new
DiInstallDevice function.
 Install an INF on every device for which it is applicable by using the new
DiInstallDriver function.
 Display the Update Hardware user interface by using the new
DiShowUpdateDevice function, which enables a driver installation package to
search Windows Update for updated drivers.
Rules that promote system reliability and stability. Under the Windows Vista
device installation architecture, devices and kernel-mode device drivers can be
installed only through approved device installation functions. These functions
restrict an external component's ability to access or modify the internal resources of
the device—the registry settings and files that the device installation architecture
uses—through unsupported means.
Using these device installation functions ensures that driver packages cannot take
actions that might conflict with other device installations, applications, or Windows
components and that, in the event of problems, that any installed driver can be
rolled back cleanly or uninstalled.
Driver packages that are designed to the Windows Vista device installation
architecture help to ensure that drivers and associated applications are removed
cleanly, without leaving files, state, or registry settings on the system that might
cause instability or loss of functionality. Such driver packages also help preserve
the stability and functionality of the system over time, as more devices are installed
and uninstalled. These benefits should help to reduce support costs for hardware
manufacturers and generate more device sales as consumers become more
confident in the installation experience.
Device Installation in Windows Vista

Note: The information in this section represents the current plan for Windows Vista,
which is subject to change. Further details will be available at Windows Vista RC1.

Device installation in Windows Vista takes place in stages, as shown in Figure 1.
Figure 1. Windows Vista Device Installation
The rest of this section explains the stages of driver installation on a computer that
is running Windows Vista.
Driver Store User Interface: Validating Trust and Licensing

At the beginning of installation, the user is prompted for any required information to
install the driver package, including validation of trust. The device installation engine
also checks the driver package for correct syntax, dependencies, and permission to
install. This stage occurs in the user context.
Driver Package Integrity

Software integrity has become a top priority for customers. Concerned by the
increase in malicious software on the Internet, these customers want to be sure that
their software has not been corrupted or tampered with. Code signing helps verify
software integrity. The Plug and Play driver signing behavior in Windows XP makes
it difficult for device vendors and corporate IT departments to deploy drivers in
some situations.
Windows Vista solves these problems by allowing vendors and IT departments to
sign and publish drivers by using an Authenticode signature. IT departments can
configure Windows to treat drivers that they signed as equivalent to drivers that
were signed by Microsoft, thus allowing an IT department to silently deploy drivers
across their corporation, even updating in-box drivers. Vendors can quickly deploy
emergency fixes to their customers without waiting for a signature from Microsoft.
Meanwhile, because these drivers are signed, IT departments and end users can
be secure, knowing that the drivers have not been altered in any way since they
were published. Further, users know the source of the drivers because the
signature also identifies the publisher.
These third-party signatures complement the signatures that Windows Hardware
Quality Labs (WHQL) gives. The third-party signatures guarantee driver integrity,
but do not imply any level of testing or quality. The signatures that are given as part
of the Windows Logo Program not only verify driver integrity, but also indicate a
level of quality that is based on tests run by WHQL.

Windows Vista contains several other changes and new features as a result of

allowing third-party signatures:
 Administrators can control which driver publishers Windows Vista trusts.
Windows installs drivers from trusted publishers without prompts and never
installs drivers from publishers that the user has chosen not to trust.
 Windows driver signing policy is always set to Warn, eliminating the Block
and Ignore options that were available in earlier versions of Windows.
 Windows treats all device setup classes equally. Certclas.inf no longer
exists.
 The ranking algorithm for choosing the best driver when Windows detects
several compatible drivers includes third-party signatures. By default, Microsoft
signatures take priority over third-party signatures, but IT departments can
configure them to be equivalent.
To ensure the integrity of all software that is running in kernel mode on x64 versions
of Windows, Windows Vista goes further and loads only signed kernel-mode
components.
Additional documentation on driver package integrity for third-party developers can
be found in the white paper titled Driver Package Integrity during Plug and Play
Device Installs in Windows Vista and in the Windows Driver Kit (WDK), under
sections titled "How Setup Selects Drivers" and "Signing Drivers for Development
and Test." Additional x64 information can be found in the white paper titled Digital
Signatures for Kernel Modules on x64-based Systems Running Windows Vista.
Driver Package Validation

Before a driver package is placed in the driver store, the user must have permission
to install the driver package. All security checks are performed before the driver
package is placed in the driver store.
Driver Store: Placing Packages on the Local System

After a driver package has passed integrity and syntax checks, the driver package
is copied to the driver store. The driver store is a secure location on the local hard
disk where the entire driver package is copied, including .inf files, catalog files, and
all files referenced by .inf files. Only the driver packages in the driver store can be
installed for a device.
All files in the driver package are considered to be critical to the installation. The .inf
file must copy all of the required files for device installation (that is, all files that are
referenced by a CopyFiles directive or a CatalogFile entry in the Version section)
so that all of the files are present in the driver store. If a co-installer references
another installer file (setup.dll), it must be part of the driver package. If the .inf file
references a file that is not included in the driver package, the driver package is not
placed in the store.
The following functions automatically place driver packages in the store. Class
installers and co-installers that call these functions are not required to do anything
else to place driver packages in the driver store:
SetupCopyOemInf
DiInstallDevice
DiInstallDriver
UpdateDriverForPlugAndPlayDevices

More information about the driver store architecture will be released on the WHDC
Web site.
Update Install User Interface

The optional update install user interface stage consists of a switch to user context
to update the user interface with status about the installation in progress before
starting core device installation.
Core Device Installation: Copying Files and Modifying the

Registry
At core device installation, the device installation engine copies files from the driver
store if necessary, modifies the registry, and sets Plug and Play properties for the
device.
During core device installation, an installer must be prepared to handle the following
device installation function codes:
DIF_ALLOW_INSTALL
DIF_INSTALLDEVICEFILES
DIF_REGISTER_COINSTALLERS
DIF_INSTALLINTERFACES
DIF_INSTALLDEVICE
The following DIF codes might also be sent during core device installation:
DIF_SELECTBESTCOMPATDRV
DIF_NEWDEVICEWIZARD_FINISHINSTALL
Core device installation always runs in the system context (noninteractive, server-
side installation). Interactive (client-side) installation is not supported in Windows
Vista. Installation fails if the installer prompts for a file. Installation hangs if a class
installer or co-installer attempts to display user interface (UI).
Core device installation always runs in a separate process. A new process is
created for each device installation. If the process does not finish in a prescribed
amount of time (the default is 5 minutes), the device installation engine proceeds as
if the process has stopped responding and ends it, so it is not possible for a bad
driver package or installer to hang the Plug and Play process.
Finish-Install User Interface: Offering Optional User Interaction

A driver package installer can optionally interact with the user by displaying finish-
install property pages. Use finish-install property pages to:
 Prompt the user to enter settings for the device.
 Install value-added software.
 Create an additional installation process.
After core device installation finishes, the device installation engine does the
following in the system context (that is, noninteractive):
 Sends the class installer or co-installer a
DIF_NEWDEVICEWIZARD_FINISHINSTALL request.
The class installer or co-installer should create any property pages to appear to
the user.

 Detects whether the class installer or co-installer provided any pages and
marks the device with CONFIGFLAG_FINISHINSTALL_UI.
This flag causes the device installation scheduler to launch this installer in the
user’s interactive process so it can display the finish-install property pages.
 Destroys the pages. (These resources must be released before changing to
user context, to prevent a memory leak.)
In user context (interactive), the device installation engine:
 Sends the class installer or co-installer another

DIF_NEWDEVICEWIZARD_FINISHINSTALL request.
The class installer or co-installer again creates any property pages to appear to
the user.
 Displays these finish-install pages to the user.
For best results, do not allow the user to continue the dialog procedure until the
separate installation process is finished because Windows may reboot after it thinks
all finish-install pages are complete.
To enable domain administrators to push installation of the driver package without
user interaction, design the class installer or co-installer so that it can be run by
using a script or unattended file and use the settings in this file instead of prompting
the user. Process these script files in the
DIF_NEWDEVICEWIZARD_FINISHINSTALL handler because that handler runs in
the system context.
For an example of using finish-install user interface in a driver package, see the
Toastpkg sample in the WDK.
 For more information about the device finish-install action, see the paper
titled Device Finish-Install Actions in Windows Vista, which is listed in
"Resources" at the end of this paper
Device Installation Rules and Guidelines for

Windows Vista
This section provides rules and guidelines for driver packages to be installed in
Windows Vista. They are organized in the following categories:
 How to access and use the registry
 How to modify or access device properties
 How to modify and access files
 Syntax rules for .inf files
 Rules for calling device installation functions
 Rules for software-first installations
 General rules for co-installers and class installers
Driver packages that do not follow these rules may not be installable on later
versions of Windows, beginning with Windows Vista. A subset of these rules and
guidelines are expected to become Windows Logo Program requirements.

Many of the rules that driver packages must follow to be installed successfully in
Windows Vista represent best practices for Windows Server 2003, Windows XP,
and earlier versions of Windows. Existing driver packages that implement these
best practices should require few if any changes to work for Windows Vista.
These rules can be summarized by the following general guidelines:
 Always use .inf files for device installation and make sure that all .inf files
are well formed.
 Use custom code (co-installers or class installers) only when absolutely
necessary.
 If you do use custom code, use only SetupAPI functions to access Plug and
Play structures.
 If you must interact with the user, use only finish-install actions or pages to
display user interface.
 Use the new driver install frameworks tools whenever possible.
 Do not make assumptions about the location, format, or meaning of registry
keys or values.
 Do not directly access or modify internal device settings.
 Do not access or change any protected data.
Applications must not use internal device state to discover and install devices, to
store and retrieve device properties, or to store and retrieve device settings.
Accessing and Modifying Registry Values

Rule #1 Do not enumerate devices from HKLM\SYSTEM\CurrentControlSet\Enum\
… to discover installed devices on the system
Registry keys do not contain the required information to enumerate installed
devices on the system. Other information is held by the Plug and Play manager,
such as whether the device is actually present or is a phantom device (one that is
not plugged in). The Plug and Play manager also performs additional filtering of
registry information. In addition, as for any registry key, the location, format, and
meaning of this key might change.
To enumerate installed devices safely:
 Use SetupDiGetClassDevs to retrieve a set of devices.
ClassGuid includes only devices for that setup class.
DIGCF_PRESENT Flags includes only devices that are present.
Enumerator includes only devices with a specific bus ID, such as USB, PCI,
PCMCIA, SCSI, or Root.
 Use SetupDiEnumDeviceInfo to enumerate the devices in the set.
The SP_DEVINFO_DATA structure ClassGuid field contains the device setup
class.
 Use SetupDiGetDeviceInstanceId to retrieve unique device instance
identifiers.
 Use SetupDiOpenDeviceInfo to locate a device directly from its device
instance identifier.

Rule #2 Do not modify registry values in DIREG_DRV

Do not modify the following registry values in a device’s software key
(DIREG_DRV):
DriverDate
DriverDateData
DriverDesc
DriverVersion
InfPath
InfSection
InfSectionExt
MatchingDeviceId
ProviderName
EnumPropPages32
The values of these properties represent a device’s installation state. Direct

modification of reserved properties may invalidate the device’s installation state. For
example, changing information related to the .inf file invalidates information about
driver files that are associated with such properties as device and driver signing
information. Changing driver version or driver date might break Windows Update
functionality.
Installation state is stored as protected properties, and installation-time only
restrictions are implemented for these properties in Windows Vista. Values may be
replicated for compatibility, and direct modification of values does not affect internal
state.
To customize device properties safely:
 Set properties that are not reserved.
For example, to change the name of the device as displayed to the user,
change its SPDRP_FRIENDLYNAME property.
 Use SetupDiGetDeviceProperty and SetupDiSetDeviceProperty to get
and set standard or custom properties in Windows Vista.
Reserved properties are protected.
Rule #3 Do not directly open a device’s software key

Do not open a device's software key at
HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}\nnnn. As with any registry
key, location or format might change. The device's software key should be opened
only after the corresponding device has been found.
In addition, do not use the SPDRP_DRIVER device property to determine the key
name; use of this property might be restricted in Windows Vista.
To open a device's software key:
 Use SetupDiCreateDevRegKey and SetupDiOpenDevRegKey and
specify DIREG_DRV KeyType.
 Kernel-mode callers should use IoOpenDeviceRegistryKey and specify
PLUGPLAY_REGKEY_DRIVER DevInstKeyType.

Rule #4 Do not directly open a device’s hardware key

Do not open a device's hardware key at
HKLM\SYSTEM\CurrentControlSet\Enum\*\*\*\Device Parameters. As with any
registry key, location or format might change. The device's hardware key should be
opened only after the corresponding device has been found.
To open or create a device's hardware key:
 Use SetupDiOpenDevRegKey and specify DIREG_DEV KeyType.
Request only necessary access rights. For details, see "Rule #12. Do not
require KEY_ALL_ACCESS or change default access rights granted to any
SetupDi-managed keys."
 Use SetupDiCreateDevRegKey and specify DIREG_DEV KeyType.
Do not rely on KEY_ALL_ACCESS access rights.
 Kernel-mode callers should use IoOpenDeviceRegistryKey and specify
PLUGPLAY_REGKEY_DEVICE DevInstKeyType.
Rule #5 Do not use SetupDiDeleteDevRegKey to delete device registry keys

SetupDiDeleteDevRegKey should not be used to delete any device registry keys,
including DIREG_DRV software keys and DIREG_DEV hardware keys, for several
reasons:
 SetupDiDeleteDevRegKey removes all custom settings in keys, including
settings that were specified during installation, settings that device drivers
stored, and settings that applications or other components stored. It also
removes critical device installation state. Internal state is protected in
Windows Vista.
 The global DIREG_DRV software key (DICS_FLAG_GLOBAL) contains
data that the device installation engine stored. (This will be addressed for
Windows Vista.) Configuration-specific keys (DICS_CONFIGSPECIFIC) do not
contain device installation engine state, but deleting them could have
implications for other components.
 The configuration-specific hardware key (DICS_FLAG_CONFIGSPECIFIC)
might contain data that the device installation engine stored. The global
DIREG_DEV key (DICS_FLAG_GLOBAL) contains no internal state, but
deleting it could have implications for other components.
Do not depend directly on the absence of these keys. When the device is
uninstalled, the system automatically deletes all DIREG_DEV and DIREG_DRV
keys.
Subkeys under DIREG_DEV and DIREG_DRV keys can be safely created and
deleted by using standard registry functions. This helps avoid naming collisions
between the system and other components. Subkeys should inherit default
permissions of parent keys.
Rule #6 Do not enumerate the device setup class keys to discover installed setup
classes
Do not enumerate the device setup class keys under
HKLM\SYSTEM\CurrentControlSet\Control\Class\… to discover installed setup
classes. As with any registry key, the location and format of device setup class keys
might change. In addition, the list of available classes might be generated in the
future from sources other than the registry.

To discover installed setup classes safely:

 Use SetupDiBuildClassInfoList to retrieve the set of device setup classes
that are currently installed on the system.
 Use SetupDiGetClassDescription to retrieve the description of an
installed class.
 Use setup class property function SetupDiGetClassRegistryProperty to
get setup class properties or SetupDiSetDeviceRegistryProperty with
SPCRP_* property codes to set setup class properties.
For Windows 2000, use CM_* function equivalents for setup class properties:
CM_Get_Class_Registry_Property and CM_CRP_* codes.
 Use SetupDiOpenClassRegKey to access persistent registry storage for
custom device setup class settings.
Rule #7 Do not directly open device setup class keys

Do not directly open device setup class keys at
HKLM\SYSTEM\CurrentControlSet\Control\Class or
HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}. As with any registry key,
the location and name of device setup class keys might change.
To open device setup class keys safely:
 Use SetupDiOpenClassRegKey.
 Use SetupDiOpenClassRegKeyEx and Specify DIOCR_INSTALLER with
Flags.
Rule #8 Do not directly open the device interface class keys

Do not directly open device interface class keys at
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses or
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{GUID}. As with any
registry key, the location and name of device interface class keys might change.
To open device interface class keys safely, use SetupDiOpenClassRegKeyEx and
specify DIOCR_INTERFACE with Flags.
Rule #9 Do not enumerate device setup class subkeys to open the software keys
for all devices in a setup class
Do not enumerate device setup class subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}\… to open the software
keys for all devices in a setup class. As with any registry key, the location, name, or
format of the key might change. In addition, keys should be opened only after the
corresponding device is located.
To enumerate device setup class subkeys safely:
 Use SetupDiGetClassDevs to retrieve all devices for a specified device
setup class.
 Use SetupDiEnumDeviceInfo to enumerate all devices in the set.
 Use SetupDiOpenDevRegKey with DIREG_DRV KeyType to open this
key for each device.
Some devices might not have DIREG_DRV keys (if not installed).

Rule #10 Do not enumerate device interface subkeys to discover device interfaces
on the system
Do not enumerate device interface subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{GUID}\… to discover
device interfaces on the system. As with any registry key, the location, name, or
format of the key might change. In addition, keys should be opened only after the
corresponding device interface is located.
To enumerate device interface subkeys safely:
 Use SetupDiGetClassDevs with the DIGCF_DEVICEINTERFACE flag set.
Set the DIGCF_PRESENT flag to include only enabled device interfaces.
Enumerator includes only device interfaces that are registered for a specific
device instance identifier.
 Use SetupDiEnumDeviceInterfaces to enumerate interfaces that are
registered for specified device interface class.
 Use IoGetDeviceInterfaces for kernel-mode callers.
Rule #11 Do not open, read, or write device interface subkeys to discover
attributes of device interfaces that are registered on the system
Do not open, read, or write device interface subkeys under
HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{GUID}\ … to discover
attributes of device interfaces that are registered on the system. As with any registry
key, the location, name, or format of the key might change. In addition, keys should
be opened only after the corresponding device interface is located.
To safetly discover attributes of device interfaces:
 Use SetupDiOpenDeviceInterface to locate a device interface and add it
to a set from its name.
 Use SetupDiGetDeviceInterfaceDetail to retrieve details for the device
interface.
The optional DeviceInfoData parameter retrieves the SP_DEVINFO_DATA
element for the device for which the interface is registered.
 Use persistent registry storage for custom device interface settings:
SetupDiCreateDeviceInterfaceRegKey to create a storage key.
SetupDiOpenDeviceInterfaceRegKey to open the storage key.
Use IoOpenDeviceInterfaceRegistryKey for kernel-mode callers.
Rule #12 Do not require KEY_ALL_ACCESS or change default access rights that
were granted to any SetupDi-managed keys
Customer problems have been traced to critical keys that were deleted by external
components or access rights of critical keys that were modified by external
components. In Windows Server 2003, SetupDiCreateDevRegKey grants only
KEY_READ and KEY_WRITE access, not KEY_ALL_ACCESS. Additional
KEY_ALL_ACCESS restrictions are enforced in Windows Vista.
To access keys safely:
 Use only supported functions to open SetupDi-managed keys.
These functions can be used to address common problems that result from
access rights restrictions.

 Request only the minimal access rights that are required for each task. For
example:
KEY_SET_VALUE
KEY_QUERY_VALUE
KEY_CREATE_SUB_KEY
KEY_ENUMERATE_SUB_KEYS
Rule #13 Use only .inf directives to modify protected registry keys
Class installers and co-installers may not call registry functions to create, change,
or delete registry keys, except under specified conditions. Registry keys should be
modified by using directives that are placed in .inf files.
Also, class installers and co-installers may not use SetupDiCreateDevRegKey,
SetupDiOpenDevRegKey, or SetupDIDeleteDevRegKey to add, delete, or
change the content of the software keys in the registry
(HKLM\SYSTEM\CurrentControlSet\Control\Class). Software keys should be
modified by using SetupAPI functions.
Exceptions. The following are exceptions to this rule that apply to more than one
function:
 Class installers and co-installers may, if necessary, use registry functions to
modify registry keys in the HKLM\Software subtree. Although this action is
permitted, it is not recommended and it might not be permitted in the future.
Alternate means of modifying the keys in this subtree, including SetupAPI
functions and directives placed in .inf files, should be used.
 Class installers and co-installers are permitted to modify registry keys in the
HKLM\System\CurrentControlSet\Control\CoDeviceInstallers key.
Rule #14 Do not modify protected registry values unless allowed

Class installers and co-installers may not call registry functions to create, change,
or delete protected registry values, except under specified conditions.
AllowUnadvisedGlobalSettings. The only exception is the HKLM\Software
subtree. Class installers and co-installers may, if necessary, use registry functions
to modify registry values in the HKLM\Software subtree. Although this action is
permitted, it is not recommended and it might not be permitted in the future.
Alternate means of modifying the values in this subtree, including SetupAPI
functions and directives placed in the .inf file, should be used.
General Exceptions. The following are exceptions to this rule that apply to more
than one function:
 Class installers and co-installers are permitted to modify RunOnce registry
entries, but the entries must consist only of calls to Rundll32.exe. Class
installers and co-installers should observe all restrictions on the use of
RunOnce in device .inf files, in particular the restriction that these registry
entries must be used solely for installations of software-only devices that are
enumerated by SWENUM, the software device enumerator.
 Class installers and co-installers may modify the CoInstallers32 and
EnumPropPages32 registry values when handling
DIF_REGISTER_COINSTALLERS requests.

Rule #15 Do not modify registry key security unless allowed

Class installers and co-installers may not modify the security of registry keys,
except under specified conditions.
Accessing and Modifying Device Properties

Rule #16 Do not open, read, or write keys or values in
HKLM\SYSTEM\CurrentControlSet\Enum\*\*\*\... to discover or change device
properties
Registry keys do not contain required information to discover or change device
properties. Plug and Play components such as SetupDi functions and the user-
mode and kernel-mode Plug and Play managers can contribute to the final property
value. In addition, the location, format, and meaning of these keys might change;
keeping their functionality independent of the backing store permits future
enhancements.
Public functions provide consistent behavior and enforce access rights to protect
these keys. In Windows Vista, keys that are already protected against write access
are also protected against read access. Use of supported SetupDi functions are
required.
To open, read, or write keys or values safely:
 Use supported SetupDi functions for device properties:
Use SetupDiGetDeviceRegistryProperty to get device properties.
Use SetupDiSetDeviceRegistryProperty with SPDRP_* property codes to set
device properties.
In Windows Vista, some properties are reserved for the device installation
engine.
 Use persistent registry storage for custom settings for devices that are
physically present and for those that are not.
Use SetupDiCreateDevRegKey to create a storage key.
Use SetupDiOpenDevRegKey to open the storage key.
DIREG_DEV KeyType persists until the device is uninstalled. DIREG_DRV
KeyType can be moved or cleared with a driver upgrade.
 Use IoGetDeviceProperty and IoOpenDeviceRegistryKey for kernel-
mode callers.
Rule #17 Do not set read-only properties or properties that the device installation
engine has reserved for use
Many properties have complex dependencies on other properties or device state.
For example, the values of SPDRP_CLASS, SPDRP_CLASSGUID, and
SPDRP_DRIVER must be consistent with each other.
Direct modification of reserved properties could invalidate device installation state.
For example, changing SPDRP_DEVICEDESC breaks backup, driver rollback, and
Windows Update.
In Windows Vista, installation-time-only restrictions will be implemented for reserved
properties.

The following properties are read only and can never be set with
SetupDiSetDeviceRegistryProperty:
SPDRP_ADDRESS
SPDRP_BUSNUMBER
SPDRP_BUSTYPEGUID
SPDRP_CAPABILITIES
SPDRP_DEVICE_POWER_DATA
SPDRP_ENUMERATOR_NAME
SPDRP_LEGACYBUSTYPE
SPDRP_PHYSICAL_DEVICE_OBJECT_NAME
SPDRP_REMOVAL_POLICY
SPDRP_REMOVAL_POLICY_HW_DEFAULT
SPDRP_UI_NUMBER
The following properties are writeable, but they are reserved for use by the device
installation engine and must not be set directly:
SPDRP_CLASS
SPDRP_CLASSGUID
SPDRP_DRIVER
SPDRP_DEVICEDESC
SPDRP_MFG
Rule #18 Do not change protected device properties

Class installers and co-installers may not change device properties except for the
friendly name (SPDRP_FRIENDLYNAME) and the upper and lower filter drivers for
the device (SPDRP_UPPERFILTERS and SPDRP_LOWERFILTERS).
Accessing and Modifying Files

Rule #19 Use only .inf directives to modify files
Class installers and co-installers may not call functions to move, copy, change, or
delete file objects or file content, except under specified conditions. Files should be
modified only by using directives placed in .inf files.
Rule #20 Do not copy files that have been deleted or renamed
Files that appear in a CopyFiles directive in the .inf file should not also appear in a
DelFiles or RenFiles directive in the .inf file. Class installers and co-installers that
use this method to copy or load a file that has been removed or deleted cause the
driver installation to fail.
Rules for Device Driver Information (.inf) Files

Rule #21 An .inf file must use valid structure and syntax
An .inf file must use valid structure and syntax to pass driver package validation
checks at the beginning of the installation process.
Use the ChkINF tool with the WDK to validate structure and syntax of .inf files.
Rule #22 An .inf file must contain valid [SourceDisksFiles] and

[SourceDisksNames] sections
An .inf file must contain valid [SourceDisksFiles] and [SourceDisksNames] sections.
The device installation engine does not copy the driver package into the driver store
unless these sections are present and filled in correctly.

Rule #23 Use the CopyInf directive to stage additional .inf files during installation
If you want to stage other .inf files during an installation that is driven by an .inf file,
use the CopyInf directive rather than the CopyFile directive.
Rule #24 Do not directly copy device driver .inf files to or delete files from
%SystemRoot%\INF
Copying or deleting .inf files from %SystemRoot%\INF invalidates the files' digital
signature and can cause file name collisions, which might invalidate existing
installed devices. In addition, .inf file store location, format, and protection might
change.
To copy or delete device driver .inf files safely:
 Use SetupCopyOEMInf to install device .inf files.
Save DestinationInfFileName for uninstall.
Use SP_COPY_NOOVERWRITE and SP_COPY_REPLACEONLY CopyStyle
to customize installation.
SetupCopyOEMInf provides automatic driver store functionality in
Windows Vista.
 Use SetupUninstallOEMInf to remove device INF files.
Uninstall all devices by using the corresponding driver package first, including
present and nonpresent devices.
 Do not use SUOI_FORCEDELETE to delete .inf files; default usage
provides safe default behavior.
Calling Device Installation Functions

See also "Rule #28. Do not call SetupDiCallClassInstaller with DIF codes in a
software-first installation to install a device."
Rule #25 Do not call protected SetupAPI functions

Class installers and co-installers may not call the following protected SetupAPI
functions, except under specified conditions:
SetupQueueCopy
SetupQueueCopyIndirect
SetupQueueCopySection
SetupQueueDefaultCopy
SetupQueueDelete
SetupQueueDeleteSection
SetupQueueRename
SetupQueueRenameSection
SetupScanFileQueue
SetupScanFileQueue is prohibited only when deleting items from the queue

(SPQ_SCAN_PRUNE_COPY_QUEUE).

Rule #26 Do not call default installation handler routines directly

Applications and co-installers must not call default installation handler routines
directly. Default installation handler routines include the following:
SetupDiInstallDevice
SetupDiRemoveDevice
SetupDiInstallInterfaces
SetupDiRegisterDeviceInfo
Default handlers may be called only by class installers while handling the
corresponding DIF code and only if not returning ERROR_DI_DO_DEFAULT.
Direct calls to default installation handler routines bypass all co-installers and class
installers and could invalidate the internal state of devices that installers store.
To call device installation routines safely:
 Use SetupDiCallClassInstaller where possible.
 Use UpdateDriverForPlugAndPlayDevices for installation.
Rule #27 Do not call deprecated CfgMgr functions

Applications and co-installers must not call CfgMgr functions that have been
superseded by SetupDi installation routines or DIF codes, such as
CM_Enable_DevNode, CM_Disable_DevNode, or CM_Uninstall_Devnode. For
information about which CM_Xxx functions are safe to use, see the WDK.
Direct calls to CfgMgr functions bypass all co-installers and class installers and
could invalidate the internal state of devices that installers store.
To call device installation routines safely:
 Use SetupDiCallClassInstaller for some DIF codes only.
 Use UpdateDriverForPlugAndPlayDevices for installation.
Software-First Installations
In a software-first installation, device driver files are staged on the system before
the device is plugged in. After the device is plugged in, the driver is installed from
the device.
Software-first installations should follow all rules for class installers and co-installers
that are described elsewhere in this paper, especially those that apply to accessing
and modifying Plug and Play resources. Existing software-first installation packages
may require changes to be compatible with the new Windows Vista device
installation architecture.
Rule #28 Do not call SetupDiCallClassInstaller with DIF codes in a software-first

installation to install a device
Calling SetupDiCallClassInstaller with specific DIF codes does not allow the
introduction of new DIF codes, which can prevent a device from being installed
completely or correctly. This is not blocked in current versions of Windows, but will
not be permitted in Windows Vista due to changes in operating system security that
prevent files from being copied or loaded.

To perform a software-first installation safely:

 Use UpdateDriverForPlugAndPlayDevices to install a selected driver
package on all devices for a given hardware or compatible ID.
 Use the new DiInstallDevice function to install a selected driver assembly
for a specific device in Windows Vista.
Rule #29 Use new DIFx tools for software-first installation

New tools are available to simplify software-first installation in Windows Vista:
 Use DIFxApp to install drivers in a Windows Installer–based installation
program.
 Use DPInst for a simple software-first installer.
For more information about the DIFx tools, see the papers listed in "Resources" at
the end of this paper.
General Rules for Class Installers and Co-Installers

Rule #30 Do not copy files on your own
Do not copy files explicitly by calling functions such as CopyFile or MoveFile. The
device installation engine notifies the Code Integrity (CI) component that files are
safe to run on the computer. Files that other mechanisms copy do not go into the CI
database and therefore are not loaded.
To copy files safely, use the SetupAPI file queue:
 Use SetupDiGetDeviceInstallParams to get the FileQueue file of the
SP_DEVINSTALL_PARAMS structure.
 Use SetupQueueCopy to add a file to the file queue if it is part of the driver
package.
 Use SetupQueueCopyIndirect to add a file to the file queue if it is not part
of the driver package.
You must provide a catalog file for the file to be copied, and the user must
already trust the provider of this catalog.
Rule #31 Do not show user interface in the class installer or co-installer while
processing core device installation DIF codes
Core device installation runs in a system (noninteractive) service, so a user cannot
see or respond to any user interface that appears in this context. Any dialog box
that is provided in a class installer or co-installer during processing of a core device
installation DIF code causes the device installation to hang.
In general, class installers and co-installers that are running in server-side
installations should not interact with the user. As such, they must not display dialog
boxes except in the finish-install user interface.
To show user interface during installation:
 Process DIF_NEWDEVICEWIZARD_FINISHINSTALL and add some
property pages. The class installer can show UI in the dialog procedure for
these finish-install pages.
 Show user interface only in the dialog procedure, not when
DIF_NEWDEVICEWIZARD_FINISHINSTALL is received because this DIF code
is sent in the system context (that is, noninteractive).

 For more information about the device finish-install a, see the paper titled
Device Finish-Install Actions in Windows Vista," which is listed in "Resources"
at the end of this paper.
Rule #32 Do not store state in the class installer or co-installer DLL
The DLL is very likely unloaded between any given DIF codes, so state does not
persist.
To preserve state in a class installer or co-installer DLL:
 Store state in the device’s driver key.
Use SetupDiOpenDevRegKey with the DIREG_DRV flag to get a registry
handle to the device’s driver key.
 Use the new device property functions SetupDiSetDeviceProperty and
SetupDiGetDeviceProperty.
Rule #33 Do not fail any DIF code with

ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION
Device installation for Windows Vista always runs in the system context (that is,
noninteractive). Client-side installation is not available, so failing installation with this
error causes the entire device installation to fail.
If the device installation requires user interaction, use a finish-install page or a
software-first installation.
For more information about the device finish-install action, see the paper titled
Device Finish-Install Actions in Windows Vista, which is listed in "Resources" at the
endo of this paper
Rule #34 Do not load any unsigned code on X64 versions of Windows Vista
If you attempt to load an unsigned executable file or DLL, the X64 CI component
prevents it from being loaded in this secure environment.
If you must load a DLL in the class installer or co-installer, it is recommended that it
be included in your driver package.
Rule #35 Do not call CreateProcess except from within a finish-install dialog
procedure
The device installation engine cannot track additional processes and has no way to
determine what they are doing or when they are finished. For example, the device
installation engine could start or stop the device or initiate a system restart while the
process is performing a critical action.
To launch other processes safely, launch them in a finish-install dialog procedure.
Do not allow the user to continue in the dialog procedure until the separate
installation process is finished.
Rule #36 Do not rename or delete protected system files unless allowed
Class installers and co-installers may not rename or delete protected system files,
and they may replace them only in rare cases.
See also "Accessing and Modifying Files," earlier in this paper.

Rule #37 Do not load modules by explicit function calls or by creating link
dependencies
Class installers and co-installers may not load modules by explicit function calls
(LoadLibrary) or by creating link dependencies. Required modules should be
copied by using a CopyFiles directive in the .inf file.
Rule #38 Do not start or control services unless allowed

Class installers and co-installers may not start or control services except under
specified conditions.
Checklist: Summary Actions for Driver Developers

 Ensure that your device installation components, applications, and services
follow these rules today so they will work in Windows Vista.
 Ensure that your Setup applications that install drivers call the appropriate
functions:
 UpdateDriverForPlugAndPlayDevices
 DiInstallDevice (in Windows Vista)
 Use the new DIFx tools to simplify your software-first solution.
 Try your existing applications, services, and device installation components
on the latest CTP build or beta build of Windows Vista.
 Tell the Microsoft DMI team about any valid scenarios that are affected by
internal resource protection that cannot be implemented by using supported
mechanisms.
 Tell the Microsoft DMI team what new functions and functionality you need
to be successful.
Resources
Glossary
client-side installation
Device installation that occurs in the interactive context of the logged-on user.
Client-side installation is no longer supported in Windows Vista.
device driver
A function driver for a hardware device that has a Plug and Play identifier.
device management and installation
The discovery and installation of available devices, storage and retrieval of
device properties, and storage and retrieval of device settings. Only supported
mechanisms should be used to perform these tasks.
Devnode
A data structure that is created and managed by the Windows Plug and Play
manager to store information about a device.
driver assembly
The group of files and registry actions that are required to install drivers and
settings on a specific Plug and Play identifier. A driver assembly is sometimes
called a driver node.

driver package
A collection of all of the files that are required to successfully load the driver.
This includes the device information (.inf) file, the catalog file, and all of the
binaries that are copied by the .inf file, including the class installer DLL, co-
installer DLL, function driver, branding icons or bitmaps, and property page
provider DLL.
hardware-first installation
The installation of device drivers that is triggered by plugging in the hardware.
internal resources
The undocumented internal state that the Plug and Play manager and device
installation architecture use, including registry keys and values and files that are
used by the device installation architecture.
nondevice driver
Any kernel-mode driver that is not a device driver, such as a filter driver, a
kernel-mode service, or a kernel-mode DLL.
phantom devnode
A devnode for a device that is not plugged in.
server-side installation
Device installation that occurs in the system context, which is noninteractive. No
user interface can appear in this context because the user cannot see it.
software-first installation
The staging of device driver files on the system before the hardware is plugged
in. After the hardware is plugged in, the driver is installed.
References
For further information, send e-mail to [email protected] with "Device
installation rules for Windows Vista" in the subject line.
Windows Driver Kit:
http://www.microsoft.com/whdc/driver/WDK/aboutWDK.mspx
Driver installation information:

Device and Driver Installation on the WHDC Web site:
http://www.microsoft.com/whdc/driver/install/default.mspx
Using Authenticode to Digitally Sign Driver Packages
http://www.microsoft.com/whdc/driver/install/authenticode.mspx
Driver Install Frameworks Tools
http://www.microsoft.com/whdc/driver/install/difxtools.mspx
Device Finish-Install Actions in Windows Vista
http://www.microsoft.com/whdc/driver/install/Finish_Install.mspx
Digital Signatures for Kernel Modules on x64-based Systems Running
Windows Vista
http://www.microsoft.com/whdc/system/platform/64bit/kmsigning.mspx
Driver Signing for Kernel-Mode Software for x64-based Systems: Frequently
Asked Questions
http://www.microsoft.com/whdc/system/platform/64bit/kmsigningFAQ.mspx
Driver Package Integrity during Plug and Play Device Installs in
Windows Vista
http://www.microsoft.com/whdc/winlogo/drvsign/pnp-driver.mspx

Newsgroups:
microsoft.public.development.device.drivers
Related WinHEC Sessions:

Device Install for Windows Vista – Parts 1 and 2
Device Install - User Research Results


Device Installation Rules and Guidelines For Windows Vista

Uploaded by

Copyright:

Available Formats

Device Installation Rules and Guidelines For Windows Vista

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Device Installation Rules and Guidelines For Windows Vista

Uploaded by

Copyright:

Available Formats

Device Installation Rules and

Guidelines for Windows Vista

© 2004-2006 Microsoft Corporation. All rights reserved.

WinHEC 2006 Version - May 9, 2006

WinHEC 2006 Version - May 9, 2006

New device installation features. In addition to solving current problems, new

Device Installation in Windows Vista

WinHEC 2006 Version - May 9, 2006

Device installation in Windows Vista takes place in stages, as shown in Figure 1.

Figure 1. Windows Vista Device Installation

Driver Store User Interface: Validating Trust and Licensing

Driver Package Integrity

WinHEC 2006 Version - May 9, 2006

Windows Vista contains several other changes and new features as a result of

Driver Package Validation

Driver Store: Placing Packages on the Local System

WinHEC 2006 Version - May 9, 2006

Update Install User Interface

Core Device Installation: Copying Files and Modifying the

Finish-Install User Interface: Offering Optional User Interaction

WinHEC 2006 Version - May 9, 2006

In user context (interactive), the device installation engine:

 Sends the class installer or co-installer another