DriverPackagePreinstall 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 DriverPackagePreinstall function preinstalls a driver package for a Plug and Play (PnP) function driver and installs the INF file for the driver package in the system INF file directory.

Syntax

DWORD DriverPackagePreinstall(
  _In_PCTSTR DriverPackageInfPath,
  _In_DWORD Flags
);

Parameters

DriverPackageInfPath [in]

A pointer to a NULL-terminated string that supplies the fully qualified path of a driver package's INF file for a PnP function driver. 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 preinstall operation.

Value Meaning
0x00000000 DriverPackagePreinstall performs a default preinstall.
DRIVER_PACKAGE_FORCE (This flag works with only the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag.) DriverPackagePreinstall preinstalls the new [driver package](https://msdn.microsoft.com/library/windows/hardware/ff544840) even if the driver package that is currently installed for a matching device is a better match for the device than the new driver package. For more information, see the following Remarks section.
DRIVER_PACKAGE_LEGACY_MODE DriverPackagePreinstall preinstalls unsigned driver packages and driver packages that cannot be completely preinstalled because there are files that cannot be found. For more information about legacy mode, see the following Remarks section.
Starting with Windows Vista, the DRIVER_PACKAGE_LEGACY_MODE flag is obsolete.
DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT DriverPackagePreinstall preinstalls the supplied driver package only if the driver package is a better match for a device in the device tree. For more information, see the following Remarks section.
DRIVER_PACKAGE_REPAIR If the specified driver package already exists, DriverPackagePreinstall replaces the existing driver package.
DRIVER_PACKAGE_SILENT DriverPackagePreinstall suppresses the display of user dialog boxes and other user messages. If a user interaction is required to complete a preinstall, the preinstall will fail. For more information, see the following Remarks section.

Return value

DriverPackagePreinstall returns ERROR_SUCCESS if the specified driver package was successfully preinstalled. Otherwise, the function did not preinstall 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, DriverPackagePreinstall returns this error code if, in response to a driver signing dialog box, the user chose not to install the 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 DriverPackagePreinstall tried to verify the driver package signature.
ERROR_ACCESS_DENIED A caller of DriverPackagePreinstall must be a member of the Administrators group to preinstall a driver package.
ERROR_ALREADY_EXISTS The driver package is already preinstalled and was not preinstalled again.
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_CANNOT_MAKE DriverPackagePreinstall did not preinstall the driver package.
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_INVALID_CATALOG_DATA The catalog file for the specified driver package is not valid or was not found.
ERROR_INVALID_FUNCTION The driver package is not for a PnP function driver.
ERROR_INVALID_NAME The specified INF file path is not valid.
ERROR_INVALID_PARAMETER A supplied parameter is not valid.
ERROR_MISSING_FILE DriverPackagePreinstall did not preinstall the driver package because files that are referenced by the INF file could not be found.
ERROR_NO_MORE_ITEMS This error code applies only if the caller specified the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag but did not specify the DRIVER_PACKAGE_FORCE flag. For more information, see the following Remarks section.
ERROR_NO_SUCH_DEVINST This error code applies only if the caller specified the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag. For more information, see the following Remarks section.
ERROR_OUTOFMEMORY Available system memory was insufficient to preinstall the driver package.
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 certificate is not valid for the current Windows version or it is expired.
TRUST_E_NOSIGNATURE The driver package is not signed.

Remarks

A caller of DriverPackagePreinstall must be a member of the Administrators group; otherwise, the function does not preinstall a driver package and returns ERROR_ACCESS_DENIED.

DriverPackagePreinstall preinstalls only driver packages for PnP functions drivers. If the driver package type is not a PnP function driver, the function does not preinstall the driver package and returns ERROR_INVALID_FUNCTION.

DriverPackagePreinstall copies the following driver package files: the INF file, the catalog file, and all the driver package files that are referenced by the INF file.

Use this function to preinstall a driver package for a PnP device that a user will subsequently connect to a computer. You should also use this function to preinstall driver packages for multifunction devices, where the installation of the multifunction device results in the installation of a driver package for each of the functions that are supported by the multifunction device.

To preinstall a driver package only if the driver is the best match for a device in the device tree, specify the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag in Flags. 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).

To preinstall a driver package if the driver package matches a device in the device tree, regardless of whether the driver package is a better match than the driver package that is currently installed for the device, specify the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag and the DRIVER_PACKAGE_FORCE flag. This situation applies to present and nonpresent devices.

If the caller specified the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag but did not specify the DRIVER_PACKAGE_FORCE flag, and if DriverPackagePreinstall subsequently returns ERROR_NO_MORE_ITEMS, the driver package matched devices in the device tree, but the driver package is not a better match for the devices than the driver packages that are currently installed for the devices. This situation applies to present and nonpresent devices.

If the caller specified the DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT flag and the DRIVER_PACKAGE_FORCE flag, and if DriverPackagePreinstall subsequently returns ERROR_NO_SUCH_DEVINST, the function did not preinstall the driver package because the driver package does not match a device in the device tree. This situation applies to present and nonpresent devices.

By default, DriverPackagePreinstall preinstalls a driver package only if the package has a digital signature that complies with PnP device installation policy. If the caller specifies the DRIVER_PACKAGE_LEGACY_MODE flag, this function will preinstall an unsigned driver package without performing signature verification. However, if the driver is signed and DPInst cannot locate the catalog file, the preinstall will fail. The function will also preinstall the driver package if there are missing files. If there are missing files, Windows will subsequently prompt the user for the location of the missing files to complete installation of the driver.

Note

Starting with Windows Vista, the DRIVER_PACKAGE_LEGACY_MODE flag is obsolete.

If the caller specifies the DRIVER_PACKAGE_SILENT_FLAG, DriverPackagePreinstall suppresses the display of user interface items. If a user interaction is required to complete a preinstall (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.

Requirements

Target platform Desktop
Version Available for Microsoft Windows 2000 and later versions of Windows.
Header Difxapi.h (include Difxapi.h)
Library Difxapi.lib

See also

DriverPackageInstall