Function Definition Panel

InstallShield 2015 » Custom Action Wizard

The Function Definition panel is where you specify the parameters for the entry-point function in your standard .dll file.

This panel is displayed only if you selected Call a function in a standard dynamic-link library in the Action Type panel of the Custom Action Wizard.

Note: The function must use the __stdcall calling convention. Functions with more than one parameter will not work properly if this convention is not used.

Panel Options

Name

Specify the name of the function that you want to call. The .dll file can have a single entry point for each custom action.

Arguments

Build the list of arguments—in order—that you want to pass to the function.

First, click the last row of the Arguments list to add a new argument. Next, complete the Type, Source, and Value columns for each argument.

Type

In this list, select the data type of the parameter. Note that there are two special cases for argument types, and these cases are identified below.

To initialize a pointer to null:

1. In the Type list, select POINTER.
2. In the Source list, select Constant.
3. In the Value list, select NULL. Do not enter 0 (zero) instead of NULL, because it is interpreted as a pointer pointing to the number 0.

To set a handle to the .msi database or the Windows Installer window:

1. In the Type list, select HANDLE.
2. In the Source list, select Constant.
3. In the Value list, select MsiHandle or MsiWindowHandle, depending whether you want a handle to the .msi database or the Windows Installer window.

Source

Indicate how you want to pass the data to the function. The following options are available in this list.

Options for Passing Data to a Function

Option

Description

Constant

The value that you want to pass is stored as a literal in your installation project. After you select Constant for the argument’s source, enter its definition in the Value column.

This “constant” does not require a name or identifier. Do not enclose string literals in quotation marks.

in Property

Select in Property for the source to specify the name of a Windows Installer property whose value will be passed to the function. This type of argument is suitable for a ByVal parameter.

inout Property

This source type is similar to a ByRef parameter. Select inout Property for the source to specify the name of a Windows Installer property whose value will be passed to the function and can be modified by the function.

out Property

An out property serves as a placeholder for a value that can be set by the function. No value is passed to the function, but the function requires the name of a property whose value it can modify.

When you select a property for the argument’s source, you must specify the name of the property in the Value column.

Value

The value can be one of two types:

A number or string literal that you enter when the argument’s source is a constant
A Windows Installer property when the argument’s source is a property

Note: When you set the Type list to HANDLE and the Source list to Constant, the Value column contains two options: MsiHandle and MsiWindowHandle. These constants can be used to get a handle to either the .msi database or the Windows Installer window.

When the source is a property, the Value list provides the name of every property in the Property Manager. You can select an existing property or enter a new name, in which case the new property is added to the Property Manager.

Remember that a property is merely a container for a value. If your parameter stores its value in an in property or inout property, ensure that you specify a value for the property in the Property Manager.

(Context Menu)

The context menu provides you with options for working with your arguments. To access the context menu, right-click an argument in the Arguments grid. The context menu options are described below.

Context Menu Options

Option

Description

Add

Click Add to add an argument to the Arguments grid.

Remove

Click Remove to delete the argument.

Move Up

The arguments must be in the precise order in which the function expects to receive them. Click Move Up to place the argument higher in the list.

Move Down

Click Move Down to place the argument lower in the list.

Return Type

Select the data type of the function’s return value. If you do not need to check the return value, you can accept void.

Return Property

Select the name of a property whose value will be set to the function’s return value. If you are going to check the return value elsewhere in your installation, you may want to initialize the return property’s value.

Note: The property cannot be set to the function’s return value unless the action is configured for immediate execution. Thus, if the action is scheduled for deferred, rollback, or commit execution, the Return Property setting is ignored at run time.

Silent mode

If you want the installation to suppress a warning message whenever the custom action fails to load the .dll file and call the function, select this check box.

See Also