TWURunPackageInstaller

The TWURunPackageInstaller function runs the installer of a downloaded update package. The function runs the local copy of the installer and adds the szInstallerArgs from the package data to the installer's command line.

URESULT TWURunPackageInstaller(
    TWUHANDLE hSession,
    const TWUPackageData *pPackage,
    const TCHAR *pszExtraArgs,
    const TCHAR *pszDirectory,
    DWORD dwRunFlags,
    PROCESS_INFORMATION *pProcessInfo,
    DWORD *pdwExitCode
);

Delphi version:

function TWURunPackageInstaller(
    hSession: TWUHANDLE;
    pPackage: PTWUPackageData;
    pszExtraArgs: PTCHAR;
    pszDirectory: PTCHAR;
    dwRunFlags: DWORD;
    var pProcessInfo: PROCESS_INFORMATION;
    var pdwExitCode: DWORD
): URESULT;

Parameters

hSession
[Input] Handle to an open TWU session.
pPackage
[Input] Pointer to the package data whose installer must be run. The installer must have been previously downloaded by TWUGetPackageInstaller.
pszExtraArgs
[Input, optional] Pointer to additional command line arguments for the installer, or NULL if you don't require any additional arguments. If you do provide additional arguments, they are appended (with a space character as separator) to the installer arguments from the update package. You can override this behavior by specifying the TWU_RUNF_REPLACEARGS flag.
pszDirectory
[Input, optional] Pointer to the name of the current directory for the installer, or NULL to use the directory in which the local copy of the installer resides. If you do specify a directory path, it should be fully qualified.
dwRunFlags
[Input] A combination of zero or more flags that modify the default behavior of the function; see Run flags below.
pProcessInfo
[Output, optional] Pointer to a variable that will receive the process information of the installer process, or NULL if you don't need this information. If you request the information, you must close its hProcess and hThread handles with calls to the Win32 API CloseHandle when you no longer need them. If you specify the TWU_RUNF_SHELLEXEC flag, only the hProcess data member is valid; without that flag, all data members of the PROCESS_INFORMATION structure are valid.
pdwExitCode
[Output, optional] Pointer to a variable that will receive the exit code of the installer process, or NULL if you don't need the exit code. This exit code is only meaningful if you specify the TWU_RUNF_SYNCHRONOUS flag; for asynchronous process execution it is always set to 0.

Return value

If the function succeeds, it returns ERROR_SUCCESS (0). If it fails, it returns a nonzero Win32 API error code. You can use TWUGetErrorMessage to retrieve the error message that corresponds to the error code.

Run flags

To modify the default behavior of the TWURunPackageInstaller function, specify one or more of the following flags in the dwRunFlags parameter. Note that some flags are mutually incompatible.

Flag Description
TWU_RUNF_REPLACEARGS Replace the szInstallerArgs from the package data with the arguments given by pszExtraArgs, instead of appending the extra arguments. If you specify this flag, the replacement takes place even if pszExtraArgs is NULL; in that case, the installer is run without any command line arguments at all.
TWU_RUNF_RUNAS

Allow the user to run the installer process under a different user account. This works only on Windows 2000 and later; it has no effect on earlier Windows NT versions or on Windows 9x.

To use this flag, you must also specify TWU_RUNF_SHELLEXEC.

TWU_RUNF_SHELLEXEC

Run the installer process with ShellExecuteEx instead of CreateProcess. This is useful if the installer package isn't an executable program but something else, for example an MSI database.

Using this flag is recommended for regular (.exe) installers on Windows Vista systems, because it will automatically invoke the UAC dialog box Windows needs your permission to continue if necessary to run the package installer with elevated privileges. (On other systems it will do no harm, so you can use it on pre-Vista systems as well.)

You should also specify this flag if you want to use the TWU_RUNF_RUNAS flag.

TWU_RUNF_SUSPENDED

Start the installer process suspended, i.e., the installer process is loaded into memory and fully initialized, but its entry point isn't called yet. This is useful if you want to perform additional synchronization.

If you specify this flag, you must provide a non-NULL pProcessInfo pointer to receive the process and main thread handles of the new process. Failing to do so would cause the new process to be orphaned in a suspended state, from which it cannot recover. To get the installer process running, you must call the Win32 API function ResumeThread on the hThread handle passed back in the pProcessInfo variable.

This flag cannot be combined with TWU_RUNF_SYNCHRONOUS or TWU_RUNF_SHELLEXEC.

TWU_RUNF_SYNCHRONOUS Run the installer synchronously, i.e., the function does not return until the installer process has terminated. Without this flag, the function returns immediately after the installer process has started. In that case, you can use the information passed back in pProcessInfo (if not NULL) for synchronization if desired.