TwuX - InstallMate Software Updater
TwuX is a stand-alone software update tool designed to be used in conjunction with our own installers such as InstallMate 9, but it can also be used with third-party installers. The functionality of TwuX.exe is equivalent to that of the Tarma Web Update DLL version, but requires no custom programming.
InstallMate Software Updater 4.9 and later
InstallMate Software Updater 4.8 and earlier
InstallMate Software Updater ["this program"] is copyright © 1990-2016 Tarma Software Research Ltd.
You may use this program for personal, business, non-profit, and for-profit purposes, provided that your usage complies with all of the following conditions:
- This program is only used to add software update functionality to a product that you or your organization are legally entitled to distribute.
- You do not charge a fee for the updater functionality per se (you are free to charge a fee for your overall product).
- You do not misrepresent the origins and authorship of this program.
- Tarma Software Research Ltd will not be held liable for errors or omissions in this program.
Other uses of this program require the express written permission from Tarma Software Research Ltd.
The download package contains two versions of the TwuX.exe tool:
- twux32.exe is the 32-bit Unicode version (can also be used on 64-bit platforms);
- twux64.exe is the 64-bit Unicode version (can only be used on 64-bit platforms).
You can use the 32-bit version on all Windows platforms; the 64-bit version will only run on 64-bit editions of Windows.
- Download TwuX.exe - version 220.127.116.1161, 20 February 2017 (with EV code signing certificates)
- Download TwuX.exe Debug edition - version 18.104.22.16861, 20 February 2017 (with standard code signing certificates)
System requirements: Runs on all Windows XP and later versions, including XP, Vista, 7, 8, 10, and their Server editions.
The last TwuX release with separate ANSI and Unicode versions was 22.214.171.12473, released on 27 October 2015.
Note: This version is no longer maintained and should only be used if you need to deploy on Windows platforms earlier than Windows XP.
The archived download package contains two versions of the TwuX.exe tool:
- twuxA.exe is the ANSI version for use on Windows 95, 98, Me;
- twuxW.exe is the Unicode version for use on Windows NT4, 2000, XP, Vista, 7, 8, and their Server editions.
We recommend using the twuxW.exe version, unless you deploy your product also on Windows 9x.
- Download TwuX.exe - version 126.96.36.19973, 27 October 2015
- Download TwuX.exe Debug edition - version 188.8.131.5273, 27 October 2015
System requirements: Runs on all Windows 9x and later versions, including NT4, 2000, XP, Vista, 7, 8, and their Server editions. Requires Internet Explorer 4 or later to be installed on the system.
TwuX performs the following actions:
- It downloads a package information file from a given URL.
- Using the information from the file, it checks if the software product described by the file is present on the computer and if so, which version is currently installed.
- If the product is not currently installed or if a newer version is available, TwuX then offers to download and install the new version.
- Optionally, TwuX will close the main program before the update is installed and restart it after the installation is complete.
To use TwuX for your own products, you need to prepare the following:
- An installer for your product (created with InstallMate or another installer builder); and
- A package information file for the installer. This can be done automatically with InstallMate; see the Generate TWU update file option.
- [Optional] A web page with the release notes for your product. You must enter the URL of this web page in the NewsURL field of the package information file. Alternatively, enter the URL in the Update URL field on the Product Info page in your InstallMate project; this will then be copied to the package information file.
Place the two files (installer plus package information file) together on your web server and make a note of the URL to the package information file. From then on, each time you release a new version of your product, you must update (1) and (2) and place the updated versions on your web server.
If you provide the URL for the release notes, then the Show Release notes button will be enabled in the Software Updater window (see screen shot above) and the user's web browser will be used to open that URL when the user clicks on that button.
You can use the update tool in two ways. In both cases, you must install TwuX.exe along with your own program, although not necessarily in the same folder.
- By calling TwuX.exe with the correct command line options from your own program, possibly in response to a Check for updates command in that program; or
- By installing a shortcut to TwuX.exe with the correct command line options in its Arguments field.
TwuX /? TwuX [options] [@response.txt] [URL]
- The first form displays a syntax summary and exits.
- The second form downloads the package information file given by URL and performs the update according to options.
The package information file must follow the format used by TWU; see Package Information File for details. Note that this type of file can be automatically generated by InstallMate 7 and InstallMate 9 when you build an installer; see the documentation of the Generate TWU update file option.
|TwuX||Name of the program; .exe is implied. You may have to use a fully qualified file path if TwuX.exe is located in a folder that does not appear in your PATH environment variable.|
[Since version 4.9] Open this web page in your web browser, then exit the program.
[Version 4.8 and earlier] Display a message box with version info and syntax summary; exit when the user closes the message box.
[Since version 4.5] Use name as the application name (and optional version) in the User-Agent string of the updater. If you do not specify this option or if name is an empty string, the default InstallMate® major.minor.build will be used.
Tip: To use an application name (and optional version number) that contains spaces, "quote" the entire option as in: "/a:MyGizmo 3.12.345"
|/f||[Since version 4.9] Force the update check, even if the user has previously indicated that he/she wanted to skip the currently available update version.|
|/k||[Since version 4.2] Keep downloaded files. By default, TwuX.exe deletes all downloaded installer files at the end of the session; this option prevents the deletion.|
Use langid as the user interface language for the updater. As a special case, if you specify /l:0 (i.e., a langid value of zero), then the updater will use the best matching available language for the user's system or fall back to US English as a last resort.
langid must be the decimal or hexadecimal Windows language identifier of the desired language; hexadecimal language identifiers must start with 0x ("zero ex"). Therefore, /l:1033 and /l:0x409 are equivalent and both designate US English. See the MSDN web site for a complete list of language identifiers.
Currently the following languages are supported: German (0x0407 or 1031); US English (0x0409 or 1033); Japanese (0x0411 or 1041); Croatian (0x041A or 1050); Turkish (0x041F or 1055).
[Since version 4.14] Check for updates, but do not install any update. If an update is available, the program exits with exit code 1604 (ERROR_INSTALL_SUSPEND); if no update is available, the exit code is 1634 (ERROR_INSTALL_NOTUSED).
Note: If you want to avoid all user interaction when using this option, then you must also specify /qb (see below).
Close all processes in list before installing updates. The list must consist of process names (including their .exe file extension) and separated by commas, like this: proc1.exe,proc2.exe,proc3.exe.
If you use the /w option (see below), then you do not have to specify the parent process name in the /p list, but note that in contrast the the /w option, the /p option does not try to restart the processes after the update.
Run in quiet mode, i.e., without querying the user for permission or showing other message boxes that require user interaction. Without this parameter, TwuX will ask for permission to install an update if available, and also confirm other actions.
If you use the second form (/qb), then the updater will ask for permission before performing an update, but will not show a message box if no update is available or if the update check fails.
If you use the third form (/qq), then the updater will run extra quiet and will perform the update without asking for permission and without showing a progress bar during the download. (The actual installation process might still show a progress bar, though.)
|/s:name||Use name as the name of the package section in the update information file. If you do not specify this option, the main section will be used.|
|/t:title||[Since version 4.9] Use title as the title in dialog boxes. If you do not specify this option, then InstallMate® Software Updater will be used initially until the package information is available, after which the title will be set to <PackageName> Software Updater.|
|/v||Run verbose; the opposite of /q. This option cancels any prior /q option.|
|/V||[Since version 4.9] Display a message box with version info; exit when the user closes the message box.|
Use hwnd as the main window handle of of the parent process. If specified, this must be the window handle of the process that nominally controls the update; it will be closed and restarted automatically if an update must be installed. You may use either decimal or hexadecimal notation to specify the handle value; a hexadecimal value must start with 0x (zero ex).
This option is typically used when TwuX is invoked from the application to which the update applies.
Use response.txt as a response file for further command line arguments, including possibly the URL of the update information file.
A response file is a plain text file (encoded in the current ANSI code page, or UTF-8 with a leading BOM, or UTF-16 with its leading BOM) that contains one or more command line arguments separated by any combination of spaces, tabs, or newlines.
The syntax of the arguments in the response file is similar to the normal command line usage; in particular, any arguments that contain internal spaces must be "quoted". However, response files differ from normal command line syntax in the following ways:
Response files may be nested and will be processed if and when they appear on the command line and in other response files, and the same left-to-right processing rules apply when conflicting arguments are encountered (i.e., the rightmost argument "wins").
Internal comment lines
Response files may contain internal comment lines for documentation purposes; the contents of a comment line are ignored by the program.
Comment lines must start with '#' in the first column of the line and extend up to and including the next line break or the end of the file, whichever comes first. '#' characters that appear after the first column of a line are not treated as comments and are considered part of the argument in which they appear. Some examples:
# This is a comment line # But this is not (# appears in column 2) "# Nor is this" /nor#this nor#this.txt # But this is another comment
Fully qualified URL of the update information file. You may specify this URL directly on the command line or in the response file, if any.
The URL can take on one of the following forms:
In all cases, server must be a server address that is valid for the protocol (for example, www.tarma.com for HTTP and HTTPS; ftp.tarma.com for FTP; or a plain host name for FILE).
The server portion may include protocol-specific qualifiers such as www.tarma.com:8080 (a port number for HTTP) or firstname.lastname@example.org (a user name for FTP).
Note that for the second file: protocol example the server portion may be empty (meaning "on the local machine"); hence the three consecutive /// characters in that case.
/path/to/file is the fully qualified path to the file on the server.
Note: The canonical forms for the file: protocol are examples #1 and #2 in the list above. However, some versions of WinInet.dll (on which TwuX.exe relies for the download process) only accept the incorrect format #3, which is simply a regular file path with a file:// prefix.
The exit code of the Twux.exe process gives an indication of the actions that were performed. However, in contrast to the usual exit code convention of "zero is success, nonzero is error", there are various nonzero exit codes that might indicate partial success.
- In programmatic use (for example, if you use CreateProcess(), ShellExecuteEx(), or some similar function to run TwuX.exe), you can retrieve the exit code through the GetExitCodeProcess() Win32 API call.
- On the command line or in a batch file the exit code can be tested through the %ERRORLEVEL% variable or by using an IF ERRORLEVEL statement, but see the caveat under Using the start /wait option below.
The following are some of the most common exit codes, but others might also occur. Consult the Windows error code list for more information.
Note: Error codes marked [InstallMate #xx] are the result of the corresponding InstallMate exit codes during the update process.
|0||ERROR_SUCCESS||Success. An update was available and was successfully installed.|
|2||ERROR_FILE_NOT_FOUND||The file specified by the URL does not exist.|
|3||ERROR_PATH_NOT_FOUND||The path contained in the URL does not exist.|
|5||ERROR_ACCESS_DENIED||[InstallMate #17] Insufficient access rights for installation.|
|13||ERROR_INVALID_DATA||Invalid or missing update file, or invalid registry data.|
|29||ERROR_WRITE_FAULT||[InstallMate #4] Error while saving installer database.|
|32||ERROR_SHARING_VIOLATION||[InstallMate #13] Application is currently running.|
|86||ERROR_INVALID_PASSWORD||[InstallMate #15] Incorrect or missing installation password.|
|87||ERROR_INVALID_PARAMETER||Invalid command line option in TwuX.|
|112||ERROR_DISK_FULL||[InstallMate #16] Insufficient disk space for installation.|
|122||ERROR_INSUFFICIENT_BUFFER||Insufficient memory to perform one or more operations.|
|123||ERROR_INVALID_NAME||No or invalid URL specified on the command line.|
|126||ERROR_MOD_NOT_FOUND||The requested package was not found in the update information retrieved from the URL.|
|740||ERROR_ELEVATION_REQUIRED||[InstallMate #10] Installer requires Administrator rights.|
|1114||ERROR_DLL_INIT_FAILED||[InstallMate #2] Installer initialization error.|
|1223||ERROR_CANCELLED||The user cancelled the update process, either directly or by denying UAC permission for the update.|
|1359||ERROR_INTERNAL_ERROR||[InstallMate #19] Error while running installer actions.|
|1602||ERROR_INSTALL_USEREXIT||[InstallMate #5] Installation cancelled by user or action.|
|1603||ERROR_INSTALL_FAILURE||[InstallMate #6] Other installation failure.|
|1604||ERROR_INSTALL_SUSPEND||An update is available but is not installed, because either the user chose to skip this version, or the /n command line option is in effect.|
|1610||ERROR_BAD_CONFIGURATION||[InstallMate #7] Invalid run mode.|
|1612||ERROR_INSTALL_SOURCE_ABSENT||An HTTP status code other than 200 (OK) was received while downloading the update|
|1618||ERROR_INSTALL_ALREADY_RUNNING||[InstallMate #20] Product installer is already running.|
|1620||ERROR_INSTALL_PACKAGE_INVALID||[InstallMate #3] Invalid or missing installer database.|
|1621||ERROR_INSTALL_UI_FAILURE||[InstallMate #8] Error while creating the user interface.|
|1625||ERROR_INSTALL_PACKAGE_REJECTED||[InstallMate #11] Target system requirements not met.|
|1627||ERROR_FUNCTION_FAILED||[InstallMate #18] Extension DLL returned error status.|
|1634||ERROR_INSTALL_NOTUSED||The currently installed product version is up to date.|
|1638||ERROR_PRODUCT_VERSION||[InstallMate #14] Previous product version detected.|
|1639||ERROR_INVALID_COMMAND_LINE||[InstallMate #9] Invalid installer command line option.|
|1793||ERROR_ACCOUNT_EXPIRED||[InstallMate #1] Installer trial period is expired or invalid.|
|2012||ERROR_TAG_NOT_FOUND||The specified update section was not found. This usually means an invalid update information file, possibly caused by an invalid URL that returns your web server's 404 error page instead of the requested file.|
|3010||ERROR_SUCCESS_REBOOT_REQUIRED||[InstallMate #12] Reboot required to complete installation.|
|12005||ERROR_INTERNET_INVALID_URL||The specified URL or one derived from it (e.g., in the package information file) is invalid.|
|Others||Consult the Windows error code list for more information|
If you run Twux.exe from a batch file or command line prompt, the default Windows behavior is to continue with the next command as soon as Twux.exe is started; it does not wait until Twux.exe has finished. As a result, the value of %ERRORLEVEL% does not necessarily reflect the Twux.exe exit code.
To remedy this, run Twux.exe as follows:
start /wait Twux.exe other_options...
This ensures that the command does not return until Twux.exe has exited.
Providing a dummy "title" field for the CMD.EXE start command
[Windows NT/2000/XP/Vista/7/8 and later] If the Twux.exe program path in the start command contains spaces, you must quote it. However, the start command on Windows NT/2000/XP/Vista/7/8 and later interprets the first quoted string as the program title and not as a program path. Therefore, you should include a dummy, quoted program title prior to the actual program path, thus:
start /wait "title" "c:\path\to\twux.exe" other_options...
This is only necessary if you quote c:\path\to\twux.exe for some reason.
Note that this tip only applies to the Cmd.exe command interpreter used on Windows NT/2000/XP/Vista/7/8 and later systems; the Command.com command interpreter on Windows 9x systems does not support a title option and therefore requires no workaround.
Here are some usage examples.
- TwuX /?
- Displays a message box with the syntax summary and exits when the message box is closed.
- TwuX /p:tin.exe http://www.tarma.com/download/tin9.txt
- Downloads the file tin9.txt from Tarma's web server and updates your InstallMate 9 installation if given permission to do so. It also closes any running tin.exe processes before installing the update.
- TwuX /q /p:tin.exe http://www.tarma.com/download/tin9.txt
- Same as the previous, but performs the whole process without asking for confirmation.
- TwuX /w:0x1a0344 http://www.tarma.com/download/tin9.txt
- Same as the second example, except that TwuX will close the process associated with main window handle 0x1a0344 before installing the update and restart it afterwards. This form is typically used when TwuX is invoked from the application to which the update applies.