DIFxDriverPackageInstall

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 DIFxDriverPackageInstall function installs a driver package in the driver store and then installs the driver in the system. 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 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 DriverPackageInstall. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax

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

Parameters

DIFxDriverPackageInstall Parameters

Parameter

Description

szDriverPackageInfPath

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

nFlags

One or more flags that control the installation operation. In most cases you can specify 0 because the installer will 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 DriverPackageInstall. 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_DONT_ASSOCIATE—By default, associates the installed driver with the application being installed. If this flag is specified the driver is not associated with any application.
• ISDIFX_OPTION_NO_REPAIR—By default, the function automatically adds the DRIVER_PACKAGE_REPAIR flag when calling the DriverPackagePreinstall function 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 path instead.
• ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBS—By default, the function resolves any text substitutions found in szDriverPackageInfPath. However, if this flag is specified, text substitutions are not resolved.

Return Values

DIFxDriverPackageInstall Return Values

Return Value

Description

ISERR_SUCCESS

The function was successful.

< ISERR_SUCCESS

The function failed.

If the return value from DriverPackageInstall 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.
• When a driver is installed by DIFxDriverPackageInstall or uninstalled by DIFxDriverPackageUninstall, the driver is associated with the application being installed by the installation by default. This association can be disabled by specifying ISDIFX_OPTION_DONT_ASSOCIATE. These functions use the following script variables to determine the application to associate:
• ISDIFXAPPID
• IFX_PRODUCT_DISPLAY_NAME
• IFX_PRODUCT_NAME
• IFX_COMPANY_NAME

InstallShield 2016 Help Library

May 2017

 Copyright Information | Flexera Software

Open topic with navigation