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

The extension DLL can contain one or both of the following function types:

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:

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 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 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.