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
- x86, x64, and arm64 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.
x86, x64, and arm64 Unicode versions
InstallMate's 11 Setup.exe executables come in x86, x64, and arm64 Unicode versions; see Setup stubs for details.
- The x86 Unicode version is compatible with 32-bit, IA64, and x64 editions of Windows XP through to 11 and their Server versions (2003 to 2025).
- The x64 Unicode version is only compatible with x64 and arm64 Windows versions, but offers the best performance on x64 systems.
- The arm64 Unicode version only compatible with arm64 Windows versions and is recommended for 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 all versions, unless you are absolutely certain that you only need one of them..
The extension DLL must use Unicode text processing. If you use the generic text macros in your source code (as the default implementation does, see below), then make sure that both the _UNICODE and the UNICODE preprocessor macros are defined when you build the extension DLL.
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 x86 DLL path, x64 DLL path, and arm64 DLL 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 11\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, do not 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.