InstallShield 2012 Spring Express Edition User Guide

Chapter 10: Customizing Installation Behavior
Using Custom Actions
Edition: The Premier and Professional editions of InstallShield include support for several custom action types that are not
available in the Express edition. These extra custom action types enable you to do the following: run InstallScript code, set
a property, set a directory, call a public method in a managed assembly, or display an error message under certain
conditions and abort the installation.
Windows Installer DLL Custom Actions
If you need to perform an action in your installation that is not natively supported by InstallShield or the
Windows Installer service, you can create a custom action that calls an entry-point function from a
Windows Installer .dll file. With this type of custom action, often called an MSI DLL action, the function
must be defined with the following signature:
UINT __stdcall FunctionName (MSIHANDLE hInstall) {...}
The function name can vary; however, the return type, calling convention, and single parameter must
use the types that are specified in the aforementioned signature. The MSIHANDLE data type that is used
in the function signature is a handle to the running installation.
The following sample code is for a function called MyFunctionName.
UINT __stdcall MyFunctionName (MSIHANDLE hInstall)
{
MessageBox(
GetForegroundWindow( ),
TEXT("This is MyFunctionName."),
TEXT("Custom Action"),
MB_OK | MB_ICONINFORMATION);
return ERROR_SUCCESS;
}
Your entry-point function should return ERROR_SUCCESS to indicate that the action finished
successfully. If your custom action returns a non-zero value and you selected No for the custom action’s
Ignore Exit Code setting, the installation exits. If you selected Yes for the custom action’s Ignore Exit
Code setting, the installation continues, regardless of the custom action’s return code.
Once your MSI DLL is ready, you must design a custom action to call the entry-point function. To learn
how to create the custom action, see Adding an MSI DLL Custom Action to Your Project.
Requirements
• Header: Declared in Msiquery.h
• Library: Use Msi.lib
Both Msiquery.h and Msi.lib can be found in the Windows Installer SDK, which can be downloaded
from Microsoft’s Web site. In addition to the two files listed above, the Windows Installer SDK contains
Microsoft’s definitive documentation on the Windows Installer APIs.
InstallShield 2012 Spring Express Edition User Guide ISE-1900-UG00 223