Export (0) Print
Expand All

DriverPackagePreinstall function

The DriverPackagePreinstall function preinstalls a driver package for a Plug and Play (PnP) function driver in the DIFx driver store 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. For more information about how to specify an INF file for a driver package, see Specifying a Driver Package INF File Path.

Flags [in]

A bitwise OR of the values in the following table that control the preinstall operation.

ValueMeaning

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

Note  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 in the DIFx driver store, DriverPackagePreinstall replaces the existing driver package in the DIFx driver store.

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 codeDescription
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. For more information about these .dll files, see How DIFxApp Works.

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. For more information about path length, see Specifying a Driver Package INF File Path.

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 in the DIFx driver store 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.

A driver package must comply with the DIFx driver package requirements that are listed in DIFx Driver Package Requirements.

DriverPackagePreinstall copies the following driver package files to the DIFx driver store: 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

Version

Available for Microsoft Windows 2000 and later versions of Windows.

Header

Difxapi.h (include Difxapi.h)

Library

Difxapi.lib

See also

DriverPackageInstall

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft