Function types | ANSI and Unicode versions | Distribution of the extension DLL | Default implementation | Implementation tips
Extension DLLs allow you to add your own installation functionality to the Tarma Installer Setup 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 Setup program. Extension DLLs must be written in C or C++; Delphi-based extension DLLs are planned for a future release.
The extension DLL can contain one or both of the following function types:
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 cTixMessage 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 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.
Tarma ExpertInstall's installer implementations (i.e., the Setup.exe programs used for installation) come in both ANSI and Unicode versions.
The extension DLL must match the installer's model: either ANSI or Unicode text processing. If you use the Win32 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 section in the TSU Configuration documentation explains when and how each installer version is used. In general, we recommend that you build your extension DLL in both ANSI and Unicode versions, unless you are absolutely certain that you only need one of them.
To distribute your extension DLL, go to the Installer Options project page, check the Include extension DLL box, then enter the paths to your compiled extension DLL versions in the ANSI path and 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).
The Tarma ExpertInstall 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 Tarma ExpertInstall\Tix folder; that same folder also contains the header files that define the data types and interfaces for use in extension DLLs.
The following table contains 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.
| 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. |
| Tix.dsp | Microsoft Visual C++ 6 project file; builds ANSI and Unicode versions of the DLL, in both Debug and Release variations. |
| Tix.h | Main header file; contains most extension DLL declarations and definitions. Do not modify. |
| TixFunc.cpp* | Sample implementation of a custom DLL function. You can use this as a starting point for your own functions. |
| TixDefs.h | Shared header file with common declarations and definitions. Do not modify. |
| TixDll.c | Implementation of the TixHandler function. 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. |
| TixDll.vcproj | Microsoft Visual C++ 7.1 (2003) project file; builds ANSI and Unicode versions of the DLL, in both Debug and Release variations. |
| TixHandlers.cpp* | Per-message function stubs. There is one function per message; comments in the function indicate how to implement the handler if required. |
| TixHandlers.h | Declarations of the handler functions in TixHandlers.cpp as used by TixDll.c. |
| TixRuntime.h | Declaration of the iTixRuntime interface to the installer's runtime engine. Do not modify. |
| TixUtils.c | Implementation of utility functions for use in extension DLLs. |
| TixUtils.h | Declarations of utility functions for use in extension DLLs. |
For best results, please observer the following tips when you implement an extension DLL.