Tarma WebUpdate
Outline of operation | High-level WebUpdate API | Where to find Tarma WebUpdate | System requirements | Reference
Tarma WebUpdate (TWU) is a dynamic link library (DLL) that enables you to perform automatic software updates from your applications. It offers the following functionality:
- Local and remote package retrieval
- Routines that retrieve package information either locally or remotely (using FTP, HTTP, or HTTPS) and download the corresponding installers to a local file.
- Update version checking
- Routines that retrieve information about locally installed packages and compare them with the remote package information to determine if an update is required.
- Installer execution
- Routines that run the downloaded installers in order to update an application.
The TWU libraries are being phased out and are replaced with the stand-alone TwuX tool, which is available free of charge from our web site. The TWU DLLs and supporting files are still included with InstallMate for the benefit of users who have existing update implementations that use TWU. For new deployments, we recommend using TwuX.
Outline of operation
To use the Tarma WebUpdate functionality in your own application, you must add some application-specific code that uses the Tarma WebUpdate (TWU) routines. In addition, you must provide the following:
- A package information file that describes the remote packages. This is a small text file that must be placed on an Internet server (FTP, HTTP, or HTTPS). You can also place this file on a local server or even on the local system; in that case, you must specify the file: protocol when you retrieve the file with TWUOpenUpdateURL.
- The actual installation packages. These must be placed on the same server as the package information file. There are no special requirements for these installation packages; they can be the same packages that you would distribute otherwise. Furthermore, they do not have to be InstallMate packages; any executable or MSI-based installer can be used.
Tip: The easiest way to generate a package information file that describes your application and its installer is to use the Generate TWU update file option on the Build - Advanced page of your installation package.
During a typical Tarma WebUpdate session, the following actions take place:
- Your application contacts your Internet server and retrieves the package information file for your application. This is done with the TWUOpenUpdateURL function.
- The package information is enumerated and compared to the currently installed version of the application. This is done with a combination of the TWUEnumPackages, TWUFindInstalledInfo, TWUCheckUpdateVersion, and TWUCompareVersions functions.
- For each package that must be installed, its installer is retrieved from the server by the TWUGetPackageInstaller function and executed by the TWURunPackageInstaller function.
- Any (temporary) downloaded files are removed with TWUCleanupDownloads and the connection is closed with TWUCloseSession.
The Tarma WebUpdate sample application demonstrates how to use the Tarma WebUpdate functionality.
Stand-alone Tarma Web Update tool
The functionality of Tarma Web Update is also available as a stand-alone tool from Tarma's web site. See TwuX - Tarma Web Update for information and a download link.
High-level WebUpdate API
For the benefit of users who do not need (or through their choice of programming language, cannot easily access) the flexibility of the standard TWU functions, we offer a simplified set of high-level functions that implements the most common update scenario. Internally the high-level functions use the regular TWU API, but they take care of most implementation details such as callback functions for you.
With the aid of the high-level functions, the outline of the code that you must add to your own application is as follows (error handling omitted for clarity):
C/C++ code
TWUPDATE hUpdate; BOOL bUpdateAvailable; const TCHAR *pszNewVersion; hUpdate = TWUOpenUpdate(GetMainHwnd()); TWUCheckUpdate(hUpdate, _T("http://www.yourdomain.com/update.txt"), NULL, 0, &bUpdateAvailable); if (bUpdateAvailable) { pszNewVersion = TWUGetUpdateVersion(hUpdate); // ...use the new version string for display purposes, if desired... TWUDownloadUpdate(hUpdate, 0); TWUInstallUpdate(hUpdate, 0); TWURegisterRestart(hUpdate, NULL, NULL, TWU_UFLAGS_CLOSEMAIN); // See Note 2 } TWUCloseUpdate(hUpdate); // In case of an in-place update, call this after the next startup: TWUCleanupUpdate();
C# code (see Note 3)
using System.Runtime.InteropServices; // for Marshal.PtrToStringAuto() IntPtr hUpdate; Boolean bUpdateAvailable; String strNewVersion; hUpdate = TWU.OpenUpdate(this.Handle); TWU.CheckUpdate(hUpdate, "http://www.yourdomain.com/update.txt", "", 0, out bUpdateAvailable); if (bUpdateAvailable) { strNewVersion = Marshal.PtrToStringAuto(TWU.GetUpdateVersion(hUpdate)); // ...use the new version string for display purposes, if desired... TWU.DownloadUpdate(hUpdate, 0); TWU.InstallUpdate(hUpdate, 0); TWU.RegisterRestart(hUpdate, "", "", 1); // See Note 2 } TWU.CloseUpdate(hUpdate); // In case of an in-place update, call this after the next startup: TWU.CleanupUpdate();
Notes
- You cannot mix high-level API calls with the standard API; during any one update session, you must use either one exclusively.
- The TWURegisterRestart call is only required if you perform an in-place update, that is, if your application updates itself. If you are using the TWU functions in a separate program, then you can omit this call.
- If you use the TWU DLL in your C# or other .Net application, then you must use the x64 version (BinX64\twu2010ui.dll) if your application runs on an x64 Windows system, and the 32-bits version (Bin\twu2010ui.dll) if running on a 32-bits Windows system. This is because the .Net interoperability layer expects to use the DLL that corresponds to the underlying Windows model, even if the .Net application itself is built as a 32-bit executable. See Where to find Tarma WebUpdate for information about the DLL versions.
For more information about the high-level API, use the links in the following table.
| Name | Description |
|---|---|
| TWUCheckUpdate | Contacts your server to check for updates |
| TWUCleanupUpdate | Performs clean-up actions after application restart |
| TWUCloseUpdate | Ends the update process and optionally restarts your application |
| TWUDownloadUpdate | Downloads the update, if any is available |
| TWUGetUpdateName | Returns the name of the update, if any |
| TWUGetUpdateVersion | Returns the version of the update, if any |
| TWUInstallUpdate | Installs the update that was downloaded, if any |
| TWUOpenUpdate | Start the update process |
| TWURegisterRestart | Registers your application for a restart following an update |
Where to find Tarma WebUpdate
The Tarma WebUpdate components are installed along with the rest of InstallMate. The following files are used with Tarma WebUpdate (all files and folders are relative to the InstallMate TWU installation folder, typically C:\Program Files\InstallMate 9\WebUpdate).
*Note: Files marked * are redistributables. If you are a registered user of InstallMate, then you may redistribute these DLLs with your own applications. The remaining files may not be redistributed.
| Folder | File | Description |
|---|---|---|
| Bin\ | TWU2010ai.dll* | Tarma WebUpdate DLL, 32-bit ANSI version. |
| TWU2010aid.dll | Tarma WebUpdate DLL, 32-bit ANSI Debug version, for testing only. | |
| TWU2010ui.dll* | Tarma WebUpdate DLL, 32-bit Unicode version. | |
| TWU2010uid.dll | Tarma WebUpdate DLL, 32-bit Unicode Debug version, for testing only. | |
| BinX64\ | TWU2010ui.dll* | Tarma WebUpdate DLL, x64 Unicode version. |
| TWU2010uid.dll | Tarma WebUpdate DLL, x64 Unicode Debug version, for testing only. | |
| Include\ | TWU.cs | C# class definition that defines the Tarma WebUpdate functions (high-level API only). You must include this file in your own C# project to use the Tarma WebUpdate functionality. |
| TWU.h | Header file that defines the Tarma WebUpdate functions and data structures. You must #include this file in your own C/C++ project to use the Tarma WebUpdate functionality. | |
| TWU.pas | Unit file for Borland Delphi that defines the Tarma WebUpdate functions and data structures. You must add a uses TWU clause to your own Delphi source files to use the Tarma WebUpdate functionality. | |
| TWUDefs.h | Base declarations for Tarma WebUpdate, automatically #included by TWU.h | |
| Lib\ | TWU2010ai.lib | 32-bit ANSI import library for Tarma WebUpdate. |
| TWU2010aid.lib | 32-bit ANSI import library for Tarma WebUpdate, Debug version. | |
| TWU2010ui.lib | 32-bit Unicode import library for Tarma WebUpdate. | |
| TWU2010uid.lib | 32-bit Unicode import library for Tarma WebUpdate, Debug version. | |
| LibX64\ | TWU2010ui.lib | x64 Unicode import library for Tarma WebUpdate. |
| TWU2010uid.lib | x64 Unicode import library for Tarma WebUpdate, Debug version. |
System requirements
Tarma WebUpdate has the following system requirements:
- Windows 95, 98, Me, NT4, 2000, XP, 2003, Vista, 2008, 7, 8, 10.
- WinInet.dll - This is a Windows system component that is available on all Windows version that have Internet Explorer 3.0 or later installed.
- A network connection for access to remote packages and package information. The usual TCP/IP ports are used for the various protocols (FTP: port 22, HTTP: port 80, HTTPS: port 443), so any firewalls must allow traffic through these ports.
To build an application that uses Tarma WebUpdate, you will need the a Microsoft Visual C++ compiler (6.0, 2002, 2003, 2005, 2008, 2010) and the files mentioned above. You can use either the ANSI or the Unicode versions of the TWU entry points.
Reference
Refer to the following topics for more information about the various functions and types.
| Name | Description |
|---|---|
| fTWUCallback | General event/progress callback function prototype |
| fTWUPackageCB | Callback function prototype for use by TWUEnumPackages and TWUEnumPackageDependencies. |
| TWUCheckUpdateVersion | Compares the file version of a local file against the version of an update package. |
| TWUCleanupDownloads | Deletes all downloaded files. |
| TWUCloseSession | Closes an update session. |
| TWUCompareVersions | Compares two version numbers. |
| TWUDebugPrintf | Prints a formatted string in the debugging log file. |
| TWUEnumPackageDependencies | Enumerates the dependencies of a package. |
| TWUEnumPackages | Enumerates the packages in the package information file. |
| TWUFindInstalledInfo | Retrieves the installation information of a currently installed application. |
| TWUFindPackage | Finds a package by name. |
| TWUGetErrorMessage | Retrieves a Win32 error message text. |
| TWUGetEventArg | Returns a pointer to an additional event callback argument. |
| TWUGetPackage | Returns a package by index. |
| TWUGetPackageCount | Returns the number of packages in the package information file. |
| TWUGetPackageInstaller | Downloads a package installer. |
| TWUGetPIF | Retrieves and parses a package information file. |
| TWUGetVersionInfo | Get the fixed VERSIONINFO for a file. |
| TWUInstalledInfo | Defines the installed product information returned by TWUFindInstalledInfo. |
| TWUOpenSession | Opens an update session. |
| TWUOpenUpdateURL | Opens an update session and downloads a package information file. |
| TWUPackageData | Defines the package information. |
| TWUParseVersion | Parse a version string into a numeric version number. |
| TWURegisterCallback | Registers an event/progress callback function |
| TWURunPackageInstaller | Executes a downloaded package installer. |