Extension DLLs
Extension DLLs allow you to add your own installation functionality to the InstallMate program. There are no inherent limits to what you can do with an extension DLL, although you should take care that your DLL does not interfere with the operation of the InstallMate program. Extension DLLs must be written in C or C++.
- Function types
- Win32 ANSI, Win32 Unicode, and x64 Unicode versions
- Distribution of the extension DLL
- Default implementation
- Implementation tips
Function types
The extension DLL can contain one or both of the following function types:
- Callback functions for significant moments in the installation or removal process
- Custom DLL functions
Callback functions
Callback functions are called by the installer at predetermined points in the installation process, for example when the installation starts or finishes, when file installation starts or finishes, etc. Callback functions are useful if your DLL must perform actions that are closely related to a specific stage in the installation process. Typically, you will use callback functions in the following situations:
- Additional target system requirements checking
- Additional installation options checking
- File or shortcut-related actions (either installation or removal)
- Registration of customer information
The callback mechanism requires a single TixHandler function in the extension DLL. The installer calls this function at predetermined stages in the installation or removal process and passes a TixMessage data packet to the function with the reason for the callback. The function also receives a pointer to the iTixRuntime interface of the installer's runtime engine; this interface can be used to communicate back to the installer. See Extension DLL data and functions for more information about the data passed to the extension DLL.
Custom DLL functions
Custom DLL functions are called by Run DLL actions in the installation project. It is completely up to you when and how you call a custom DLL function; you can also pass one or more arguments to the function. This makes custom DLL functions much more flexible than the callback functions.
Each custom DLL function must conform to the fTixCustomFunc prototype; you can have any number of custom functions in your extension DLL. Similar to callback functions, custom functions receive a pointer to the iTixRuntime interface of the installer's runtime engine. See Extension DLL data and functions for more information about the data passed to the extension DLL.
Note: Even if your extension DLL is only meant for custom DLL functions, you must still provide a TixHandler entry point as well. Its implementation must handle at least the following messages:
TIXMSG_INITIALIZE
TIXMSG_TERMINATE
TIXMSG_GETVERSION
We recommend that you use the default implementation (see below) for all extension DLLs; this will take care of the required message handling.
Predefined custom DLL functions
The extension DLL as distributed with InstallMate contains a number of predefined custom DLL functions that you can use in your installers. See Predefined extension DLL functions for a complete list.
Utility functions
To help you write your own custom functions, the extension DLL as distributed with InstallMate contains a number of utility functions that help you deal with common situations in an efficient way while programming your extension DLL. These functions include file and folder path manipulation, file and folder operations, and many others. See TixUtils library for a complete list.
Win32 ANSI, Win32 Unicode, and x64 Unicode versions
From InstallMate 9.5 onward, support for pre-Windows XP platforms was dropped. As a side effect of this change, InstallMate 9.5 and later no longer include an ANSI version of the Setup executable. As of InstallMate 9.5, all extensions DLLs must therefore be built as Unicode versions, either 32-bit or x64.
InstallMate 9.5 and later
InstallMate's 9.5 and later Setup.exe executables come in Win32 Unicode and x64 Unicode versions; see Setup stubs for details.
- The Win32 Unicode version is compatible with both 32-bit, IA64, and x64 editions of Windows XP, 2003, Vista, 2008, 7, 8, 2012.
- The x64 Unicode version is only compatible with x64 Windows versions (the x64 editions of XP, 2003, Vista, 2008, 7, 8, 2012), but offers the best performance on those systems.
The Setup stubs documentation explains when and how each installer version is used. In general, we recommend that you build your extension DLL in Win32 Unicode and x64 Unicode versions, unless you are absolutely certain that you only need one of them.
InstallMate 9.0 to 9.4
InstallMate's 9.0 to 9.4 Setup.exe executables come in Win32 ANSI, Win32 Unicode, and x64 Unicode versions; see Setup stubs (InstallMate 9.0-9.4) for details.
- The Win32 ANSI version is compatible with most Windows 32-bit platforms (Windows 95, 98, Me, NT4, 2000, XP, 2003, Vista, 2008) and with Windows x64 versions, but its text processing is restricted to the default ANSI character set on the target system.
- The Win32 Unicode version is compatible with Windows NT-based systems (Windows NT4, 2000, XP, 2003, Vista, 2008) and with Windows x64 versions. It provides better performance and uses Unicode text processing internally, which considerably improves its localization support.
- The x64 Unicode version is only compatible with x64 Windows versions (the x64 editions of XP, 2003, Vista, 2008), but offers the best performance on those systems.
The extension DLL must match the installer's model: either ANSI or Unicode text processing. If you use the generic text macros in your source code (as the default implementation does, see below), then it is fairly easy to write source code that can be compiled for either ANSI or Unicode text processing.
The Setup stubs (InstallMate 9.0-9.4) documentation explains when and how each installer version is used. In general, we recommend that you build your extension DLL in Win32 ANSI, Win32 Unicode, and x64 Unicode versions, unless you are absolutely certain that you only need one of them.
Distribution of the extension DLL
To distribute your extension DLL, go to the Installer options project page, click Advanced... and go to the Extension DLL tab. Check the Include extension DLL box, then enter the paths to your compiled extension DLL versions in the Win32 ANSI path (InstallMate 9.0 to 9.4 only), Win32 Unicode path, and x64 Unicode path fields. The appropriate extension DLL version or versions will automatically be added to the installation package and will be available during installation.
Note: You do not need to, and should not, include your extension DLL as a regular installation file (unless you have a special reason to distribute the extension DLL).
Default implementation
The InstallMate distribution contains a default implementation of an extension DLL that you can use as the starting point for your own DLL. The source code for the default implementation is located in the InstallMate 9\Tix folder; that same folder also contains the header files that define the data types and interfaces for use in extension DLLs.
The following tables contain a short description of each file. Files marked * are typically customized; the other files should be considered read-only and need not be modified under normal circumstances.
Files for your own custom code
| File | Description |
|---|---|
| Custom.rc* | Resource script for any custom resources. It is linked to resource.h; you can use standard resource editors (including those in the Microsoft Visual C/C++ environments) to create and modify resources in this file. |
| resource.h* | Resource identifiers for use with Custom.rc. |
| TixCustom.cpp* | Sample implementation of a custom DLL function. You can use this as a starting point for your own functions. |
| TixHandlers.cpp* | Per-message function stubs. There is one function per message; comments in the function indicate how to implement the handler if required. |
Useful read-only files
| File | Description |
|---|---|
| Tix.h | Main header file; contains most extension DLL declarations and definitions. Do not modify. |
| TixDefs.h | Shared header file with common declarations and definitions. Do not modify. |
| TixRuntime.h | Declaration of the iTixRuntime interface to the installer's runtime engine. Do not modify. |
| TixUtils.h | Declarations of utility functions for use in extension DLLs. |
Visual C/C++ project files
| File | Description |
|---|---|
| TixDll.vcxproj | Microsoft Visual C++ project file; builds Win32 ANSI and Unicode versions of the DLL, in both Debug and Release variations, plus x64 Unicode also as Debug and Release variations. |
Other implementation files
| File | Description |
|---|---|
| TixDll.c | Implementation of the TixHandler and DllMain functions. This implementation calls per-message handler functions defined in TixHandlers.cpp. Do not modify TixDll.c; place your own code in TixHandlers.cpp instead. |
| TixDll.rc | Standard resources for the extension DLL. Do not modify. |
| TixFunc.cpp | Implementations of most predefined DLL functions. Do not modify. |
| TixFuncText.cpp | Implementations of all text-processing predefined DLL functions. Do not modify. |
| TixHandlers.h | Declarations of the handler functions in TixHandlers.cpp as used by TixDll.c. Do not modify. |
| TixUtils.c | Implementation of utility functions for use in extension DLLs. |
Implementation tips
For best results, please observer the following tips when you implement an extension DLL.
- DO keep it small. If you need tips, contact us.
- DO NOT depend on runtime support beyond standard Windows system DLLs. In particular, try not to depend on the presence of MFC, VB, or other vendor-specific support libraries.
- DO NOT assume anything about the location of the extension DLL with respect to the InstallMate executable. The extension DLL is moved around during installation.
- DO NOT cause or throw exceptions. Although the installer wraps calls to the extension DLL in a try/catch block, exceptions will cause the installer to disable the extension DLL for the remainder of the session.
- If your extension DLL needs to display message boxes, dialogs, or other secondary windows from your extension DLL, DO use the InstallMate window as the parent for your windows. You can obtain a handle to the InstallMate window through iTixRuntime::GetWindow().
- If running a silent installation, DO NOT display message boxes, dialogs, or other windows that require user interaction. DO use iTixRuntime::IsSilentInstall() to check for this condition.