DIFxDriverPackagePreinstall

InstallShield 2016 » InstallScript Language Reference

Project • This function applies to InstallScript projects only. This function is not required in InstallScript MSI projects since DIFx can be called by the Windows Installer in those projects.

The DIFxDriverPackagePreinstall function preinstalls a driver package for a Plug and Play (PnP) function driver in the driver store and installs the .inf file for the driver package in the system .inf file directory. If all of the files associated with the driver are in a single component or you can guarantee that all appropriate driver files will be installed when this component’s Installed event is called, then the recommended place for calling this function is in the component containing the DIFx driver's Installed event. Otherwise, call this function in the installation’s OnMoved event.

If uninstall logging is enabled when this function is called, the driver pre-installed by this function is logged for uninstallation and is automatically removed by the OnUninstallingDIFxDriverFile event when the application is removed.

Note • This function calls the DIFxAPI function DriverPackagePreinstall. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax

DIFxDriverPackagePreinstall( byval string szDriverPackageInfPath, byval number nFlags, byval number nISFlags );

Parameters

DIFxDriverPackagePreinstall Parameters

Parameter

Description

szDriverPackageInfPath

String that supplies the fully qualified path to the driver package .inf file of the driver package to pre-install.

nFlags

One or more flags that control the installation operation. In most cases, specify 0 to have the installer automatically add the appropriate flags.

The following additional flags can be specified manually:

Note • These flags are defined by and passed directly to the Flags parameter of the DIFxAPI function DriverPackagePreinstall. See the DIFxAPI documentation for additional information regarding these flags.

•

DRIVER_PACKAGE_REPAIR—Re-installs the specified driver package in the driver store even if the driver package is already installed. This flag is specified automatically in repair mode.

•

DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT—(Applies only to PnP function drivers) Preinstalls and installs the driver only if the driver package is a better match to a device in the device tree.

•

DRIVER_PACKAGE_FORCE—(Applies only to PnP function drivers) By default, installs a new driver for device only if the new driver is a better match for the device than the driver currently installed for the device. If you specify this flag, the function preinstalls and installs the specified driver package even if the driver package currently installed for a device is a better match for the device than the specified driver package.

•

DRIVER_PACKAGE_SILENT—Suppresses the display of user dialogs. If a user interaction is required to continue the installation, for example, in response to a driver signing dialog, the installation operation fails without displaying a user message. The function returns an error code that indicates the cause of the failure.

•

DRIVER_PACKAGE_LEGACY_MODE—Preinstalls and installs unsigned driver packages and driver packages that cannot be completely preinstalled because there are files that cannot be found.

nISFlags

Specifies InstallScript-specific flags. The following flags are available:

•

0—Default behavior

•

ISDIFX_OPTION_NO_REPAIR—By default, the function automatically adds the DRIVER_PACKAGE_REPAIR flag when calling DriverPackagePreinstall if REINSTALLMODE is TRUE. If this flag is specified, DRIVER_PACKAGE_REPAIR is not added automatically. However, it is passed if it is specified in nFlags.

•

ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH—By default, the function logs the installed driver for uninstallation in the installed driver cache. If this flag is specified, the driver is logged in the package page instead.

•

ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBS—By default, the function resolves any text substitutions found in szDriverPackageInfPath. If this flag is specified, text substitutions are not resolved.

Return Values

DIFxDriverPackagePreinstall Return Values
Return Value	Description
ISERR_SUCCESS	The function was successful.
< ISERR_SUCCESS	The function failed. If the return value from DriverPackagePreinstall is a Win32 error (a positive return value), ISERR_WIN_BASE is added to the error to ensure that it is < ISERR_SUCCESS. You can use the following code to get the original Win32 error, if desired: if( nResult & ISERR_WIN_BASE ) then nResult = nResult - ISERR_WIN_BASE; endif; For a list of specific errors, see DIFxAPI Errors (InstallScript Projects).

Additional Information

For more information on DIFx and DIFxAPI, see the MSDN Library.

Open topic with navigation

DIFxDriverPackagePreinstall

InstallShield 2016 Help Library

May 2017