Working with a DLL File for an Action in a Suite/Advanced UI Installation

InstallShield 2016

Project • This information applies to Suite/Advanced UI projects.

Edition • The Advanced UI project type is available in the Professional edition of InstallShield. The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.

Creating a DLL File for a DLL Action

The first step in adding a DLL action to a Suite/Advanced UI project is to create the DLL. You can create the DLL with any recent version of Visual C++ or any tool or language that supports COM and DLL exports.

The Suite/Advanced UI engine requires that each action have one entry point. To specify the entry point, enter it in the Function Name setting for the action in the Events view. The function should be defined as follows:

HRESULT __stdcall MyFunction(IDispatch *pAction);

To be able to call this function from the Suite/Advanced UI installation, you must include a definition file (.def) when you build the DLL to export the function properly. The following is the contents of a sample .def file. The name after LIBRARY should be the name that you are using for the DLL.

LIBRARY "MyActionLibrary"

EXPORTS

    MyAction

The Suite/Advanced UI installation calls the function entry point when an action for an event or a package in the installation is scheduled to run. Your entry-point function should return ERROR_SUCCESS to indicate that the action finished successfully. If the action fails, it should return a non-zero value. The values are the same ones that Windows Installer custom actions return.

Note that although the Suite/Advanced UI installation allows any action to be performed, actions are run with the privileges that they are configured to have. Some actions may require administrator privileges (such as reading IIS 7.x configuration data). In such cases, in order for the action to access the required data successfully, the action would need to be configured to require administrator privileges; that is, Yes would need to be selected for the Requires Administrative Privileges setting for the action in the Events view. As an alternative, the Suite/Advanced UI installation’s Setup.exe file could be run with administrator privileges, or it would need to include an administrator manifest. However, privileges should be elevated for as short of a duration as possible.

The IDispatch interface that is passed to the action’s entry point implements the ISuiteExtension2 interface (which includes all of the ISuiteExtension methods and properties). To obtain a pointer to ISuiteExtension2, call the QueryInterface method on the IDispatch interface. The ISuiteExtension2 interface allows the action function to access the attribute parameter that is defined for the action in the Suite/Advanced UI project. Note that each action in the project receives a different interface pointer that is specific to each action instance. Therefore, the interface pointer that is passed to the entry point function should always be used and should not be saved across calls to the action DLL.

The interface is defined as follows:

interface ISuiteExtension2 : IDispatch {

  [propget, id(1), helpstring("Attribute")]

    HRESULT Attribute([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

  [id(2), helpstring("method LogInfo")]

    HRESULT LogInfo([in]BSTR bstr);

  [propget, id(3), helpstring("Property")]

    HRESULT Property([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

  [propput, id(3), helpstring("Property")]

    HRESULT Property([in]BSTR bstrName, [in]BSTR bstrValue);

  [id(4), helpstring("FormatProperty")]

    HRESULT FormatProperty([in]BSTR bstrValue, [out, retval]BSTR *bstrReturnValue);

  [id(5), helpstring("ResolveString")]

    HRESULT ResolveString([in]BSTR bstrStringId, [out, retval]BSTR *bstrReturnValue);

  [id(6), helpstring("ProgressMessage")]

    HRESULT SendProgressMessage([in]BSTR bstrMsg, [in]INT iCurrent, [in]INT iMax,

                                [in]EnumProgressFlags eFlags);

};

Suite/Advanced UI projects use the function prototype to pass the ISuiteExtension2 COM interface pointer to an action, which enables you to access the following functions:

HRESULT LogInfo([in]BSTR bstr);

This method writes any information that is needed to the Suite/Advanced UI debug log, making it available for debugging or other informational purposes. The bstr parameter contains the string to be written to the log.

HRESULT get_Property([in]BSTR bstrName, [out, retval]BSTR *bstrValue);

This method retrieves the value of any property that is currently defined in the running Suite/Advanced UI installation. Properties that are not defined return an empty value. The bstrName parameter specifies the name of the property whose value is being obtained. The value for the property is returned in the bstrValue parameter.

HRESULT put_Property([in]BSTR bstrName, [in]BSTR bstrValue);

This method sets the value of a new property or changes the value of an existing property in the currently running Suite/Advanced UI installation. Passing an empty value effectively deletes the property. The bstrName parameter specifies the name of the property to set. The bstrValue parameter specifies the value to set for the specified property.

HRESULT FormatProperty([in]BSTR bstrValue, [out, retval]BSTR *bstrReturnValue);

This method resolves embedded formatted expressions in the string that is provided in the bstrValue parameter. The formatted value is returned in the bstrReturnValue parameter. To learn about the syntax that is available for formatted expressions, see Using Formatted Expressions that Advanced UI and Suite/Advanced UI Installations Resolve at Run Time.

HRESULT ResolveString([in]BSTR bstrStringId, [out, retval]BSTR *bstrReturnValue);

This method resolves a Suite/Advanced UI string identifier into the corresponding string value for the currently running Suite/Advanced UI installation in the currently selected UI language. The bstrStringId parameter specifies the string identifier to resolve, and the resolved string is returned in bstrReturnValue. If no such string identifier exists, the returned string is empty.

HRESULT SendProgressMessage([in]BSTR bstrMsg, [in]INT iCurrent, [in]INT iMax,

                            [in]EnumProgressFlags eFlags);

This method updates the status message and the progress bar on the InstallationProgress wizard page of the Suite/Advanced UI installation. To update the progress bar, specify epfProgressValid for the eFlags parameter; to update the status message, specify epfMessageValid. To update both the status message and the progress bar, use the bitwise OR operator (|) with both flags.

Note that the get_Attribute method is not available for DLL actions in a Suite/Advanced UI installation, and it should not be called.

To access the ISuiteExtension2 interface from your DLL, you can use #import to incorporate the type library information from the SetupSuite.exe file that is installed with InstallShield. The path is:

InstallShield Program Files Folder\Redist\Language Independent\i386\SetupSuite.exe"

For example, to import the type library in a VC++ project (such as in stdafx.h), use the following statement:

#import "C:\Program Files\InstallShield\2016\Redist\Language Independent\i386\SetupSuite.exe" no_namespace raw_interfaces_only named_guids

Note that if InstallShield is installed to a different location, adjust the path in the #import statement accordingly.

Adding a DLL Action

To add an action that calls a function in a DLL file during a Suite/Advanced UI installation:

Once you have added the action to your project, schedule it as needed. For more information, see Scheduling a Suite/Advanced UI Action.

See Also

Using Actions to Extend the Behavior of a Suite/Advanced UI Installation

Open topic with navigation