DriverPackageInstall function

The DriverPackageInstall function preinstalls a driver package in the DIFx driver store 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. 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 installation operation.

ValueMeaning

0x00000000

DriverPackageInstall performs a default installation.

DRIVER_PACKAGE_FORCE

(Applies only to PnP function drivers) DriverPackageInstall preinstalls and installs the specified driver package 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.

Note  Starting with Windows Vista, the DRIVER_PACKAGE_LEGACY_MODE flag is obsolete.

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 in the DIFx driver store 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 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, 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. For more information about these .dll files, see How DIFxApp Works.

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_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 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 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, as described in DPInst Driver Support.

By default, the function preinstalls a driver package for a PnP function driver in the DIFx driver store, 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 from the DIFx driver store. 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. For more information about how DIFxAPI and Windows handles driver signing requirements, see DIFx Driver Package Requirements.

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

Version

The DriverPackageInstall function is available for Microsoft Windows 2000 and later versions of Windows.

Header

Difxapi.h (include Difxapi.h)

Library

Difxapi.lib

See also

DriverPackagePreinstall
DriverPackageUninstall
INSTALLERINFO

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft