Calling a Function in a DLL from a Wizard Page or Window in a Suite Installation

In Suite installations, InstallShield lets you define actions that an end user triggers when using some of the various wizard interface controls. See the Configuring an Action for a Control on a Wizard Page or Window help topic for more details about the actions. If you need to perform an action in your Suite installation that is not natively supported by InstallShield, you can create an action that calls a function from a .dll file. This .dll file can perform any function that you require, such as verifying a serial number.

The first step in creating an action that calls a function in a DLL is to write the DLL. InstallShield requires a precise prototype for an entry-point function in a DLL called as the result of an action. Flexera does not provide technical support for Windows programming or DLL debugging. You are responsible for correctly writing any DLL functions. Prototype your DLL functions as shown below. Any variation in return type or type and number of parameters can cause the action to fail.

HRESULT __stdcall Foo(IDispatch*)

InstallShield uses the function prototype to pass the ISuiteUIExtension COM interface pointer to your DLL, which enables you to access the following functions available in the Suite bootstrap (Suite_UI.dll):

  • BrowseFile

    HRESULT BrowseFile(BSTR bstrCaption, BSTR bstrInitialFile, BSTR* pbstrFile)

    This function launches the Browse for Files or Folders dialog box when an end user clicks the control. The string of instructions that are displayed on this dialog box are typically the value of a string identifier that you specified by the bstrCaption parameter.

    The initial file that is selected on this dialog box is the full path and file name of the file that you specified by the bstrInitialFile parameter.

    If the end user selects a file in this dialog box and clicks the OK button, the dialog box closes, and the function sets the pbstrFile parameter to the full path and file name of the file that the end user selected. If the end user clicks the Cancel button, the function returns E_FAIL.

    If the function succeeds, it returns S_OK.

  • BrowseFolder

    HRESULT BrowseFolder(BSTR bstrCaption, BSTR bstrInitialFolder, BSTR* pbstrFolder)

    This function launches the Browse for Folder dialog box when an end user clicks the control. The string of instructions that are displayed on this dialog box is typically the value of a string identifier that you specified by the bstrCaption parameter.

    The initial folder that is selected on this dialog is the full path of the folder that you specified by the bstrInitialFolder parameter

    If the end user selects a folder in this dialog box and clicks the OK button, the dialog box closes, and the function sets the pbstrFolder parameter to the full path of the folder that the end user selected. If the end user clicks the Cancel button, the function returns E_FAIL.

    If the function succeeds, it returns S_OK.

  • DoModal

    HRESULT DoModal(BSTR bstrDialogName, LONG* pnResult);

    This function shows a secondary window that you specified by the bstrDialogName parameter as a modal window.

    If the end user clicks the OK button, the modal window closes, and the function sets the pnResult parameter to IDOK. If the end user clicks the Cancel button, the function sets the pnResult parameter to IDCANCEL.

    If the function succeeds, it returns S_OK.

  • MessageBox

    HRESULT MessageBox(BSTR bstrMessage, BSTR bstrTitle, LONG nType, LONG* pnResult);

    This function shows a modal dialog box that contains a system icon, and a brief message that you specified by the bstrMessage parameter.

    When the end user closes the message box, the function returns and sets the pnResult parameter to an integer value that indicates which button the end user clicked.

  • SetActivePage

    HRESULT SetActivePage(BSTR bstrPage);

    This function moves to a specific wizard page that you specified as the
    bstrPage parameter of this function.

    If the function  succeeds, it returns S_OK.

  • OpenDocument

    HRESULT OpenDocument(BSTR bstrDocument, BSTR bstrVerb);

    This function performs an operation on a file that you specified by the bstrDocument parameter. The bstrVerb parameter specifies the action to be performed.

    It calls the ShellExecuteEx Windows function. Typical verbs include open, edit, print, and runas. For details about the verb, refer to the lpVerb member of the SHELLEXECUTEINFO structure.

  • LogInfo

    HRESULT LogInfo(BSTR bstrMessage);

    This function writes a message that you specified as the bstrMessage parameter to a log file for your Setup.exe.

    If the function succeeds, it returns S_OK.
     
  • get_Property

    HRESULT get_Property(BSTR bstrProperty, BSTR* pbstrValue);

    This function retrieves the value of a specific property that you specified as the
    bstrProperty parameter.


    If the function succeeds, it returns S_OK.
     

  • put_Property

    HRESULT put_Property(BSTR bstrProperty, BSTR bstrValue);

    This function sets a specific property that you specified as the bstrProperty parameter to a specific value.

    If the function succeeds, it returns S_OK.
     

  • FormatProperty

    HRESULT FormatProperty(BSTR bstrValue, BSTR* bstrReturnValue);

    This function substitutes properties using a format string in a string that you specified as the bstrValue parameter. When the function returns, the substituted string is set to the bstrReturnValue parameter.

  • ResolveString

    HRESULT ResolveString(BSTR bstrStringId, BSTR* bstrReturnValue);

    This function resolves a string identifier that you specified by the bstrStringId parameter. When the function returns, the value of the string identifier is set to the bstrReturnValue parameter.
     

  • get_Attribute

    HRESULT get_Attribute(BSTR bstrName, BSTR* pbstrValue);

    The function is reserved for future use. It currently returns E_NOTIMPL.


To access the ISuiteUIExtension interface from your DLL, you need to incorporate the type library information from the SetupSuite.exe file that is installed with InstallShield. The default path is:

C:Program FilesInstallShield2012RedistLanguage Independenti386SetupSuite.exe

The example below shows how to display a message box when an end user clicks a control:

#include "stdafx.h"
#include <atlstr.h>
#import "C:Program FilesInstallShield2012 RedistLanguage Independenti386SetupSuite.exe" no_namespace raw_interfaces_only
named_guids

HRESULT __stdcall Action(IDispatch *pDispSuiteUIExtension)
{
    
CComQIPtr<ISuiteUIExtension> spSuiteUIExtenstion = pDispSuiteUIExtension;

    long lResult = 0;
    return spSuiteUIExtenstion->MessageBox(CComBSTR(L"Hello"), CComBSTR(L"DLL Action"), MB_OK, &lResult);
}

Once your DLL is ready, you must add the DLL to your Suite installation, and design an action to call the entry-point function. The following is the syntax of the action statement that calls a DLL function.

{DLLName::FunctionName}

For example, to call a function called Action in TestDLL.dll when an end user clicks the control, enter the following action statement:

{TestDLL::Action}

To add a DLL action to your Suite project:

  1. In the View List under Behavior and Logic, click Support Files.
  2. In the Behavior and Logic explorer, select the Language Independent node and add TestDLL.dll.
  3. In the View List under User Interface, click Wizard Interface.
  4. In the Wizard Interface explorer, select the dialog that you want to modify.
  5. Do one of the following:
    • To configure the action of one of the navigation controls (the Next, Back, Cancel, Install, or Finish buttons)—In the right pane, expand the settings for the control whose action you want to modify
    • To configure the action of any of the other controls—In the wizard editor, select the control whose action you want to modify.
  6. In the Action setting, enter the action statement to call a DLL function in TestDLL.dll.
    {TestDLL::Action}

Note that actions that call a function in a DLL require InstallShield 2012 SP1. To obtain SP1, see Q201298: InstallShield 2012 Service Pack 1. For information about the InstallShield 2012 release, see the InstallShield 2012 demo.

4 comments on “Calling a Function in a DLL from a Wizard Page or Window in a Suite Installation

  1. Attila Balazsy on   # Reply

    Is there any way to call a method from a managed dll or it just supports native assemblies?

  2. Hidenori Yamanashi on   # Reply

    Hi Attila, thanks for reading our blog. InstallShield has support for native DLLs. You’d need to write a C/C++ DLL that calls a method in a managed DLL.

  3. Alex on   # Reply

    Is there any way to use c# dll instead of c++?

  4. Flexera on   # Reply

    Hi Alex, Yes, InstallShield has support for native DLLs. You’ll need to write a C/C++ DLL that calls a method in a managed DLL.

    Thanks for your question and for reading InstallTalk!

Leave a Reply

Your email address will not be published. Required fields are marked *