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.

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.

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.

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

See also

DriverPackagePreinstall