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.

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 Tarma Installer 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 Build Configuration.

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.

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;

hUpdate = TWUOpenUpdate(GetMainHwnd());
TWUCheckUpdate(hUpdate, _T("http://www.yourdomain.com/update.txt"), NULL, 0, &bUpdateAvailable);
if (bUpdateAvailable)
{
    TWUDownloadUpdate(hUpdate, 0);
    TWUInstallUpdate(hUpdate, 0);
    TWURegisterRestart(hUpdate, NULL, NULL, TWU_UFLAGS_CLOSEMAIN);  // See Note 3
}
TWUCloseUpdate(hUpdate);

// In case of an in-place update, call this after the next startup:
TWUCleanupUpdate();

C# code (see Note 4)

IntPtr hUpdate;
Boolean bUpdateAvailable;

hUpdate = TWU.OpenUpdate(this.Handle);
TWU.CheckUpdate(hUpdate, "http://www.yourdomain.com/update.txt", "", 0, out bUpdateAvailable);
if (bUpdateAvailable)
{
    TWU.DownloadUpdate(hUpdate, 0);
    TWU.InstallUpdate(hUpdate, 0);
    TWU.RegisterRestart(hUpdate, "", "", 1);  // See Note 3
}
TWU.CloseUpdate(hUpdate);

// In case of an in-place update, call this after the next startup:
TWU.CleanupUpdate();

Notes

1. This high-level API is included in Tarma Installer 5.7.3662 and later.
2. You cannot mix high-level API calls with the standard API; during any one update session, you must use either one exclusively.
3. 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.
4. If you use the TWU DLL in your C# or other .Net application, then you must use the x64 version (BinX64\twu2009ui.dll) if your application runs on an x64 Windows system, and the 32-bits version (Bin\twu2009ui.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.

Where to find Tarma WebUpdate

The Tarma WebUpdate components are installed along with the rest of Tarma Installer. The following files are used with Tarma WebUpdate (all files and folders are relative to the Tarma Installer TWU installation folder, typically C:\Program Files\Tarma Installer 5\WebUpdate).

*Note: Files marked * are redistributables. If you are a registered user of Tarma Installer, then you may redistribute these DLLs with your own applications. The remaining files may not be redistributed.

System requirements

Tarma WebUpdate has the following system requirements:

• Windows 95, 98, Me, NT4, 2000, XP, 2003, Vista, 2008, 7.
• WinInet.dll - This is a Windows system component that is available on all 32-bit 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) 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.