Package Information File

File sections | Accessing the PIF contents | Sample package information file

The package information file used by Tarma WebUpdate is a text file in Windows .ini format that stores version information about the packages. During a web update this file is retrieved, its contents are interpreted to see if updates are necessary, and if they are, the actual package installers are retrieved and executed.

Some tips:

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.

File sections

A package information file must contain the following sections.

[TarmaWebUpdate]

This section is used to identify Tarma WebUpdate package information files. It declares the TWU version format, plus a list of the packages that appear in the file. Each declared package must appear as a separate section elsewhere in the package information file.

This section contains the following keys:

Key Description
Version TWU package information format version. Must be set to 1.
Packages Comma-separated list of the packages that appear in the file. Do not places spaces around the commas, unless you want them to be part of the package names.

[package name]

For each declared package, a corresponding package section must appear in the package information file. Each package section describes a single package. A package information file must contain at least one package description, but it may contain several. The packages in a package file may be related (for example, through dependencies), or they may be unrelated if you want to use a single package information file for several products. After downloading and parsing the PIF (see TWUGetPIF), the data are available as a TWUPackageData objects through calls to TWUGetPackage.

This section contains the following keys:

Key Description
ProductCode Unique product code, as used for the registration of the product's uninstall information registry key.
AltProductCodes Optional list of alternate product codes, separated by commas. These product codes are tried, in order, if the primary ProductCode is not present on the target system.
Version Product version as a.b.c.d.
DisplayName Name of the product for display to the user.
DisplayVersion Version of the product for display to the user.
NewsURL Optional URL to a What's New or similar web page that can be used to display release information about the update.
InstallerPath Path to the package installer, relative to the location of the package information file itself.
InstallerArgs Command line arguments for the package installer, if any.
DownloadSize Optional, estimated size of the package installer, in bytes. TWU determines the download size when the package download starts; the DownloadSize field (and its counterpart in TWUPackageData) can be used if the client code wants to provide an early indication of the expected download size.
DependsOn Comma-separated list of the packages that must be pre-installed for the current package. These package, if any, must appear in the same package information file. Do not places spaces around the commas, unless you want them to be part of the package names.

Accessing the PIF contents

Because package information files follow the Windows .ini format, you can use Win32 functions such as GetPrivateProfileInt and GetPrivateProfileString to read portions of the file. The best place to process PIF contents is as part of an event callback function, in particular the following events:

Event Description
TWU_CBEVENT_PIF_STARTPARSE

Parsing of the downloaded PIF is about to start.

GetEventArg(pszEventMsg, 0)=Path to the local PIF copy

TWU_CBEVENT_PIF_ENDPARSE

Parsing of the downloaded PIF is complete.

GetEventArg(pszEventMsg, 0)=Path to the local PIF copy

TWU_CBEVENT_PIF_STARTPACKAGE

Parsing of a package section in the downloaded PIF is about to start.

GetEventArg(pszEventMsg, 0)=Path to the local PIF copy

GetEventArg(pszEventMsg, 1)=Package section name

TWU_CBEVENT_PIF_ENDPACKAGE

Parsing of a package section in the downloaded PIF is completed.

GetEventArg(pszEventMsg, 0)=Path to the local PIF copy

GetEventArg(pszEventMsg, 1)=Package section name

You can use this as follows in your code:

URESULT MyCallback(TWUHANDLE hSession, int nEventCode,
    const TCHAR *pszEventMsg, UINT64 ulProgress,
    UINT64 ulTotal, LPARAM lCookie)
{
    TCHAR szBuffer[256];

    switch (nEventCode)
    {
    case TWU_CBEVENT_PIF_STARTPACKAGE:
        if (GetPrivateProfileString(GetEventArg(pszEventMsg, 1),
            _T("MyKey"), NULL, szBuffer, __countof(szBuffer),
            GetEventArg(pszEventMsg, 0)) > 0)
        {
            ...do stuff with szBuffer...
        }
        break;
    }
    return ERROR_SUCCESS;
}

Sample package information file

[TarmaWebUpdate]
Version=1
Packages=tin2,tin3,winsizer

[tin2]
ProductCode=InstallMate
Version=2.99.2185.0
DisplayName=Tarma QuickInstall 2
DisplayVersion=2.99.2185 (24 December 2005)
NewsURL=http://www.installmate.com/products/tin2/history.htm
InstallerPath=tin2.exe
InstallerArgs=
DownloadSize=1400560

[tin3]
ProductCode={760C70C3-ABE2-4F51-89D3-0FA2C43E8F51}
Version=3.0.2186.0
DisplayName=InstallMate
DisplayVersion=3.0.2186 Beta (25 December 2005)
NewsURL=http://www.installmate.com/products/tin3/history.htm
InstallerPath=tin3beta.exe
InstallerArgs=
DownloadSize=2756408

[winsizer]
ProductCode=WinSizer
Version=1.41.2086.0
DisplayName=WinSizer
DisplayVersion=1.41.2086 (16 September 2005)
NewsURL=http://www.installmate.com/products/winsizer/index.htm
InstallerPath=WinSizerSetup.exe
InstallerArgs=
DownloadSize=103368