Technical Reference InstallMate User's Manual
InstallMate 7

Windows Logo Requirements

Installers created with InstallMate 7 comply with Microsoft's Windows Logo requirements for all supported versions of Windows, including Windows 7.

To obtain a copy of the Windows Logo requirements for Windows 7, go to the following web page. You need to download an XPS document from this web page.

Below is a point-by-point overview of the logo requirements as they apply to installation tools, relative to the most recent (Windows 7) set of Windows Logo requirements. You can use this overview as a reference if you want to obtain Windows Logo validation for installers created with InstallMate 7. The terminology used below corresponds to the terms used in the Windows Logo requirements documentation.

If you need additional information or implementation details to achieve Windows Logo certification, then please contact support@tarma.com.

Supported Windows versions

Do not modify WRP protected resources

Installers built with InstallMate 7 fully adhere to the Windows Resource Protection (WRP) guidelines (this was called Windows File Protection before the introduction of Windows Vista).

File protection

Before a file is replaced or removed, InstallMate uses the SfcIsFileProtected() function to check if the file is protected. If it is, then no attempt is made to modify the file. In the installer's log file, this is indicated with a TSU:W0009 diagnostic.

Registry key protection

Before a registry key is modified or removed, InstallMate uses the SfcIsKeyProtected() function to check if the key is protected. If it is, then no attempt is made to modify the key or any of its values. In the installer's log file, this is indicated with an "Access denied" error code (decimal 5) on the applicable registry action.

Applies to

Fall-back behavior

On platforms that do not implement resource protection, the installer obeys the usual Windows security settings as applied through ACLs.

Windows Restart Manager support

Installers built with InstallMate 7 use the Windows Restart Manager functionality where available to manage in-use file replacements and system reboots. In particular, each installer performs the following Restart Manager-related tasks during an installation session.

  1. The RmStartSession() function is called to obtain a Restart Manager session context. Secondary installers automatically join the primary installer's Restart Manager session, instead of starting a separate session.
  2. The installer builds a list of files that need to be replaced during installation. This list takes into account factors such as file versions and file replacement policies (both user-specified and WRP-based). Files that are newly installed (i.e., that do not replace existing files) are excluded from the list.
  3. If the list is not empty, then the following happens:
    1. The RmRegisterResources() function is called with the list of files that need to be replaced.
    2. The RmGetList() function is called to obtain the Restart Manager's reboot status. If a reboot is indicated, then the internal TsuRebootRequired variable is set.
    3. The RmShutdown() function is called to try and shut down any processes that hold resources listed for replacement.
  4. The installer performs its installation tasks, including the replacement of files where applicable. If, despite the RmShutdown() function call, in-use files are encountered, then they are handled as described under the Fall-back behavior heading below.
  5. At the end of the session, the RmRestart() function is called to restart any applications and services that were shut down earlier.
  6. The RmEndSession() function is called to release any internal resources held by Restart Manager.

Any system reboots are managed as described in the section System reboot management.

Applies to

This applies to all platforms where Restart Manager functionality is available. Nominally this includes Windows Vista and later, including their Server editions. However, the installer does not assume specific platforms; instead, it performs a direct check on the availability of the Restart Manager entry points and will use them on any platform that implements them.

See also Windows Vista Restart Manager support.

Fall-back behavior

On platforms where Restart Manager functionality is not available, InstallMate manages the replacement of in-use files on its own. This functionality is also used in situations where Restart Manager is unable to shut down all processes that hold in-use files.

If an in-use file is encountered that needs to be replaced, then the following happens:

The remainder of the installation session is modified somewhat:

Note that the installer makes no attempt to shut down any processes.

Remarks

The chances of encountering in-use files can be reduced by specifying a running process check on the Installer Options page. If any processes are specified and either Process check: Advisory check or Process check: Blocking check is set, then the installer will inform the user if any conflicting processes are running prior to installation and offer the user the opportunity to close down those processes. However, the installer will never forcibly shut down any processes by itself, except as documented earlier through the Windows Restart Manager functionality.

System reboot management

Installers built with InstallMate 7 have flexible system reboot management, but will never reboot the system without the user's consent. In particular:

If a system reboot is required but not performed, an exit code of 12 (Reboot required) is returned by the installation process as documented in InstallMate Command Line Options. This allows higher-level processes to act upon or propagate the reboot status.

Applies to

All supported Windows versions.

Remarks

The need for a system reboot to complete the installation is indicated by the TsuRebootRequired internal variable. In addition, the TsuRebootMode variable can override this by suppressing all reboots, by always scheduling one, or by following whatever the TsuRebootRequired variable indicates (this is the default). However, while these variables may be used by actions in the installer, they will never cause a reboot without the user's consent.

A reboot may be requested and the TsuRebootRequired variable be set by one or more of the following:

An overall forced reboot, reflected in the TsuRebootMode variable, may be set by one or more of the following:

Note: Even a "forced" reboot status only leads to an actual system reboot if the user consents.

Conversely, system reboots may be suppressed by any of the following:

If system reboots are suppressed by any of these methods, then the installer will not initiate a system reboot and will not ask the user for consent (because none is required). However, the exit code of the installation process is still set to 12 (Reboot required) if the TsuRebootRequired variable indicates the need for a reboot.

Clean, reversible installation

Installers built with InstallMate 7 perform clean, reversible installations and removals, as required by the Windows Logo requirements.

Installation roll back in case of failure

During the first installation and any subsequent updates, InstallMate keeps track of all system resources that it changes or replaces, and will roll back any changes if the installation session ends prematurely through a failure or because the user cancels the installation before it completes.

To achieve this, InstallMate implements a two-phase commit protocol as follows:

  1. During the initial phase, all installation actions are performed as required. An internal journal is kept that records all system modifications and their original state, keeping a copy of each replaced or deleted file, each modified registry key or value, and all other modified system resources where necessary.
  2. If the initial phase completes successfully, then all system modifications are committed and roll-back copies are discarded.
  3. If the initial phase does not complete successfully, whether through a system failure, insufficient access rights, or because of a user action, then the journal is used to restore the original system state. Among other things, any replaced or deleted files are restored to their original versions, newly installed files and folders are removed, and any system changes (including, but not limited to, registry key and value changes) are rolled back. The roll back takes place in the reverse order of the original changes, to ensure that any overlapping modifications are rolled back correctly.

This two-phase commit protocol is executed automatically, without user intervention. It extends to custom actions, which have an Execute option for this purpose:

The effect of the Execute option on these actions is as follows:

Execute Description
Immediate Execute the action when encountered in the action sequence. This is the default.
Commit Defer execution until the installation is committed. This option allows you to implement the "Commit" part of a two-phase commit protocol that is only executed if the installation was successful.
Rollback Defer execution until the installation is rolled back. This option allows you to implement the "Rollback" part of a two-phase commit protocol that is only executed if the installation fails and must be rolled back.

Applies to

All supported Windows platforms.

Remarks

In addition to the automatic roll back mechanism, developers who use InstallMate can also specify on a per-file and per-resource basis if individual files or other system resources should be restored to their original (pre-installation) versions if the developer's product is ever uninstalled. This takes the form of a Remove action: Restore original option in the applicable installation item. For further details, see:

This type of resource restoration is separate from of the automatic roll back mechanism.

Installation requirements

Installers built with InstallMate 7 comply with the general installation requirements prescribed by the Windows Logo requirements. According to the Windows Logo requirements, an installer should:

Applies to

All supported Windows platforms.

Product uninstaller information

Installers built with InstallMate 7 register all product uninstallation information prescribed by the Windows Logo requirements, plus additional information that is not required, but commonly used (or that was required by earlier versions of Windows).

The following information is recorded in the registry under the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\{...product GUID...} registry key for per-machine installations, or under the equivalent HKEY_CURRENT_USER registry key for per-user installations.

Registry value Type Description
Comments REG_SZ

[Optional] Additional product-related information, copied from the Comments variable (which is in turn initialized from the Comments field on the Product Identification page).

This registry value is only written if the Comments field was enabled on the Product Identification page.

Contact REG_SZ

[Optional] Primary contact email address for the product, copied from the Email variable (which is in turn initialized from the Email address field on the Product Identification page).

This registry value is only written if the Email address field was enabled on the Product Identification page.

DisplayIcon REG_SZ Fully qualified path to the .ico file that contains the product's application icon. The .ico file contains a copy of the icon that was specified in the Custom icon field of the Build Configuration that was used to build the installer, or a standard icon if no custom icon was specified.
DisplayName REG_SZ Descriptive name of the installed product. This defaults to <ProductName> <ProductVersion> (i.e., the name of the product followed by its version), but can be modified in the Display name field on the Installer Options page.
DisplayVersion REG_SZ Version number of the product, as text (the Version, VersionMajor, and VersionMinor registry values contain the product's version number in binary format). It is copied from the ProductVersion variable (which is in turn initialized from the Version field on the Product Identification page).
EstimatedSize REG_DWORD Total installed size for the product, in KB. This information is displayed in the Add/Remove Programs control panel applet.
HelpLink REG_SZ

[Optional] URL of the product's technical support web page, copied from the SupportURL variable (which is in turn initialized from the Support URL field on the Product Identification page).

This registry value is only written if the Support URL field was enabled on the Product Identification page.

HelpTelephone REG_SZ

[Optional] Telephone number of the product's technical support department, copied from the Telephone variable (which is in turn initialized from the Telephone field on the Product Identification page).

This registry value is only written if the Telephone field was enabled on the Product Identification page.

InstallDate REG_SZ Date on which the product was most recently installed, copied from the InstallDate variable. The date is in the format YYYYMMDD (4-digit year, 2-digit month, 2-digit day of the month) and corresponds to the date according to the local time zone that was in effect during installation.
InstallLocation REG_SZ Fully qualified path to the primary installation folder, resolved as <<PRIMARYFOLDER>>. Typically, this refers to the product's top-level installation folder, for example C:\Program Files\Application Name.
InstallSource REG_SZ Fully qualified path to the folder that contains the installation package that was used to install the product, resolved as <SourceDir>. This path is used during subsequent Change/Modify sessions.
Language REG_DWORD Installation language of the product, from <ProductLanguage>. The language ID is defined as per Win32 conventions; see External link Language Identifiers on the MSDN web site.
ModifyPath REG_SZ

[Optional] Fully qualified command line to the installer, complete with the correct arguments to perform a Change/Modify session.

The presence of this command line causes the Add/Remove Programs control panel in recent Windows versions to display a Change button or option (in addition to the Remove button or Uninstall option).

This registry value is only written if the Register A/RP Change option field was checked on the Installer Options page.

Publisher REG_SZ Name of the product's publisher, copied from the Publisher variable (which is in turn initialized from the Publisher field on the Product Identification page).
QuietUninstallString REG_SZ

Fully qualified command line to the installer, complete with the correct arguments to perform a non-interactive ("silent" or "quiet") uninstallation.

This command line is used by automated uninstallations, including the Uninstall Product action. It is not used by the Add/Remove Programs control panel.
ParentDisplayName REG_SZ

[Optional] This registry value is only present if the product in question is an add-on or update to another product and the option Uninstaller: Update uninstaller is specified on the Installer Options page.

In that case, its value is copied from the MainProductName variable (which is in turn initialized from the Main product name field on the Product Identification page).
ParentKeyName REG_SZ

[Optional] This registry value is only present if the product in question is an add-on or update to another product and the option Uninstaller: Update uninstaller is specified on the Installer Options page.

In that case, its value is copied from the MainProductCode variable (which is in turn initialized from the Add-on/Update for product field on the Product Identification page).
ReleaseType REG_SZ

[Optional] This registry value is only present if the product in question is an add-on or update to another product and the option Uninstaller: Update uninstaller is specified on the Installer Options page.

In that case, it is set to the string Update. This causes Windows XP, Vista, and later to hide the product information in the Add/Remove Programs control panel unless the user checks the Show updates box in the control panel.
TinFolder REG_SZ Fully qualified path to the InstallMate folder for the product on the target system, copied from the TinProductFolder variable. This folder contains the product's uninstaller program and associated information.
TinVersion REG_SZ Internal version number of the InstallMate program that was used to install the product, typically something like 7000.
TizPath REG_SZ Fully qualified path to the installation package that was used to install the product, available as <TizPath>. This path is used during subsequent Change/Modify sessions.
UninstallString REG_SZ

Fully qualified command line to the installer, complete with the correct arguments to perform an interactive uninstallation. This command line is used by the Add/Remove Programs control panel.

This registry value is not written if the setting Uninstaller: Hidden uninstaller is specified on the Installer Options page; in that case, only the QuietUninstallString registry value is set.

URLInfoAbout REG_SZ

[Optional] URL of the product's web page, copied from the Website variable (which is in turn initialized from the Web site URL field on the Product Identification page).

This registry value is only written if the Web site URL field was enabled on the Product Identification page.

URLUpdateInfo REG_SZ

[Optional] URL of the product's update web page, copied from the UpdateURL variable (which is in turn initialized from the Update URL field on the Product Identification page).

This registry value is only written if the Update URL field was enabled on the Product Identification page.

Version REG_DWORD Binary version number for the product. It is derived from the ProductVersion variable; if that variable contains version a.b.c.d, then the Version field is set to the DWORD value (((a * 256) + b) * 65536 + c), where a and b are taken modulo 256 and c is taken modulo 65536. Missing version parts are treated as zeroes.
VersionMajor REG_DWORD Binary major version number for the product. It is derived from the ProductVersion variable; if that variable contains version a.b.c.d, then the VersionMajor field is set to the DWORD value a modulo 65536.
VersionMinor REG_DWORD Binary minor version number for the product. It is derived from the ProductVersion variable; if that variable contains version a.b.c.d, then the VersionMajor field is set to the DWORD value b modulo 65536.

Applies to

All supported Windows platforms.

Remarks

The uninstaller information can be completely suppressed by setting Uninstaller: Don't register on the Installer Options page. However, this causes a BLD:Q0066 build diagnostic (Uninstaller registration is suppressed - application cannot be removed easily). The default setting is Uninstaller: Normal uninstaller, which registers the uninstaller information as documented above.

Install to the correct folders by default

Installers built with InstallMate 7 provide full access to all standard Windows folders, and where possible default to the appropriate installation folders. In particular:

A more detailed overview of the standard folders and their behavior across Windows editions is given in the Files and folders and the Standard folders help topics.

The topic Dealing with access rights helps developers to understand the required privilege levels across the various Windows versions.

Applies to

All supported Windows platforms.

Digitally sign files & drivers

Installers built with InstallMate 7 support digital (Authenticode) signatures on executable files as described by the Windows Logo requirements. The following InstallMate features are specifically aimed at digital signatures:

Applies to

All supported Windows platforms.

Support x64 versions of Windows

Installers built with InstallMate 7 fully comply with the x64 Windows requirements of the Windows Logo program.

Correct detection of x64 Windows versions

InstallMate correctly detects x64 Windows versions if the installation takes place on an x64 Windows system. In particular, the following variables can be used to distinguish between various Windows versions (x64 or otherwise):

Full x64 Windows folder access

InstallMate provides full access to the 64-bit variations of standard Windows folders. In particular, the following 64-bit folders are supported:

The developer can use these folders on the Files and Folders page to install 64-bit executables.

Note: It may be necessary to add these folders using the File > Import > Project Items... command, then selecting the Insert 64-bit support.xml.

Although files in these folders are typically controlled by components that prevent their installation on 32-bit platforms, no great harm is done should installation on a 32-bit platform occur: in that case, the missing 64-bit folders are automatically replaced by simulated 64-bit counterparts of the corresponding Windows folders. While this does not allow the files to function per se (64-bit executables will not run on 32-bit platforms), they are at least kept separate from similar 32-bit files and are stored in folders that are clearly marked as 64-bit folders.

For details about these folders, see the Files and folders help topic.

Full x64 Windows registry access

InstallMate provides full access to the 64-bit view of the registry as well as the 32-bit view. This is implemented through the Registry view setting of the Registry Key attributes. The following Registry view options are available.

Registry view option 32-bit Windows 64-bit Windows
Existing key, else Native Always uses 32-bit registry Checks 64-bit and 32-bit views (in that order) and uses the first that already contains the key. If neither does, uses the 64-bit registry.
Native only Always uses 32-bit registry Always uses 64-bit registry
64-bit, then 32-bit Always uses 32-bit registry

Tries to use the 64-bit view first, followed by the 32-bit one if the 64-bit failed.

Note: This option differs from Existing key, else Native in that it will not try the 32-bit registry view if the registry action succeeds in the 64-bit view, even if the key already exists in the 32-bit view.

64-bit only Always fails Always uses 64-bit registry
32-bit only Always uses 32-bit registry Always uses 32-bit registry

Registry value lookup through symbolic expressions and registry lookup performed by actions such as Uninstall Product behave as Existing key, else native. Product uninstaller registration takes place as Native only.

For more details about the registry views, see the Registry Views section in the Registry Key attributes help topic.

Self-registration of x64 DLLs

InstallMate can perform self-registration of x64 as well as 32-bit DLLs and type libraries (in addition to self-registration of .exe files). Because this type of self-registration takes place in-process, the installer uses two small helper executables to host x64 or 32-bit DLLs and type libraries as required.

Native x64 Setup stubs available

The InstallMate distribution includes both 32-bit and x64 Windows Setup stubs. Depending on the parameters of the build process, either or both of the 32-bit and x64 Setup stubs are included in the installation package. However, full 64-bit installation functionality is available in all Setup stubs, whether these are 32-bit or x64 executables.

For more details about the available stubs and the stub selection process, see the Setup stubs help topic.

No 16-bit code

No part of the Tama Installer functionality uses 16-bit code.

Other 64-bit features

During the installer build process, the preflight checks performed by the Tarma development environment will detect 64-bit executables and issue diagnostic messages if these files are not installed in folders that are designated for 64-bit programs. Likewise, attempts to install 32-bit executables in 64-bit folders are also flagged. This allows the developer to correct potential problems before the installer package is deployed.

Applies to

All x64 Windows editions, and to all IA64 Windows editions except as noted in the Remarks section, below.

Remarks

All InstallMate x64 Windows functionality applies equally to IA64 Windows editions, with the following exceptions:

Do not block installation or application launch based on OS version check

Installers built with InstallMate 7 allow Windows version detection prior to the installation, but do not do so by default. However, if the developer decides to allow or disallow installation on specific Windows versions, he can specify the criteria on the System Requirements page. The checks on this page can be done for all known Windows versions, or for the rest group Future Windows versions.

In addition to the System Requirements checks, which take place prior to installation, InstallMate also offers the following features that help to fine-tune Windows version checks should this be necessary for the product:

The checks can use any suitable comparison operations, including inclusive or exclusive version range comparisons.

Applies to

All supported Windows versions.

Remarks

The installation-time checks use the standard Windows functions GetVersionEx(), GetSystemInfo(), and GetNativeSystemInfo() as appropriate and available on the target system to collect their information. Because of the nature of the installer's checks, the VerifyVersionInfo() is not suitable in this case.

Follow User Account Control (UAC) Guidelines

Installers built with InstallMate 7 comply with the UAC guidelines as documented in the Windows Logo requirements. In particular, InstallMate contains Setup stubs sets with the following UAC elevation levels in their embedded application manifests:

The desired stub set may be selected by the developer as part of the Advanced build configuration options, or it may be configured automatically based on the Installation level setting on the Installer Options page.

The topic Dealing with access rights helps developers to understand the required privilege levels across the various Windows versions.

Applies to

Windows Vista and later. However, InstallMate does not assume a specific Windows version; instead, the installers contain the required UAC-compatible application manifests and rely on the target system to handle the desired privilege elevation if supported and applicable.

Remarks

In addition to the required UAC-compatible application manifests, all InstallMates on all Windows platforms perform runtime checks prior to installation to find out if access to the installation folders and other system resources is allowed. Based on the outcome of these checks and the Installation level setting on the Installer Options page, the installer may inform the user that the installation can only be performed as a Current User installation, or that the installation cannot proceed at all and must be restarted under an Administrator account.

.Net and the Global Assembly Cache

Installers built with InstallMate 7 use the officially documented Windows API to install and remove .Net global assemblies in the Global Assembly Cache (GAC). This involves the IAssemblyCache COM interface and some of its methods (i.e., member functions):

 IAssemblyCache
    InstallAssembly()
    UninstallAssembly()
    ...other methods...

(See http://msdn.microsoft.com/en-us/library/ms231448.aspx for documentation of this COM interface.)

This means that the installer does not touch the GAC itself; that is all done by Windows. What happens during installation is this:

  1. The installer unpacks the assembly files and places them in a temporary staging directory (under %TEMP%\...unique ID...)
  2. The installer then obtains a pointer to the IAssemblyCache interface by calling the Windows function CreateAssemblyCache(). The returned IAssemblyCache pointer represents the global assembly cache interface. (See http://msdn.microsoft.com/en-us/library/ms230575.aspx for documentation.)
  3. The installer calls IAssemblyCache::InstallAssembly() with the required parameters. This causes the Windows .Net support to copy the assembly files from their temporary staging location to the GAC and to update whatever registry entries need to be updated.
  4. During removal, the installer again calls CreateAssemblyCache() to obtain an IAssemblyCache pointer, and then uses IAssemblyCache::UninstallAssembly() to remove the assembly (or not, if any other references are still active). Again, it's Windows' own .Net support that performs the GAC actions, not InstallMate.

Applies to

All Windows platforms that have .Net support installed. InstallMate does not assume a specific Windows version; instead, the installers check for the presence of the CreateAssemblyCache() function and the availability of the IAssemblyCache interface, and will use those on any platform that implements this functionality.

Other features

In addition to the items discussed above, InstallMate contains many other features that improve the installation experience and general Windows compatibility and system security, and that may therefore be relevant during the Windows Logo certification process.

Platform support from Windows 95 to Windows 7 and beyond

InstallMate has built-in support for all publicly released Windows version from Windows 95 to Windows 7. Moreover, the availability of features is not assumed based on Windows version checks, but on direct checks for the feature with appropriate error handling or a suitable fall-back strategy if the feature in question is not present. This also makes the installers future-proof.

Support for Windows Preinstallation Environment

InstallMate also supports the Windows Preinstallation Environment (WinPE) editions of Windows XP, Vista, and 7. Installers built with InstallMate do not use MSI and are fully compatible with the restricted WinPE environments.

Terminal Server aware

All InstallMates are compatible with Terminal Server environment and are marked as such (/TSAWARE) in their executables. In particular, an installer running in a Terminal Server environment will switch the environment to installation mode prior to installation, and back to execution mode afterwards.

Unicode

The installer's database and the main Setup stubs are Unicode through-and-through, and they are also bidi-aware. This allows the installer to handle all languages and locales that are supported by the target system. The only ANSI-based code that is present is in the Setup32a.exe stub that is used for the Windows 95, 98, and Me platforms. However, these legacy platforms are ANSI-only and therefore require ANSI-based executables for correct operation. (The ANSI version of the installer is fully MBCS-compatible and will handle double-byte character sets without problems.)

Compiler security features

InstallMate is compiled with a modern Microsoft C/C++ compiler and linker toolset and its executables use the following compiled-in security features:

Furthermore, the installers use the Windows heap for memory management, which (at least on recent Windows versions) includes a number of heap-related security checks. Wherever applicable, InstallMate follows Windows Best Practices and uses safe coding techniques to improve the installer's robustness even further.

Current User installations are fully isolated

InstallMate has a (what we believe to be) unique installation mode called Current User installation. While most installers offer some form of per-user installation, Tarma's is unique in the following respects:

These features allow an application to be installed by an unprivileged user for his or her own exclusive use. They also allow multiple independent installations of the same product. In fact, there can be as many independent installations as there are user accounts on the system, plus one additional per-machine installation.

Note: These Current User installation features are available from Windows 2000 onwards. Earlier versions either do not implement a functional All Users/Current User separation (this applies to Windows 95, 98, and Me) or do not allow the HKEY_CLASSES_ROOT registry key to be redirected (this applies to Windows NT4).

Documentation Home | Using InstallMate Builder | Knowledge Base | Frequently Asked Questions
InstallMate 7 User's Manual - © 1990-2010 Tarma Software Research. All rights reserved.
$Id: winlogo.htm 1442 2010-08-20 05:51:40Z dave $