Creating an Extension Condition DLL for an Advanced UI or Suite/Advanced UI Project

InstallShield 2019

Project • This information applies to the following project types:

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.

Note • Flexera 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 explained below. Any variation in return type can cause the extension condition DLL to fail.

The first step in creating an extension condition is to create the DLL. You can create an extension condition DLL with any recent version of Visual C++ or any tool or language that supports COM and DLL exports.

The Advanced UI and Suite/Advanced UI engine requires two entry points per condition—one to validate the condition and one to evaluate the condition. Both entry points must be based on the name of the extension condition. For example, for a condition called MyCondition, the DLL that tests the condition must export the following entry points:

These functions should be defined as follows:

HRESULT __stdcall MyCondition_Validate(IDispatch *pCondition);

HRESULT __stdcall MyCondition_Evaluate(IDispatch *pCondition, VARIANT_BOOL *pbResult);

To be able to call these functions from the Advanced UI or 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 "MyConditionLibrary"

EXPORTS

    MyCondition_Validate

    MyCondition_Evaluate

The Advanced UI or Suite/Advanced UI installation calls the validation entry point while parsing the conditions that were defined in the project. This enables the extension condition to ensure that the condition parameters that were defined in the project are suitable for the condition to evaluate in a predictable manner. This entry point is called any time an extension condition of this type is found for an exit condition, a detection condition, or any other type of condition. Returning S_OK from this entry point indicates to the Advanced UI or Suite/Advanced UI installation that the condition is valid. Returning a failed HRESULT status causes the Advanced UI or Suite/Advanced UI installation to abort with an error for the condition that was last validated.

The Advanced UI or Suite/Advanced UI installation calls the evaluation entry point any time that an extension condition of this type is referenced by a condition that was configured in the project. The evaluation is allowed to perform any action that is necessary to evaluate the condition to a true or false result. The result is returned in the form of a VARIANT_BOOL in the pbEvalResult parameter. A result of VARIANT_TRUE is treated as a true result and a result of VARIANT_FALSE is treated as a false result. A success status (S_OK) should be returned from an evaluation function. A failure status aborts the evaluation of the current condition block being evaluated, but it does not cause the installation to abort.

Note that although the Advanced UI or Suite/Advanced UI installation allows any action to be performed, extension conditions run with the privileges of the Advanced UI or Suite/Advanced UI installation from which they are called. Some actions may require administrator privileges (such as reading IIS 7.x configuration data). In such cases, in order for the condition to access the required data successfully, the installation would need to be run with administrator privileges, or it would need to include an administrator manifest.

The IDispatch interface that is passed to the validation and evaluation entry points implements the ISuiteExtension interface. To obtain a pointer to an ISuiteExtension, call the QueryInterface method on the IDispatch interface. The ISuiteExtension interface allows the condition functions to access the attribute parameters that are defined for the extension condition in the Advanced UI or Suite/Advanced UI project. Note that each condition in the project receives a different interface pointer that is specific to each condition 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 extension DLL.

The interface is defined as follows:

interface ISuiteExtension : 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);

};

Advanced UI and Suite/Advanced UI projects use the function prototype to pass the ISuiteExtension COM interface pointer to an extension condition DLL, which enables you to access the following functions:

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

This method retrieves the value of an attribute for the current condition instance. The attribute name is passed in bstrName, and its corresponding value is returned in bstrValue.

HRESULT LogInfo([in]BSTR bstr);

This method writes any information that is needed to the Advanced UI or 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 Advanced UI or 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 Advanced UI or 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 an Advanced UI or Suite/Advanced UI string identifier into the corresponding string value for the currently running Advanced UI or 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.

To access the ISuiteExtension 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\2019\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.

Once you have created your extension condition DLL, you can add it to your project. To learn how, see Adding an Extension Condition DLL to an Advanced UI or Suite/Advanced UI Project.

See Also

Creating a Custom Condition for an Advanced UI or Suite/Advanced UI Installation

Referring to Feature States and Other Feature Data in the UI of an Advanced UI or Suite/Advanced UI Project

Open topic with navigation