InstallShield 2012 Express Edition User Guide - Knowledge Base ...

Chapter 10: Customizing Installation Behavior
Using Custom Actions
new custom action that you are adding to your project, it is recommended that you use an MSI DLL
custom action instead of a standard DLL, since an MSI DLL action offers more flexible scheduling
options.
Once your 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 a DLL Custom Action to Your Project.
Classic DLL Custom Action Function Prototype
InstallShield requires a precise prototype for an entry-point function in a DLL called as the result of a
custom action.
Flexera Software does not provide technical support for Windows programming or DLL debugging. You
are responsible for correctly writing any DLL functions. Prototype your custom DLL functions as shown
below. Any variation in return type or type and number of parameters can cause the custom action to
fail.
LONG WINAPI Foo(HWND, LPTSTR , LPTSTR, LPTSTR, LPTSTR);
InstallShield uses the function prototype to pass the following information to your DLL:
1. Parameter 1 passes the installation’s window handle. This parameter always returns NULL.
2. Parameter 2 passes the source directory [SRCDIR].
3. Parameter 3 passes the support directory [SUPPORTDIR].
4. Parameter 4 passes the main target directory [INSTALLDIR].
5. Parameter 5 passes the database directory [DATABASEDIR].
If you are prototyping a custom action to handle the serial number entered in the Customer Information
run-time dialog, then Parameter 4 will be the serial number.
The body of your DLL function can do just about anything you want. Obviously, you may have good use
for the values passed to the function by the installation.
Your DLL function must return a value of type LONG as a state flag signaling the completion of the
routine. If your function returns zero and you selected No for the custom action’s Ignore Exit Code
setting, the installation exits. If it returns any other value, or if you selected Yes for the custom action’s
Ignore Exit Code setting, the installation continues.
Sample DLL Function
This section contains sample source code. This sample contains a function, Foo(), that displays a
message box showing the values that were passed to the function.
#include
#ifdef __cplusplus
extern "C" {
#endif
// Foo() function definition.
LONG WINAPI Foo(HWND hwnd, LPSTR szSrcDir, LPSTR szSupport, LPSTR szInst, LPSTR szDbase)
{ CHAR szTmp[1024];
int ret;
// Construct a string to display the values passed into Foo().
wsprintf(szTmp, "Extension called. hwnd=%x szSrcDir=%s szSupport=%s szInst=%s. Do you want" \
InstallShield 2012 Express Edition User Guide ISE-1800-UG01 225