fTixCustomFunc prototype

The fTixCustomFunc prototype defines the parameters and calling convention for custom DLL functions that are called by Run DLL actions. The name is only a placeholder; your own functions may use any legal C/C++ function name, as long as they conform to the prototype.

typedef DWORD (TIXAPI *fTixCustomFunc)(
    iTixRuntime *pTixRuntime,
    int nArgCount,
    const TCHAR **ppszArguments
);

The function receives zero or more 0-terminated string arguments. These arguments are parsed from the Arguments attribute of the Run DLL action that calls the function; this allows you to call the function multiple times with different arguments, or with arguments that depend on the installer's state. The installer will expand any symbolic references and break the argument string into separate arguments before calling the function, similar to the way Windows parses command line arguments before calling the main() entry point in a traditional C or C++ program.

Parameters

pTixRuntime

Pointer to the installer's runtime engine interface. You can use this interface to communicate with the installer.

nArgCount

Number of arguments for the function. The actual arguments are passed in as 0-terminated strings in ppszArguments.

ppszArguments

Array of 0-terminated arguments for the function. As per C/C++ conventions, the arguments are numbered 0..nArgCount-1, so ppszArguments[0] is the first argument and ppszArguments[nArgCount-1] the last. If there are no arguments, nArgCount is 0. In contrast with the traditional main() arguments, ppszArguments[0] does not contain the program's name or path; it is simply the first argument, if any.

Return value

The function must return ERROR_SUCCESS (0, zero) if successful, or a nonzero error code if a failure occurred. Typically, you would return a Win32-style error code if the function encounters a problem. A nonzero return value might terminate the action sequence or even the entire installation (this depends on the Error handling... settings on the Installation Options project page), so you should be careful in what you return.

Implementation tips

The exported name of the function must use standard Win32 decorations; it must not use C++ name mangling. You must also add an 'A' suffix if your extension DLL is compiled for ANSI characters, or 'W' if Unicode. Therefore, you should define your custom DLL functions as follows:

EXTERN_C __declspec(dllexport)
DWORD TIXAPI _F(MyCustomFunc)(
    iTixRuntime *pTixRuntime,
    int nArgCount,
    const TCHAR **ppszArguments
)
{
    ...body of the function...
}

Replace MyCustomFunc with your own function name. The declaration above ensures that the compiler will emit the function's name with the standard Win32 decorations instead of its own C++ scheme.

To use the passed-in arguments, you should use a loop construction like:

int i;
for (i = 0; i < nArgCount; ++i)
{
    ...use ppszArguments[i] here...
}