DriverPackageInstall function
Starting in Windows 10 Version 1607 (Redstone 1), the Driver Install Frameworks (DIFx) tools are no longer included in the WDK.
For more information, see DIFx Guidelines.
The DriverPackageInstall function preinstalls a driver package and then installs the driver in the system.
Syntax
DWORD DriverPackageInstall(
_In_PCTSTR DriverPackageInfPath,
_In_DWORD Flags,
_In_opt_PCINSTALLERINFO_W pInstallerInfo,
_Out_BOOL *pNeedReboot
);
Parameters
DriverPackageInfPath [in]
A pointer to a NULL-terminated string that supplies the fully qualified path of the driver package's INF file of the driver package to install. The INF file cannot be in the system INF file directory.
Flags [in]
A bitwise OR of the values in the following table that control the installation operation.
| Value | Meaning |
|---|---|
| 0x00000000 | DriverPackageInstall performs a default installation. |
| DRIVER_PACKAGE_FORCE | (Applies only to PnP function drivers) DriverPackageInstall preinstalls and installs the specified [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) even if the driver package that is currently installed for a device is a better match for the device than the specified driver package. For more information, see the following Remarks section. |
| DRIVER_PACKAGE_LEGACY_MODE | DriverPackageInstall preinstalls and installs unsigned driver packages and driver packages that cannot be completely preinstalled because there are files that cannot be found. For more information, see the following Remarks section.
|
| DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT | (Applies only to PnP function drivers) DriverPackageInstall preinstalls and installs the driver only if the driver package is a better match to a device in the device tree. For more information, see the following Remarks section. |
| DRIVER_PACKAGE_REPAIR | DriverPackageInstall re-installs the specified driver package even if the driver package is already installed. |
| DRIVER_PACKAGE_SILENT | DriverPackageInstall suppresses the display of user interface items. If a user interaction is required to complete an installation, the installation will fail. For more information, see the following Remarks section. |
pInstallerInfo [in, optional]
A pointer to a constant INSTALLERINFO structure that supplies information about an application that is associated with the driver that is being installed. This pointer is optional and can be NULL. If the pointer is NULL, the driver package is not associated with an application. For more information about supplying the structure, see the following Remarks section.
pNeedReboot [out]
A pointer to a BOOL-typed variable. On return, DriverPackageInstall sets this variable to TRUE if a system restart is required to complete the installation. Otherwise, the function sets this variable to FALSE.
Return value
DriverPackageInstall returns ERROR_SUCCESS if the specified driver package was successfully installed. Otherwise, the function did not install the driver package and returns an error code that indicates the cause of the failure. The following table contains the most common return values.
| Return code | Description |
|---|---|
| CERT_E_EXPIRED | The signing certificate is expired. |
| CERT_E_UNTRUSTEDROOT | The catalog file has an Authenticode signature whose certificate chain terminates in a root certificate that is not trusted. |
| CERT_E_WRONG_USAGE | The certificate for the driver package is not valid for the requested usage. If the driver package does not have a valid WHQL signature, DriverPackageInstall returns this error if, in response to a driver signing dialog box, the user chose not to install a driver package, or if the caller specified the DRIVER_PACKAGE_SILENT flag. |
| CRYPT_E_FILE_ERROR | The catalog file for the specified driver package was not found; or possibly, some other error occurred when DriverPackageInstall tried to verify the driver package signature. |
| ERROR_ACCESS_DENIED | A caller of DriverPackageInstall must be a member of the Administrators group to install a driver package. |
| ERROR_BAD_ENVIRONMENT | The current Microsoft Windows version does not support this operation. An old or incompatible version of DIFxApp.dll or DIFxAppA.dll might be present in the system. |
| ERROR_CANT_ACCESS_FILE | DriverPackageInstall could not preinstall the driver package because the specified INF file is in the system INF file directory. |
| ERROR_FILE_NOT_FOUND | The INF file that was specified by DriverPackageInfPath was not found. |
| ERROR_FILENAME_EXCED_RANGE | The INF file path, in characters, that was specified by DriverPackageInfPath is greater than the maximum supported path length. |
| ERROR_IN_WOW64 | The 32-bit version DIFxAPI does not work on Win64 systems. A 64-bit version of DIFxAPI is required. |
| ERROR_INSTALL_FAILURE | The installation failed. |
| ERROR_INVALID_CATALOG_DATA | The catalog file for the specified driver package is not valid or was not found. |
| ERROR_INVALID_NAME | The specified INF file path is not valid. |
| ERROR_INVALID_PARAMETER | A supplied parameter is not valid. |
| ERROR_NO_DEVICE_ID | The driver package does not specify a hardware identifier or compatible identifier that is supported by the current platform. |
| ERROR_NO_MORE_ITEMS | (Applies only to PnP function drivers) The specified driver package was not installed for matching devices because the driver packages already installed for the matching devices are a better match for the devices than the specified driver package. The driver package was preinstalled unless the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag was specified. |
| ERROR_NO_SUCH_DEVINST | (Applies only to PnP function drivers) The driver package was not installed on any device because there are no matching devices in the device tree. The driver package was preinstalled unless the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag was specified. |
| ERROR_OUTOFMEMORY | Available system memory was insufficient to perform the operation. |
| ERROR_SHARING_VIOLATION | A component of the driver package is locked by a thread or process. This error can occur if a process or thread, other than the thread or process of the caller, is currently accessing the same driver package as the caller. |
| ERROR_SIGNATURE_OSATTRIBUTE_MISMATCH | The signing certificate is not valid for the current Windows version or it is expired. |
| ERROR_UNSUPPORTED_TYPE | The driver package type is not supported. |
| TRUST_E_NOSIGNATURE | The driver package is not signed. |
Remarks
A caller of DriverPackageInstall must be a member of the Administrators group; otherwise the function does not install a driver package and returns ERROR_ACCESS_DENIED.
To associate a driver package with an application, use the structure that is pointed to by pInstallerInfo to supply the required information about the application. The same application information should be passed to DriverPackageUninstall to uninstall the driver. For more information about how to associate an application with a driver package, see INSTALLERINFO.
How DriverPackageInstall installs a driver package is type-specific.
By default, the function preinstalls a driver package for a PnP function driver, regardless of whether the driver package matches a device in the device tree. However, if the caller specifies the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag in Flags, DriverPackageInstall only preinstalls a driver package if the driver package is a better match to a device in the device tree. This situation applies to present devices (devices that are currently configured in the device tree) and nonpresent devices (devices that were previously installed but are currently not configured in the device tree). The function installs the driver package for present devices and sets the CONFIGFLAG_REINSTALL flag for nonpresent devices.
By default, DriverPackageInstall installs a function driver for a PnP device only if the driver is the best match for a device in the device tree. However, the function also supports forcing the installation of a new driver for a device even if the driver that is currently installed on the device is a better match than the new driver. To force such an installation, use the DRIVER_PACKAGE_FORCE flag. This situation applies to present devices and nonpresent devices. If the driver matches a nonpresent device, the function sets the CONFIGFLAG_REINSTALL flag for the device.
If the caller specifies the DRIVER_PACKAGE_ONLY_IF_PRESENT flag and the DRIVER_PACKAGE_FORCE flag, DriverPackageInstall preinstalls a driver package only if the package matches a device in the device tree and installs the package for a device, regardless of whether the driver package is a better match for the device. This situation applies to both present and nonpresent devices.
By default, DriverPackageInstall installs a driver package only if the driver package has a WHQL signature or a Microsoft Authenticode signature. If the caller specifies the DRIVER_PACKAGE_LEGACY_MODE flag, the function installs unsigned driver packages without performing signature verification. However, if the driver is signed and DPInst cannot locate the catalog file, the preinstall will fail. In addition, Windows driver signing requirements apply to the installation of a driver package. These requirements depend on the Windows version, the signature type, the driver package type, and the driver signing options that are set for a computer.
If the caller specifies the DRIVER_PACKAGE_LEGACY_MODE flag for a driver package that has missing files, Windows will subsequently prompt the user to provide the location of the missing files to complete an installation.
Note
Starting with Windows Vista, the DRIVER_PACKAGE_LEGACY_MODE flag is obsolete.
If the installation of a driver package for a parent device subsequently causes the PnP manager to try to install child devices of the parent device, you can use DriverPackagePreinstall to preinstall the driver packages for the child devices before installing the parent device. If the function drivers for the child devices are preinstalled before the parent device is installed, Windows automatically installs the preinstalled driver packages for the child devices after the parent device is installed.
If the caller specifies the DRIVER_PACKAGE_SILENT_FLAG, DriverPackageInstall suppresses the display of user interface items. If a user interaction is required to complete an installation (for example, in response to a driver signing dialog box), the installation operation will fail without displaying a user message. The function will return an error code that indicates the cause of the failure. For example, if the driver package is not signed, the function returns TRUST_E_NOSIGNATURE.
To obtain more detailed information about the error condition when DriverPackageInstall returns ERROR_INSTALL_FAILURE, the caller should first register a callback function by calling either the SetDifxLogCallback or DIFXAPISetLogCallback function before it calls DriverPackageInstall. Before DriverPackageInstall returns ERROR_INSTALL_FAILURE, it generates an error log callback event that contains detailed information about the error that occurred.
Requirements
| Target platform | Desktop |
| Version | The DriverPackageInstall function is available for Microsoft Windows 2000 and later versions of Windows. |
| Header | Difxapi.h (include Difxapi.h) |
| Library | Difxapi.lib |