The DriverPackageInstall function preinstalls a driver package in the driver store and then installs the driver in the system.

DWORD 
  DriverPackageInstall(
    IN LPCTSTR  DriverPackageInfPath, 
    IN DWORD  Flags,
    IN PCINSTALLERINFO  pInstallerInfo OPTIONAL,
    OUT BOOL  *pNeedReboot
    );

Parameters

DriverPackageInfPath

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

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

Value	Meaning
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 not a better match for the device than the specified driver package. For more information, see the following Comments 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 Comments 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 Comments section.
DRIVER_PACKAGE_REPAIR	DriverPackageInstall re-installs the specified driver package in the 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 Comments section.

pInstallerInfo

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

pNeedReboot

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.

Comments

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 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 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, Setup 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

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

Headers: Declared in Difxapi.h. Include Difxapi.h.

Library: Contained in Difxapi.lib, which is included in the Windows Vista and later versions of the Windows Driver Kit (WDK).

See Also

DriverPackagePreinstall, DriverPackageUninstall, INSTALLERINFO