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.
|
| 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 |