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.

Warning 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:

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:

  1. Your application contacts your Internet server and retrieves the package information file for your application. This is done with the TWUOpenUpdateURL function.
  2. 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.
  3. For each package that must be installed, its installer is retrieved from the server by the TWUGetPackageInstaller function and executed by the TWURunPackageInstaller function.
  4. 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

  1. You cannot mix high-level API calls with the standard API; during any one update session, you must use either one exclusively.
  2. 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.
  3. 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:

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.